Go package for computer vision using OpenCV 4 and beyond.
Branch: master
Clone or download
deadprogram release: prepare for release 0.18.0
Signed-off-by: Ron Evans <ron@hybridgroup.com>
Latest commit 2ec65a3 Nov 28, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github docs: add a Github issue template to project May 29, 2018
cmd profile: add build tag matprofile to allow for conditional inclusion … Nov 28, 2018
contrib build: use use opencv4 file for pkg-config Nov 19, 2018
data CascadeClassifier now working Sep 20, 2017
images Adding opencv::drawKeypoints() support Jun 23, 2018
openvino Removing linking against face contrib module Nov 19, 2018
.astylerc Add astyle config Mar 15, 2018
.gitignore build: gitignore build directory Mar 25, 2018
.travis.yml profile: move MatProfile tests into separate test file so they only r… Nov 28, 2018
CHANGELOG.md release: prepare for release 0.18.0 Nov 28, 2018
CONTRIBUTING.md Add example of how to run individual test Oct 3, 2018
LICENSE.txt docs: update APache 2.0 license to include full text to make Github a… Feb 7, 2018
Makefile build: update Makefile and Windows build command file to OpenCV 4.0.0 Nov 19, 2018
README.md profile: add build tag matprofile to allow for conditional inclusion … Nov 28, 2018
ROADMAP.md Prepare for release 0.17.0 Oct 9, 2018
appveyor.yml profile: move MatProfile tests into separate test file so they only r… Nov 28, 2018
appveyor_build_opencv.cmd build: update CI to use 4.0.0 release Nov 19, 2018
calib3d.cpp Change overloaded func to single func Jun 7, 2018
calib3d.go Change overloaded func to single func Jun 7, 2018
calib3d.h Change overloaded func to single func Jun 7, 2018
calib3d_test.go core: correct CopyTo to use pointer to Mat as destination Jun 14, 2018
cgo.go build: use use opencv4 file for pkg-config Nov 19, 2018
core.cpp core: add ScaleAdd() method to Mat Oct 19, 2018
core.go profile: add build tag matprofile to allow for conditional inclusion … Nov 28, 2018
core.h core: add ScaleAdd() method to Mat Oct 19, 2018
core_test.go profile: move MatProfile tests into separate test file so they only r… Nov 28, 2018
dnn.cpp dnn: add GetPerfProfile function to Net Jun 14, 2018
dnn.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
dnn.h dnn: add GetPerfProfile function to Net Jun 14, 2018
dnn_ext.go Close images in tests. Sep 30, 2018
dnn_test.go Fix dnn tests. Nov 18, 2018
env.cmd Deprecate env scripts and update README May 27, 2018
env.sh Deprecate env scripts and update README May 27, 2018
features2d.cpp features2d: update drawKeypoints() to use new stricter enum Nov 19, 2018
features2d.go Merge branch 'dev' into feature/openvino-ie-support Jul 2, 2018
features2d.h Adding opencv::drawKeypoints() support Jun 23, 2018
features2d_test.go Close images in tests. Sep 30, 2018
gocv.go opencv: update to OpenCV version 3.4.1 Mar 4, 2018
helpers_test.go test: add some attiribution from test function Dec 26, 2017
highgui.cpp Support pkg-config via cgo directives May 26, 2018
highgui.go Support pkg-config via cgo directives May 26, 2018
highgui_gocv.h Support pkg-config via cgo directives May 26, 2018
highgui_test.go Update with dev. Nov 18, 2018
imgcodecs.cpp Added IMEncodeWithParams function Oct 3, 2018
imgcodecs.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
imgcodecs.h Added IMEncodeWithParams function Oct 3, 2018
imgcodecs_test.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
imgproc.cpp Added fitLine function Oct 4, 2018
imgproc.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
imgproc.h Added fitLine function Oct 4, 2018
imgproc_colorcodes.go opencv: update to OpenCV version 3.4.1 Mar 4, 2018
imgproc_test.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
mat_noprofile.go profile: add build tag matprofile to allow for conditional inclusion … Nov 28, 2018
mat_profile.go profile: add build tag matprofile to allow for conditional inclusion … Nov 28, 2018
matprofile_test.go profile: move MatProfile tests into separate test file so they only r… Nov 28, 2018
objdetect.cpp Astyle cpp/h files Mar 15, 2018
objdetect.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
objdetect.h Astyle cpp/h files Mar 15, 2018
objdetect_test.go Add Mat profile wrapper in other areas of the library. Nov 18, 2018
travis_build_opencv.sh build: update CI to use 4.0.0 release Nov 19, 2018
version.cpp Astyle cpp/h files Mar 15, 2018
version.go release: prepare for release 0.18.0 Nov 28, 2018
version.h Astyle cpp/h files Mar 15, 2018
version_test.go core: test that we are using 4.0.x version now Nov 19, 2018
video.cpp Astyle cpp/h files Mar 15, 2018
video.go core: use Mat* to indicate when a Mat is mutable aka an output parameter Mar 20, 2018
video.h Astyle cpp/h files Mar 15, 2018
video_test.go Close images in tests. Sep 30, 2018
videoio.cpp Return the right type and error when opening VideoCapture fails Nov 13, 2018
videoio.go Updated function documentation with information about errors. Nov 13, 2018
videoio.h Return the right type and error when opening VideoCapture fails Nov 13, 2018
videoio_test.go Return the right type and error when opening VideoCapture fails Nov 13, 2018
win_build_opencv.cmd build: update Makefile and Windows build command file to OpenCV 4.0.0 Nov 19, 2018

