opencv-rust

Rust OpenCV bindings

Rust bindings for the popular OpenCV computer vision library.

The API is usable, but unstable and not very battle-tested; use at your own risk.

Changelog | Troubleshooting | Support the project

Quickstart

Make sure the supported OpenCV version (4.x or 5.x) and Clang (part of LLVM, needed for automatic binding generation) are installed in your system. OpenCV 3.4 is still supported but deprecated and will be removed in a future release.

Update your Cargo.toml

opencv = "0.100.1"

Import prelude

use opencv::prelude::*;

Getting OpenCV

See INSTALL.md for instructions on how to install required system dependencies.

Troubleshooting

See TROUBLESHOOTING.md for some common issues and their solutions.

Environment variables

The following variables must be set when building without pkg_config, cmake or vcpkg. You can set them on any platform, the specified values will override those automatically discovered.

• OPENCV_LINK_LIBS Comma separated list of library names to link to. .lib, .so or .dylib extension is optional. For every library you can specify optional "dylib=", "static=" or "framework=" prefix to indicate the specific type. E.g. "opencv_world411", "framework=OpenCL". Additionally, extensions can be used to indicate the type as well, ".a" and ".lib" for static libraries and ".framework" for macOS frameworks. E.g. "OpenCL.framework".

  If this list starts with '+' (plus sign) then the specified items will be appended to whatever the system probe returned. E.g. a value of "+dc1394" will do a system discovery of the OpenCV library and its linked libraries and then will additionally link dc1394 library at the end. Can be useful if the system probe produces a mostly working setup, but has incomplete link list, or the order is wrong (especially important during static linking).

• OPENCV_LINK_PATHS Comma separated list of paths to search for libraries to link. E.g. "C:\tools\opencv\build\x64\vc15\lib". The path list can start with '+', see OPENCV_LINK_LIBS for a detailed explanation (e.g. "+/usr/local/lib").

• OPENCV_INCLUDE_PATHS Comma separated list of paths to search for system include files during compilation. E.g. "C:\tools\opencv\build\include". One of the directories specified therein must contain "opencv2/core/version.hpp" or "core/version.hpp" file, it's used to detect the version of the headers. The path list can start with '+', see OPENCV_LINK_LIBS for a detailed explanation (e.g. "+/opt/cuda/targets/x86_64-linux/include/").

The following variables are rarely used, but you might need them under some circumstances:

• OPENCV_PACKAGE_NAME In some cases you might want to override the pkg-config, cmake or vcpkg package name, you can use this environment variable for that. If you set it pkg-config will expect to find the file with that name and .pc extension in the package directory. Cmake will look for that file with .cmake extension. And vcpkg will use that name to try to find package in packages directory under VCPKG_ROOT. You can also use separate environment variables to set different package names for different package systems:

  • OPENCV_PKGCONFIG_NAME
  • OPENCV_CMAKE_NAME
  • OPENCV_VCPKG_NAME

• OPENCV_CMAKE_BIN Path to cmake binary (used in OpenCV discovery process using cmake). If not set then just "cmake" will be used. For example, you can set something like "/usr/local/bin/cmake" here.

• OPENCV_DISABLE_PROBES Comma separated list of OpenCV package auto-discovery systems to exclude from running. Might be useful if one of the higher priority systems is producing incorrect results. Can contain the following values:

  • environment - reads data only from the OPENCV_LINK_LIBS, OPENCV_LINK_PATHS and OPENCV_INCLUDE_PATHS environment variables
  • pkg_config
  • cmake
  • vcpkg_cmake - like vcpkg, but only uses vcpkg for path discovery, the actual OpenCV probe is done using cmake (cmake related environment variables are applicable with this probe)
  • vcpkg

• OPENCV_MSVC_CRT Allows selecting the CRT library when building with MSVC for Windows. Allowed values are "static" for /MT and "dynamic" for /MD.

• OPENCV_CMAKE_TOOLCHAIN_FILE Path to a cmake toolchain file to be used during OpenCV discovery. Useful when cross-compiling. This will pass -DCMAKE_TOOLCHAIN_FILE=<value> to cmake command line.

• OPENCV_CMAKE_ARGS Additional arguments to be passed to cmake during OpenCV discovery. This will be parsed according to the POSIX command line rules (e.g. quotes are supported) and passed as is to cmake.

The following variables affect the building the of the opencv crate, but belong to external components:

• PKG_CONFIG_PATH Where to look for *.pc files see the man pkg-config Path specified here must contain opencv.pc (pre OpenCV 4) or opencv4.pc (OpenCV 4 and later).

• VCPKG_ROOT, VCPKGRS_DYNAMIC and VCPKGRS_TRIPLET The root of vcpkg installation, flag allowing use of *.dll libraries and selected vcpkg triplet, see the documentation for vcpkg crate

