Rust OpenCV 绑定

Rust 对流行的 OpenCV 计算机视觉库的绑定。

API 可用，但不稳定，未经充分测试；使用风险自负。

变更日志 | 故障排除 | 支持项目

快速入门

请确保支持的 OpenCV 版本（3.4 或 4.x）和 Clang（LLVM 的一部分，用于自动绑定生成）已安装在您的系统上。

更新 Cargo.toml

opencv = "0.92.2"

导入预定义

use opencv::prelude::*;

获取 OpenCV

有关如何安装所需系统依赖项的说明，请参阅 INSTALL.md。

故障排除

有关一些常见问题和它们的解决方案，请参阅 TROUBLESHOOTING.md。

环境变量

当使用 pkg_config、cmake 或 vcpkg 构建 OpenCV 时，必须设置以下变量。您可以在任何平台上设置它们，指定的值将覆盖自动发现的值。

• OPENCV_LINK_LIBS 连接到库的逗号分隔列表。扩展名 .lib、.so 或 .dylib 是可选的。如果您指定 ".framework" 扩展名，则构建脚本将链接 macOS 框架而不是普通共享库。例如，"opencv_world411"。

  如果此列表以“+”开头，则指定的项目将被附加到系统探测返回的内容。例如，“+dc1394”将执行OpenCV库及其链接库的系统发现，然后在末尾额外链接dc1394库。如果系统探测产生了一个基本可用的设置，但链接列表不完整，或者顺序错误（特别是在静态链接期间尤为重要），则可能很有用。

• OPENCV_LINK_PATHS 以逗号分隔的路径列表，用于搜索要链接的库。例如，“C:\tools\opencv\build\x64\vc15\lib”。路径列表可以以“+”开头，有关详细信息，请参阅OPENCV_LINK_LIBS（例如，“+/usr/local/lib”）。

• OPENCV_INCLUDE_PATHS 以逗号分隔的路径列表，用于编译期间搜索系统包含文件。例如，“C:\tools\opencv\build\include”。其中指定的目录之一必须包含“opencv2/core/version.hpp”或“core/version.hpp”文件，用于检测头文件的版本。路径列表可以以“+”开头，有关详细信息，请参阅OPENCV_LINK_LIBS（例如，“+/opt/cuda/targets/x86_64-linux/include/”）。

以下变量很少使用，但在某些情况下可能需要使用

• OPENCV_PACKAGE_NAME 在某些情况下，您可能希望覆盖pkg-config、cmake或vcpkg的包名，您可以使用此环境变量来做到这一点。如果设置了它，pkg-config将期望在包目录中找到具有该名称和.pc扩展名的文件。Cmake将使用.cmake扩展名查找该文件。vcpkg将使用该名称在packages目录下尝试查找包，该目录位于VCPKG_ROOT下。您还可以使用单独的环境变量为不同的包系统设置不同的包名

  • OPENCV_PKGCONFIG_NAME
  • OPENCV_CMAKE_NAME
  • OPENCV_VCPKG_NAME

• OPENCV_CMAKE_BIN cmake二进制文件的路径（用于使用cmake进行OpenCV发现过程）。如果未设置，则仅使用“cmake”。例如，您可以将以下内容设置在这里：“/usr/local/bin/cmake”。

• OPENCV_DISABLE_PROBES 以逗号分隔的OpenCV包自动发现系统列表，排除运行。如果其中一个优先级较高的系统产生了错误的结果，则可能很有用。可以包含以下值

  • 环境 - 只从OPENCV_LINK_LIBS、OPENCV_LINK_PATHS和OPENCV_INCLUDE_PATHS环境变量中读取数据
  • pkg_config
  • cmake
  • vcpkg_cmake - 与vcpkg类似，但仅使用vcpkg进行路径发现，实际的OpenCV探测使用cmake进行（适用于此探测的cmake相关环境变量适用）
  • vcpkg