README.md

GoCV

GoCV

GoDoc Travis Build Status AppVeyor Build status codecov Go Report Card License

The GoCV package provides Go language bindings for the OpenCV 4 computer vision library.

The GoCV package supports the latest releases of Go and OpenCV (v4.0.0) on Linux, macOS, and Windows. We intend to make the Go language a "first-class" client compatible with the latest developments in the OpenCV ecosystem.

GoCV also supports Intel OpenVINO. Check out the OpenVINO README for more info on how to use GoCV with the Intel OpenVINO toolkit.

How to use

Hello, video

This example opens a video capture device using device "0", reads frames, and shows the video in a GUI window:

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

Face detect

GoCV

This is a more complete example that opens a video capture device using device "0". It also uses the CascadeClassifier class to load an external data file containing the classifier data. The program grabs each frame from the video, then uses the classifier to detect faces. If any faces are found, it draws a green rectangle around each one, then displays the video in an output window:

package main

import (
	"fmt"
	"image/color"

	"gocv.io/x/gocv"
)

func main() {
    // set to use a video capture device 0
    deviceID := 0

	// open webcam
	webcam, err := gocv.OpenVideoCapture(deviceID)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer webcam.Close()

	// open display window
	window := gocv.NewWindow("Face Detect")
	defer window.Close()

	// prepare image matrix
	img := gocv.NewMat()
	defer img.Close()

	// color for the rect when faces detected
	blue := color.RGBA{0, 0, 255, 0}

	// load classifier to recognize faces
	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
		}

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

		// draw a rectangle around each face on the original image
		for _, r := range rects {
			gocv.Rectangle(&img, r, blue, 3)
		}

		// show the image in the window, and wait 1 millisecond
		window.IMShow(img)
		window.WaitKey(1)
	}
}

More examples

There are examples in the cmd directory of this repo in the form of various useful command line utilities, such as capturing an image file, streaming mjpeg video, counting objects that cross a line, and using OpenCV with Tensorflow for object classification.

How to install

To install GoCV, run the following command:

go get -u -d gocv.io/x/gocv

To run code that uses the GoCV package, you must also install OpenCV 3.4.3 on your system. Here are instructions for Ubuntu, Raspian, macOS, and Windows.

Ubuntu/Linux

Installation

