Struct MultiCameraSystem

pub struct MultiCameraSystem<R: RealField + Serialize + Copy> { /* private fields */ }

A calibrated multi-camera system for 3D computer vision applications.

This structure manages a collection of cameras with known intrinsic and extrinsic parameters, providing high-level operations for 3D reconstruction, triangulation, and geometric analysis. It’s the primary interface for multi-view geometry operations in the Braid system.

Core Capabilities

• 3D Triangulation: Reconstruct 3D points from 2D observations across cameras
• Reprojection Analysis: Compute and analyze reprojection errors for quality assessment
• Geometric Validation: Verify camera calibration quality and detect issues
• Format Conversion: Import/export from various camera system formats (PyMVG, etc.)

Mathematical Foundation

The system operates on the principle that multiple cameras observing the same 3D point provide redundant information that can be used to:

1. Triangulate the 3D position via geometric intersection of viewing rays
2. Validate the reconstruction by reprojecting back to all cameras
3. Optimize camera parameters through bundle adjustment

Camera Naming

Cameras are identified by string names within the system. This allows for flexible camera management and easy association of observations with specific cameras.

Example

use braid_mvg::{Camera, MultiCameraSystem, PointWorldFrame, extrinsics, make_default_intrinsics, UndistortedPixel};
use std::collections::BTreeMap;
use nalgebra::{Point3, Point2};

// Create cameras
let camera1 = Camera::new(640, 480,
    extrinsics::make_default_extrinsics::<f64>(),
    make_default_intrinsics::<f64>())?;
let camera2 = Camera::new(640, 480,
    extrinsics::make_default_extrinsics::<f64>(),
    make_default_intrinsics::<f64>())?;

// Build multi-camera system
let mut cameras = BTreeMap::new();
cameras.insert("cam1".to_string(), camera1);
cameras.insert("cam2".to_string(), camera2);
let system = MultiCameraSystem::new(cameras);

// Create observations for triangulation as slice of tuples
let observations = vec![
    ("cam1".to_string(), UndistortedPixel { coords: Point2::new(320.0, 240.0) }),
    ("cam2".to_string(), UndistortedPixel { coords: Point2::new(320.0, 240.0) }),
];

// Use for 3D triangulation
if let Ok(point_3d) = system.find3d(&observations) {
    println!("Reconstructed 3D point: {:?}", point_3d.coords);
}

Implementations

impl<R> MultiCameraSystem<R>

where R: RealField + Serialize + DeserializeOwned + Default + Copy,

pub fn to_pymvg_writer<W: Write>(&self, writer: &mut W) -> Result<()>

Export the camera system to PyMVG format via a writer.

This method serializes the multi-camera system to PyMVG JSON format, writing the result to the provided writer.

Arguments

• writer - Writer to output the PyMVG JSON data

Returns

Ok(()) on success, or MvgError if serialization fails.

pub fn from_pymvg_json<Rd: Read>(reader: Rd) -> Result<Self>

Create a multi-camera system from PyMVG JSON format.

This constructor deserializes a multi-camera system from PyMVG JSON format, reading from the provided reader.

Arguments

• reader - Reader containing PyMVG JSON data

Returns

A new MultiCameraSystem instance, or MvgError if parsing fails.

impl<R: RealField + Default + Serialize + Copy> MultiCameraSystem<R>

pub fn new(cams_by_name: BTreeMap<String, Camera<R>>) -> Self

Create a new multi-camera system from a collection of cameras.

Arguments

• cams_by_name - Map of camera names to Camera instances

Returns

A new MultiCameraSystem instance

pub fn comment(&self) -> Option<&String>

Get an optional comment describing this camera system.

Returns

Optional reference to the comment string

pub fn cams_by_name(&self) -> &BTreeMap<String, Camera<R>>

Get the collection of cameras in this system.

pub fn new_with_comment( cams_by_name: BTreeMap<String, Camera<R>>, comment: String, ) -> Self

Create a new multi-camera system with an optional comment.

Arguments

• cams_by_name - Map of camera names to Camera instances
• comment - Descriptive comment for the camera system

Returns

A new MultiCameraSystem instance

pub fn new_inner( cams_by_name: BTreeMap<String, Camera<R>>, comment: Option<String>, ) -> Self

Internal constructor for creating a multi-camera system.

Arguments

• cams_by_name - Map of camera names to Camera instances
• comment - Optional descriptive comment

Returns

