face_go

face-go

Translate to：简体中文

A face recognition library based on insightface, implemented using Go + OpenCV + ONNX Runtime, supporting cross-platform usage.

This project uses the buffalo_l model from insightface, providing face detection and feature extraction capabilities. It is suitable for identity verification, face comparison, face clustering, and similar scenarios.

Features

• Multi-platform support: macOS / Linux / Windows
• Model inference accelerated by ONNXRuntime
• Supports reading images and extracting face feature vectors
• Uses OpenCV for affine transformation alignment
• Provides a user-friendly Go interface for integration with other modules
• Usable in face comparison, face clustering, and other tasks

Dependencies

Quick Start

1. Install Dependencies

macOS (Homebrew):

brew install go opencv pkg-config

Ubuntu / Debian:

sudo apt update
sudo apt install -y golang libopencv-dev pkg-config

Windows:

Install OpenCV and add the include and lib directories to your system environment variables.

Recommended: download a precompiled version from OpenCV Releases

Download ONNX Runtime

Download and extract the official release v1.22.0: microsoft onnxruntime v1.22.0 After extraction, add the include/ and lib/ paths to your environment variables.

macOS/Linux example:

export CGO_CPPFLAGS="-I/path/to/onnxruntime/include"
export CGO_LDFLAGS="-L/path/to/onnxruntime/lib"
export DYLD_LIBRARY_PATH="/path/to/onnxruntime/lib:$DYLD_LIBRARY_PATH"  # macOS
export LD_LIBRARY_PATH="/path/to/onnxruntime/lib:$LD_LIBRARY_PATH"      # Linux

Windows notes:

Windows does not support pkg-config; you must configure OpenCV and ONNXRuntime paths manually.

set OPENCV_INC_PATH=C:\opencv\build\include
set OPENCV_LIB_PATH=C:\opencv\build\x64\mingw\lib
set CGO_CPPFLAGS=-IC:\onnxruntime\include
set CGO_LDFLAGS=-LC:\onnxruntime\lib -lopencv_core -lopencv_imgproc -lopencv_calib3d

Modify C:\opencv and C:\onnxruntime based on your actual installation paths.

Download Model

wget https://github.com/deepinsight/insightface/releases/download/v0.7/buffalo_l.zip
unzip buffalo_l.zip

Build

You need to enable CGO and link to OpenCV and ONNX Runtime based on your platform.

go build .

If the build fails, make sure CGO_CPPFLAGS, CGO_LDFLAGS, and your dynamic libraries are correctly configured and discoverable by the system.

Example

package main

import (
	facego "github.com/123cdxcc/face-go"
	"github.com/disintegration/imaging"
	"io"
	"os"
	"fmt"
    "log"
)

func main() {
	facego.InitOnnxRuntime("./onnxruntime-osx-arm64-1.22.0/lib/libonnxruntime.1.22.0.dylib")
	if err := facego.LoadOnnxModel("./buffalo_l"); err != nil {
		log.Fatal("Load model fail: ", err.Error())
	}
	defer facego.Cleanup()
	f, err := os.Open("a.jpg")
	if err != nil {
		panic(err)
	}
	faceVector, err := FeaturesInfer(f)
	if err != nil {
		return
	}
	fmt.Println(faceVector)
}

func FeaturesInfer(f io.Reader) ([]float32, error) {
	srcImg, err := imaging.Decode(f)
	if err != nil {
		return nil, err
	}
	_, kpss, err := facego.FaceDetect(srcImg)
	if err != nil {
		return nil, err
	}
	if len(kpss) == 0 {
		return nil, fmt.Errorf("no face detected")
	}
	data, _, err := facego.FaceFeatures(srcImg, kpss[0])
	if err != nil {
		return nil, err
	}
	return data, nil
}

Common Issues

dyld: Library not loaded: @rpath/libonnxruntime.dylib

Reason: macOS does not automatically read DYLD_LIBRARY_PATH when running go run generated binaries.

Solution 1:

go build -o face .
install_name_tool -add_rpath $(pwd)/onnxruntime-osx-universal2-1.12.1/lib face
./arcface

Solution 2:

When developing with GoLand or other IDEs, add the environment variables to your run configuration so you can run directly.

ld: warning: ignoring duplicate libraries: '-lopencv_core'

Reason: OpenCV libraries are linked more than once. Usually harmless.

Suggestion:

• Use pkg-config to automatically generate dependency flags instead of manually adding -lopencv_*
• Or safely ignore the warning

References

• https://github.com/microsoft/onnxruntime
• https://github.com/deepinsight/insightface
• https://github.com/jack139/arcface-go
• https://github.com/yalue/onnxruntime_go