You can use make to install OpenCV 4.0.0 with the handy Makefile included with this repo. If you already have installed OpenCV, you do not need to do so again. The installation performed by the Makefile is minimal, so it may remove OpenCV options such as Python or Java wrappers if you have already installed OpenCV some other way.

Quick Install

The following commands should do everything to download and install OpenCV 4.0.0 on Linux:

cd $GOPATH/src/gocv.io/x/gocv
make install

If it works correctly, at the end of the entire process, the following message should be displayed:

gocv version: 0.17.0
opencv lib version: 4.0.0

That's it, now you are ready to use GoCV.

Complete Install

If you have already done the "Quick Install" as described above, you do not need to run any further commands. For the curious, or for custom installations, here are the details for each of the steps that are performed when you run make install.

Install required packages

First, you need to change the current directory to the location of the GoCV repo, so you can access the Makefile:

cd $GOPATH/src/gocv.io/x/gocv

Next, you need to update the system, and install any required packages:

make deps

Download source

Now, download the OpenCV 4.0.0 and OpenCV Contrib source code:

make download

Build

Build everything. This will take quite a while:

make build

Install

Once the code is built, you are ready to install:

make sudo_install

Verifying the installation

To verify your installation you can run one of the included examples.

First, change the current directory to the location of the GoCV repo:

cd $GOPATH/src/gocv.io/x/gocv

Now you should be able to build or run any of the examples:

go run ./cmd/version/main.go

The version program should output the following:

gocv version: 0.17.0
opencv lib version: 4.0.0

Cleanup extra files

After the installation is complete, you can remove the extra files and folders:

make clean

Cache builds

If you are running a version of Go older than v1.10 and not modifying GoCV source, precompile the GoCV package to significantly decrease your build times:

go install gocv.io/x/gocv

Custom Environment

By default, pkg-config is used to determine the correct flags for compiling and linking OpenCV. This behavior can be disabled by supplying -tags customenv when building/running your application. When building with this tag you will need to supply the CGO environment variables yourself.

For example:

export CGO_CPPFLAGS="-I/usr/local/include"
export CGO_LDFLAGS="-L/usr/local/lib -lopencv_core -lopencv_face -lopencv_videoio -lopencv_imgproc -lopencv_highgui -lopencv_imgcodecs -lopencv_objdetect -lopencv_features2d -lopencv_video -lopencv_dnn -lopencv_xfeatures2d"

Please note that you will need to run these 2 lines of code one time in your current session in order to build or run the code, in order to setup the needed ENV variables. Once you have done so, you can execute code that uses GoCV with your custom environment like this:

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

Alpine 3.7 Docker image

There is a Docker image with Alpine 3.7 that has been created by project contributor @denismakogon. You can find it located at https://github.com/denismakogon/gocv-alpine.

Raspbian

Installation

We have a special installation for the Raspberry Pi that includes some hardware optimizations. You use make to install OpenCV 4.0.0 with the handy Makefile included with this repo. If you already have installed OpenCV, you do not need to do so again. The installation performed by the Makefile is minimal, so it may remove OpenCV options such as Python or Java wrappers if you have already installed OpenCV some other way.

Quick Install

The following commands should do everything to download and install OpenCV 4.0.0 on Raspbian:

cd $GOPATH/src/gocv.io/x/gocv
make install_raspi

If it works correctly, at the end of the entire process, the following message should be displayed:

gocv version: 0.17.0
opencv lib version: 4.0.0

That's it, now you are ready to use GoCV.

macOS

Installation

You can install OpenCV 4.0.0 using Homebrew.

If you already have an earlier version of OpenCV (3.4.x) installed, you should probably remove it before installing the new version:

brew uninstall opencv

You can then install OpenCV 4.0.0:

brew install hybridgroup/tools/opencv

This new Homebrew recipe will install only OpenCV 4.0.0 without all of the Python dependencies.

pkgconfig Installation

pkg-config is used to determine the correct flags for compiling and linking OpenCV. You can install it by using Homebrew:

brew install pkgconfig

Verifying the installation

To verify your installation you can run one of the included examples.

First, change the current directory to the location of the GoCV repo:

cd $GOPATH/src/gocv.io/x/gocv

Now you should be able to build or run any of the examples:

go run ./cmd/version/main.go

The version program should output the following:

gocv version: 0.17.0
opencv lib version: 4.0.0

Cache builds

If you are running a version of Go older than v1.10 and not modifying GoCV source, precompile the GoCV package to significantly decrease your build times:

go install gocv.io/x/gocv

Custom Environment

By default, pkg-config is used to determine the correct flags for compiling and linking OpenCV. This behavior can be disabled by supplying -tags customenv when building/running your application. When building with this tag you will need to supply the CGO environment variables yourself.

For example:

export CGO_CXXFLAGS="--std=c++11"
export CGO_CPPFLAGS="-I/usr/local/Cellar/opencv/4.0.0/include"
export CGO_LDFLAGS="-L/usr/local/Cellar/opencv/4.0.0/lib -lopencv_stitching -lopencv_superres -lopencv_videostab -lopencv_aruco -lopencv_bgsegm -lopencv_bioinspired -lopencv_ccalib -lopencv_dnn_objdetect -lopencv_dpm -lopencv_face -lopencv_photo -lopencv_fuzzy -lopencv_hfs -lopencv_img_hash -lopencv_line_descriptor -lopencv_optflow -lopencv_reg -lopencv_rgbd -lopencv_saliency -lopencv_stereo -lopencv_structured_light -lopencv_phase_unwrapping -lopencv_surface_matching -lopencv_tracking -lopencv_datasets -lopencv_dnn -lopencv_plot -lopencv_xfeatures2d -lopencv_shape -lopencv_video -lopencv_ml -lopencv_ximgproc -lopencv_calib3d -lopencv_features2d -lopencv_highgui -lopencv_videoio -lopencv_flann -lopencv_xobjdetect -lopencv_imgcodecs -lopencv_objdetect -lopencv_xphoto -lopencv_imgproc -lopencv_core"

Please note that you will need to run these 3 lines of code one time in your current session in order to build or run the code, in order to setup the needed ENV variables. Once you have done so, you can execute code that uses GoCV with your custom environment like this:

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

Windows

Installation

The following assumes that you are running a 64-bit version of Windows 10.

In order to build and install OpenCV 4.0.0 on Windows, you must first download and install MinGW-W64 and CMake, as follows.

MinGW-W64

Download and run the MinGW-W64 compiler installer from https://sourceforge.net/projects/mingw-w64/?source=typ_redirect.

The latest version of the MinGW-W64 toolchain is 7.3.0, but any version from 7.X on should work.

Choose the options for "posix" threads, and for "seh" exceptions handling, then install to the default location c:\Program Files\mingw-w64\x86_64-7.3.0-posix-seh-rt_v5-rev2.

Add the C:\Program Files\mingw-w64\x86_64-7.3.0-posix-seh-rt_v5-rev2\mingw64\bin path to your System Path.

CMake

Download and install CMake https://cmake.org/download/ to the default location. CMake installer will add CMake to your system path.

OpenCV 4.0.0 and OpenCV Contrib Modules

The following commands should do everything to download and install OpenCV 4.0.0 on Windows:

chdir %GOPATH%\src\gocv.io\x\gocv
win_build_opencv.cmd

It might take up to one hour.

Last, add C:\opencv\build\install\x64\mingw\bin to your System Path.

Verifying the installation

Change the current directory to the location of the GoCV repo:

chdir %GOPATH%\src\gocv.io\x\gocv

Now you should be able to build or run any of the command examples:

go run cmd\version\main.go

The version program should output the following:

gocv version: 0.17.0
opencv lib version: 4.0.0

That's it, now you are ready to use GoCV.

Cache builds

If you are running a version of Go older than v1.10 and not modifying GoCV source, precompile the GoCV package to significantly decrease your build times:

