GoCV

GoCV 包为 OpenCV 4 计算机视觉库提供了 Go 语言绑定。

GoCV 支持在 Linux、Docker、macOS 和 Windows 上使用最新版本的 Go 和 OpenCV（v4.12.0）。我们的持续使命是帮助 Go 编程语言成为与 OpenCV 生态系统最新发展兼容的“一流”客户端。

GoCV 支持使用 Nvidia GPU 进行硬件加速的 CUDA。有关如何将 GoCV 与 OpenCV/CUDA 结合使用的更多信息，请参阅 CUDA README。

GoCV 还支持 Intel OpenVINO。有关如何将 GoCV 与 Intel OpenVINO 工具包结合使用的更多信息，请参阅 OpenVINO README。

使用方法

你好，视频

此示例使用设备“0”打开视频捕获设备，读取帧，并在 GUI 窗口中显示视频：

package main

import (
	"gocv.io/x/gocv"
)

func main() {
	webcam, _ := gocv.OpenVideoCapture(0)
	window := gocv.NewWindow("Hello")
	img := gocv.NewMat()

	for {
		webcam.Read(&img)
		window.IMShow(img)
		window.WaitKey(1)
	}
}

人脸检测

这是一个更完整的示例，它使用设备“0”打开视频捕获设备。它还使用 CascadeClassifier 类加载包含分类器数据的外部数据文件。程序从视频中逐帧抓取图像，然后使用分类器检测人脸。如果发现有人脸，它会在每张脸上绘制一个绿色矩形，然后在输出窗口中显示视频：

package main

import (
	"fmt"
	"image/color"

	"gocv.io/x/gocv"
)

func main() {
    // 设置使用视频捕获设备 0
    deviceID := 0

	// 打开网络摄像头
	webcam, err := gocv.OpenVideoCapture(deviceID)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer webcam.Close()

	// 打开显示窗口
	window := gocv.NewWindow("Face Detect")
	defer window.Close()

	// 准备图像矩阵
	img := gocv.NewMat()
	defer img.Close()

	// 检测到人脸时矩形的颜色
	blue := color.RGBA{0, 0, 255, 0}

	// 加载用于识别人脸的分类器
	classifier := gocv.NewCascadeClassifier()
	defer classifier.Close()

	if !classifier.Load("data/haarcascade_frontalface_default.xml") {
		fmt.Println("Error reading cascade file: data/haarcascade_frontalface_default.xml")
		return
	}

	fmt.Printf("start reading camera device: %v\n", deviceID)
	for {
		if ok := webcam.Read(&img); !ok {
			fmt.Printf("cannot read device %v\n", deviceID)
			return
		}
		if img.Empty() {
			continue
		}

		// 检测人脸
		rects := classifier.DetectMultiScale(img)
		fmt.Printf("found %d faces\n", len(rects))

		// 在原始图像上为每张脸绘制一个矩形
		for _, r := range rects {
			gocv.Rectangle(&img, r, blue, 3)
		}

		// 在窗口中显示图像，并等待 1 毫秒
		window.IMShow(img)
		window.WaitKey(1)
	}
}

更多示例

本仓库的 cmd 目录 中包含各种实用命令行工具的示例，例如 捕获图像文件、流式传输 mjpeg 视频、统计越过某条线的物体数量，以及 使用 OpenCV 和 DNN 进行人脸跟踪。

安装方法

要安装 GoCV，您必须先在系统上安装匹配版本的 OpenCV。当前版本的 GoCV 需要 OpenCV 4.12.0。

我们还提供了适用于 Linux、macOS、Windows 及其他平台的安装说明。

Linux

请访问我们的网站：https://gocv.io/getting-started/linux/

macOS

请访问我们的网站：https://gocv.io/getting-started/macos/

Windows

请访问我们的网站：https://gocv.io/getting-started/windows/

Docker

请访问我们的网站：https://gocv.io/getting-started/docker/

Android

