od-bridge

C ABI bridge for od_opencv, designed for Go CGO integration (or any language with C FFI).

Wraps ONNX Runtime inference behind 5 flat C functions and POD (plain old data) structs. The header od_bridge.h is auto-generated by cbindgen on every build.

Table of Contents

• How it works
• Build
• Header generation (cbindgen)
• Installation
• C API
  • Types
  • Functions
• Usage from Go (CGO)
• Usage from Rust
• Running examples
• Features
• Memory management
• Why unsafe
• Pre-built binaries
• 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).

# CPU only
cargo build --release

# With CUDA execution provider
cargo build --release --features cuda

Output artifacts in target/release/:

File	Use case
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 (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 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.

Installation

After building, install the shared library, header, and pkg-config file:

sudo mkdir -p /usr/local/include/od-bridge
sudo cp od_bridge.h /usr/local/include/od-bridge/

PC_DIR=$(pkg-config --variable pc_path pkg-config | cut -d: -f1)
sudo cp od_bridge.pc "$PC_DIR/"

sudo cp target/release/libod_bridge.so /usr/local/lib/

# 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 (I use it btw))
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/local.conf
sudo ldconfig

Verify:

# pkg-config finds the library
pkg-config --cflags --libs od_bridge

# Library is in the linker cache
ldconfig -p | grep od_bridge

After this, downstream projects can use pkg-config to resolve paths automatically. For example, in Go CGO:

/*
#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:

OD_BRIDGE_PREFIX=/opt/od-bridge cargo build --release

Uninstall

PC_DIR=$(pkg-config --variable pc_path pkg-config | cut -d: -f1)
sudo rm /usr/local/lib/libod_bridge.so
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

// 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

Function	Feature	Description
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.

See od_bridge.h for full signatures and doc comments.

Usage from Go (CGO)

/*
#cgo LDFLAGS: -L/path/to/od-bridge/target/release -lod_bridge -lm -ldl -lpthread
#cgo CFLAGS: -I/path/to/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]
}

At runtime, set LD_LIBRARY_PATH to include the directory with libod_bridge.so:

LD_LIBRARY_PATH=/path/to/od-bridge/target/release go run .

Usage from Rust

The crate also produces an rlib, so it can be used directly from Rust without FFI overhead:

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 and examples/bench.rs for complete examples.

Running examples

1. Download test data

# 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.

Install darknet2onnx following the installation guide.

Convert:

darknet2onnx \
  --cfg yolov4-tiny.cfg \
  --weights yolov4-tiny.weights \
  --output yolov4-tiny.onnx \
  --format yolov8

See 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

# 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

Features

Feature	Default	C function added	Backend
(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.

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.
• Passing NULL to any _free 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

May be in future there will be pre-built libod_bridge.so / libod_bridge.a for Linux x86_64 in GitHub Releases. This way consumers don't need a Rust toolchain, but I don't have that much time to maintain it right now.

License

MIT