go install gocv.io/x/gocv

Custom Environment

By default, OpenCV is expected to be in C:\opencv\build\install\include. This behavior can be disabled by supplying -tags customenv when building/running your application. When building with this tag you will need to supply the CGO environment variables yourself.

Due to the way OpenCV produces DLLs, including the version in the name, using this method is required if you're using a different version of OpenCV.

For example:

set CGO_CXXFLAGS="--std=c++11"
set CGO_CPPFLAGS=-IC:\opencv\build\install\include
set CGO_LDFLAGS=-LC:\opencv\build\install\x64\mingw\lib -lopencv_core400 -lopencv_face400 -lopencv_videoio400 -lopencv_imgproc400 -lopencv_highgui400 -lopencv_imgcodecs400 -lopencv_objdetect400 -lopencv_features2d400 -lopencv_video400 -lopencv_dnn400 -lopencv_xfeatures2d400 -lopencv_plot400 -lopencv_tracking400 -lopencv_img_hash400

Please note that you will need to run these 3 lines of code one time in your current session in order to build or run the code, in order to setup the needed ENV variables. Once you have done so, you can execute code that uses GoCV with your custom environment like this:

go run -tags customenv cmd\version\main.go

Android

There is some work in progress for running GoCV on Android using Gomobile. For information on how to install OpenCV/GoCV for Android, please see: https://gist.github.com/ogero/c19458cf64bd3e91faae85c3ac887481

See original discussion here: https://github.com/hybridgroup/gocv/issues/235

Profiling

Since memory allocations for images in GoCV are done through C based code, the go garbage collector will not clean all resources associated with a Mat. As a result, any Mat created must be closed to avoid memory leaks.

To ease the detection and repair of the resource leaks, GoCV provides a Mat profiler that records when each Mat is created and closed. Each time a Mat is allocated, the stack trace is added to the profile. When it is closed, the stack trace is removed. See the runtime/pprof documentation.

In order to include the MatProfile custom profiler, you MUST build or run your application or tests using the -tags matprofile build tag. For example:

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

You can get the profile's count at any time using:

gocv.MatProfile.Count()

You can display the current entries (the stack traces) with:

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

This can be very helpful to track down a leak. For example, suppose you have the following nonsense program:

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())
}

Running this program produces the following output:

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

We can see that this program would leak memory. As it exited, it had one Mat that was never closed. The stack trace points to exactly which line the allocation happened on (line 11, the gocv.NewMat()).

Furthermore, if the program is a long running process or if GoCV is being used on a web server, it may be helpful to install the HTTP interface )). For example:

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

This will leak a Mat once per second. You can see the current profile count and stack traces by going to the installed HTTP debug interface: http://localhost:6060/debug/pprof/gocv.io/x/gocv.Mat.

How to contribute

Please take a look at our CONTRIBUTING.md document to understand our contribution guidelines.

Then check out our ROADMAP.md document to know what to work on next.

Why this project exists

The https://github.com/go-opencv/go-opencv package for Go and OpenCV does not support any version above OpenCV 2.x, and work on adding support for OpenCV 3 had stalled for over a year, mostly due to the complexity of SWIG. That is why we started this project.

The GoCV package uses a C-style wrapper around the OpenCV 4 C++ classes to avoid having to deal with applying SWIG to a huge existing codebase. The mappings are intended to match as closely as possible to the original OpenCV project structure, to make it easier to find things, and to be able to figure out where to add support to GoCV for additional OpenCV image filters, algorithms, and other features.

For example, the OpenCV videoio module wrappers can be found in the GoCV package in the videoio.* files.

This package was inspired by the original https://github.com/go-opencv/go-opencv project, the blog post https://medium.com/@peterleyssens/using-opencv-3-from-golang-5510c312a3c and the repo at https://github.com/sensorbee/opencv thank you all!

License

Licensed under the Apache 2.0 license. Copyright (c) 2017-2018 The Hybrid Group.

Logo generated by GopherizeMe - https://gopherize.me