# od-bridge
C ABI bridge for [od_opencv](https://github.com/LdDl/object-detection-opencv-rust), designed for Go CGO integration (or any language with C FFI).
Wraps ONNX Runtime inference behind flat C functions and POD (plain old data) structs for both object detection (YOLO) and face detection + recognition (YuNet + ArcFace). The header `od_bridge.h` is auto-generated by `cbindgen` on every build.
## Table of Contents
- [How it works](#how-it-works)
- [Build](#build)
- [Header generation (cbindgen)](#header-generation-cbindgen)
- [Installation](#installation)
- [C API](#c-api)
- [Types](#types)
- [Functions](#functions)
- [Face Pipeline API](#face-pipeline-api)
- [Usage from Go (CGO)](#usage-from-go-cgo)
- [Usage from Rust](#usage-from-rust)
- [Running examples](#running-examples)
- [Go examples](#go-examples)
- [Features](#features)
- [Memory management](#memory-management)
- [Why unsafe](#why-unsafe)
- [Pre-built binaries](#pre-built-binaries)
- [License](#license)
## How it works
```
Caller (Go / C / Python / ...)
-> C ABI (od_bridge.h)
-> od-bridge (Rust)
-> od_opencv
-> ONNX Runtime (CPU or CUDA)
```
The caller provides raw RGB pixels (`uint8`, HWC layout). All image preprocessing (resize, normalize, CHW transpose) happens inside ORT, so there is no CPU-side format conversion overhead.
## Build
Requires Rust 1.85+ (edition 2024).
```bash
# CPU only
cargo build --release
# With CUDA execution provider
cargo build --release --features cuda
```
Output artifacts in `target/release/`:
| `libod_bridge.so` | Dynamic linking (Linux) |
| `libod_bridge.a` | Static linking |
| `libod_bridge.rlib` | Rust-to-Rust dependency |
The C header `od_bridge.h` is generated in the crate root on every build (see below).
## Header generation (cbindgen)
The file `od_bridge.h` is not maintained by hand. It is regenerated automatically on every `cargo build` via a [build script](build.rs):
```rust
// build.rs (simplified)
cbindgen::Builder::new()
.with_crate(&crate_dir)
.with_language(cbindgen::Language::C)
.with_include_guard("OD_BRIDGE_H")
.generate()
.expect("Unable to generate C bindings")
.write_to_file("od_bridge.h");
```
`cbindgen` inspects `#[repr(C)]` structs, enums, and `extern "C"` functions in `src/lib.rs` and produces a standard C header with typedefs, function prototypes, and doc comments. If you add or change a public FFI symbol, the header updates on the next build.
The same build script also generates `od_bridge.pc` from the [od_bridge.pc.in](od_bridge.pc.in) template, substituting `@PREFIX@` and `@VERSION@` placeholders. This `.pc` file is used by `pkg-config` during installation (see below).
The `cbindgen` configuration lives in [cbindgen.toml](cbindgen.toml).
## Installation
After building, install the shared library, static library, header, and pkg-config file:
```bash
sudo mkdir -p /usr/local/include/od-bridge
sudo cp od_bridge.h /usr/local/include/od-bridge/
sudo cp target/release/libod_bridge.so /usr/local/lib/
sudo cp target/release/libod_bridge.a /usr/local/lib/
# Generate and install pkg-config file
od_bridge.pc.in | sudo tee /usr/local/lib/pkgconfig/od_bridge.pc > /dev/null
# If built with --features cuda (or tensorrt), install ORT provider libraries:
# sudo cp target/release/libonnxruntime_providers_cuda.so /usr/local/lib/
# sudo cp target/release/libonnxruntime_providers_shared.so /usr/local/lib/
# Ensure /usr/local/lib is in the linker search path (needed on some distros, e.g. Arch)
```
Verify:
```bash
# pkg-config finds the library
pkg-config --cflags --libs od_bridge
# Library is in the linker cache
After this, downstream projects can use `pkg-config` to resolve paths automatically. For example, in Go CGO:
```go
/*
#cgo pkg-config: od_bridge
#include "od_bridge.h"
*/
import "C"
```
If `pkg-config` is not available on the system, you can link manually with `-lod_bridge -lm -ldl -lpthread` and `-I/usr/local/include/od-bridge`.
### Custom prefix
By default the `.pc` file uses `/usr/local` as prefix. To change it, set `OD_BRIDGE_PREFIX` before building:
```bash
OD_BRIDGE_PREFIX=/opt/od-bridge cargo build --release
```
### Uninstall
```bash
sudo rm -f /usr/local/lib/libod_bridge.a
sudo rm -f /usr/local/lib/libonnxruntime_providers_cuda.so
sudo rm -f /usr/local/lib/libonnxruntime_providers_shared.so
sudo rm "$PC_DIR/od_bridge.pc"
sudo rm -r /usr/local/include/od-bridge
sudo ldconfig
```
## C API
### Types
```c
// Single detection result (flat POD, safe for memcpy).
typedef struct OdDetection {
int32_t bbox_x; // top-left X (pixels)
int32_t bbox_y; // top-left Y (pixels)
int32_t bbox_w; // width (pixels)
int32_t bbox_h; // height (pixels)
int32_t class_id; // zero-based class index
float confidence; // [0.0, 1.0]
} OdDetection;
// Heap-allocated array of detections. Must be freed via od_detections_free().
typedef struct OdDetections {
OdDetection *data; // pointer to first element (NULL if count == 0)
int32_t len; // number of elements
} OdDetections;
// Error codes.
typedef enum OdError {
Ok = 0,
InvalidArgument = 1,
ModelLoadFailed = 2,
DetectionFailed = 3,
ImageConvertFailed = 4,
} OdError;
```
### Functions
| `od_model_create(path, w, h)` | default | Load ONNX model (CPU). Returns `ModelHandle*` or `NULL`. |
| `od_model_create_cuda(path, w, h)` | `cuda` | ONNX model with CUDA execution provider. |
| `od_model_create_tensorrt(path, w, h)` | `tensorrt` | ONNX model with TensorRT execution provider. |
| `od_model_create_trt(engine_path)` | `trt` | Serialized TensorRT engine (no input dims needed). |
| `od_model_create_rknn(path, num_classes)` | `rknn` | RKNN model for Rockchip NPU. |
| `od_model_free(handle)` | default | Free a model handle. |
| `od_model_detect(handle, rgb, w, h, conf, nms, out)` | default | Run inference (any backend). Fills `OdDetections`. |
| `od_detections_free(detections)` | default | Free detection results. |
Face pipeline functions are documented in the [Face Pipeline API](#face-pipeline-api) section below.
See `od_bridge.h` for full signatures and doc comments.
### Face Pipeline API
Face detection (YuNet) + recognition (ArcFace) combined into a single pipeline. Same pattern as YOLO: opaque handle, flat C structs, explicit free.
#### Types
```c
typedef struct FaceDetectionResult {
float bbox_x, bbox_y, bbox_w, bbox_h; // bounding box (pixels)
float confidence; // [0.0, 1.0]
float landmarks[10]; // 5 landmarks: [x0,y0, ..., x4,y4]
float embedding[512]; // L2-normalized ArcFace embedding
} FaceDetectionResult;
typedef struct FaceDetectionResults {
FaceDetectionResult *data;
int32_t len;
} FaceDetectionResults;
```
#### Functions
| `face_pipeline_create(det, rec)` | default | Create pipeline (YuNet + ArcFace, CPU). Returns `FacePipelineHandle*` or `NULL`. |
| `face_pipeline_create_cuda(det, rec)` | `cuda` | Same with CUDA acceleration. |
| `face_pipeline_create_tensorrt(det, rec)` | `tensorrt` | Same with TensorRT acceleration. |
| `face_pipeline_aligned_size(handle)` | default | Returns expected aligned face size (read from ONNX model, e.g. 112). |
| `face_pipeline_process(handle, rgb, w, h, conf, nms, out)` | default | Detect faces + extract embeddings. Fills `FaceDetectionResults`. |
| `face_pipeline_embed(handle, rgb, size, out)` | default | Extract embedding from a pre-aligned face. |
| `face_pipeline_destroy(handle)` | default | Free pipeline handle. |
| `face_pipeline_results_free(results)` | default | Free results batch. |
## Usage from Go (CGO)
### YOLO detection
```go
/*
#cgo pkg-config: od_bridge
#include "od_bridge.h"
#include <stdlib.h>
*/
import "C"
import "unsafe"
func main() {
modelPath := C.CString("model.onnx")
defer C.free(unsafe.Pointer(modelPath))
handle := C.od_model_create(modelPath, 416, 416)
if handle == nil {
panic("failed to load model")
}
defer C.od_model_free(handle)
// rgb = []byte with width*height*3 bytes (HWC, row-major)
var out C.struct_OdDetections
rc := C.od_model_detect(
handle,
(*C.uint8_t)(unsafe.Pointer(&rgb[0])),
C.int32_t(width), C.int32_t(height),
0.3, 0.4,
&out,
)
if rc != C.Ok {
panic("detection failed")
}
defer C.od_detections_free(&out)
// read out.data[0..out.len]
}
```
### Face pipeline
```go
/*
#cgo pkg-config: od_bridge
#include "od_bridge.h"
#include <stdlib.h>
*/
import "C"
import (
"fmt"
"unsafe"
)
func main() {
det := C.CString("face_detection_yunet_2023mar.onnx")
defer C.free(unsafe.Pointer(det))
rec := C.CString("w600k_mbf.onnx")
defer C.free(unsafe.Pointer(rec))
pipeline := C.face_pipeline_create(det, rec)
if pipeline == nil {
panic("failed to create face pipeline")
}
defer C.face_pipeline_destroy(pipeline)
// Query aligned face size from the model (don't hardcode 112!)
alignedSize := C.face_pipeline_aligned_size(pipeline)
fmt.Printf("Aligned face size: %dx%d\n", alignedSize, alignedSize)
// rgb = []byte with width*height*3 bytes (HWC, row-major)
var out C.struct_FaceDetectionResults
rc := C.face_pipeline_process(
pipeline,
(*C.uint8_t)(unsafe.Pointer(&rgb[0])),
C.int32_t(width), C.int32_t(height),
0.7, 0.3,
&out,
)
if rc != C.Ok {
panic("face pipeline failed")
}
defer C.face_pipeline_results_free(&out)
// Read results: out.data[i].bbox_x, .confidence, .landmarks, .embedding
faces := unsafe.Slice(out.data, int(out.len))
for i, f := range faces {
fmt.Printf("Face #%d: conf=%.1f%% bbox=(%.1f,%.1f,%.1fx%.1f)\n",
i, f.confidence*100, f.bbox_x, f.bbox_y, f.bbox_w, f.bbox_h)
}
}
```
If od-bridge is installed system-wide (see [Installation](#installation)), `pkg-config` resolves everything automatically. Otherwise, point CGO at the build directory:
```bash
CGO_LDFLAGS="-L/path/to/od-bridge/target/release -lod_bridge -lm -ldl -lpthread" \
CGO_CFLAGS="-I/path/to/od-bridge" \
LD_LIBRARY_PATH=/path/to/od-bridge/target/release \
go run .
```
For complete, runnable Go examples see [examples_go/](examples_go/).
## Usage from Rust
The crate also produces an `rlib`, so it can be used directly from Rust without FFI overhead:
```rust
use od_bridge::*;
use std::ffi::CString;
use std::ptr;
let path = CString::new("model.onnx").unwrap();
let handle = unsafe { od_model_create(path.as_ptr(), 416, 416) };
assert!(!handle.is_null());
let mut out = OdDetections { data: ptr::null_mut(), len: 0 };
let rc = unsafe {
od_model_detect(handle, pixels.as_ptr(), w, h, 0.3, 0.4, &mut out)
};
assert_eq!(rc, OdError::Ok);
// ... use results ...
unsafe {
od_detections_free(&mut out);
od_model_free(handle);
}
```
See `examples/basics.rs`, `examples/bench.rs`, `examples/face_arcface.rs`, and `examples/face_yunet.rs` for complete examples.
## Running examples
### 1. Download test data
```bash
# YOLOv4-tiny weights and config
curl -LO https://github.com/AlexeyAB/darknet/releases/download/yolov4/yolov4-tiny.weights
curl -LO https://raw.githubusercontent.com/AlexeyAB/darknet/refs/heads/master/cfg/yolov4-tiny.cfg
# Test image
curl -LO https://raw.githubusercontent.com/AlexeyAB/darknet/refs/heads/master/data/dog.jpg
# COCO class names
curl -LO https://raw.githubusercontent.com/AlexeyAB/darknet/refs/heads/master/data/coco.names
```
All downloaded files (`*.weights`, `*.cfg`, `*.names`, `*.jpg`) are in `.gitignore`.
### 2. Convert to ONNX
The bridge works with ONNX models. Convert darknet weights using [darknet2onnx](https://github.com/LdDl/darknet2onnx).
Install darknet2onnx following the [installation guide](https://github.com/LdDl/darknet2onnx?tab=readme-ov-file#installation).
Convert:
```bash
darknet2onnx \
--cfg yolov4-tiny.cfg \
--weights yolov4-tiny.weights \
--output yolov4-tiny.onnx \
--format yolov8
```
See [darknet2onnx README](https://github.com/LdDl/darknet2onnx#readme) for all options (`--opset`, `--format yolov5|yolov8`, macOS/Windows binaries, etc.).
Prepared ONNX file is considered to be ignored by git.
### 3. Run
```bash
# Basic detection
cargo run --release --example basics -- \
--model yolov4-tiny.onnx \
--image dog.jpg \
--width 416 --height 416 \
--names coco.names
# Benchmark
cargo run --release --example bench -- \
--model yolov4-tiny.onnx \
--image dog.jpg \
--width 416 --height 416 \
--iters 100
```
If everyting is fine they you should see output like:
```
# Basic run
Image: 768x576, 1327104 bytes
Model loaded: yolov4-tiny.onnx
Detections: 3
[0] class=dog(16) conf=87.3% bbox=(136, 205, 182x337)
[1] class=truck(7) conf=80.8% bbox=(463, 79, 240x91)
[2] class=bicycle(1) conf=61.0% bbox=(72, 100, 505x379)
Done.
# Benchmark run
Model: yolov4-tiny.onnx
Image: 768x576
Warmup: 3 iters
Benchmark: 100 iters
100 iters in 1.63s
avg = 16.35 ms/frame
61.2 FPS
```
## Go examples
Complete, runnable Go examples live in [examples_go/](examples_go/):
| [yolo_detect/](examples_go/yolo_detect/) | `yolov4-tiny.onnx` | — | `dog.jpg` |
| [face_pipeline/](examples_go/face_pipeline/) | `face_detection_yunet_2023mar.onnx` | `w600k_mbf.onnx` | `arnold.jpg` |
| [face_pipeline_r50/](examples_go/face_pipeline_r50/) | `face_detection_yunet_2023mar.onnx` | `w600k_r50.onnx` | `arnold.jpg` |
| [face_yunet_nano/](examples_go/face_yunet_nano/) | `yunet_n_320_320.onnx` | `w600k_mbf.onnx` | `oscar_selfies.jpg` |
Each example has build instructions in the source file header.
## Features
### Object detection (YOLO)
| (none) | yes | `od_model_create` | ONNX Runtime, CPU |
| `cuda` | no | `od_model_create_cuda` | ONNX Runtime, CUDA EP |
| `tensorrt` | no | `od_model_create_tensorrt` | ONNX Runtime, TensorRT EP |
| `trt` | no | `od_model_create_trt` | Native TensorRT (serialized `.engine` file) |
| `rknn` | no | `od_model_create_rknn` | Rockchip RKNN NPU (`.rknn` file) |
All backends share the same `od_model_detect` / `od_model_free` / `od_detections_free` functions. The `ModelHandle` dispatches to the correct runtime internally.
Note: `od_model_create_trt` takes only `engine_path` (no input dimensions, they are baked into the engine). `od_model_create_rknn` takes `model_path` and `num_classes` instead of input dimensions.
### Face pipeline (YuNet + ArcFace)
| (none) | yes | `face_pipeline_create` | ONNX Runtime, CPU |
| `cuda` | no | `face_pipeline_create_cuda` | ONNX Runtime, CUDA EP |
| `tensorrt` | no | `face_pipeline_create_tensorrt` | ONNX Runtime, TensorRT EP |
All variants share the same `face_pipeline_process` / `face_pipeline_embed` / `face_pipeline_destroy` / `face_pipeline_results_free` functions.
## Memory management
- `od_model_create*` allocates a `ModelHandle` on the heap via `Box::into_raw`. The caller owns it and must call `od_model_free` exactly once.
- `od_model_detect` allocates the results array as a `Box<[OdDetection]>` and passes ownership to the caller via the `OdDetections` struct. The caller must call `od_detections_free` exactly once per successful detect call.
- `face_pipeline_create*` / `face_pipeline_destroy` follow the same pattern for the face pipeline handle.
- `face_pipeline_process` allocates `FaceDetectionResults`; free with `face_pipeline_results_free`.
- Passing NULL to any `_free` / `_destroy` function is a safe no-op.
- Double-free is undefined behavior.
## Why unsafe
Every public function in this crate is `unsafe extern "C"`. This is not a design choice, it is a hard requirement of the C ABI: the whole point of the crate is to expose symbols callable from C, Go, Python, or any other language via FFI. Rust's safety guarantees end at the FFI boundary because the compiler cannot verify what the caller does with raw pointers.
Specifically, `unsafe` is required here for:
- **`extern "C"` functions.** Rust 2024 edition requires `#[unsafe(no_mangle)]` and treats all `extern "C"` fn as unsafe by definition, since the caller is outside Rust's type system.
- **Raw pointer dereference.** The caller passes `*const c_char`, `*const u8`, `*mut OdDetections`, etc. Rust must trust that these point to valid memory of the correct size.
- **`Box::into_raw` / `Box::from_raw`.** Heap allocation is transferred across the FFI boundary. The Rust side gives up ownership (`into_raw`), the C side holds the pointer, and Rust reclaims it later (`from_raw`). There is no way to express this ownership transfer in safe Rust.
- **`slice::from_raw_parts`.** Building a slice from a raw pixel pointer requires trusting the caller-provided length.
All unsafe operations are confined to the FFI boundary layer. The actual inference logic inside `od_opencv` is safe Rust. The bridge does the minimum unsafe work needed to convert between C ABI conventions and Rust types.
## Pre-built binaries
Pre-built `libod_bridge.so` / `libod_bridge.a` for Linux x86_64 and aarch64 are available in [GitHub Releases](https://github.com/LdDl/od-bridge/releases). This way consumers don't need a Rust toolchain.
```bash
# Download and install (no Rust required)
./install.sh # installs to /usr/local
# ./install.sh /opt/custom # or custom prefix
```
Each release includes CPU and CUDA variants. See the [release workflow](.github/workflows/release.yml) for details.
## License
[MIT](LICENSE)