opencv-rust

The crate provides an ergonomic interface but does not provide full Rust safety guarantees regarding borrow-checking and shared mutable ownership.

Key Concept: Mat Ownership Mat is essentially a reference-counted object. You may own a Mat in Rust that is actually a mutable reference to another Mat under the hood. To ensure safety, treat the API as you would C++ and use .clone() when necessary to manage ownership correctly.

The crate uses libclang to parse OpenCV C++ headers, generates a C interface, and wraps it in Rust.

Module Mapping

While C++ uses a single large cv:: namespace, this crate organizes code into one Rust module per major OpenCV module.

• Example: C++ cv::Mat becomes opencv::core::Mat in Rust.

Naming Conventions

• Methods and fields are snake_cased.
• Method arguments that have default values in C++ do not include them in the Rust signatures (though they are documented).
• Overloaded methods are renamed using a *_1, *_2 suffix pattern.

Error Handling

Most functions return a Result to expose potential C++ exceptions. However, some methods are infallible and return a naked value (e.g., property reads or functions marked CV_NOEXCEPT in OpenCV headers).

Class Fields

Fields of OpenCV classes are accessed via getters and setters. These functions are infallible and return values directly instead of a Result.

String Truncation in Infallible Setters

For infallible setters accepting &str, if the string contains a null byte (\0), the value will be truncated at that byte. For example, passing "123\0456" will set the property to "123".

Some API functions (like set_mouse_callback) accept closures as callbacks.

Warning: The current implementation leaks the passed callback argument. Closures used as callbacks will never be freed during the program's lifetime, and their Drop implementation will not be called. Use this with caution as it can lead to memory accumulation.

To use the opencv bindings in your Rust project, ensure you have a supported OpenCV version (4.x or 5.x) and Clang (part of LLVM) installed on your system.

1. Add the dependency to your Cargo.toml:

opencv = "0.100.0"

2. Import the prelude in your Rust code to access the API:

use opencv::prelude::*;

Cross-compilation is supported, specifically for targeting Raspberry Pi from an x86-64 Linux host. The project provides a Dockerfile to simplify this setup.

Build the Cross-compilation Image

docker build -t rpi-xcompile -f tools/docker/rpi-xcompile.Dockerfile tools

Prerequisites

• qemu-arm must be present on the host system.
• binfmt-misc must be set up.
  • For Debian-based distros: Install the qemu-arm package.
  • For OpenSUSE: Install qemu-linux-user via zypper.

Once the image is built, it contains a sample build script at /usr/local/bin/cargo-xbuild which you can use to check the environment and command line arguments for cross-compiling inside the container.

Before starting, ensure your environment meets the following requirements:

Supported OpenCV Versions

• 5.x
• 4.x
• 3.4 (Deprecated; will be removed in a future release)

Minimum Rust Version (MSRV)

• rustc 1.88.0 or later is required.

Platform Support

Primary development occurs on Linux, but macOS and Windows are also supported.

The easiest way to install OpenCV on macOS is via Homebrew. If installed through Homebrew, the crate can automatically detect OpenCV, so you should not set OPENCV_LINK_LIBS, OPENCV_LINK_PATHS, or OPENCV_INCLUDE_PATHS.

Using Homebrew

brew install opencv

You will need a working C++ compiler and libclang. You can install Command Line Tools via xcode-select --install, install Xcode from the App Store, or install llvm via Brew:

brew install llvm

Required Environment Variables

Even with automatic detection, ensure the following variables are configured:

export DYLD_FALLBACK_LIBRARY_PATH="$(xcode-select --print-path)/Toolchains/XcodeDefault.xctoolchain/usr/lib/"
export LDFLAGS=-L/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib