vision/README.md

# @go/vision

极致精简、工业级的高性能图像处理与全能媒体工具集。

## 🎯 设计哲学

`go/vision` 致力于消除 Go 语言在媒体处理领域的摩擦。通过纯 Go 的核心算法与标准化的外部工具编排，提供一套语义一致、零摩擦、高性能一站式 API 体系。

*   **零摩擦**: 自动探测/引导环境准备（如 FFmpeg），一键式识别与转换。
*   **工业级**: 错误驱动架构（No internal logging），完备的单元测试覆盖。
*   **全能型**: 涵盖静态图、动图、视频、扫码、色彩分析与几何变换。

## 🚀 核心能力

### 1. 基础绘图与画布 (Canvas)
*   **流式 API**: 支持矩形、圆角、路径、点/线、阴影、暗角等绘制。
*   **现代文本**: 内置 `CompositeFace`，完美支持多字体回退 (Fallback) 与中英文混排。

### 2. 图像处理与变换
*   **几何变换**: 缩放 (Resize/Fit/Fill)、旋转、镜像、**4 点透视变换 (WarpPerspective)**。
*   **高级滤镜**: 模糊、锐化、灰度、亮度/对比度、色彩反转、卷积滤波。
*   **色彩分析**: 调色板提取 (`ExtractPalette`)、平均色计算。

### 3. 智能视觉 (Intelligence)
*   **码码识别**: 集成 QR Code、条形码 (Code128, UPC/EAN) 的生成与自动解码识别。
*   **感知哈希 (PHash)**: 基于图像特征的指纹计算，用于海量图片相似度查重。
*   **验证码引擎**: 高强度抗 OCR 图形验证码生成。
*   **模板匹配**: `FindTemplate` 支持在大图中精准定位子图。

### 4. 动态媒体 (Animation & Video)
*   **GIF 引擎**: 高质量 GIF 序列生成，内置 `Plan9` 调色板与 `Floyd-Steinberg` 抖动。
*   **视频编排**: 基于 FFmpeg 的视频帧提取与合成，支持多平台二进制自动引导。

## 📦 安装

```bash
go get apigo.cc/go/vision
```

## 💡 快速开始

### 1. 扫码与识别
```go
// 自动尝试 QR 和条码识别
c, _ := vision.Load("code.jpg")
content, err := c.DecodeAll() 

// 生成二维码并保存
qr, _ := vision.GenerateQRCode("https://apigo.cc", 256)
vision.Save(qr, "qr.png")
```

### 2. 透视变换 (WarpPerspective)
常用于文档扫描纠偏。
```go
c, _ := vision.Load("skewed_doc.jpg")
// 指定源图中的四个角点 (TL, TR, BR, BL)
srcPoints := [4]image.Point{
    {150, 20}, {450, 50}, {480, 380}, {100, 350},
}
c.WarpPerspective(srcPoints, 300, 400)
vision.Save(c, "flat_doc.png")
```

### 3. 生成 GIF 动画
```go
anim := vision.NewAnimation()
for i := 0; i < 10; i++ {
    c := vision.New(100, 100, "#FFFFFF")
    c.Circle(50, 50, float64(i*5), &vision.DrawStyle{FillColor: "#FF0000"})
    anim.AddFrame(c, 10) // 100ms 延迟
}
anim.SaveGIF("motion.gif", 0) // 0 表示无限循环
```

### 4. 视频帧提取
```go
v, _ := vision.NewVideo()
frame, _ := v.ExtractFrame("movie.mp4", 5.0) // 提取第 5 秒的帧
frame.Blur(2.0)
vision.Save(frame, "preview.jpg")
```

### 5. 验证码生成
```go
captcha := vision.GenerateCaptcha(&vision.CaptchaOption{
    Length: 6,
    Width: 200,
    Height: 60,
})
vision.Save(captcha, "captcha.png")
```

## 🛠 API 概览

| 模块 | 主要 API |
| :--- | :--- |
| **Canvas** | `New`, `Load`, `Save`, `Clear`, `Sub`, `Clone`, `Put`, `LoadFonts` |
| **Draw** | `Rect`, `RoundedRect`, `Circle`, `Line`, `Path`, `RandBG` |
| **Effect** | `Resize`, `Rotate`, `Blur`, `Sharpen`, `AdjustBrightness`, `Grayscale`, `Invert` |
| **Transform** | `WarpPerspective`, `FlipH`, `FlipV` |
| **Recognition** | `DecodeQRCode`, `DecodeBarcode`, `DecodeAll`, `PHash`, `Distance`, `FindTemplate` |
| **Media** | `NewAnimation`, `NewVideo`, `ProcessVideoFrames`, `DiffFrames` |

## ⚙️ 环境依赖

*   **FFmpeg**: 视频处理模块依赖 `ffmpeg` 二进制文件。
    *   `vision.NewVideo()` 会尝试自动探测系统路径。
    *   如果未安装，它会提示下载路径或尝试自动引导（取决于权限）。

---
本项目由 AI 驱动开发与维护，遵循极致的代码质量与性能标准。