Crate cv_convert

Data conversion among computer vision libraries.

Version Selection

In the default setting, up-to-date dependencies are used. The default dependency versions are listed in [features] in cv-convert Cargo.toml.

You can manually select desired dependency versions. The choices of dependency versions are named accordingly as Cargo features. For example, the feature nalgebra_0-31 enables nalgebra 0.31.x. It allows to list crate version selections in Cargo.toml.

[dependencies.cv-convert]
version = 'x.y.z'
default-features = false
features = [
    'image_0-24',
    'opencv_0-76',
    'tch_0-10',
    'nalgebra_0-32',
    'ndarray_0-15',
]

It’s impossible to enable two or more versions for a dependency. For example, nalgebra_0-31 and nalgebra_0-32 are incompatible.

Traits

The traits FromCv and IntoCv provide .from_cv() and .into_cv(), and traits TryFromCv and TryIntoCv provide .try_from_cv() and .try_into_cv() methods respectively. Just like std’s From, Into, TryFromCv and TryIntoCv.

use cv_convert::{FromCv, IntoCv, TryFromCv, TryIntoCv};
use nalgebra as na;
use opencv as cv;

// FromCv
let cv_point = cv::core::Point2d::new(1.0, 3.0);
let na_points = na::Point2::<f64>::from_cv(&cv_point);

// IntoCv
let cv_point = cv::core::Point2d::new(1.0, 3.0);
let na_points: na::Point2<f64> = cv_point.into_cv();

// TryFromCv
let na_mat = na::DMatrix::from_vec(2, 3, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
let cv_mat = cv::core::Mat::try_from_cv(&na_mat).unwrap();

// TryIntoCv
let na_mat = na::DMatrix::from_vec(2, 3, vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
let cv_mat: cv::core::Mat = na_mat.try_into_cv().unwrap();

Supported conversions

The notations are used for simplicity.

• S -> T suggests the conversion is defined by non-fallible FromCv.
• S ->? T suggests the conversion is defined by fallible TryFromCv.
• (&)T means the type can be either owned or borrowed.
• &'a S -> &'a T suggests that the target type borrows the source type.

opencv -> opencv

• (&)Mat ->? Point_
• (&)Mat ->? Point3_
• (&)Point_ ->? Mat
• (&)Point3_ ->? Mat

std -> tch

• owned/borrowed multi-dimensional array ->? Tensor
  • (&)[T; N] ->? Tensor
  • (&)[[T; N2]; N1] ->? Tensor
  • … and so on up to 6 dimensions

tch -> std

• &’a Tensor -> &’a multi-dimensional array
  • &’a Tensor -> &’a [T; N]
  • &’a Tensor -> &’a [[T; N2]; N1]
  • … and so on up to 6 dimensions
• (&)Tensor -> owned multi-dimensional array
  • (&)Tensor ->? [T; N]
  • (&)Tensor ->? [[T; N2]; N1]
  • … and so on up to 6 dimensions

tch -> ndarray

• &Tensor ->? Array

ndarray -> tch

• &Array ->? Tensor

ndarray -> opencv

• &Array ->? Mat

image -> tch

• (&)ImageBuffer ->? TchTensorAsImage
• (&)DynamicImage ->? TchTensorAsImage

image -> opencv

• (&)ImageBuffer ->? Mat
• (&)DynamicImage ->? Mat

opencv -> image 0.23

• Mat ->? (&)ImageBuffer

opencv -> image 0.24

• Mat ->? (&)ImageBuffer
• Mat ->? (&)DynamicImage

opencv -> imageproc

• (&)Point_ -> Point

imageproc -> opencv

• (&)Point -> Point_

opencv -> nalgebra

• (&)Mat ->? OMatrix
• (&)Point_ -> Point2
• (&)Point3_ -> Point2
• (&)OpenCvPose<(&)Point3d> ->? Isometry3
• (&)OpenCvPose<(&)Mat> ->? Isometry3

nalgebra -> opencv

• (&)OMatrix ->? Mat
• (&)Point2 -> Point_
• (&)Point3 -> Point3_
• (&)Translation<N, D> ->? Mat
• (&)Isometry3 ->? OpenCvPose<Point3_>
• (&)Isometry3 ->? OpenCvPose
• (&)Isometry3 ->? OpenCvPose

opencv -> tch

• (&)Mat ->? Tensor

  The input Mat is regarded as an n-dimensional array with a m-channel elements. The output Tensor have n+1 dimensions, which last additional m-sized dimension is the channel.

• (&)Mat ->? TchTensorAsImage

  The input Mat must be a 2D image. The output Tensor within TchTensorAsImage has 3 dimensions, which last additional dimension is the channel.

• &Mat ->? OpenCvMatAsTchTensor

tch -> opencv

• (&)Tensor ->? Mat

  The n-dimensinoal input Tensor is converted to a Mat with n dimensions and a channel of size 1.

• (&)TchTensorAsImage ->? Mat

  The output Mat is a 2D image, which height, width and channel size are judged from the input TchTensorAsImage shape.

opencv -> ndarray

• &Mat ->? ArrayView
• (&)Mat ->? Array

Notes for OpenCV

For opencv older than 0.66, some systems requires clang-runtime feature to build successfully. Otherwise you will get libclang shared library is not loaded on this thread! panic. Add opencv dependency along side cv-convert in your project Cargo.toml to enable this feature.

cv-convert = { version = "0.22.0", default-features = false, features = ["opencv_0-65"] }
opencv = { version = "0.65", features = ["clang-runtime"] }

Most opencv modules, such as videoio and aruco, are disabled by default to avoid bloating. Add opencv dependency to your project Cargo.toml to enable default modules in your project.

Re-exports

pub use image_0_24 as image;

pub use nalgebra_0_32 as nalgebra;

pub use opencv_0_85 as opencv;

pub use ndarray_0_15 as ndarray;

pub use tch_0_14 as tch;

pub use imageproc_0_23 as imageproc;

Modules

prelude

Structs

OpenCvMatAsTchTensor

A Tensor which data reference borrows from a Mat. It can be dereferenced to a Tensor.

OpenCvPose

A pair of rvec and tvec from OpenCV, standing for rotation and translation.

TchTensorAsImage

An 2D image Tensor with dimension order.

Enums

TchTensorImageShape

Describes the image channel order of a Tensor.

Traits

FromCv

Type conversion that is analogous to From.

IntoCv

Type conversion that is analogous to Into.

OpenCvElement

TryFromCv

Fallible type conversion that is analogous to TryFrom.

TryIntoCv

Fallible type conversion that is analogous to TryInto.