vision

package module
v1.5.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 5, 2026 License: MIT Imports: 36 Imported by: 0

README

@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)

// 生成动画预览 (WebP/GIF, 默认 30s 采样一帧,自动填充/裁剪)
vision.GenerateVideoPreview("movie.mp4", "preview.webp", 320, 180)

// 生成单张预览图 (JPG/PNG, 取视频中间帧)
vision.GenerateVideoPreview("movie.mp4", "preview.jpg", 320, 180)

// 提取多张预览帧到文件夹 (输出 1.webp, 2.webp...)
vision.GenerateVideoPreview("movie.mp4", "frames_dir", 320, 180)

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

命令行工具 (vision)

vision 包内置了一个全能的命令行工具,位于 cmd/vision 目录下。

安装

使用 go install 安装:

go install apigo.cc/go/vision/cmd/vision@latest
常用命令
# 1. 查看图片信息与调色板
vision photo.jpg

# 2. 识别二维码/条码
vision code.png --decode

# 3. 生成二维码
vision --data "https://apigo.cc" -o qr.png --size 512

# 4. 批量处理图像 (缩放、模糊、灰度)
vision in.png -o out.png --resize 800x600 --blur 1.5 --grayscale

# 5. 生成视频动态预览 (WebP)
vision video.mp4 --type video -o preview.webp --width 320 --height 180 --step 30

# 6. 生成验证码
vision --captcha -o captcha.png --len 6

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Convert

func Convert(srcPath, dstPath string, quality ...int) error

Convert 将图像文件转换为另一种格式

func ConvertAll

func ConvertAll(srcDir, dstDir string, toExt string, quality ...int) (int, []error)

ConvertAll 将目录下的所有符合条件的图片转换为目标格式

func ConvertHEIC added in v1.0.9

func ConvertHEIC(src, dst string) error

ConvertHEIC 使用探测到的工具将 HEIC 转换为 PNG 临时文件

func DetectHEICConverter added in v1.0.9

func DetectHEICConverter() string

DetectHEICConverter 探测系统中可用的 HEIC 转换工具。 优先级: sips (macOS) > heif-convert (libheif) > magick (ImageMagick)

func DiffFrames

func DiffFrames(prev, curr *Canvas) float64

DiffFrames 计算两帧之间的差异 (简单运动检测基础)

func Distance

func Distance(h1, h2 uint64) int

Distance 计算两个哈希值之间的 Hamming 距离

func DownloadFFmpeg

func DownloadFFmpeg(targetDir string) (string, error)

DownloadFFmpeg 下载对应系统的 FFmpeg 二进制文件

func EnsureFFmpeg

func EnsureFFmpeg() (string, error)

EnsureFFmpeg 确保 ffmpeg 命令可用

func GenerateAudioPreview added in v1.0.6

func GenerateAudioPreview(mediaPath, outPath string) error

GenerateAudioPreview 提取音频用于预览或语音转写 支持根据 outPath 后缀输出格式: - .ogg: 使用 libopus (16kHz, 单声道, 12kbps), 极致压缩且保留人声特征,适合转写 - .wav: 标准 PCM (16kHz, 单声道), 无损但体积较大,部分转写引擎强制要求 - 其他: 默认使用 libopus 转为 ogg

func GenerateImagePreview added in v1.0.6

func GenerateImagePreview(srcPath, outPath string, width, height int) error

GenerateImagePreview 生成图片预览 支持缩放并裁剪以填充指定尺寸 (Fill 模式) 根据 outPath 后缀自动转换格式 (.webp, .jpg, .png 等)

func GenerateVideoPreview added in v1.0.6

func GenerateVideoPreview(videoPath, outPath string, width, height int, frameInterval ...int) error

GenerateVideoPreview 生成视频预览 根据 outPath 后缀判断输出格式: - .webp | .gif: 生成动态动画 (默认每 30 秒采样一帧,可通过 frameInterval 调整) - .jpg | .jpeg | .png: 生成单张预览图 (取视频中间帧) - 其他: 将 outPath 视为文件夹,在其中生成多张静态 .webp 图像 frameInterval: 每隔多少秒采样一帧,默认 30。