目前正在进行使用 Gomobile 在 Android 上运行 GoCV 的工作。有关如何在 Android 上安装 OpenCV/GoCV 的信息，请参阅： https://gist.github.com/ogero/c19458cf64bd3e91faae85c3ac8874120

原始讨论请见： https://github.com/hybridgroup/gocv/issues/235

性能分析

由于 GoCV 中图像的内存分配是通过 C 代码完成的，因此 Go 垃圾回收器不会清理与 Mat 相关的所有资源。因此，任何创建的 Mat 都必须关闭，以避免内存泄漏。

为了便于检测和修复资源泄漏，GoCV 提供了一个 Mat 分析器，用于记录每个 Mat 的创建和关闭时间。每次分配 Mat 时，堆栈跟踪都会被添加到分析记录中；当 Mat 被关闭时，相应的堆栈跟踪会被移除。有关详细信息，请参阅 runtime/pprof 文档。

要启用 MatProfile 自定义分析器，您必须使用 -tags matprofile 构建标记来构建或运行您的应用程序或测试。例如：

go run -tags matprofile cmd/version/main.go

您可以随时使用以下代码获取分析记录中的计数：

gocv.MatProfile.Count()

您还可以使用以下代码显示当前的条目（即堆栈跟踪）：

var b bytes.Buffer
gocv.MatProfile.WriteTo(&b, 1)
fmt.Print(b.String())

这对于追踪内存泄漏非常有帮助。例如，假设您有以下无意义的程序：

package main

import (
	"bytes"
	"fmt"

	"gocv.io/x/gocv"
)

func leak() {
	gocv.NewMat()
}

func main() {
	fmt.Printf("initial MatProfile count: %v\n", gocv.MatProfile.Count())
	leak()

	fmt.Printf("final MatProfile count: %v\n", gocv.MatProfile.Count())
	var b bytes.Buffer
	gocv.MatProfile.WriteTo(&b, 1)
	fmt.Print(b.String())
}

运行该程序会产生如下输出：

initial MatProfile count: 0
final MatProfile count: 1
gocv.io/x/gocv.Mat profile: total 1
1 @ 0x40b936c 0x40b93b7 0x40b94e2 0x40b95af 0x402cd87 0x40558e1
#	0x40b936b	gocv.io/x/gocv.newMat+0x4b	/go/src/gocv.io/x/gocv/core.go:153

#	0x40b93b6	gocv.io/x/gocv.NewMat+0x26	/go/src/gocv.io/x/gocv/core.go:159
#	0x40b94e1	main.leak+0x21			/go/src/github.com/dougnd/gocvprofexample/main.go:11
#	0x40b95ae	main.main+0xae			/go/src/github.com/dougnd/gocvprofexample/main.go:16
#	0x402cd86	runtime.main+0x206		/usr/local/Cellar/go/1.11.1/libexec/src/runtime/proc.go:201

我们可以看到，这个程序会泄漏内存。当它退出时，仍然有一个未关闭的 Mat 对象。堆栈跟踪精确地指出了分配发生的具体行（第11行，即 gocv.NewMat()）。

此外，如果该程序是一个长期运行的进程，或者 GoCV 被用于 Web 服务器中，那么安装 HTTP 接口可能会很有帮助。例如：

package main

import (
	"net/http"
	_ "net/http/pprof"
	"time"

	"gocv.io/x/gocv"
)

func leak() {
	gocv.NewMat()
}

func main() {
	go func() {
		ticker := time.NewTicker(time.Second)
		for {
			<-ticker.C
			leak()
		}
	}()

	http.ListenAndServe("localhost:6060", nil)
}

这段代码每秒会泄漏一个 Mat 对象。你可以通过访问已安装的 HTTP 调试接口来查看当前的性能剖析计数和堆栈跟踪：http://localhost:6060/debug/pprof/gocv.io/x/gocv.Mat。

如何贡献

请查看我们的 CONTRIBUTING.md 文档，以了解我们的贡献指南。

然后，请查阅我们的 ROADMAP.md 文档，以了解接下来可以开展的工作。