• OPENCV_MSVC_CRT 允许在Windows上使用MSVC构建时选择CRT库。允许的值是"static"对应于/MT，以及"dynamic"对应于/MD。

以下变量影响构建opencv crate，但属于外部组件

• PKG_CONFIG_PATH 查找*.pc文件的路径，请参阅man pkg-config。此处指定的路径必须包含opencv.pc（OpenCV 4之前）或opencv4.pc（OpenCV 4及以后版本）。

• VCPKG_ROOT、VCPKGRS_DYNAMIC 和 VCPKGRS_TRIPLET vcpkg 安装根目录，允许使用 *.dll 库和选定的 vcpkg triplet，详见 vcpkg crate 的文档

• OpenCV_DIR 包含 OpenCV 包 cmake 文件的目录。通常其中包含 OpenCVConfig.cmake、OpenCVConfig-version.cmake 和 OpenCVModules.cmake。

• LD_LIBRARY_PATH 在 Linux 上，在运行时设置查找已安装 *.so 文件的目录列表。Linux 文档 中有更多信息。此处指定的路径必须包含 libopencv_*.so 文件。

• DYLD_LIBRARY_PATH 和 DYLD_FALLBACK_LIBRARY_PATH 与 LD_LIBRARY_PATH 类似，但在 macOS 上加载 *.dylib 文件，详见 man dyld 和 此 SO 答案 以获取更多信息。此处指定的路径必须包含 *.dylib 文件。

• PATH Windows 在 PATH 中查找 *.dll，确保设置它，或者将所需的 OpenCV *.dll 复制到您的二进制文件旁边。确保以 UNIX 风格（/C/Program Files/Dir）指定路径，因为冒号在 PATH 中可能被解释为条目分隔符。更多信息请参阅 此处。

• clang crate 环境变量 请参阅 crate 的 README

Cargo 功能

• 每个 OpenCV 模块都有一个特征名称（例如 imgproc、highgui 等）。它们默认都启用，但如果找不到相应的模块，则它将被静默忽略。如果您需要选择特定的模块集，请确保禁用默认功能并提供所需的特征集

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

• rgb - 允许使用 rgb crate 类型作为 Mat 元素

API 详细信息

API 文档 自动从 OpenCV 的 doxygen 文档翻译而来。您可能仍然需要参考官方的 OpenCV C++ 文档。

OpenCV 版本支持

目前支持以下 OpenCV 版本

• 3.4
• 4.x

最小 rustc 版本（MSRV）

目前，需要 Rust 版本 1.66.0 或更高版本。一般政策是支持一年前的 rust 版本。提升比那更早的版本不被视为破坏性更改。

平台支持

目前，该 crate 的主要开发和测试是在 Linux 上进行的，但也支持其他主要平台：macOS 和 Windows。

有关更多详细信息，请参阅CI构建脚本：Linux OpenCV安装，macOS OpenCV作为框架安装，macOS通过brew安装OpenCV，Windows通过Chocolatey安装OpenCV，Windows通过vcpkg安装OpenCV，测试运行器脚本。

功能

一般来说，该包试图仅封装OpenCV API并提供一些方便的函数，以便更容易地在Rust中使用。我们试图不添加任何额外的功能。

错误

大多数函数返回一个Result以暴露潜在的C++异常。尽管一些方法（如属性读取或OpenCV头文件中标记为CV_NOEXCEPT的函数）是可靠的，并返回一个裸值。

CV_MAKETYPE

CV_MAKETYPE和相关的CV_MAT_DEPTH常量函数可用于替换相应的OpenCV宏。但通常在相应的Rust类型上调用::opencv_type()函数更简单。例如。

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++运算符

支持一些C++运算符，它们被转换为Rust侧的相应函数。以下是相应的函数名称列表

