30 releases (15 breaking)
✓ Uses Rust 2018 edition
|new 0.15.1||Jun 15, 2019|
|0.14.0||May 28, 2019|
|0.3.0||Mar 29, 2019|
|0.2.4||Dec 27, 2018|
#1 in Science
289 downloads per month
Experimental Rust bindings for OpenCV 3.
The API is usable but unstable and not very battle-tested; use at your own risk.
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.
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 keeps hold of the
passed callback argument forever. 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 (they are stored in global static
There is a plan to implement possibility to be able to free at least some of the
Although crate tries to provide ergonomic Rust interface for OpenCV, don't expect
Rust safety guarantees at this stage. It's especially true for borrow checking and
shared mutable ownership. Notable example would be
Mat which is a reference counted
object in its essence. You can own a seemingly separate
Mat in Rust terms, but
it's going to be a mutable reference to the other
Mat under the hood. Treat safety
of the crate's API as you would treat one of C++, use
clone() when needed.
The following external dependencies are required:
- OpenCV 3.4.6 (other 3.4 versions may work, but development is done against this version)
OpenCV is a complicated dependency with a lot of different configurations that can break this crate since it relies on fragile header parsing. Try these strategies in order, continuing to the next if builds with this crate fail.
if OpenCV is installed, its version can be checked with:
Install OpenCV 3.4.6. Check your platform's package manager or see the upstream OpenCV installation guides.
See the upstream guides for compiling OpenCV for your platform. Make sure to compile from the correct release tag! We recommend including opencv_contrib and configuring your build with the same flags the travis build uses:
cmake \ -DCMAKE_BUILD_TYPE=Release \ -DBUILD_PERF_TESTS=OFF \ -DBUILD_TESTS=OFF \ -DINSTALL_TESTS=OFF \ -DBUILD_DOCS=OFF \ -DBUILD_EXAMPLES=OFF \ -DBUILD_opencv_apps=ALL \ -DWITH_IPP=OFF \ -DPYTHON_EXECUTABLE=OFF \ -DINSTALL_PYTHON_EXAMPLES=OFF \ -DWITH_LAPACK=ON \ -DWITH_EIGEN=ON \ -DBUILD_SHARED_LIBS=ON \ -DWITH_TBB=ON \ -DOPENCV_ENABLE_NONFREE=ON \ -DCMAKE_INSTALL_PREFIX=/usr \ -DOPENCV_EXTRA_MODULES_PATH=$PATH_TO_OPENCV_CONTRIB_MODULES \ $PATH_TO_OPENCV_SRC
The following modules require contrib installed:
If you can't use OpenCV 3.4.6, the (no longer maintained)
version of this crate is known to work with OpenCV
188.8.131.52 (and probably other 2.4 versions).
This crate works following the model of python and java's OpenCV wrappers - it parses the OpenCV 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 huge
cv:: namespace. We instead made one rust module for each major
OpenCV module. So, for example, C++
in this crate.
The methods and field names have been snake_cased. Methods arguments with default value lose these default values, but they are reported in the API documentation.
Overloaded methods have been — manually — given different names.
All methods return a Result to hack around C++ exception handling.
Most of the API is covered, but for various reasons several modules are not yet implemented. If a missing module is near and dear to you, file an issue (or better, open a pull request!)
The crate itself, as imported by users, consists of generated rust
code in src 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
cargo build -vv --features buildtime_bindgen. When changing
the codegen, be sure to push changes to the generated code!
hdr_parser.py comes from OpenCV python/java generator. We've tried
not to mess too much with this file, but had to make a few changes.
gen_rust.py is initially a copy of gen_java, also from the OpenCV
generators, but it has drifted significantly from the original.
The license for the original work is MIT.
Special thanks to ttacon for yielding the crate name.