• OpenCV_DIR The directory that contains OpenCV package cmake files. Usually there are OpenCVConfig.cmake, OpenCVConfig-version.cmake and OpenCVModules.cmake in it.

• LD_LIBRARY_PATH On Linux it sets the list of directories to look for the installed *.so files during runtime. Linux documentation has more info. Path specified here must contain libopencv_*.so files.

• DYLD_LIBRARY_PATH and DYLD_FALLBACK_LIBRARY_PATH Similar to LD_LIBRARY_PATH, but for loading *.dylib files on macOS, see man dyld and this SO answer for more info. Path specified here must contain *.dylib files.

• PATH Windows searches for *.dlls in PATH among other places, be sure to set it up, or copy required OpenCV *.dlls next to your binary. Be sure to specify paths in UNIX style (/C/Program Files/Dir) because colon in PATH might be interpreted as the entry separator. Summary here.

• OPENCV_CLANG_ARGS Allow custom arguments for generating and parsing code with clang, see the documentation for clang arguments.

• clang crate environment variables See crate's README

Cargo features

• There is a feature named after each OpenCV module (e.g. imgproc, highgui, etc.). They are all enabled by default, but if a corresponding module is not found then it will silently be ignored. If you need to select a specific set of modules be sure to disable the default features and provide the required feature set:

  opencv = { version = ..., default-features = false, features = ["calib3d", "features2d", "flann"]}
  

• clang-runtime - enables the runtime detection of libclang (runtime feature of clang-sys). Useful as a workaround for when your dependencies (like bindgen) pull in clang-sys with hard runtime feature.
• rgb - allow using rgb crate types as Mat elements
• f16 - add intergration with f16 type from the half crate

API details

API Documentation is automatically translated from OpenCV's doxygen docs. Most likely you'll still want to refer to the official OpenCV C++ documentation as well.

OpenCV version support

The following OpenCV versions are supported at the moment:

• 3.4 (deprecated, will be removed in a future release)
• 4.x
• 5.x

Minimum rustc version (MSRV)

Currently, Rust version 1.88.0 or later is required. General policy is that rust version from 1 year ago is supported. Bumping versions older than that is not considered a breaking change.

Platform support

Currently, the main development and testing of the crate is performed on Linux, but other major platforms are also supported: macOS and Windows.

For some more details please refer to the CI build scripts: Linux OpenCV install, macOS OpenCV install as framework, macOS OpenCV install via brew, Windows OpenCV install via Chocolatey, Windows OpenCV install via vcpkg, Test runner script.

Functionality

Generally the crate tries to only wrap OpenCV API and provide some convenience functions to be able to use it in Rust easier. We try to avoid adding any functionality besides that.

Errors

Most functions return a Result to expose a potential C++ exception. Although some methods like property reads or functions that are marked CV_NOEXCEPT in the OpenCV headers are infallible and return a naked value.

CV_MAKETYPE

CV_MAKETYPE and related CV_MAT_DEPTH constant functions are available to replace the corresponding OpenCV macros. Yet it's usually easier to call ::opencv_type() function on the corresponding Rust type. E.g.:

let t = u16::opencv_type(); // equivalent to CV_MAKETYPE(CV_16U, 1)
let t = Vec2f::opencv_type(); // equivalent to CV_MAKETYPE(CV_32F, 2)

C++ operators

Some C++ operators are supported, they are converted to the corresponding functions on Rust side. Here is the list with the corresponding function name:

• [] → get() or get_mut()
• +, - → add(), sub()
• *, / → mul(), div()
• () (function call) → apply()
• = → set()
• * (deref) → try_deref() or try_deref_mut()
• ==, != → equals(), not_equals()
• >, >= → greater_than(), greater_than_or_equal()
• <, <= → less_than(), less_than_or_equal()
• ++, -- → incr(), decr()
• &, |, ^ → and(), or(), xor()
• ! → negate()

Class fields

Fields of OpenCV classes are accessible through setters and getters. Those functions are infallible, they return the value directly instead of Result.

Infallible functions

For infallible functions (like setters) that accept &str values the following logic applies: if a Rust string passed as argument contains null byte then this string will be truncated up to that null byte. So if for example you pass "123\0456" to the setter, the property will be set to "123".

Callbacks

Some API functions accept callbacks, e.g. set_mouse_callback. While currently it's possible to successfully use those functions there are some limitations to keep in mind. Current implementation of callback handling leaks the passed callback argument. That means that the closure used as a callback will never be freed during the lifetime of a program and moreover Drop will not be called for it. There is a plan to implement possibility to be able to free at least some closures.

Unsafety

Although the crate tries to provide an ergonomic Rust interface for OpenCV, don't expect Rust safety guarantees at this stage. It's especially tru