StereoCalibration

SUMMARY

Left and right camera intrinsics plus the rigid transform and baseline between their optical frames, with optional color-camera calibration.

python

import numpy as np

from telekinesis import datatypes

camera = datatypes.CameraCalibration(
    width=1280,
    height=720,
    distortion_model="plumb_bob",
    distortion_parameters=[-0.2, 0.1, 0.0, 0.0, 0.0],
    intrinsic_matrix=[1000.0, 0.0, 640.0, 0.0, 1000.0, 360.0, 0.0, 0.0, 1.0],
)
left_to_right = np.eye(4, dtype=np.float32)
left_to_right[0, 3] = 0.12
calibration = datatypes.StereoCalibration(camera, camera, left_to_right)

Parameters

Parameter	Type	Default	Description
`left`	`CameraCalibration`	Required	Calibration for the left camera.
`right`	`CameraCalibration`	Required	Calibration for the right camera.
`left_to_right`	`Mat4x4 \| Transform3D \| np.ndarray`	Required	Homogeneous rigid transform from the left optical frame to the right optical frame.
`color`	`CameraCalibration \| None`	`None`	Optional calibration for a third color camera.
`left_to_color`	`Mat4x4 \| Transform3D \| np.ndarray \| None`	`None`	Optional rigid transform from the left optical frame to the color optical frame; required exactly when `color` is provided.

Coordinates and translation values are expressed in metres.

Raises

Exception	Condition
`TypeError`	A camera calibration or transform uses an unsupported representation.
`ValueError`	A transform is non-finite, has an invalid homogeneous bottom row, contains a non-orthonormal or improper rotation, or `color` and `left_to_color` are not provided together.

Attributes

Attribute	Type	Description
`left`	`CameraCalibration`	Independent value containing the left-camera calibration.
`right`	`CameraCalibration`	Independent value containing the right-camera calibration.
`left_to_right`	`Mat4x4`	Independent left-to-right optical-frame transform.
`color`	`CameraCalibration \| None`	Independent optional color-camera calibration.
`left_to_color`	`Mat4x4 \| None`	Independent optional left-to-color transform.
`baseline`	`float`	Euclidean translation distance between the left and right optical frames, in metres.

Calibration and transform inputs are stored independently, and the accessors return independent values.

Methods

Method	Returns	Description
`StereoCalibration.coerce(value)`	`StereoCalibration`	Returns an existing instance or constructs one from a dictionary of constructor fields.
`copy()`	`StereoCalibration`	Returns an independent copy of the stereo calibration.

Operators

Operation	Behavior
`calibration == other`	Compares both camera calibrations and all transforms by semantic value.
`repr(calibration)`	Shows the baseline and whether color-camera calibration is present.

Example

python

"""Demonstrates the Telekinesis StereoCalibration datatype."""

import time

import numpy as np
from loguru import logger

from telekinesis import datatypes


def stereo_calibration_example():
    """Demonstrate creation, inspection, operations, and serialization."""

    # ======================= Create ============================================
    camera = datatypes.CameraCalibration(
        width=1280,
        height=720,
        distortion_model="plumb_bob",
        distortion_parameters=[-0.2, 0.1, 0.0, 0.0, 0.0],
        intrinsic_matrix=[1000.0, 0.0, 640.0, 0.0, 1000.0, 360.0, 0.0, 0.0, 1.0],
    )
    left_to_right = np.eye(4, dtype=np.float32)
    left_to_right[0, 3] = 0.12
    calibration = datatypes.StereoCalibration(
        left=camera,
        right=camera,
        left_to_right=datatypes.Mat4x4(left_to_right),
    )
    logger.info(f"Created StereoCalibration: {calibration}")

    # ======================= Inspect ===========================================
    logger.info(f"left calibration: {calibration.left}")
    logger.info(f"right calibration: {calibration.right}")
    logger.info(f"left-to-right transform:\n{calibration.left_to_right.to_numpy()}")
    logger.info(f"baseline={calibration.baseline:.3f} m")

    # ======================= Operations ========================================
    transform_copy = calibration.left_to_right
    transform_copy.data = np.eye(4, dtype=np.float32)
    logger.info(
        "Mutating the returned transform does not affect the calibration: "
        f"baseline={calibration.baseline:.3f} m"
    )

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(calibration)
    serialization_ms = (time.perf_counter() - start) * 1000

    start = time.perf_counter()
    deserialized = datatypes.deserialize(serialized)["param_0"]
    deserialization_ms = (time.perf_counter() - start) * 1000

    logger.info(f"Deserialized StereoCalibration: {deserialized}")
    logger.info(f"Round-trip successful: {calibration == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    stereo_calibration_example()

StereoCalibration ​

Parameters ​

Raises ​

Attributes ​

Methods ​

Operators ​