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_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二进制文件的路径（在OpenCV使用cmake的发现过程中使用）。如果未设置，则将使用“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 三联组，请参阅 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、通过Chocolatey安装Windows OpenCV、通过vcpkg安装Windows 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()