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 的视频帧提取与合成，支持多平台二进制自动引导。

📦 安装

go get apigo.cc/go/vision

💡 快速开始

1. 扫码与识别

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

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

2. 透视变换 (WarpPerspective)

常用于文档扫描纠偏。

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 动画

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. 视频帧提取

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

5. 多媒体预览与转写转码

针对 Web 端、列表缩略图或语音转写场景的一站式优化预览。支持自动缩放并裁剪以适应指定尺寸。

// 生成图片缩略图 (WebP, 自动填充/裁剪)
vision.GenerateImagePreview("photo.jpg", "thumb.webp", 200, 200)

// 生成 4 帧动画 WebP (自动填充/裁剪, 效果动态)
vision.GenerateVideoPreview("movie.mp4", "preview.webp", 320, 180)

// 提取音频预览片段 (16kHz Ogg Opus, 最长 3 分钟)
vision.GenerateAudioPreview("input.mp4", "preview.ogg")

🛠 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 驱动开发与维护，遵循极致的代码质量与性能标准。