Hand-Eye Calibration

APIs for detecting calibration boards and fiducial markers, and for computing the hand-eye transformation (eye-in-hand or eye-to-hand). See How to run and integrate Zivid Hand-Eye Calibration for the full tutorial.

        %%{init: {'themeVariables': {'fontSize': '18px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 35}}}%%
flowchart TD
  subgraph collection [Stage 1: Data Collection]
    Camera
    RobotPose["Robot pose"]
    captureOp(["captureCalibrationBoard()"])
    Frame
    detectBoardOp(["detectCalibrationBoard()"])
    detectMarkersOp(["detectMarkers()"])
    DetectionResult
    DetectionResultFiducialMarkers
    HandEyeInput

    Camera --> captureOp --> Frame
    Frame --> detectBoardOp --> DetectionResult
    Frame --> detectMarkersOp --> DetectionResultFiducialMarkers
    DetectionResult -.-> HandEyeInput
    DetectionResultFiducialMarkers -.-> HandEyeInput
    RobotPose -.-> HandEyeInput
  end

  subgraph calibration [Stage 2: Calibration]
    eyeInHandOp(["calibrateEyeInHand()"])
    eyeToHandOp(["calibrateEyeToHand()"])
    HandEyeOutput
    transformOp(["transform()"])
    residualsOp(["residuals()"])
    Matrix4x4
    HandEyeResidual["[HandEyeResidual]"]

    HandEyeOutput --> transformOp --> Matrix4x4
    HandEyeOutput --> residualsOp --> HandEyeResidual
  end

  HandEyeInput -.-> eyeInHandOp --> HandEyeOutput
  HandEyeInput -.-> eyeToHandOp --> HandEyeOutput

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class Camera,RobotPose,Frame,DetectionResult,DetectionResultFiducialMarkers,HandEyeInput,HandEyeOutput,Matrix4x4,HandEyeResidual zividClass
  class captureOp,detectBoardOp,detectMarkersOp,eyeInHandOp,eyeToHandOp,transformOp,residualsOp api

captureCalibrationBoard

Captures a frame optimized for calibration board detection. Convenience alternative to a manual capture followed by detectCalibrationBoard.

C++

Frame Zivid::Calibration::captureCalibrationBoard(Zivid::Camera &camera)

Capture calibration board with the given camera.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

This function will perform a relatively slow but high-quality point cloud capture with the given camera. This function is necessary for applications that require very high-accuracy captures, such as in-field verification/correction.

The Frame that is returned from this function may be used as input to Zivid::Calibration::detectCalibrationBoard(const Zivid::Frame &frame). You may also use Zivid::Calibration::detectCalibrationBoard(Zivid::Camera &camera) directly, which will invoke this function under the hood and yield a DetectionResult.

C#

class Detector

Public Static Functions

static Frame ^ CaptureCalibrationBoard (Camera ^ camera)

Capture calibration board with the given camera.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

This function will perform a relatively slow but high-quality point cloud capture with the given camera. This function is necessary for applications that require very high-accuracy captures, such as in-field verification/correction.

The Frame that is returned from this function may be used as input to Calibration::Detector::DetectCalibrationBoard(Frame ^frame). You may also use Calibration::Detector::DetectCalibrationBoard(Camera ^camera) directly, which will invoke this function under the hood and yield a DetectionResult.

Parameters:: camera – Camera to be used to capture the calibration board

Python

zivid.calibration.capture_calibration_board(camera) — see How to run and integrate Zivid Hand-Eye Calibration.

detectCalibrationBoard

Detects the Zivid calibration board in a frame or directly from a live camera. Returns a DetectionResult with the board pose and feature points.

C++

DetectionResult Zivid::Calibration::detectCalibrationBoard(Zivid::Camera &camera)

Detects feature points from a calibration board using the given camera.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

This function will perform a relatively slow but high-quality point cloud capture with the given camera. This function is necessary for applications that require very high-accuracy DetectionResult, such as in-field verification/correction.

Parameters:: camera – Camera to be used to capture the calibration board

DetectionResult Zivid::Calibration::detectCalibrationBoard(const Frame &frame)

Detects feature points from a calibration board in a frame.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

Parameters:: frame – A frame containing an image of a calibration board

C#

class Detector

Public Static Functions

static Zivid::NET::Calibration::DetectionResult ^ DetectCalibrationBoard (Camera ^ camera)

Detects feature points from a calibration board using the given camera.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

This function will perform a relatively slow but high-quality point cloud capture with the given camera. This function is necessary for applications that require very high-accuracy DetectionResult, such as in-field verification/correction.

Parameters:: camera – Camera to be used to capture the calibration board

static Zivid::NET::Calibration::DetectionResult ^ DetectCalibrationBoard (Frame ^ frame)

Detects feature points from a calibration board in a Frame.

The functionality is to be exclusively used in combination with Zivid verified calibration boards. For further information please visit Zivid help page.

Parameters:: frame – A frame containing an image of a calibration board

Python

zivid.calibration.detect_calibration_board(frame) — see How to run and integrate Zivid Hand-Eye Calibration.

DetectionResult

Result of a calibration board detection. Provides the board pose, centroid, and feature point arrays.

C++

class DetectionResult

A result returned by the detectCalibrationBoard(…) call.

Public Functions

bool valid() const

Test if DetectionResult is valid.

DetectionResult is valid if status is OK.

Returns:: True if DetectionResult is valid.

CalibrationBoardDetectionStatus status() const

Get the status of the detection.

Returns:: The detection status.

explicit operator bool() const

Test if DetectionResult is valid.

DetectionResult is valid if all the feature points were detected.

Returns:: True if DetectionResult is valid.

std::string statusDescription() const

Get human-readable description of the status.

Useful for feedback if valid() is false.

This returns a free-form string and should not be considered API stable.

Returns:: A string which describes the detection status

PointXYZ centroid() const

Get the centroid of the detected feature points in camera-space.

If valid() is false, an exception will be thrown.

Returns:: The XYZ position of the feature point centroid.

Pose pose() const

Get position and orientation of the top left detected corner in camera coordinate system.

This is the top left inner corner as viewed from the board’s coordinate system.

Pose calculation works for official Zivid calibration boards only. An exception will be thrown if valid() is false or if the board is not supported.

For an illustration of where the origin of the pose is located, see Zivid Calibration Object.

Returns:: The XYZ position and orientation of the top left corner.

Array2D<PointXYZ> featurePoints() const

Get the detected feature points in camera-space.

Returns a 2D array of 3D coordinates representing the centers of the calibration board squares. The element at index (0,0) corresponds to the physical top-left corner of the board. The first index moves down the physical board, while the second index moves to the right. If the valid() function returns false, an exception will be thrown.

Returns:: Feature points.

Array2D<PointXY> featurePoints2D() const

Get the detected feature points in pixel-space.

Same as featurePoints(), but with 2D coordinates instead of 3D coordinates. The points are reported at subpixel accuracy. If the valid() function returns false, an exception will be thrown.

Returns:: Feature points in 2D.

std::string toString() const

Get string representation of DetectionResult.

Returns:: DetectionResult as string

C#

class DetectionResult

A result returned by the Detector.DetectCalibrationBoard(…) call.

Public Functions

bool Valid()

Test if DetectionResult is valid.

DetectionResult is valid if all the feature points were detected.

Returns:: True if DetectionResult is valid.

DetectionStatus Status(): Get detection status/validity as an enum.

System::String ^ StatusDescription (): Get a human readable description of the DetectionStatus.

Zivid::NET::PointXYZ Centroid()

Get the centroid of the detected feature points in camera-space.

If Valid() is false, an exception will be thrown.

Returns:: The XYZ position of the feature point centroid.

Zivid::NET::Calibration::Pose ^ Pose ()

Get position and orientation of the top left detected corner in camera coordinate system.

This is the top left inner corner as viewed from the board’s coordinate system.

Pose calculation works for official Zivid calibration boards only. An exception will be thrown if Valid() is false or if the board is not supported.

For an illustration of where the origin of the pose is located, see Zivid Calibration Object.

Returns:: The XYZ position and orientation of the top left corner.

DetectedPointsArray ^ FeaturePoints ()

Get the detected feature points in camera-space.

Returns a 2D array of 3D coordinates representing the centers of the calibration board squares. The element at index (0,0) corresponds to the physical top-left corner of the board. The first index moves down the physical board, while the second index moves to the right. If the Valid() function returns false, an exception will be thrown.

Returns:: Feature points.

Detected2DPointsArray ^ FeaturePoints2D ()

Get the detected feature points in pixel-space.

Same as FeaturePoints(), but with 2D coordinates instead of 3D coordinates. The points are reported at subpixel accuracy. If the Valid() function returns false, an exception will be thrown.

Returns:: Feature points in 2D.

System::String ^ ToString () override

Get string representation of DetectionResult.

Returns:: DetectionResult as string

Public Static Functions

static static operator bool (DetectionResult ^ result)

Test if DetectionResult is valid.

DetectionResult is valid if all the feature points were detected.

Returns:: True if DetectionResult is valid.

Python

zivid.calibration.DetectionResult — see How to run and integrate Zivid Hand-Eye Calibration.

detectMarkers

Detects ArUco / AprilTag fiducial markers in a frame. Use instead of detectCalibrationBoard when working with marker-based hand-eye calibration.

C++

DetectionResultFiducialMarkers Zivid::Calibration::detectMarkers(const Frame &frame, const std::vector<int> &allowedMarkerIds, const MarkerDictionary &markerDictionary)

Detects fiducial markers such as ArUco markers in a frame.

Only markers with integer IDs are supported. For further information on fiducial markers see this wikipedia page. For more information on ArUco markers specifically, refer to the OpenCV documentation. The Frame need not contain all markers listed in allowedMarkerIds for a successful detection.

Parameters:

frame – A frame containing an image of one or several fiducial markers
allowedMarkerIds – A list of the IDs of markers to be detected
markerDictionary – The marker dictionary that describes the appearance of each marker

C#

class Detector

Public Static Functions

static Zivid::NET::Calibration::DetectionResultFiducialMarkers ^ DetectMarkers (Frame ^ frame, System::Collections::Generic::IEnumerable< int > ^ allowedMarkerIds, Zivid::NET::MarkerDictionary ^ markerDictionary)

Detects fiducial markers such as ArUco markers in a frame.

Only markers with integer IDs are supported. For further information on fiducial markers see this wikipedia page. For more information on ArUco markers specifically, refer to the OpenCV documentation. The Frame need not contain all markers listed in allowedMarkerIds for a successful detection.

Parameters:

frame – A frame containing an image of one or several fiducial markers
allowedMarkerIds – A list of the IDs of markers to be detected
markerDictionary – The marker dictionary that describes the appearance of each marker

Python

zivid.calibration.detect_markers(frame, allowed_marker_ids, marker_dictionary) — see How to run and integrate Zivid Hand-Eye Calibration.

DetectionResultFiducialMarkers

Result of a fiducial marker detection. Provides a list of detected MarkerShape objects.

C++

class DetectionResultFiducialMarkers

Stores the result returned by a detectMarkers(const Frame &frame, const std::vector<int> &markerIds, const MarkerDictionary &markerDictionary) call.

Public Functions

bool valid() const

Test if the detection result is valid.

The detection result is valid if at least one of the specified markers were detected.

Returns:: True if the detection result is valid.

explicit operator bool() const

Test if the detection result is valid.

The detection result is valid if at least one of the specified markers were detected.

Returns:: True if the detection result is valid.

const std::vector<MarkerShape> &detectedMarkers() const

Get the ids of the detected fiducial markers.

Only markers belonging to the dictionary that was used at detection are reported. Furthermore markers are filtered to only include the ones with allowed ids, specified at detection. Markers can be detected multiple times if they are present on the scene multiple times. Note that even though the detection result is valid, other functions such as hand eye calibration might fail because of duplicates.

Returns:: An array of marker shapes describing the geometry of each detected marker.

const std::vector<int> &allowedMarkerIds() const

Fetch the allowed marker ids this detection result was made with.

Returns:: Allowed marker ids this detection result was made with.

std::string toString() const

Get string representation of the detection result.

Returns:: The detection result as string

C#

class DetectionResultFiducialMarkers

Stores the result returned by a DetectMarkers(…) call.

Public Functions

bool Valid()

Test if the detection result is valid.

The detection result is valid if at least one of the specified markers were detected.

Returns:: True if the detection result is valid.

cli::array< MarkerShape ^> ^ DetectedMarkers ()

Get the ids of the detected fiducial markers.

Only markers belonging to the dictionary that was used at detection are reported. Furthermore markers are filtered to only include the ones with allowed ids, specified at detection. Markers can be detected multiple times if they are present on the scene multiple times. Note that even though the detection result is valid, other functions such as hand eye calibration might fail because of duplicates.

Returns:: An array of marker shapes describing the geometry of each detected marker.

cli::array< int > ^ AllowedMarkerIds ()

Fetch the allowed marker ids this detection result was made with.

Returns:: Allowed marker ids this detection result was made with.

System::String ^ ToString () override

Get string representation of detection result.

Returns:: Detection result as string

Public Static Functions

static static operator bool (DetectionResultFiducialMarkers ^ result)

Test if the detection result is valid.

The detection result is valid if at least one of the specified markers were detected.

Returns:: True if the detection result is valid.

Python

zivid.calibration.DetectionResultFiducialMarkers — see How to run and integrate Zivid Hand-Eye Calibration.

MarkerDictionary

Identifies the fiducial marker family (e.g. ArUco 4×4, AprilTag 36h11). Pass to detectMarkers to select which markers to look for.

C++

class MarkerDictionary

Holds information about fiducial markers such as ArUco or AprilTag for detection.

For more information on ArUco markers see the OpenCV documentation on ArUco markers To get more information about fiducial markers in general, refer to the wikipedia page

Public Functions

size_t markerCount() const

Query the number of markers in the dictionary.

Returns:: The number of markers in the dictionary.

std::string toString() const: Get the string representation of the dictionary.

Public Static Functions

static MarkerDictionary fromString(const std::string &dictionaryName)

Construct a marker dictionary from the name of the dictionary.

The name should match exactly one of the built-in dictionaries of MarkerDictionary. Example: “aruco4x4_50”. An exception is thrown if the name is not recognized.

Parameters:: dictionaryName – The name of the dictionary.
Returns:: A new dictionary from the given name.

Public Static Attributes

static const MarkerDictionary aruco4x4_50: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 50.

static const MarkerDictionary aruco4x4_100: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 100.

static const MarkerDictionary aruco4x4_250: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 250.

static const MarkerDictionary aruco4x4_1000: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 1000.

static const MarkerDictionary aruco5x5_50: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 50.

static const MarkerDictionary aruco5x5_100: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 100.

static const MarkerDictionary aruco5x5_250: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 250.

static const MarkerDictionary aruco5x5_1000: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 1000.

static const MarkerDictionary aruco6x6_50: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 50.

static const MarkerDictionary aruco6x6_100: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 100.

static const MarkerDictionary aruco6x6_250: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 250.

static const MarkerDictionary aruco6x6_1000: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 1000.

static const MarkerDictionary aruco7x7_50: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 50.

static const MarkerDictionary aruco7x7_100: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 100.

static const MarkerDictionary aruco7x7_250: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 250.

static const MarkerDictionary aruco7x7_1000: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 1000.

C#

class MarkerDictionary

Holds information about fiducial markers such as ArUco markers for detection.

For more information on ArUco markers see the OpenCV documentation on ArUco markers To get more information about fiducial markers in general, refer to the wikipedia page

Public Functions

int MarkerCount()

Query the number of markers in the dictionary.

Returns:: The number of markers in the dictionary.

System::String ^ ToString () override: Get the string representation of the dictionary.

Properties

static MarkerDictionary^ Aruco4x4_50: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 50.

static MarkerDictionary^ Aruco4x4_100: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 100.

static MarkerDictionary^ Aruco4x4_250: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 250.

static MarkerDictionary^ Aruco4x4_1000: Built-in OpenCV dictionary of ArUco markers of size 4x4 with a dictionary size 1000.

static MarkerDictionary^ Aruco5x5_50: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 50.

static MarkerDictionary^ Aruco5x5_100: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 100.

static MarkerDictionary^ Aruco5x5_250: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 250.

static MarkerDictionary^ Aruco5x5_1000: Built-in OpenCV dictionary of ArUco markers of size 5x5 with a dictionary size 1000.

static MarkerDictionary^ Aruco6x6_50: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 50.

static MarkerDictionary^ Aruco6x6_100: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 100.

static MarkerDictionary^ Aruco6x6_250: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 250.

static MarkerDictionary^ Aruco6x6_1000: Built-in OpenCV dictionary of ArUco markers of size 6x6 with a dictionary size 1000.

static MarkerDictionary^ Aruco7x7_50: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 50.

static MarkerDictionary^ Aruco7x7_100: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 100.

static MarkerDictionary^ Aruco7x7_250: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 250.

static MarkerDictionary^ Aruco7x7_1000: Built-in OpenCV dictionary of ArUco markers of size 7x7 with a dictionary size 1000.

Public Static Functions

static MarkerDictionary ^ FromString (System::String^ dictionaryName)

Construct a marker dictionary from the name of the dictionary.

The name should match exactly one of the built-in dictionaries. Example: “aruco4x4_50”. An exception is thrown if the name is not recognized.

Parameters:: dictionaryName – The name of the dictionary.
Returns:: A new dictionary from the given name.

Python

zivid.calibration.MarkerDictionary — see zivid-python.

MarkerShape

A detected fiducial marker — its ID, corner points, and pose.

C++

class MarkerShape

Holds physical (3D) and image (2D) properties of a detected fiducial marker.

For more information on ArUco markers see the OpenCV documentation on ArUco markers. To get more information about fiducial markers in general, refer to the wikipedia page.

Public Functions

std::array<PointXY, 4> cornersInPixelCoordinates() const

Get 2D image coordinates of the corners of the detected marker.

Returns:: 2D image coordinates of the corners of the detected marker.

std::array<PointXYZ, 4> cornersInCameraCoordinates() const

Get 3D spatial coordinates of the corners of the detected marker.

Returns:: 3D spatial coordinates of the corners of the detected marker.

int id() const

Get the id of the detected marker.

Returns:: The id of the detected marker.

Pose pose() const

Get 3D pose of the marker.

The returned pose will be positioned at the center of the marker, and have an orientation such that its z-axis points perpendicularly into the face of the marker.

For an illustration of where the origin of the pose is located, see Zivid Calibration Object.

Returns:: The XYZ position and orientation of the marker in the form of a Pose object.

std::string toString() const

Get string representation of the marker shape.

Returns:: Marker shape as string

C#

class MarkerShape

Holds physical (3D) and image (2D) properties of a detected fiducial marker.

For more information on ArUco markers see the OpenCV documentation on ArUco markers To get more information about fiducial markers in general, refer to the wikipedia page

Public Functions

cli::array< Zivid::NET::PointXY > ^ CornersInPixelCoordinates ()

Get 2D image coordinates of the corners of the detected marker.

Returns:: 2D image coordinates of the corners of the detected marker.

cli::array< Zivid::NET::PointXYZ > ^ CornersInCameraCoordinates ()

Get 3D spatial coordinates of the corners of the detected marker.

Returns:: 3D spatial coordinates of the corners of the detected marker.

int Id()

Get the id of the detected marker.

Returns:: The id of the detected marker.

Zivid::NET::Calibration::Pose ^ Pose ()

Get 3D pose of the marker.

The returned pose will be positioned at the center of the marker, and have an orientation such that its z-axis points perpendicularly into the face of the marker.

For an illustration of where the origin of the pose is located, see Zivid Calibration Object.

Returns:: The XYZ position and orientation of the marker in the form of a Pose object.

System::String ^ ToString () override

Get string representation of MarkerShape.

Returns:: MarkerShape as string

Python

zivid.calibration.MarkerShape — see zivid-python.

Pose

A rigid transform (rotation and translation), such as a robot pose, passed to HandEyeInput.

C++

class Pose

Describes a rigid transform (rotation+translation), such as a robot pose.

Public Functions

ZIVID_UTILS_EXPORT Pose(): Default-constructs a Pose with an identity transform.

ZIVID_UTILS_EXPORT Pose(const Matrix4x4 &transform)

Pose constructor taking a 4x4 transform.

Translation part of transform should be in units of millimeters. The constructor throws if the input transform does not describe pure rotation and translation.

Parameters:: transform – Provides orientation (rotation) and location (translation) for the pose.

ZIVID_UTILS_EXPORT Matrix4x4 toMatrix () const

Converts robot pose to a 4x4 matrix.

Returns:: 4 by 4 matrix.

ZIVID_UTILS_EXPORT std::string toString () const

Get string representation of the Pose.

Returns:: Pose as string

C#

class Pose

Describes a rigid transform (rotation+translation), such as a robot pose.

Public Functions

Pose (cli::array< float > ^ poseArray)

Pose constructor taking a 4x4 transform.

Translation part of transform should be in units of millimeters. The constructor throws if the input transform does not describe pure rotation and translation.

Parameters:: poseArray – Provides orientation (rotation) and location (translation) for the pose as a flattened 1D array (row major)

Pose (ManagedArray2D ^ poseArray)

Pose constructor taking a 4x4 transform, stored in a 2D array.

The input parameter poseArray assumes that its zeroth dimension is the row index. Translation part of transform should be in units of millimeters. The constructor throws if the input transform does not describe pure rotation and translation.

Parameters:: poseArray – Provides orientation (rotation) and location (translation) for the pose as a 2D array

Pose (Matrix4x4 ^ poseMat)

Pose constructor taking a 4x4 transform matrix.

Translation part of transform should be in units of millimeters. The constructor throws if the input transform does not describe pure rotation and translation.

Parameters:: poseMat – Provides orientation (rotation) and location (translation) for the pose as a 4x4 matrix

System::String ^ ToString () override

Get string representation of the Pose.

Returns:: Pose as string

ManagedArray2D ^ ToMatrix ()

Check if the pose is disposed.

Converts robot pose to a 4x4 matrix

Returns:: 4 by 4 matrix as a 2D array

Python

zivid.calibration.Pose — see How to run and integrate Zivid Hand-Eye Calibration.

HandEyeInput

Pairs a robot pose with a DetectionResult (or DetectionResultFiducialMarkers) for one calibration position. Build one per robot pose and collect into a list before calling the calibration functions.

C++

class HandEyeInput

Binds together a robot pose and the detection result acquired from the pose.

Public Functions

HandEyeInput(const Pose &robotPose, const DetectionResult &detectionResult)

Constructs a HandEyeInput instance from a calibration board detection result.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection result. Zivid point clouds are, by default, in millimeters.

Parameters:

robotPose – Robot pose for detected feature points.
detectionResult – Calibration board detection result.

HandEyeInput(const Pose &robotPose, const DetectionResultFiducialMarkers &detectionResult)

Constructs a HandEyeInput instance from a fiducial marker detection result.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection result. Zivid point clouds are, by default, in millimeters.

Parameters:

robotPose – Robot pose for the detected markers.
detectionResult – Fiducial marker detection result.

const Pose &robotPose() const

Robot pose for the detected object(s).

Returns:: Robot pose.

const DetectionResult &detectionResult() const

Feature detection result.

Only use this function if the HandEyeInput was created from a DetectionResult object. Throws an exception otherwise.

Returns:: Detection result.

std::string toString() const

Get string representation of the hand-eye calibration input.

Returns:: Hand-eye calibration input as string.

C#

class HandEyeInput

Binds together a robot pose and the detection result acquired from the pose.

Public Functions

HandEyeInput (Zivid::NET::Calibration::Pose ^ robotPose, Zivid::NET::Calibration::DetectionResult ^ detectionResult)

Constructs a HandEyeInput instance from a calibration board detection result.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection result. Zivid point clouds are, by default, in millimeters.

Parameters:

robotPose – Robot pose for detected feature points.
detectionResult – Calibration board detection result.

HandEyeInput (Zivid::NET::Calibration::Pose ^ robotPose, Zivid::NET::Calibration::DetectionResultFiducialMarkers ^ detectionResult)

Constructs a HandEyeInput instance from a fiducial marker detection result.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection result. Zivid point clouds are, by default, in millimeters.

Parameters:

robotPose – Robot pose for the detected markers.
detectionResult – Fiducial marker detection result.

Zivid::NET::Calibration::Pose ^ RobotPose ()

Robot pose for detected feature points.

Returns:: Robot pose

Zivid::NET::Calibration::DetectionResult ^ DetectionResult ()

Feature detection result.

Only use this function if the HandEyeInput was created from a DetectionResult object. Throws an exception otherwise.

Returns:: Detection result.

System::String ^ ToString () override

Get string representation of the hand-eye calibration input.

Returns:: Hand-eye calibration input as string

Python

zivid.calibration.HandEyeInput — see How to run and integrate Zivid Hand-Eye Calibration.

calibrateEyeInHand / calibrateEyeToHand

Compute the hand-eye transformation from a list of HandEyeInput pairs. Use calibrateEyeInHand when the camera is mounted on the robot arm (moves with the arm); use calibrateEyeToHand when it is fixed in the scene.

C++

HandEyeOutput Zivid::Calibration::calibrateEyeInHand(const std::vector<HandEyeInput> &inputs)

Performs eye-in-hand calibration.

The procedure requires all robot poses to be different. At least 2 poses are required when using a calibration board, or 6 poses when using fiducial markers. For fiducial markers, each marker must be detected across 2 poses at minimum. An exception will be thrown if the preceding requirements are not fulfilled.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection results. Zivid point clouds are, by default, in millimeters.

Parameters:: inputs – Vector of HandEyeInput instances.
Returns:: Instance of HandEyeOutput.

HandEyeOutput Zivid::Calibration::calibrateEyeToHand(const std::vector<HandEyeInput> &inputs)

Performs eye-to-hand calibration.

The procedure requires all robot poses to be different. At least 2 poses are required when using a calibration board, or 6 poses when using fiducial markers. For fiducial markers, each marker must be detected across 2 poses at minimum. An exception will be thrown if the preceding requirements are not fulfilled.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection results. Zivid point clouds are, by default, in millimeters.

Parameters:: inputs – Vector of HandEyeInput instances.
Returns:: Instance of HandEyeOutput.

C#

class Calibrator

Public Static Functions

static HandEyeOutput ^ CalibrateEyeInHand (System::Collections::Generic::IEnumerable< HandEyeInput ^> ^ input)

Performs eye-in-hand calibration.

The procedure requires feature point sets acquired at the minimum from two poses. All the input poses have to be different. The feature point sets cannot be empty. All the feature point sets have to have same number of feature points. An exception will be thrown if the above requirements are not fulfilled. Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection results. Zivid point clouds are, by default, in millimeters.

Parameters:: input – Collection of HandEyeInput instances
Returns:: Instance of HandEyeOutput

static HandEyeOutput ^ CalibrateEyeToHand (System::Collections::Generic::IEnumerable< HandEyeInput ^> ^ input)

Performs eye-to-hand calibration.

The procedure requires feature point sets acquired at the minimum from two poses. All the input poses have to be different. The feature point sets cannot be empty. All the feature points have to have same number of elements. An exception will be thrown if the above requirements are not fulfilled. Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection results. Zivid point clouds are, by default, in millimeters.

Parameters:: input – Collection of robot pose and corresponding feature points pairs
Returns:: Instance of HandEyeOutput

Python

zivid.calibration.calibrate_eye_in_hand(inputs) / zivid.calibration.calibrate_eye_to_hand(inputs) — see How to run and integrate Zivid Hand-Eye Calibration.

HandEyeOutput

Result of a hand-eye calibration. Provides the 4×4 transformation matrix and per-pose residuals.

C++

class HandEyeOutput

The hand-eye calibration result containing the computed pose and reprojection errors for all the input poses.

For eye-in-hand, the computed pose represents camera pose in robot end-effector frame.

For eye-to-hand, the computed pose represents camera pose in robot base frame.

Public Functions

HandEyeOutput(const Matrix4x4 &transform, const std::vector<HandEyeResidual> &residuals)

Constructs a HandEyeOutput instance.

Parameters:

transform – Computed hand-eye calibration transform (camera pose in robot end-effector frame for eye-in-hand or camera pose in robot base frame for eye-to-hand).
residuals – Per pose hand-eye residuals.

bool valid() const

Test if HandEyeOutput is valid.

Returns:: True if HandEyeOutput is valid.

explicit operator bool() const

Test if HandEyeOutput is valid.

Returns:: True if HandEyeOutput is valid.

const Matrix4x4 &transform() const

Hand-eye transform.

A computed 4x4 matrix describing hand-eye calibration transform (camera pose in robot end-effector frame for eye-in-hand or camera pose in robot base frame for eye-to-hand). The units of the translation part are the same as the units of the input.

eye-in-hand: camera pose in robot end-effector frame.

eye-to-hand: camera pose in robot base frame.

An exception is thrown if the result is not valid.

Returns:: 4x4 transformation matrix.

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

Hand-eye calibration residuals.

Feature points (for each input pose) are transformed into a common frame. A rigid transform between feature points and corresponding centroids are utilized to compute residuals for rotational and translational parts. An exception is thrown if the result is not valid.

Returns:: Vector of hand-eye calibration residuals.

const HandEyeStatus &status() const

Get the status of the hand-eye calibration output.

Returns:: HandEyeStatus object representing the status of the calibration output.

std::string toString() const

Get string representation of the hand-eye calibration output.

Returns:: Calibration output as string

C#

class HandEyeOutput

The hand-eye calibration result containing the computed pose and reprojection errors for all the hand-eye input poses.

For eye-in-hand, the computed pose represents camera pose in robot end-effector frame.

For eye-to-hand, the computed pose represents camera pose in robot base frame.

An exception is thrown if the result is not valid.

Public Types

enum class CalibrationStatus

Status of hand-eye calibration indicating success or the reason for failure.

Hand-eye calibration computes the transformation between robot and camera coordinate systems. This status identifies common issues and provides guidance for resolution.

Values:

enumerator Ok

Calibration succeeded.

The computed transformation is ready for use.

Users are encouraged to verify the result (e.g., via a touch test or other validation procedures) before deployment.

enumerator InsufficientMotion

The computed solution is not well defined due to lack of motion in the dataset.

Recommended action: Collect more captures with greater variation in robot poses across all degrees of freedom in translation and rotation.

enumerator InsufficientDataQuality

The computed solution has high residual errors, indicating poor data quality.

Common causes:

Calibration board or fiducial markers are poorly detected
Suboptimal lighting, exposure, or camera focus
Motion or vibration during image capture
Calibration object or camera moves between captures
Inaccurate or inconsistent robot pose measurements

Recommended action: Ensure proper lighting, sharp focus, and consistent setup throughout data collection.

Public Functions

bool Valid()

Test if HandEyeOutput is valid.

Returns:: True if HandEyeOutput is valid

ManagedArray2D ^ Transform ()

Hand-eye transform.

A computed 4x4 matrix describing hand-eye calibration transform (camera pose in robot end-effector frame for eye-in-hand or camera pose in robot base frame for eye-to-hand). The units of the translation part are the same as the units of the input.

eye-in-hand: camera pose in robot end-effector frame.

eye-to-hand: camera pose in robot base frame.

An exception is thrown if the result is not valid.

Returns:: 4x4 transformation matrix.

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

Hand-eye calibration residuals.

Feature points (for each input pose) are transformed into a common frame. A rigid transform between feature points and corresponding centroids are utilized to compute residuals for rotational and translational parts. An exception is thrown if the result is not valid.

Returns:: Vector of hand-eye calibration residuals

CalibrationStatus Status()

Get the status of the hand-eye calibration.

Returns:: CalibrationStatus indicating success or the reason for failure.

System::String ^ ToString () override

Get string representation of the hand-eye calibration output.

Returns:: Hand-eye calibration output as string

Public Static Functions

static static operator bool (HandEyeOutput ^ output)

Test if HandEyeOutput is valid.

Returns:: True if HandEyeOutput is valid

Python

zivid.calibration.HandEyeOutput — see How to run and integrate Zivid Hand-Eye Calibration.

HandEyeResidual

Per-pose calibration residual — rotation (degrees) and translation (mm). Lower is better; inspect to diagnose poor calibration quality.

C++

class HandEyeResidual

Representation of the estimated errors of a calibrated hand-eye transform.

Public Functions

HandEyeResidual(float rotation, float translation)

Constructs a hand-eye residual instance.

Parameters:

rotation – Residual for rotation part.
translation – Residual for translation part.

float rotation() const

Rotational residual in degrees.

Returns:: Rotational residual.

float translation() const

Translational residual.

The unit of the residual is the same as the unit of the hand-eye inputs. Zivid point clouds are, by default, in millimeters.

Returns:: Translational residual.

std::string toString() const

Get string representation of the hand-eye residual.

Returns:: Hand-eye residual as string

C#

class HandEyeResidual

Representaton of the estimated errors of a calibrated hand-eye transform.

Public Functions

HandEyeResidual(float rotation, float translation)

Constructs a hand-eye residual instance.

Parameters:

rotation – Residual for rotation part
translation – Residual for translation part

float Rotation()

Rotational residual in degrees.

Returns:: Rotational residual

float Translation()

Translational residual.

The unit of the residual is the same as the unit of the hand-eye inputs. Zivid point clouds are, by default, in millimeters.

Returns:: Translational residual

System::String ^ ToString () override

Get string representation of the hand-eye residual.

Returns:: Hand-eye residual as string

Python

zivid.calibration.HandEyeResidual — see How to run and integrate Zivid Hand-Eye Calibration.

HandEyeStatus

Enum describing the outcome of a calibration run (e.g. Ok, InsufficientDataPoints).

C++

enum class Zivid::Calibration::HandEyeStatus

Status of hand-eye calibration indicating success or the reason for failure.

Hand-eye calibration computes the transformation between robot and camera coordinate systems. This status identifies common issues and provides guidance for resolution.

Values:

enumerator ok

Calibration succeeded.

The computed transformation is ready for use.

Users are encouraged to verify the result (e.g., via a touch test or other validation procedures) before deployment.

enumerator insufficientMotion

The computed solution is not well defined due to lack of motion in the dataset.

Recommended action: Collect more captures with greater variation in robot poses across all degrees of freedom in translation and rotation.

enumerator insufficientDataQuality

The computed solution has high residual errors, indicating poor data quality.

Common causes:

Calibration board or fiducial markers are poorly detected
Suboptimal lighting, exposure, or camera focus
Motion or vibration during image capture
Calibration object or camera moves between captures
Inaccurate or inconsistent robot pose measurements

Recommended action: Ensure proper lighting, sharp focus,and consistent setup throughout data collection. Tune the camera capture settings to ensure optimal image quality, for example using Zivid Studio. Make sure the robot manipulator is properly calibrated, such that the robot poses are consistent and accurate.

C#

See Calibration::HandEyeOutput::CalibrationStatus in the C# API reference.

Python

zivid.calibration.HandEyeOutput.status — see zivid-python.