Repository files navigation

Rust bindings for the popularOpenCV computer vision library.

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

Changelog |Troubleshooting |Support the project

Make sure the supported OpenCV version (3.4, 4.x or 5.x) and Clang (part of LLVM, needed for automatic bindinggeneration) are installed in your system.

Update your Cargo.toml

opencv ="0.95.0"

Import prelude

use opencv::prelude::*;

SeeINSTALL.md for instructions on how to install requiredsystem dependencies.

SeeTROUBLESHOOTING.md for some common issues andtheir solutions.

The following variables must be set when building withoutpkg_config,cmake orvcpkg. You can set themon any platform, the specified values will override those automatically discovered.

• OPENCV_LINK_LIBSComma separated list of library names to link to..lib,.so or.dylib extension is optional. For everylibrary you can specify optional "dylib=", "static=" or "framework=" prefix to indicate the specific type.E.g. "opencv_world411", "framework=OpenCL".

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

• OPENCV_LINK_PATHSComma 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 '+', seeOPENCV_LINK_LIBS for a detailed explanation (e.g."+/usr/local/lib").

• OPENCV_INCLUDE_PATHSComma 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 '+', seeOPENCV_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_NAMEIn some cases you might want to override the pkg-config, cmake or vcpkg package name, you can use thisenvironment variable for that. If you set it pkg-config will expect to find the file with that name and.pcextension in the package directory. Cmake will look for that file with.cmake extension. And vcpkg will usethat name to try to find package inpackages directory underVCPKG_ROOT. You can also use separateenvironment variables to set different package names for different package systems:

  • OPENCV_PKGCONFIG_NAME
  • OPENCV_CMAKE_NAME
  • OPENCV_VCPKG_NAME

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

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

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

• OPENCV_MSVC_CRTAllows selecting the CRT library when building with MSVC for Windows. Allowed values are"static" for/MTand"dynamic" for/MD.

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

• PKG_CONFIG_PATHWhere to look for*.pc files see theman pkg-configPath specified here must containopencv.pc (pre OpenCV 4) oropencv4.pc (OpenCV 4 and later).

• VCPKG_ROOT,VCPKGRS_DYNAMIC andVCPKGRS_TRIPLETThe root ofvcpkg installation, flag allowing use of*.dll libraries and selectedvcpkg triplet, see thedocumentation forvcpkg crate

• OpenCV_DIRThe directory that contains OpenCV package cmake files. Usually there areOpenCVConfig.cmake,OpenCVConfig-version.cmake andOpenCVModules.cmake in it.

• LD_LIBRARY_PATHOn 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 containlibopencv_*.so files.

• DYLD_LIBRARY_PATH andDYLD_FALLBACK_LIBRARY_PATHSimilar toLD_LIBRARY_PATH, but for loading*.dylib files on macOS, seeman dyldandthis SO answer for more info. Path specified here must contain*.dylib files.

• PATHWindows searches for*.dlls inPATH 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 coloninPATH might be interpreted as the entry separator. Summaryhere.

• OPENCV_CLANG_ARGSAllow custom arguments for generating and parsing code with clang, seethedocumentation for clang arguments.

• clang crate environment variablesSee crate'sREADME

• There is a feature named after each OpenCV module (e.g.imgproc,highgui, etc.). They are all enabled bydefault, but if a corresponding module is not found then it will silently be ignored. If you need to select aspecific 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 ofclang-sys). Useful as aworkaround for when your dependencies (likebindgen) pull inclang-sys with hardruntime feature.
• rgb - allow usingrgb crate types asMat elements
• f16 - add intergration withf16 type from thehalf crate

API Documentation is automatically translated from OpenCV's doxygen docs. Mostlikely you'll still want to refer to the officialOpenCV C++ documentationas well.

The following OpenCV versions are supported at the moment:

• 3.4
• 4.x
• 5.x (preliminary)

Currently, Rust version 1.77.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.

Currently, the main development and testing of the crate is performed on Linux, but other major platforms arealso 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.

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

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

CV_MAKETYPE and relatedCV_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)

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

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

Fields of OpenCV classes are accessible through setters and getters. Those functions are infallible, theyreturn the value directly instead ofResult.

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

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

Although the crate tries to provide an ergonomic Rust interface for OpenCV, don't expectRust safety guarantees at this stage. It's especially true for the borrow-checking and theshared mutable ownership. Notable example would beMat which is a reference countedobject in its essence. You can own a seemingly separateMat in Rust terms, butit's going to be a mutable reference to the otherMat under the hood. Treat safetyof the crate's API as you would treat one of C++, useclone() when needed.

To be able to use some modules you need to haveopencv_contribinstalled. You can find the full list of contrib moduleshere.

While most of the API is covered, for various reasons (that might no longer hold) there are modules andfunctions that are not yet implemented. If a missing module/function is near and dear to you, please file anissue (or better, open a pull request!).

This crate works similar to the model of python and java's OpenCV wrappers - it uses libclang to parse theOpenCV C++ headers, generates a C interface to the C++ API, and wraps the C interface in Rust.

All the major modules in the C++ API are merged together in a hugecv:: namespace. We instead made one rustmodule for each major OpenCV module. So, for example, C++cv::Mat isopencv::core::Mat in this crate.

The methods and field names have been snake_cased. Methods arguments with default value lose these defaultvalues, but they are reported in the API documentation.

Overloaded methods have been mostly manually given different names or automatically renamed to *_1, *_2, etc.

If you can't use OpenCV 3.x or higher, the (no longer maintained)0.2.4 version of this crate is known towork with OpenCV2.4.7.13 (and probably other 2.4 versions). Please refer to the README.md file for thatversion because the crate has gone through the considerable rewrite since.

The last version with confirmed OpenCV 3.2 support is 0.75.0, after that this branch of OpenCV is no longertested and supported. Since version 0.94.0 the support of OpenCV 3.2 is removed from the codebase.

The binding generator code lives in a separate crate underbinding-generator. During thebuild phase it creates bindings from the header files and puts them intobindings directory. Thoseare then transferred tosrc for the consumption by the crate users.

The crate itself, as imported by users, consists of generated rust code insrc committed to the repo.This way, users don't have to handle the code generation overhead in their builds. When developing this crate,you can test changes to the binding generation usingcargo build -vv. When changing thebinding-generator,be sure to push changes to the generated code!

If you're looking for things to improve be sure to search fortodo andfixme labels in the projectsource, those usually carry the comment of what exactly needs to be fixed.

The license for the original work isMIT.

Special thanks tottacon for yielding the crate name.