{"id":13439740,"url":"https://github.com/twistedfall/opencv-rust","last_synced_at":"2025-05-12T09:23:24.191Z","repository":{"id":30362381,"uuid":"33914894","full_name":"twistedfall/opencv-rust","owner":"twistedfall","description":"Rust bindings for OpenCV","archived":false,"fork":false,"pushed_at":"2025-04-09T02:59:41.000Z","size":23286,"stargazers_count":2152,"open_issues_count":31,"forks_count":170,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-23T15:54:59.758Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twistedfall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["twistedfall"]}},"created_at":"2015-04-14T06:32:54.000Z","updated_at":"2025-04-22T21:46:16.000Z","dependencies_parsed_at":"2023-10-20T13:40:10.705Z","dependency_job_id":"7b3c1377-35e9-437e-9be6-8ceffab66499","html_url":"https://github.com/twistedfall/opencv-rust","commit_stats":{"total_commits":1140,"total_committers":38,"mean_commits":30.0,"dds":0.1903508771929825,"last_synced_commit":"015123c0dcf619f6e7d598b684dbd5bc5cf0b0a3"},"previous_names":["kali/opencv-rust"],"tags_count":197,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twistedfall%2Fopencv-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twistedfall%2Fopencv-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twistedfall%2Fopencv-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twistedfall%2Fopencv-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twistedfall","download_url":"https://codeload.github.com/twistedfall/opencv-rust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253540659,"owners_count":21924523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T03:01:16.707Z","updated_at":"2025-05-11T08:36:21.987Z","avatar_url":"https://github.com/twistedfall.png","language":"Rust","readme":"# Rust OpenCV bindings\n\n[![Build status](https://github.com/twistedfall/opencv-rust/workflows/opencv-rust/badge.svg)](https://github.com/twistedfall/opencv-rust/actions/workflows/opencv-rust.yml)\n[![Documentation](https://docs.rs/opencv/badge.svg)](https://docs.rs/opencv)\n[![Package](https://img.shields.io/crates/v/opencv.svg)](https://crates.io/crates/opencv)\n\nRust bindings for the popular [OpenCV](https://opencv.org/) computer vision library.\n\nThe API is usable, but unstable and not very battle-tested; use at your own risk.\n\n[Changelog](https://github.com/twistedfall/opencv-rust/blob/master/CHANGES.md) |\n[Troubleshooting](https://github.com/twistedfall/opencv-rust/blob/master/TROUBLESHOOTING.md) |\n[Support the project](https://github.com/sponsors/twistedfall)\n\n## Quickstart\n\nMake sure the supported OpenCV version (3.4, 4.x or 5.x) and Clang (part of LLVM, needed for automatic binding\ngeneration) are installed in your system.\n\nUpdate your Cargo.toml\n\n```toml\nopencv = \"0.94.4\"\n```\n\nImport prelude\n\n```rust\nuse opencv::prelude::*;\n```\n\n## Getting OpenCV\n\nSee [INSTALL.md](https://github.com/twistedfall/opencv-rust/blob/master/INSTALL.md) for instructions on how to install required\nsystem dependencies.\n\n## Troubleshooting\n\nSee [TROUBLESHOOTING.md](https://github.com/twistedfall/opencv-rust/blob/master/TROUBLESHOOTING.md) for some common issues and\ntheir solutions.\n\n## Environment variables\n\nThe following variables must be set when building without `pkg_config`, `cmake` or `vcpkg`. You can set them\non any platform, the specified values will override those automatically discovered.\n\n* `OPENCV_LINK_LIBS`\n  Comma separated list of library names to link to. `.lib`, `.so` or `.dylib` extension is optional. For every\n  library you can specify optional \"dylib=\", \"static=\" or \"framework=\" prefix to indicate the specific type.\n  E.g. \"opencv_world411\", \"framework=OpenCL\".\n\n  If this list starts with '+' (plus sign) then the specified items will be appended to whatever the system\n  probe returned. E.g. a value of \"+dc1394\" will do a system discovery of the OpenCV library and its linked\n  libraries and then will additionally link `dc1394` library at the end. Can be useful if the system probe\n  produces a mostly working setup, but has incomplete link list, or the order is wrong (especially important\n  during static linking).\n\n* `OPENCV_LINK_PATHS`\n  Comma separated list of paths to search for libraries to link. E.g. \"C:\\tools\\opencv\\build\\x64\\vc15\\lib\".\n  The path list can start with '+', see `OPENCV_LINK_LIBS` for a detailed explanation (e.g.\n  \"+/usr/local/lib\").\n\n* `OPENCV_INCLUDE_PATHS`\n  Comma separated list of paths to search for system include files during compilation. E.g.\n  \"C:\\tools\\opencv\\build\\include\". One of the directories specified therein must contain\n  \"opencv2/core/version.hpp\" or \"core/version.hpp\" file, it's used to detect the version of the headers.\n  The path list can start with '+', see `OPENCV_LINK_LIBS` for a detailed explanation (e.g.\n  \"+/opt/cuda/targets/x86_64-linux/include/\").\n\nThe following variables are rarely used, but you might need them under some circumstances:\n\n* `OPENCV_PACKAGE_NAME`\n  In some cases you might want to override the pkg-config, cmake or vcpkg package name, you can use this\n  environment variable for that. If you set it pkg-config will expect to find the file with that name and `.pc`\n  extension in the package directory. Cmake will look for that file with `.cmake` extension. And vcpkg will use\n  that name to try to find package in `packages` directory under `VCPKG_ROOT`. You can also use separate\n  environment variables to set different package names for different package systems:\n\t* `OPENCV_PKGCONFIG_NAME`\n\t* `OPENCV_CMAKE_NAME`\n\t* `OPENCV_VCPKG_NAME`\n\n* `OPENCV_CMAKE_BIN`\n  Path to cmake binary (used in OpenCV discovery process using cmake). If not set then just \"cmake\" will be\n  used. For example, you can set something like \"/usr/local/bin/cmake\" here.\n\n* `OPENCV_DISABLE_PROBES`\n  Comma separated list of OpenCV package auto-discovery systems to exclude from running. Might be useful if\n  one of the higher priority systems is producing incorrect results. Can contain the following values:\n\t* environment - reads data only from the `OPENCV_LINK_LIBS`, `OPENCV_LINK_PATHS` and `OPENCV_INCLUDE_PATHS`\n\t  environment variables\n\t* pkg_config\n\t* cmake\n\t* vcpkg_cmake - like vcpkg, but only uses vcpkg for path discovery, the actual OpenCV probe is done using\n\t  cmake (cmake related environment variables are applicable with this probe)\n\t* vcpkg\n\n* `OPENCV_MSVC_CRT`\n  Allows selecting the CRT library when building with MSVC for Windows. Allowed values are `\"static\"` for `/MT`\n  and `\"dynamic\"` for `/MD`.\n\nThe following variables affect the building the of the `opencv` crate, but belong to external components:\n\n* `PKG_CONFIG_PATH`\n  Where to look for `*.pc` files see the [man pkg-config](https://linux.die.net/man/1/pkg-config)\n  Path specified here must contain `opencv.pc` (pre OpenCV 4) or `opencv4.pc` (OpenCV 4 and later).\n\n* `VCPKG_ROOT`, `VCPKGRS_DYNAMIC` and `VCPKGRS_TRIPLET`\n  The root of `vcpkg` installation, flag allowing use of `*.dll` libraries and selected `vcpkg` triplet, see the\n  [documentation for `vcpkg` crate](https://docs.rs/vcpkg)\n\n* `OpenCV_DIR`\n  The directory that contains OpenCV package cmake files. Usually there are `OpenCVConfig.cmake`,\n  `OpenCVConfig-version.cmake` and `OpenCVModules.cmake` in it.\n\n* `LD_LIBRARY_PATH`\n  On Linux it sets the list of directories to look for the installed `*.so` files during runtime.\n  [Linux documentation](https://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html) has more info.\n  Path specified here must contain `libopencv_*.so` files.\n\n* `DYLD_LIBRARY_PATH` and `DYLD_FALLBACK_LIBRARY_PATH`\n  Similar to `LD_LIBRARY_PATH`, but for loading `*.dylib` files on macOS, see [man dyld](https://man.cx/dyld(1))\n  and [this SO answer](https://stackoverflow.com/a/3172515) for more info. Path specified here must contain\n  `*.dylib` files.\n\n* `PATH`\n  Windows searches for `*.dll`s in `PATH` among other places, be sure to set it up, or copy required OpenCV\n  `*.dll`s next to your binary. Be sure to specify paths in UNIX style (/C/Program Files/Dir) because colon\n  in `PATH` might be interpreted as the entry separator. Summary [here](https://stackoverflow.com/a/6546427).\n\n* `OPENCV_CLANG_ARGS`\n  Allow custom arguments for generating and parsing code with clang, see\n  the [documentation for clang arguments](https://docs.rs/clang/latest/clang/struct.Parser.html#method.arguments).\n\n* clang crate environment variables\n  See crate's [README](https://github.com/KyleMayes/clang-sys/blob/master/README.md#environment-variables)\n\n## Cargo features\n\n* There is a feature named after each OpenCV module (e.g. `imgproc`, `highgui`, etc.). They are all enabled by\n  default, but if a corresponding module is not found then it will silently be ignored. If you need to select a\n  specific set of modules be sure to disable the default features and provide the required feature set:\n  ```\n  opencv = { version = ..., default-features = false, features = [\"calib3d\", \"features2d\", \"flann\"]}\n  ```\n* `clang-runtime` - enables the runtime detection of libclang (`runtime` feature of `clang-sys`). Useful as a\n  workaround for when your dependencies (like `bindgen`) pull in `clang-sys` with hard `runtime` feature.\n* `rgb` - allow using [`rgb`](https://crates.io/crates/rgb) crate types as `Mat` elements\n* `f16` - add intergration with `f16` type from the `half` crate\n\n## API details\n\n[API Documentation](https://docs.rs/opencv) is automatically translated from OpenCV's doxygen docs. Most\nlikely you'll still want to refer to the official [OpenCV C++ documentation](https://docs.opencv.org/master)\nas well.\n\n### OpenCV version support\n\nThe following OpenCV versions are supported at the moment:\n\n* 3.4\n* 4.x\n* 5.x (preliminary)\n\n### Minimum rustc version (MSRV)\n\nCurrently, Rust version 1.77.0 or later is required. General policy is that rust version from 1 year ago is supported.\nBumping versions older than that is not considered a breaking change.\n\n### Platform support\n\nCurrently, the main development and testing of the crate is performed on Linux, but other major platforms are\nalso supported: macOS and Windows.\n\nFor some more details please refer to the CI build scripts:\n[Linux OpenCV install](https://github.com/twistedfall/opencv-rust/blob/master/ci/install-ubuntu.sh),\n[macOS OpenCV install as framework](https://github.com/twistedfall/opencv-rust/blob/master/ci/install-macos-framework.sh),\n[macOS OpenCV install via brew](https://github.com/twistedfall/opencv-rust/blob/master/ci/install-macos-brew.sh),\n[Windows OpenCV install via Chocolatey](https://github.com/twistedfall/opencv-rust/blob/master/ci/install-windows-chocolatey.sh),\n[Windows OpenCV install via vcpkg](https://github.com/twistedfall/opencv-rust/blob/master/ci/install-windows-vcpkg.sh),\n[Test runner script](https://github.com/twistedfall/opencv-rust/blob/master/ci/script.sh).\n\n### Functionality\n\nGenerally the crate tries to only wrap OpenCV API and provide some convenience functions\nto be able to use it in Rust easier. We try to avoid adding any functionality besides\nthat.\n\n### Errors\n\nMost functions return a `Result` to expose a potential C++ exception. Although some methods like property reads\nor functions that are marked CV_NOEXCEPT in the OpenCV headers are infallible and return a naked value.\n\n### CV_MAKETYPE\n\n`CV_MAKETYPE` and related `CV_MAT_DEPTH` constant functions are available to replace the corresponding OpenCV macros.\nYet it's usually easier to call `::opencv_type()` function on the corresponding Rust type. E.g.:\n\n```rust\nlet t = u16::opencv_type(); // equivalent to CV_MAKETYPE(CV_16U, 1)\nlet t = Vec2f::opencv_type(); // equivalent to CV_MAKETYPE(CV_32F, 2)\n```\n\n### C++ operators\n\nSome C++ operators are supported, they are converted to the corresponding functions on Rust side. Here is the\nlist with the corresponding function name:\n\n* `[]` → `get()` or `get_mut()`\n* `+`, `-` → `add()`, `sub()`\n* `*`, `/` → `mul()`, `div()`\n* `()` (function call) → `apply()`\n* `=` → `set()`\n* `*` (deref) → `try_deref()` or `try_deref_mut()`\n* `==`, `!=` → `equals()`, `not_equals()`\n* `\u003e`, `\u003e=` → `greater_than()`, `greater_than_or_equal()`\n* `\u003c`, `\u003c=` → `less_than()`, `less_than_or_equal()`\n* `++`, `--` → `incr()`, `decr()`\n* `\u0026`, `|`, `^` → `and()`, `or()`, `xor()`\n* `!` → `negate()`\n\n### Class fields\n\nFields of OpenCV classes are accessible through setters and getters. Those functions are infallible, they\nreturn the value directly instead of `Result`.\n\n### Infallible functions\n\nFor infallible functions (like setters) that accept `\u0026str` values the following logic applies: if a Rust\nstring passed as argument contains null byte then this string will be truncated up to that null byte. So if\nfor example you pass \"123\\0456\" to the setter, the property will be set to \"123\".\n\n### Callbacks\n\nSome API functions accept callbacks, e.g. `set_mouse_callback`. While currently it's possible to successfully\nuse those functions there are some limitations to keep in mind. Current implementation of callback handling\nleaks the passed callback argument. That means that the closure used as a callback will never be freed during\nthe lifetime of a program and moreover Drop will not be called for it. There is a plan to implement possibility\nto be able to free at least some closures.\n\n### Unsafety\n\nAlthough the crate tries to provide an ergonomic Rust interface for OpenCV, don't expect\nRust safety guarantees at this stage. It's especially true for the borrow-checking and the\nshared mutable ownership. Notable example would be `Mat` which is a reference counted\nobject in its essence. You can own a seemingly separate `Mat` in Rust terms, but\nit's going to be a mutable reference to the other `Mat` under the hood. Treat safety\nof the crate's API as you would treat one of C++, use `clone()` when needed.\n\n## Contrib modules\n\nTo be able to use some modules you need to have [`opencv_contrib`](https://github.com/opencv/opencv_contrib)\ninstalled. You can find the full list of contrib modules [here](https://github.com/opencv/opencv_contrib/tree/master/modules).\n\n## Missing modules and functions\n\nWhile most of the API is covered, for various reasons (that might no longer hold) there are modules and\nfunctions that are not yet implemented. If a missing module/function is near and dear to you, please file an\nissue (or better, open a pull request!).\n\n## The binding strategy\n\nThis crate works similar to the model of python and java's OpenCV wrappers - it uses libclang to parse the\nOpenCV C++ headers, generates a C interface to the C++ API, and wraps the C interface in Rust.\n\nAll the major modules in the C++ API are merged together in a huge `cv::` namespace. We instead made one rust\nmodule for each major OpenCV module. So, for example, C++ `cv::Mat` is `opencv::core::Mat` in this crate.\n\nThe methods and field names have been snake_cased. Methods arguments with default value lose these default\nvalues, but they are reported in the API documentation.\n\nOverloaded methods have been mostly manually given different names or automatically renamed to *_1, *_2, etc.\n\n## Older OpenCV branches support\n\n### OpenCV 2\n\nIf you can't use OpenCV 3.x or higher, the (no longer maintained) `0.2.4` version of this crate is known to\nwork with OpenCV `2.4.7.13` (and probably other 2.4 versions). Please refer to the README.md file for that\nversion because the crate has gone through the considerable rewrite since.\n\n### OpenCV 3.2\n\nThe last version with confirmed OpenCV 3.2 support is 0.75.0, after that this branch of OpenCV is no longer\ntested and supported. Since version 0.94.0 the support of OpenCV 3.2 is removed from the codebase.\n\n## Contributor's Guide\n\nThe binding generator code lives in a separate crate under [binding-generator](binding-generator). During the\nbuild phase it creates bindings from the header files and puts them into [bindings](bindings) directory. Those\nare then transferred to [src](src) for the consumption by the crate users.\n\nThe crate itself, as imported by users, consists of generated rust code in [src](src) committed to the repo.\nThis way, users don't have to handle the code generation overhead in their builds. When developing this crate,\nyou can test changes to the binding generation using `cargo build -vv`. When changing the `binding-generator`,\nbe sure to push changes to the generated code!\n\nIf you're looking for things to improve be sure to search for `todo` and `fixme` labels in the project\nsource, those usually carry the comment of what exactly needs to be fixed.\n\nThe license for the original work is [MIT](https://opensource.org/licenses/MIT).\n\nSpecial thanks to [ttacon](https://github.com/ttacon) for yielding the crate name.\n","funding_links":["https://github.com/sponsors/twistedfall"],"categories":["Libraries","库 Libraries","库","Rust","Image and Video Processing","Rust Libraries"],"sub_categories":["Image processing","图像处理 Image processing","图像处理","Who this is for"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwistedfall%2Fopencv-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwistedfall%2Fopencv-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwistedfall%2Fopencv-rust/lists"}