CameraCalibration

SUMMARY

Intrinsic calibration parameters for a camera.

from telekinesis import datatypes
calibration = 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],
)

API Reference

Complete API documentation for CameraCalibration, including parameters, attributes, and methods.

View Reference →

Parameters

Parameter	Type	Default	Description
width	int	Required	Calibrated image width in pixels, in the range [0, 2**32 - 1].
height	int	Required	Calibrated image height in pixels, in the range [0, 2**32 - 1].
distortion_model	str | DistortionModel	Required	Camera distortion model, provided as a DistortionModel member or its string value. The selected model determines the required distortion coefficients.
distortion_parameters	np.ndarray | list[float]	Required	Ordered distortion coefficients with shape (M,), where M is the parameter_count of the selected distortion model.
intrinsic_matrix	np.ndarray | list[float]	Required	Camera intrinsic matrix in row-major order. Accepts a matrix with shape (3, 3) or a flat sequence of length 9.

Raises

Exception	Condition
TypeError	width/height isn't int-convertible, or distortion_parameters/intrinsic_matrix can't be converted to a float64 array
ValueError	width/height falls outside [0, 2**32 - 1]; distortion_model isn't a valid DistortionModel member or matching string; distortion_parameters's length doesn't match distortion_model.parameter_count; intrinsic_matrix doesn't have exactly 9 elements; or distortion_parameters/intrinsic_matrix contains a non-finite value

Attributes

Attribute	Type	Description
width	int	Image width in pixels.
height	int	Image height in pixels.
distortion_model	str	Distortion model name as a plain string, even when constructed from a DistortionModel member.
distortion_parameters	np.ndarray	Defensive copy of the distortion parameters, shape (M,), float64.
intrinsic_matrix	np.ndarray	Defensive copy of the intrinsic camera matrix, shape (3, 3), float64, row-major.

These attributes have no setters; CameraCalibration is immutable after construction. Each read returns a fresh copy, so mutating it does not affect the instance.

Methods

Method	Type	Description
CameraCalibration.coerce(value)	CameraCalibration	Converts a dict of calibration fields into a CameraCalibration. Accepts a dict with width, height, distortion_model, distortion_parameters, and intrinsic_matrix keys, which is passed straight to the constructor. If value is already a CameraCalibration, it is returned unchanged.

Operators

Operation	Behavior
cc == other	True only if other is also a CameraCalibration with equal width/height/distortion_model and elementwise-equal distortion_parameters/intrinsic_matrix. NotImplemented (so False) for any other type.
repr(cc)	CameraCalibration(width=1280, height=720, distortion_model=<DistortionModel.PLUMB_BOB: 'plumb_bob'>). Omits distortion_parameters and intrinsic_matrix.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("camera_calibration_example", spawn=True)
datatypes.visualize(calibration, entity_path="/calibration", label="CameraCalibration")

Example

"""Demonstrates the Telekinesis CameraCalibration datatype."""

import time

import rerun as rr
from loguru import logger

from telekinesis import datatypes

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

    # ======================= Create ============================================
    camera_calibration = 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],
    )
    logger.info(f"Created CameraCalibration: {camera_calibration}")

    calibration_from_dict = datatypes.CameraCalibration.coerce(
        {
            "width": 640,
            "height": 480,
            "distortion_model": "plumb_bob",
            "distortion_parameters": [0.0, 0.0, 0.0, 0.0, 0.0],
            "intrinsic_matrix": [500.0, 0.0, 320.0, 0.0, 500.0, 240.0, 0.0, 0.0, 1.0],
        }
    )
    logger.info(f"CameraCalibration coerced from dict: {calibration_from_dict}")

    # distortion_model also accepts a DistortionModel member directly, with a
    # parameter count matching that model (8 for rational_polynomial).
    rational_calibration = datatypes.CameraCalibration(
        width=1280,
        height=720,
        distortion_model=datatypes.DistortionModel.RATIONAL_POLYNOMIAL,
        distortion_parameters=[-0.2, 0.1, 0.0, 0.0, 0.0, 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],
    )
    logger.info(f"Rational-polynomial CameraCalibration: {rational_calibration}")

    # ======================= Inspect ===========================================
    logger.info(f"width={camera_calibration.width}")
    logger.info(f"height={camera_calibration.height}")
    logger.info(f"distortion_model={camera_calibration.distortion_model}")
    logger.info(f"distortion_parameters={camera_calibration.distortion_parameters}")
    logger.info(f"intrinsic_matrix=\n{camera_calibration.intrinsic_matrix}")
    logger.info(
        f"DistortionModel.PLUMB_BOB.parameter_names="
        f"{datatypes.DistortionModel.PLUMB_BOB.parameter_names}"
    )
    logger.info(
        f"DistortionModel.RATIONAL_POLYNOMIAL.parameter_count="
        f"{datatypes.DistortionModel.RATIONAL_POLYNOMIAL.parameter_count}"
    )

    # ======================= Operations =========================================
    # intrinsic_matrix returns a defensive copy; mutating it does not affect the original.
    intrinsic_matrix_view = camera_calibration.intrinsic_matrix
    intrinsic_matrix_view[0, 0] = -1.0
    logger.info(f"Original fx unaffected: {camera_calibration.intrinsic_matrix[0, 0]}")

    logger.info(f"camera_calibration == camera_calibration: {camera_calibration == camera_calibration}")
    logger.info(
        f"camera_calibration == calibration_from_dict: "
        f"{camera_calibration == calibration_from_dict}"
    )

    # ======================= Visualize =========================================
    rr.init("camera_calibration_example", spawn=True)
    datatypes.visualize(camera_calibration, entity_path="/camera_calibration")

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(camera_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 CameraCalibration: {deserialized}")
    logger.info(f"Round-trip successful: {camera_calibration == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    camera_calibration_example()