# 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 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](#how-it-works)
- [Build](#build)
- [Header generation (cbindgen)](#header-generation-cbindgen)
- [C API](#c-api)
- [Types](#types)
- [Functions](#functions)
- [Usage from Go (CGO)](#usage-from-go-cgo)
- [Usage from Rust](#usage-from-rust)
- [Running examples](#running-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
fn main() {
let crate_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
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 `cbindgen` configuration lives in [cbindgen.toml](cbindgen.toml).
## 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. |
See `od_bridge.h` for full signatures and doc comments.
## Usage from Go (CGO)
```go
/*
#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`:
```bash
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:
```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` and `examples/bench.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
```
## Features
| (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](https://github.com/LdDl/od-bridge/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](LICENSE)