Multi-Camera Calibration

APIs for computing the relative poses of multiple Zivid cameras so their point clouds can be merged into a single coordinate frame. See Multi-Camera Calibration Tutorial for the full tutorial.

        %%{init: {'themeVariables': {'fontSize': '18px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 35}}}%%
flowchart LR
  subgraph detect [For each camera]
    Camera
    detectOp(["detectCalibrationBoard()"])
    DetectionResult
    Camera -.-> detectOp --> DetectionResult
  end

  calibrateOp(["calibrateMultiCamera()"])
  MultiCameraOutput
  transformsOp(["transforms()"])
  residualsOp(["residuals()"])
  Matrix4x4["[Matrix4x4]"]
  MultiCameraResidual["[MultiCameraResidual]"]

  DetectionResult -.-> calibrateOp --> MultiCameraOutput
  MultiCameraOutput --> transformsOp --> Matrix4x4
  MultiCameraOutput --> residualsOp --> MultiCameraResidual

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class Camera,DetectionResult,MultiCameraOutput,Matrix4x4,MultiCameraResidual zividClass
  class detectOp,calibrateOp,transformsOp,residualsOp api

detectCalibrationBoard

Detect the Zivid calibration board in a frame from each camera. Collect one DetectionResult per camera (primary camera first) before calling calibrateMultiCamera.

See detectCalibrationBoard on the Hand-Eye Calibration page for the full API.

calibrateMultiCamera

Computes a transform for each camera that maps its points into the coordinate frame of the primary camera (index 0).

C++

MultiCameraOutput Zivid::Calibration::calibrateMultiCamera(const std::vector<DetectionResult> &detectionResults)

Performs multi-camera calibration.

Multi-camera calibration is used in a multi-camera setup to find the pose of secondary cameras in the frame of a designated primary camera, e.g. to combine points clouds into a single frame of reference.

The input is generated by imaging the same checkerboard from each camera and inserting the resulting frame into Zivid::Calibration::detectCalibrationBoard(const Zivid::Frame &frame). Add the resulting DetectionResult objects to a vector with the first element corresponding to the primary camera.

The returned object contains a vector of transforms, which provides the pose of camera[i] in the frame of camera[0]. Apply transform[i] to the points from camera[i] to get the same points in the frame of camera[0]. The returned object also contains a vector of residuals corresponding to each transform.

Parameters:: detectionResults – Vector of DetectionResult instances.
Returns:: A MultiCameraOutput instance.

C#

class Calibrator

Public Static Functions

static MultiCameraOutput ^ CalibrateMultiCamera (System::Collections::Generic::IEnumerable< DetectionResult ^> ^ detectionResults)

Performs multi-camera calibration.

Multi-camera calibration is used in a multi-camera setup to find the pose of secondary cameras in the frame of a designated primary camera, e.g. to combine points clouds into a single frame of reference.

The input is generated by imaging the same calibration board from each camera and inserting the resulting point clouds into Detector. Add the resulting DetectionResult objects to a sequence with the first element corresponding to the primary camera.

The returned object contains an array of transforms, which provides the pose of camera[i] in the frame of camera[0]. Apply transform[i] to the points from camera[i] to get the same points in the frame of camera[0]. The returned object also contains an array of residuals corresponding to each transform.

Parameters:: detectionResults – List of DetectionResult instances
Returns:: Instance of MultiCameraOutput

Python

zivid.calibration.calibrate_multi_camera(detection_results) — see Multi-Camera Calibration Tutorial.

MultiCameraOutput

Result of a multi-camera calibration. Provides a vector of 4×4 transform matrices (one per camera, identity for the primary) and corresponding residuals.

C++

class MultiCameraOutput

The results from a multi-camera calibration process.

Public Functions

MultiCameraOutput(const std::vector<Matrix4x4> &transforms, const std::vector<MultiCameraResidual> &residuals)

Constructs a MultiCameraOutput instance.

Parameters:

transforms – Vector of transforms for each camera.
residuals – Vector of multi-camera residuals for each camera.

bool valid() const

Test if MultiCameraOutput is valid.

Returns:: True if MultiCameraOutput is valid.

explicit operator bool() const

Test if MultiCameraOutput is valid.

Returns:: True if MultiCameraOutput is valid.

const std::vector<Matrix4x4> &transforms() const

Multi-camera calibration transforms.

Returns:: Vector of affine transformations in the form of 4x4 matrices.

const std::vector<MultiCameraResidual> &residuals() const

Multi-camera calibration residuals.

The residuals provide a measure of the overlap error that can be expected when transforming point clouds to the coordinate system of the primary camera.

The residual for each camera is calculated by applying each transform to the corresponding feature points used in the calibration process. The points are then compared with the feature points of the primary camera, and the average error between the two is calculated. By definition the first residual will therefore always be zero.

Returns:: Vector of multi-camera calibration residuals.

std::string toString() const

Get string representation of the multi-camera calibration output.

Returns:: Calibration output as string

C#

class MultiCameraOutput

Public Functions

bool Valid()

Test if MultiCameraOutput is valid.

Returns:: True if MultiCameraOutput is valid

cli::array< ManagedArray2D ^> ^ Transforms ()

Multi-camera calibration transforms.

Returns:: Array of affine transformations in the form of 4x4 matrices.

cli::array< MultiCameraResidual ^> ^ Residuals ()

Multi-camera calibration residuals.

The residuals provide a measure of the overlap error that can be expected when transforming point clouds to the coordinate system of the primary camera.

The residual for each camera is calculated by applying each transform to the corresponding feature points used in the calibration process. The points are then compared with the feature points of the primary camera, and the average error between the two is calculated. By definition the first residual will therefore always be zero.

Returns:: Array of multi-camera calibration residuals.

System::String ^ ToString () override

Get string representation of the multi-camera calibration output.

Returns:: Multi-camera calibration output as string

Public Static Functions

static static operator bool (MultiCameraOutput ^ output)

Test if MultiCameraOutput is valid.

Returns:: True if MultiCameraOutput is valid

Python

zivid.calibration.MultiCameraOutput — see Multi-Camera Calibration Tutorial.

MultiCameraResidual

Per-camera overlap error in mm. The residual for the primary camera (index 0) is always zero by definition.

C++

class MultiCameraResidual

Representation of the estimated errors of a multi-camera calibration.

Public Functions

MultiCameraResidual(float translation)

Constructs a multi-camera residual instance.

Parameters:: translation – Average overlap error in millimeters.

float translation() const

Get the average overlap error.

Returns:: Average overlap error in millimeters.

std::string toString() const

Get string representation of the multi-camera residual.

Returns:: Multi-camera residual as string

C#

class MultiCameraResidual

Representaton of the estimated errors of a multi-camera calibration.

Public Functions

float Translation()

Get the average overlap error.

Returns:: Average overlap error in millimeters.

System::String ^ ToString () override

Get string representation of the multi-camera residual.

Returns:: Multi-camera residual as string

Python

zivid.calibration.MultiCameraResidual — see zivid-python.