func LoadFonts

func LoadFonts(paths ...string)

LoadFonts 加载指定路径的字体文件

func Optimize

func Optimize(path string, maxWidth int, quality int) error

Optimize 优化图片大小 (通过调整质量或缩放)

func PHash

func PHash(img image.Image) uint64

PHash 计算图像的感知哈希值 (Perceptual Hash) 返回 64 位整数。Hamming 距离越小,图片越相似。

func ParseColor

func ParseColor(hex string) color.Color

ParseColor 将多种格式的十六进制颜色字符串转换为 color.Color 支持格式: #RRGGBB, #RRGGBBAA, #RGB, #RGBA

func ProcessVideoFrames

func ProcessVideoFrames(totalFrames int, provider func(int) (*Canvas, error), processor StreamProcessor) error

ProcessVideoFrames 模拟视频帧处理 (通过一系列图片或自定义逻辑) 这是一个为未来视频流处理预留的语义化接口

func RGBAToHex

func RGBAToHex(c color.RGBA) string

RGBAToHex 将 RGBA 转换为 Hex 字符串

func RandColor

func RandColor() string

RandColor 生成随机颜色 hex 字符串

func Recognize added in v1.0.7

func Recognize(path string) (string, error)

Recognize 从指定路径加载图片并自动识别其中的任何码 (QR, Barcode)

func Save

func Save(c *Canvas, path string, quality ...int) error

Save 将画布保存到文件

Types

type Animation

type Animation struct {
	Frames []*Canvas
	Delays []int // 每帧延迟时间 (单位: 1/100 秒)
}

Animation 代表一个动画序列 (如 GIF)

func GenerateGIFCaptcha added in v1.0.4

func GenerateGIFCaptcha(opt *CaptchaOption) *Animation

GenerateGIFCaptcha 生成动态 GIF 验证码

func LoadGIF

func LoadGIF(path string) (*Animation, error)

LoadGIF 从文件加载 GIF 动画

func NewAnimation

func NewAnimation() *Animation

NewAnimation 创建一个空动画

func (*Animation) AddFrame

func (a *Animation) AddFrame(c *Canvas, delay int)

AddFrame 添加一帧到动画中 delay: 延迟时间 (100 = 1秒)

func (*Animation) SaveGIF

func (a *Animation) SaveGIF(path string, loopCount int) error

SaveGIF 将动画保存为 GIF 文件

func (*Animation) TextWatermark added in v1.0.5

func (a *Animation) TextWatermark(text string, pos Position, style *DrawStyle, opacity float64, padding int, angle ...float64)

TextWatermark 给动画所有帧添加文字水印

func (*Animation) TileTextWatermark added in v1.0.5

func (a *Animation) TileTextWatermark(text string, style *DrawStyle, opacity float64, spacing int, angle float64)

TileTextWatermark 给动画所有帧平铺文字水印

func (*Animation) TileWatermark added in v1.0.5

func (a *Animation) TileWatermark(mark *Canvas, opacity float64, spacing int, angle float64)

TileWatermark 给动画所有帧平铺图片水印

func (*Animation) Watermark added in v1.0.5

func (a *Animation) Watermark(mark *Canvas, pos Position, opacity float64, padding int, angle ...float64)

Watermark 给动画所有帧添加图片水印

type Canvas

type Canvas struct {
	// contains filtered or unexported fields
}

Canvas 代表一个绘图画布,封装了图像处理与绘制能力

func Capture added in v1.0.7

func Capture(videoPath string, offsetSeconds ...float64) (*Canvas, error)

Capture 是从视频中提取指定时间的帧的便捷封装。 如果未提供 offsetSeconds,默认提取第 0 秒。

func GenerateBarcode

func GenerateBarcode(content string, width, height int) (*Canvas, error)

GenerateBarcode 生成一个条形码画布 (Code128)

func GenerateCaptcha