为什么会有这个项目

针对 Go 和 OpenCV 的 https://github.com/go-opencv/go-opencv 包并不支持 OpenCV 2.x 以上的版本，而对 OpenCV 3 的支持工作也已经停滞了一年多，这主要是由于 SWIG 的复杂性所致。因此，我们启动了这个项目。

GoCV 包使用一种 C 风格的封装层来围绕 OpenCV 4 的 C++ 类进行封装，从而避免直接对庞大的现有代码库应用 SWIG。这些映射尽可能地与原始 OpenCV 的项目结构保持一致，以便于查找相关内容，并能够确定在 GoCV 中为额外的 OpenCV 图像滤波器、算法和其他功能添加支持的位置。

例如，OpenCV 的 videoio 模块（位于 https://github.com/opencv/opencv/tree/master/modules/videoio）的封装可以在 GoCV 包的 videoio.* 文件中找到。

本项目受到最初的 https://github.com/go-opencv/go-opencv 项目、博客文章 https://medium.com/@peterleyssens/using-opencv-3-from-golang-5510c312a3c 以及仓库 https://github.com/sensorbee/opencv 的启发——在此向所有贡献者表示感谢！

许可证

本项目采用 Apache 2.0 许可证授权。版权所有 © 2017–2026 The Hybrid Group。

Logo 由 GopherizeMe 生成 - https://gopherize.me

GoCV 快速上手指南

GoCV 是为 Go 语言提供的 OpenCV 4 计算机视觉库绑定，支持 Linux、macOS、Windows 及 Docker 环境，并可选支持 CUDA 加速和 Intel OpenVINO。

环境准备

系统要求

• Go 版本：最新稳定版
• OpenCV 版本：必须安装 OpenCV 4.12.0
• 操作系统：Linux、macOS、Windows 或 Docker

前置依赖

在使用 GoCV 之前，必须先在其操作系统上编译并安装匹配版本的 OpenCV。由于国内网络环境，建议参考以下方案：

• Linux/macOS/Windows：请访问官方安装指南页面获取详细步骤（需自行解决 OpenCV 源码下载加速问题）：
  • Linux: https://gocv.io/getting-started/linux/
  • macOS: https://gocv.io/getting-started/macos/
  • Windows: https://gocv.io/getting-started/windows/
• Docker：推荐使用官方提供的 Docker 镜像，可避免本地编译 OpenCV 的繁琐过程：https://gocv.io/getting-started/docker/

注意：GoCV 本身不包含 OpenCV 二进制文件，必须确保系统中已正确安装 pkg-config 能找到的 OpenCV 库。

安装步骤

确保 OpenCV 4.12.0 安装完成后，使用 go get 命令安装 GoCV 包：

go get -u gocv.io/x/gocv

验证安装是否成功，可以运行版本检测工具：

go run -mod=mod gocv.io/x/gocv/cmd/version/main.go

如果输出显示了 Go 版本、OpenCV 版本以及目标操作系统信息，则说明安装成功。

基本使用

示例：读取摄像头画面 (Hello, Video)

以下是最简单的示例，打开默认摄像头（设备 0），读取视频帧并在窗口中显示。

package main

import (
	"gocv.io/x/gocv"
)

func main() {
	webcam, _ := gocv.OpenVideoCapture(0)
	window := gocv.NewWindow("Hello")
	img := gocv.NewMat()

	for {
		webcam.Read(&img)
		window.IMShow(img)
		window.WaitKey(1)
	}
}

运行说明：

1. 将代码保存为 main.go。
2. 确保摄像头已连接。
3. 运行程序：go run main.go。
4. 按任意键关闭窗口退出。

重要提示：内存管理

GoCV 中的 Mat 对象底层由 C 代码分配内存，Go 的垃圾回收器无法自动释放。因此，所有创建的 Mat 对象必须手动调用 .Close() 方法，否则会导致内存泄漏。在生产环境中，请配合 defer 使用：

img := gocv.NewMat()
defer img.Close()