A new MultiCameraSystem instance

pub fn cam_by_name(&self, name: &str) -> Option<&Camera<R>>

Get a camera by name.

Arguments

• name - Name of the camera to retrieve

Returns

Optional reference to the Camera, or None if not found

pub fn from_pymvg(pymvg_system: &PymvgMultiCameraSystemV1<R>) -> Result<Self>

Create a multi-camera system from a PyMVG data structure.

Arguments

• pymvg_system - PyMVG multi-camera system data structure

Returns

A new MultiCameraSystem instance, or MvgError if conversion fails

pub fn to_pymvg(&self) -> Result<PymvgMultiCameraSystemV1<R>>

Convert this multi-camera system to PyMVG format.

This method converts the camera system to PyMVG data structure format for interoperability with PyMVG library and JSON serialization.

Returns

A PymvgMultiCameraSystemV1 structure, or MvgError if conversion fails

Example

use braid_mvg::{MultiCameraSystem, Camera, extrinsics, make_default_intrinsics};
use std::collections::BTreeMap;

let mut cameras = BTreeMap::new();
cameras.insert("cam1".to_string(), Camera::new(640, 480,
    extrinsics::make_default_extrinsics::<f64>(),
    make_default_intrinsics::<f64>())?);
let system = MultiCameraSystem::new(cameras);
let pymvg_system = system.to_pymvg()?;

pub fn get_reprojection_undistorted_dists( &self, points: &[(String, UndistortedPixel<R>)], this_3d_pt: &PointWorldFrame<R>, ) -> Result<Vec<R>>

Find reprojection error of 3D coordinate into pixel coordinates.

Note that this returns the reprojection distance of the undistorted pixels.

pub fn find3d_and_cum_reproj_dist( &self, points: &[(String, UndistortedPixel<R>)], ) -> Result<PointWorldFrameWithSumReprojError<R>>

Find 3D coordinate and cumulative reprojection distance using pixel coordinates from cameras

pub fn find3d( &self, points: &[(String, UndistortedPixel<R>)], ) -> Result<PointWorldFrame<R>>

Find 3D coordinate using pixel coordinates from cameras

pub fn align(&self, s: R, rot: Matrix3<R>, t: Vector3<R>) -> Result<Self>

Apply a similarity transformation to all cameras in the system.

This method applies the same similarity transformation (scale, rotation, translation) to all cameras in the multi-camera system. This is commonly used for:

• Coordinate system alignment between different camera systems
• Scale recovery in structure-from-motion pipelines
• Aligning reconstructed coordinates with ground truth

Mathematical Details

The transformation applies: X' = s*R*X + t to all camera positions and orientations.

Arguments

• s - Uniform scale factor (must be positive)
• rot - 3×3 rotation matrix (must be orthogonal with determinant +1)
• t - 3×1 translation vector

Returns

A new aligned MultiCameraSystem, or MvgError if transformation fails

Errors

Returns an error if:

• The rotation matrix is invalid
• The scale factor is non-positive
• Any camera transformation fails

Example

use braid_mvg::{MultiCameraSystem, Camera, extrinsics, make_default_intrinsics};
use nalgebra::{Matrix3, Vector3};
use std::collections::BTreeMap;

let mut cameras = BTreeMap::new();
cameras.insert("cam1".to_string(), Camera::new(640, 480,
    extrinsics::make_default_extrinsics::<f64>(),
    make_default_intrinsics::<f64>())?);
let system = MultiCameraSystem::new(cameras);

let scale = 2.0;
let rotation = Matrix3::identity();
let translation = Vector3::zeros();
let aligned_system = system.align(scale, rotation, translation)?;

Trait Implementations

impl<R: Clone + RealField + Serialize + Copy> Clone for MultiCameraSystem<R>

fn clone(&self) -> MultiCameraSystem<R>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<R: Debug + RealField + Serialize + Copy> Debug for MultiCameraSystem<R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, R> Deserialize<'de> for MultiCameraSystem<R>

where R: Deserialize<'de> + RealField + Serialize + Copy,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<R: PartialEq + RealField + Serialize + Copy> PartialEq for MultiCameraSystem<R>

fn eq(&self, other: &MultiCameraSystem<R>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<R> Serialize for MultiCameraSystem<R>

where R: Serialize + RealField + Serialize + Copy,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<R: RealField + Serialize + Copy> StructuralPartialEq for MultiCameraSystem<R>