func GenerateCaptcha(opt *CaptchaOption) *Canvas

GenerateCaptcha 生成一个验证码画布

func GenerateQRCode

func GenerateQRCode(content string, size int) (*Canvas, error)

GenerateQRCode 生成一个包含二维码的画布

func Load

func Load(path string) (*Canvas, error)

Load 从文件加载图像并创建画布

func New

func New(width, height int, backgroundColor ...string) *Canvas

New 创建一个新的画布

func (*Canvas) AdjustBrightness

func (c *Canvas) AdjustBrightness(percent float64)

AdjustBrightness 调整亮度

func (*Canvas) AdjustContrast

func (c *Canvas) AdjustContrast(percent float64)

AdjustContrast 调整对比度

func (*Canvas) AdjustSaturation

func (c *Canvas) AdjustSaturation(percent float64)

AdjustSaturation 调整饱和度

func (*Canvas) Blur

func (c *Canvas) Blur(sigma float64)

Blur 模糊处理

func (*Canvas) Circle

func (c *Canvas) Circle(x, y, r float64, opt *DrawStyle)

Circle 绘制圆形

func (*Canvas) Clear

func (c *Canvas) Clear(x, y, w, h int)

Clear 清除指定区域,如果设置了背景色则填充背景色,否则填充透明

func (*Canvas) Clone

func (c *Canvas) Clone() *Canvas

Clone 克隆当前画布

func (*Canvas) Convolve3x3

func (c *Canvas) Convolve3x3(kernel [9]float64)

Convolve3x3 应用 3x3 卷积核

func (*Canvas) DecodeAll

func (c *Canvas) DecodeAll() (string, error)

DecodeAll 自动尝试识别图片中的任何码 (QR, Barcode)

func (*Canvas) DecodeBarcode

func (c *Canvas) DecodeBarcode() (string, error)

DecodeBarcode 识别图片中的条形码

func (*Canvas) DecodeQRCode

func (c *Canvas) DecodeQRCode() (string, error)

DecodeQRCode 识别图片中的二维码

func (*Canvas) DrawText

func (c *Canvas) DrawText(x, y float64, text string, opt *TextOption)

DrawText 在画布上绘制文本

func (*Canvas) ExtractPalette

func (c *Canvas) ExtractPalette(n int) []ColorCount

ExtractPalette 从图像中提取调色板(主要颜色) n: 提取的前 n 种颜色

func (*Canvas) Fill

func (c *Canvas) Fill(w, h int)

Fill 缩放画布以填充指定尺寸,保持宽高比并裁剪

func (*Canvas) FindTemplate

func (c *Canvas) FindTemplate(template *Canvas) MatchResult

FindTemplate 在当前画布中查找子图 (模板匹配) 使用简单的平方差和 (Sum of Squared Differences) 算法

func (*Canvas) Fit

func (c *Canvas) Fit(w, h int)

Fit 缩放画布以适应指定尺寸,保持宽高比

func (*Canvas) FlipH

func (c *Canvas) FlipH()

FlipH 水平翻转

func (*Canvas) FlipV

func (c *Canvas) FlipV()

FlipV 垂直翻转

func (*Canvas) GenerateJigsaw added in v1.0.4

func (c *Canvas) GenerateJigsaw(x, y, size int) *JigsawResult

GenerateJigsaw 生成滑块拼图物料

func (*Canvas) GetAverageColor

func (c *Canvas) GetAverageColor() color.Color

GetAverageColor 计算画布的平均颜色

func (*Canvas) Grayscale

func (c *Canvas) Grayscale()

Grayscale 转为灰度图

func (*Canvas) Height

func (c *Canvas) Height() int

Height 返回画布高度

func (*Canvas) Image

func (c *Canvas) Image() image.Image

Image 返回底层图像

func (*Canvas) Invert

func (c *Canvas) Invert()

Invert 反转颜色

func (*Canvas) Line

func (c *Canvas) Line(x1, y1, x2, y2 float64, opt *DrawStyle)

Line 绘制直线

func (*Canvas) Path

