jeffmo / cv-rs

Rust wrapper for OpenCV (manual at this point)

cv-rs

This library primarily provides idiomatic bindings and APIs for OpenCV 3.x.

Documentation

Table of Contents

• Background
• Install
• Usage
• Contribute
• License

Background

OpenCV (Open Source Computer Vision Library: http://opencv.org) is an open-source BSD-licensed library that includes several hundreds of computer vision algorithms. It's mainly developed in C++. This library provides Rust bindings to access OpenCV functionalities. First, C bindings are created (in native folder); then Rust APIs are constructed atop. Although this manual process seems an inefficient process, it has served me well as a learning experience to both OpenCV and Rust. In terms of OpenCV API coverage, modules and functions are implemented as needed.

Please check out the documentation to see what has been ported. If you have demand for porting specific features, please open an issue, or better create a PR.

Attempts to use rust-bindgen or cpp_to_rust haven't been very successful (I probably haven't tried hard enough). There is another port opencv-rust which generates OpenCV bindings using a Python script (more automated).

Install

Before anything, make sure you have OpenCV 3 installed. If you are using windows, follow this instruction, otherwise read this Introduction to OpenCV to get started.

Then in any Rust project, add this to your Cargo.toml:

[dependencies]
cv = { git = "https://github.com/nebgnahz/cv-rs.git" }

And add this to your crate:

extern crate cv;
use cv::*;

And then, enjoy the power of OpenCV.

If you'd like to use OpenCV GPU functions, it's inside cv::cuda. Enable it with the following code in Cargo.toml:

[dependencies.cv]
git = "https://github.com/nebgnahz/cv-rs"
features = [ "cuda" ]

All possible features are listed below:

• cuda - for CUDA support, requires installed CUDA
• tesseract - for Tesseract OCR support, requires installed Tesseract

Windows

If you are using MSVC toolchain (mandatory if you want to use CUDA)

Prerequisites

• Installed git.
• Installed CMake x64 (download link).
• Installed Visual Studio 2015 (download link), VS2017 is not supported by nVidia at this moment, don't even try, it won't compile.

Installation steps

• Create directory C:\opencv.
• Copy .git and .windows folders there (you can run them from the cv-rs directory itself, but you may encounter an error that paths are too long)
• Run powershell console as administrator in c:\opencv.
• (Optional, skip these steps if you don't need CUDA)
  1. Download CUDA from official site. Choose local package.
  2. Run PowerShell -NoExit -File .\.windows\msvc_1_install_CUDA.ps1 -FileName path_to_installer (for example, C:\Users\UserName\Downloads\cuda_9.1.85_win10.exe).
• Run PowerShell -NoExit -File (.\.windows\msvc_2_build_OCV.ps1 -EnableCuda $False -Compiler vc15) (note braces). 1 stays for compilation with CUDA, 0 for compilation without it. Possible compiler values: vc14 for VS2015/vc15 for VS2017. Caution: CUDA is compatible with VS2015 only
• Wait until installation finishes. Now you have properly configured OpenCV.

If you are using GNU toolchain

Prerequisites

• Installed git.
• Installed CMake x64 (download link).
• Installed MinGW (download link). Choose architecture x86_64 during installation.

Installation steps

• Create directory C:\opencv.
• Copy .git and .windows folders there (you can run them from the cv-rs directory itself, but you may encounter an error that paths are too long)
• Run powershell console as administrator in c:\opencv.
• Run PowerShell -NoExit -File .\.windows\mingw_build_OCV.ps1 -MinGWPath "C:\Program Files\mingw-w64\x86_64-7.2.0-posix-seh-rt_v5-rev1\mingw64\bin" (your path may be different).
• Wait until installation finishes. Now you have properly configured OpenCV.

Usage

See available examples on how this library might be used.

• Display Image
• Video Capture, optional GPU code
• Face Detection
• Camshift
• HOG Detection, optional GPU code

Contribute

See the contribute file! PRs highly welcome.

You may also simply open up an issue for feature/porting request.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © Ben Zhang