• [] → get()或get_mut()
• +，- → add()，sub()
• *，/ → mul()，div()
• ()（函数调用）→ apply()
• = → set()
• *（解引用）→ try_deref()或try_deref_mut()
• ==，!= → equals()，not_equals()
• >，>= → greater_than()，greater_than_or_equal()
• <, <= → less_than(), less_than_or_equal()
• ++, -- → incr(), decr()
• &, |, ^ → and(), or(), xor()
• ! → negate()

类字段

OpenCV 类的字段可以通过设置器和获取器访问。这些函数是可靠的，它们直接返回值而不是 Result。

可靠的函数

对于接受 &str 值的可靠函数（例如设置器），以下逻辑适用：如果作为参数传递的 Rust 字符串包含空字节，则该字符串将截断到该空字节。因此，如果您将 "123\0456" 传递给设置器，该属性将设置为 "123"。

回调

某些 API 函数接受回调，例如 set_mouse_callback。虽然目前可以使用这些函数，但需要注意一些限制。当前回调处理的实现会泄漏传递的回调参数。这意味着用作回调的闭包在整个程序的生命周期内将不会被释放，并且此外不会为其调用 Drop。有一个计划来实现能够释放至少一些闭包的可能性。

不安全性

尽管该软件包试图为 OpenCV 提供一个符合人体工程学的 Rust 接口，但在这个阶段不要期望 Rust 安全保证。这尤其适用于借用检查和共享可变所有权。一个显著的例子是 Mat，它本质上是一个引用计数的对象。在 Rust 术语中，您可以拥有一个看似独立的 Mat，但在底层它将成为对另一个 Mat 的可变引用。将此软件包的 API 安全性视为您对待 C++ 的方式一样，在需要时使用 clone()。

贡献模块

要使用某些模块，您需要安装 opencv_contrib。您可以在 这里 找到贡献模块的完整列表。

缺失的模块和函数

尽管 API 的大部分都已覆盖，但由于各种原因（可能不再成立），还有一些模块和函数尚未实现。如果您特别关心缺失的模块/函数，请提交一个问题（或者更好的，提交一个 pull request）！

绑定策略

此软件包的工作方式类似于 python 和 java 的 OpenCV 包装器模型 - 它使用 libclang 解析 OpenCV C++ 头文件，生成 C 接口到 C++ API，并使用 Rust 包装 C 接口。

C++ API中的所有主要模块都合并到了一个庞大的cv::命名空间中。我们为每个主要的OpenCV模块创建了一个Rust模块。例如，C++中的cv::Mat在这个crate中是opencv::core::Mat。

方法和字段名称已被转换为snake_case。具有默认值的方法参数会失去这些默认值，但在API文档中进行了说明。

重载的方法大多数已被手动赋予不同的名称或自动重命名为*_1, *_2等。

支持较老的OpenCV分支

OpenCV 2

如果你不能使用OpenCV 3.x或更高版本，已知（不再维护）的该crate的0.2.4版本可以与OpenCV 2.4.713（以及其他2.4版本）一起工作。请参阅README.md文件了解该版本，因为自那时以来crate已经进行了相当大的重写。

OpenCV 3.2

支持OpenCV 3.2的最后一个版本是0.75.0，之后这个OpenCV分支不再进行测试和支持。尽管如此，它可能仍然可以工作。

贡献者指南

绑定生成器代码位于binding-generator下的单独crate中。在构建阶段，它从头文件创建绑定并将它们放入bindings目录。然后，它们被转移到src供crate用户使用。

用户导入的crate本身由src中的生成Rust代码组成，并提交到仓库。这样，用户不需要在构建中处理代码生成开销。在开发此crate时，您可以使用cargo build -vv测试绑定生成的更改。当更改binding-generator时，请确保将更改推送到生成的代码！

如果您正在寻找可以改进的内容，请确保在项目源代码中搜索todo和fixme标签，这些通常包含需要修复的确切内容的注释。

原始作品的许可证为MIT。

特别感谢ttacon为crate名称让步。