func (c *Canvas) Path(path string, opt *DrawStyle)

Path 绘制 SVG 路径

func (*Canvas) Pixelate

func (c *Canvas) Pixelate(size int)

Pixelate 像素化处理

func (*Canvas) Put

func (c *Canvas) Put(src *Canvas, x, y int)

Put 将另一个画布内容贴入当前画布

func (*Canvas) PutQRCode

func (c *Canvas) PutQRCode(content string, x, y, size int) error

PutQRCode 在当前画布指定位置绘制二维码

func (*Canvas) RandBG

func (c *Canvas) RandBG(level int)

RandBG 绘制随机干扰背景 (1-10 档)

func (*Canvas) RandText

func (c *Canvas) RandText(text string) [][4]float64

RandText 绘制随机扭曲文本 (用于验证码)

func (*Canvas) Recognize added in v1.0.7

func (c *Canvas) Recognize() (string, error)

Recognize 是 DecodeAll 的别名,用于自动识别图片中的任何码 (QR, Barcode)

func (*Canvas) Rect

func (c *Canvas) Rect(x, y, w, h float64, opt *DrawStyle)

Rect 绘制矩形

func (*Canvas) Resize

func (c *Canvas) Resize(w, h int)

Resize 缩放画布到指定尺寸

func (*Canvas) Rotate

func (c *Canvas) Rotate(angle float64)

Rotate 旋转画布

func (*Canvas) RoundedRect

func (c *Canvas) RoundedRect(x, y, w, h, r float64, opt *DrawStyle)

RoundedRect 绘制圆角矩形

func (*Canvas) Sepia

func (c *Canvas) Sepia()

Sepia 应用怀旧滤镜

func (*Canvas) SetColor

func (c *Canvas) SetColor(hex string)

SetColor 设置当前绘图颜色 (支持 hex 格式)

func (*Canvas) SetFont

func (c *Canvas) SetFont(size float64, names ...string) error

SetFont 设置画布字体

func (*Canvas) Sharpen

func (c *Canvas) Sharpen(sigma float64)

Sharpen 锐化

func (*Canvas) Sub

func (c *Canvas) Sub(x, y, w, h int) *Canvas

Sub 提取子区域并返回新画布

func (*Canvas) TextWatermark added in v1.0.4

func (c *Canvas) TextWatermark(text string, pos Position, style *DrawStyle, opacity float64, padding int, angle ...float64)

TextWatermark 给画布添加文字水印

func (*Canvas) TileTextWatermark added in v1.0.5

func (c *Canvas) TileTextWatermark(text string, style *DrawStyle, opacity float64, spacing int, angle float64)

TileTextWatermark 平铺文字水印

func (*Canvas) TileWatermark added in v1.0.5

func (c *Canvas) TileWatermark(mark *Canvas, opacity float64, spacing int, angle float64)

TileWatermark 平铺图片水印 spacing: 间距 angle: 旋转角度 (弧度)

func (*Canvas) Vignette

func (c *Canvas) Vignette(intensity float64)

Vignette 应用暗角效果

func (*Canvas) WarpPerspective

func (c *Canvas) WarpPerspective(srcPoints [4]image.Point, dstWidth, dstHeight int)

WarpPerspective 执行透视变换(4点变换) srcPoints: 源图像中的 4 个点 [TL, TR, BR, BL] dstWidth, dstHeight: 目标图像的尺寸

func (*Canvas) Watermark added in v1.0.4

func (c *Canvas) Watermark(mark *Canvas, pos Position, opacity float64, padding int, angle ...float64)

Watermark 给画布添加图片水印 mark: 水印画布 pos: 位置 opacity: 透明度 (0.0 - 1.0) padding: 边距 angle: 旋转角度 (弧度)

func (*Canvas) Width

func (c *Canvas) Width() int

Width 返回画布宽度

type CaptchaOption

type CaptchaOption struct {
	Text       string
	Length     int
	Width      int
	Height     int
	NoiseLevel int // 1-10
}

