Crate cv_convert

Data conversion among computer vision libraries.

Usage

No crates are enabled by default. You must specify which computer vision libraries you want to use as features when adding cv-convert to your project.

[dependencies.cv-convert]
version = 'x.y.z'
default-features = false
features = [
    'image',
    'opencv',
    'tch',
    'nalgebra',
    'ndarray',
    'imageproc',
]

Available Features

Library features:

• image - Enable image crate support
• imageproc - Enable imageproc crate support
• nalgebra - Enable nalgebra crate support
• ndarray - Enable ndarray crate support
• opencv - Enable opencv crate support
• tch - Enable tch crate support

Documentation feature:

• docs-only - Used for documentation generation only

Traits

The trait ToCv provides .to_cv() method for infallible conversions, and TryToCv provides .try_to_cv() method for fallible conversions. Just like std’s Into and TryInto traits.

use cv_convert::{ToCv, TryToCv};
use nalgebra as na;
use opencv as cv;

// ToCv - infallible conversion
let cv_point = cv::core::Point2d::new(1.0, 3.0);
let na_point: na::Point2<f64> = cv_point.to_cv();

// ToCv - the other direction
let na_point = na::Point2::<f64>::new(1.0, 3.0);
let cv_point: cv::core::Point2d = na_point.to_cv();

// TryToCv - fallible conversion
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 = na_mat.try_to_cv().unwrap();

// TryToCv - the other direction
let cv_mat = cv::core::Mat::from_slice_2d(&[&[1.0, 2.0, 3.0], &[4.0, 5.0, 6.0]]).unwrap();
let na_mat: na::DMatrix<f64> = cv_mat.try_to_cv().unwrap();

Supported conversions

The notations are used for simplicity.

• S -> T suggests the conversion is defined by non-fallible ToCv.
• S ->? T suggests the conversion is defined by fallible TryToCv.
• (&)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 tch;

Modules

prelude

Structs

TchTensorAsImage

An 2D image Tensor with dimension order.

TensorAsArray

A wrapper for a borrowed array reference from a tensor.

Enums

TchTensorImageShape

Describes the image channel order of a Tensor.

Traits

AsRefCv

ToCv

Type conversion that is analogous to Into.

TryAsRefCv

TryToCv

Fallible type conversion that is analogous to TryInto.