Cal3Unified - GTSAM Docs

Cal3Unified is a newer wide-angle calibration model that can even represent omnidirectional cameras. It combines Brown–Conrady distortion with a mirror parameter xi, covering perspective and central catadioptric cameras within one projection model.

Authors: Frank Dellaert, et al. (see THANKS for the full author list)

See LICENSE for the license information

try:
    import google.colab
    %pip install --quiet gtsam-develop
except ImportError:
    pass

import gtsam
import numpy as np

Initialization¶

The explicit constructor makes the model and parameter order visible. A default constructor is also available, but calibrated values are preferable in real projection code.

calibration = gtsam.Cal3Unified(
    500.0, 495.0, 0.0, 320.0, 240.0,
    1e-3, -1e-5, 2e-4, -1e-4, 0.8,
)
print(calibration)

Calibration parameters¶

xi() is the mirror parameter. spaceToNPlane() and nPlaneToSpace() convert between the model’s space-plane and normalized-plane coordinates. vector() collects the optimized parameters, while K() returns the intrinsic matrix associated with the linear part of the model.

print("xi:", calibration.xi())
print("distortion:", calibration.k())
space_point = np.array([0.1, -0.05])
plane = calibration.spaceToNPlane(space_point)
print("normalized plane:", plane)
recovered_space_point = calibration.nPlaneToSpace(plane)
print("back to space-plane coordinates:", recovered_space_point)
np.testing.assert_allclose(recovered_space_point, space_point, atol=1e-12)

Calibrating and uncalibrating points¶

uncalibrate() maps normalized image coordinates to pixels and applies this model’s distortion. calibrate() performs the inverse mapping iteratively. Their round trip is the most direct way to check parameter conventions.

normalized = np.array([0.12, -0.08])
pixel = calibration.uncalibrate(normalized)
recovered = calibration.calibrate(pixel)
print("pixel:", pixel)
print("recovered normalized point:", recovered)
np.testing.assert_allclose(recovered, normalized, atol=1e-7)

Manifold operations¶

Calibration objects participate in nonlinear optimization through retract() and localCoordinates(). The tangent coordinates follow the order returned by vector() for the parameters that this model optimizes.

delta = np.array([1.0, -1.0, 0.01, 0.2, -0.2, 1e-5, -1e-6, 1e-5, -1e-5, 1e-3])
perturbed = calibration.retract(delta)
recovered_delta = calibration.localCoordinates(perturbed)
print("parameter increment:", recovered_delta)
np.testing.assert_allclose(recovered_delta, delta, atol=1e-9)

Source¶

Cal3Unified.h

AI assistance caveat¶

AI was used to help draft this documentation, and inaccuracies could be present.