CaptchaOption 定义验证码生成选项

type ColorCount

type ColorCount struct {
	Color color.Color
	Hex   string
	Count int
}

ColorCount 记录颜色及其出现的频率

type CompositeFace

type CompositeFace struct {
	Names []string
	Faces []font.Face
}

CompositeFace 支持多字体回退的字体接口实现

func (*CompositeFace) Close

func (c *CompositeFace) Close() error

func (*CompositeFace) Glyph

func (c *CompositeFace) Glyph(dot fixed.Point26_6, r rune) (dr image.Rectangle, mask image.Image, maskp image.Point, advance fixed.Int26_6, ok bool)

func (*CompositeFace) GlyphAdvance

func (c *CompositeFace) GlyphAdvance(r rune) (advance fixed.Int26_6, ok bool)

func (*CompositeFace) GlyphBounds

func (c *CompositeFace) GlyphBounds(r rune) (bounds fixed.Rectangle26_6, advance fixed.Int26_6, ok bool)

func (*CompositeFace) Kern

func (c *CompositeFace) Kern(r0, r1 rune) fixed.Int26_6

func (*CompositeFace) Metrics

func (c *CompositeFace) Metrics() font.Metrics

type DrawStyle

type DrawStyle struct {
	StrokeColor  string
	StrokeWidth  float64
	LineCap      gg.LineCap
	LineJoin     gg.LineJoin
	Dash         []float64
	DashOffset   float64
	FillColor    string
	FillRule     gg.FillRule
	ShadowColor  string
	ShadowOffset float64
	ShadowBlur   float64
}

DrawStyle 定义图形绘制样式

type Format

type Format string

Format 定义支持的图像格式

const (
	PNG  Format = "png"
	JPEG Format = "jpeg"
	JPG  Format = "jpg"
	GIF  Format = "gif"
)

type JigsawResult added in v1.0.4

type JigsawResult struct {
	Background *Canvas // 带槽口的背景
	Piece      *Canvas // 拼图块
	X, Y       int     // 槽口位置
}

JigsawResult 滑块拼图结果

type MatchResult

type MatchResult struct {
	Point image.Point
	Score float64 // 相似度分数 (0.0 - 1.0)
}

MatchResult 模板匹配结果

type Position added in v1.0.4

type Position int

Position 水印位置

const (
	TopLeft Position = iota
	TopCenter
	TopRight
	LeftCenter
	Center
	RightCenter
	BottomLeft
	BottomCenter
	BottomRight
)

type StreamProcessor

type StreamProcessor func(frame *Canvas, frameIndex int) error

StreamProcessor 定义帧处理器函数

type TextOption

type TextOption struct {
	Width       float64
	Height      float64
	LineHeight  float64
	Align       string // left, center, right
	VAlign      string // top, middle, bottom
	Color       string
	BgColor     string
	BorderColor string
	BorderWidth float64
	Padding     [4]float64 // top, right, bottom, left
}

TextOption 定义文本绘制选项

type Video

type Video struct {
	FFmpegPath string
}

Video 代表一个视频操作封装

func NewVideo

func NewVideo() (*Video, error)

NewVideo 创建一个视频处理器,自动查找或下载 ffmpeg

func (*Video) CreateVideoFromImages

func (v *Video) CreateVideoFromImages(imagePattern string, frameRate int, outPath string) error

CreateVideoFromImages 从一系列图片创建视频

func (*Video) ExtractFrame

func (v *Video) ExtractFrame(videoPath string, offsetSeconds float64) (*Canvas, error)

ExtractFrame 从视频中提取指定时间的帧

func (*Video) WatermarkVideo added in v1.0.4

func (v *Video) WatermarkVideo(videoPath, markPath, outPath, pos string) error

WatermarkVideo 给视频添加水印 videoPath: 输入视频 markPath: 水印图片路径 outPath: 输出视频路径 pos: 水印位置 (使用 FFmpeg 语法, 如 '10:10', 'main_w-overlay_w-10:10')

Directories

Path Synopsis
cmd
vision command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址