Camera calibration files

Each session requires a TOML file in the calibrations/ directory that contains camera parameters for all views in Anipose format. The TOML file must include one [cam_N] section for each camera view, where N is the camera index (0, 1, 2, etc.).

Each camera section must contain:

  • name: A string identifier for the camera (e.g., β€œcam0”, β€œleft”, β€œfront”)

  • size: Array of two integers [width, height] specifying image dimensions in pixels

  • matrix: 3x3 camera intrinsic matrix as nested arrays

  • distortions: Array of 5 distortion coefficients [k1, k2, p1, p2, k3]

  • rotation: Array of 3 rotation angles in radians (Rodrigues vector)

  • translation: Array of 3 translation values [x, y, z] in world coordinate units

Example TOML calibration file:

[cam_0]
name = "view0"
size = [2816, 1408]
matrix = [
    [1993.4, 0.0, 1408.0],
    [0.0, 1993.4, 704.0],
    [1451.1, 993.0, 1.0]
]
distortions = [-0.121, 0.0, 0.0, 0.0, 0.0]
rotation = [0.830, -2.001, 1.630]
translation = [-0.001, 0.122, 1.482]

[cam_1]
name = "view1"
size = [2816, 1408]
matrix = [
    [1915.1, 0.0, 1408.0],
    [0.0, 1915.1, 704.0],
    [1585.2, 835.4, 1.0]
]
distortions = [-0.057, 0.0, 0.0, 0.0, 0.0]
rotation = [1.883, -0.765, 0.604]
translation = [0.003, 0.089, 1.545]

[metadata]
# Optional metadata section for additional information

The number of camera sections must match the number of views specified in your configuration file.

Calibrations index file (optional override)

By default, the CLI automatically discovers calibration files from image paths without any additional configuration. The session identifier is extracted from the frame’s path: frames are expected to live under labeled-data/<session>_<view>/, and the session is everything before the last _ in that subfolder name. For example, labeled-data/session0_view0/frame00001.png yields session session0.

Given the session, it looks for calibrations/<session>.toml first, then falls back to calibration.toml at the project root. No camera_params_file config entry is needed for this to work.

If you need per-frame control over which calibration file is used β€” for example, when frames from the same session use different calibrations β€” you can supply a calibrations.csv that maps each labeled image to its calibration file explicitly. This file must have exactly two columns:

  • First column (no header): The relative path to each labeled image, without view-specific subdirectories. This should match the image paths that appear in your labeled data CSV files, but with any view-specific path components removed.

  • Second column (file header): The relative path to the TOML calibration file for that session.

Example calibrations.csv format:

,file
labeled-data/session0/img00000005.png,calibrations/session0.toml
labeled-data/session0/img00000010.png,calibrations/session0.toml
labeled-data/session0/img00000230.png,calibrations/session0.toml
labeled-data/session1/img00000151.png,calibrations/session1.toml
labeled-data/session1/img00000201.png,calibrations/session1.toml

Note that the first column uses the session name (e.g., session0) rather than the view-specific directory names (e.g., session0_view0, session0_view1).

To use this CSV instead of auto-discovery, point to it in your configuration file:

data:
  camera_params_file: /path/to/project/calibrations.csv