Crate opencv_ros_camera

Geometric models of OpenCV/ROS cameras for photogrammetry

About

This crate provides a geometric model of a camera compatible with OpenCV as used by ROS (the Robot Operating System). The crate is in pure Rust, can be compiled in no_std mode, implements the IntrinsicsParameters trait from the cam-geom and provides support to read and write camera models in various formats.

In greater detail:

• Compatible with camera calibrations made by the ROS camera_calibration package, including monocular and stereo calibrations. Despite this compatibility, does not depend on ROS or OpenCV. (Furthermore, there is also no dependency on the excellent rosrust crate).
• Can be compiled without the Rust standard library or allocator to support embedded applications.
• The RosOpenCvIntrinsics type implements the IntrinsicsParameters trait from the cam-geom crate. Thus, a cam_geom::Camera can be created to handle intrinsic parameters using RosOpenCvIntrinsics and camera pose handled by the ExtrinsicParameters struct from cam-geom. (See the example below.)
• When compiled with the serde-serialize feature, read camera calibrations saved by the ROS camera_calibration/cameracalibrator.py node in ~/.ros/camera_info/camera_name.yaml with from_ros_yaml.
• When compiled with the serde-serialize feature, read and write the RosOpenCvIntrinsics struct using serde.

Example - read a ROS YAML file and create a cam_geom::Camera from it.

Let’s say we have YAML file saved by the ROS camera_calibration/cameracalibrator.py node. How can we create a cam_geom::Camera from this?

use nalgebra::{Matrix2x3, Unit, Vector3};

// Here we have the YAML file contents hardcoded in a string. Ordinarily, you
// would read this from a file such as `~/.ros/camera_info/camera_name.yaml`, but
// for this example, it is hardcoded here.
let yaml_buf = b"image_width: 659
image_height: 494
camera_name: Basler_21029382
camera_matrix:
  rows: 3
  cols: 3
  data: [516.385667640757, 0, 339.167079537312, 0, 516.125799367807, 227.37993524141, 0, 0, 1]
distortion_model: plumb_bob
distortion_coefficients:
  rows: 1
  cols: 5
  data: [-0.331416226762003, 0.143584747015566, 0.00314558656668844, -0.00393597842852019, 0]
rectification_matrix:
  rows: 3
  cols: 3
  data: [1, 0, 0, 0, 1, 0, 0, 0, 1]
projection_matrix:
  rows: 3
  cols: 4
  data: [444.369750976562, 0, 337.107817516087, 0, 0, 474.186859130859, 225.062742824321, 0, 0, 0, 1, 0]";

// The ROS YAML file does not contain the pose (no extrinsic parameters). Here we
// specify them directly. The camera is at (10,0,0), looking at (0,0,0), with up (0,0,1).
let camcenter = Vector3::new(10.0, 0.0, 0.0);
let lookat = Vector3::new(0.0, 0.0, 0.0);
let up = Unit::new_normalize(Vector3::new(0.0, 0.0, 1.0));
let pose = cam_geom::ExtrinsicParameters::from_view(&camcenter, &lookat, &up);

// We need the `serde-serialize` feature for the `from_ros_yaml` function.
#[cfg(feature = "serde-serialize")]
{
    let from_ros = opencv_ros_camera::from_ros_yaml(&yaml_buf[..]).unwrap();

    // Finally, create camera from intrinsic and extrinsic parameters.
    let camera = cam_geom::Camera::new(from_ros.intrinsics, pose);
}

testing

Test no_std compilation with:

# install target with: "rustup target add thumbv7em-none-eabihf"
cargo check --no-default-features --target thumbv7em-none-eabihf

Run unit tests with:

cargo test
cargo test --features serde-serialize

serde support requires std.

re-render README.md

cargo install cargo-readme
cargo readme > README.md

Structs

• Distortion
  Specifies distortion using the Brown-Conrady “plumb bob” model.
• NamedIntrinsicParameters
  A struct with RosOpenCvIntrinsics, camera name and image sensor dimensions.
• RosCameraInfo
  Camera calibration info as saved by ROS.
• RosMatrix
  Matrix saved by ROS.
• RosOpenCvIntrinsics
  A perspective camera model with distortion compatible with OpenCV and ROS.
• UndistortedPixels
  Undistorted 2D pixel locations

Enums

• Error
  Possible errors.
• TermCriteria
  The type defines termination criteria for iterative algorithms.

Traits

• CameraExt
  Extension trait to add world_to_undistorted_pixel() method.

Functions

• from_ros_yaml
  Construct NamedIntrinsicParameters from ROS format YAML data.

Type Aliases

• Result
  Result type