Scriptable Calibration Workflow

[mprib]

I wanted to scope out a planned update that will make it easier to script and automate the calibration workflow. Along with this I'll be renaming some things and generally trying to get the code a bit more "ergonomic".

The basic idea is that you can install the calibration pipeline tools with: pip install caliscope to use it as a library. Alternatively, you can use pip install caliscope[gui] to add the full graphical application.

Does the API below make sense for your use case?

Planned workflow example

from pathlib import Path
from caliscope.api import (
    Charuco,
    CharucoTracker,
    CameraArray,
    CaptureVolume,
    extract_image_points,
    calibrate_intrinsics,
)

project = Path("/path/to/my/project")

# --- 1. Define calibration target ---
charuco = Charuco.from_squares(columns=4, rows=5, square_size_cm=3.0)
tracker = CharucoTracker(charuco)

# Save a printable board image 
charuco.save_image("charuco_board.png")
charuco.save_mirror_image("charuco_mirror_board.png")

Creating cameras

Cameras can be initialized several ways depending on what you have:

# From video files (reads resolution from metadata)
intrinsic_videos = {
    0: project / "intrinsic" / "cam_0.mp4",
    1: project / "intrinsic" / "cam_1.mp4",
    2: project / "intrinsic" / "cam_2.mp4",
}
cameras = CameraArray.from_videos(intrinsic_videos)

# From known image sizes (no video files needed)
cameras = CameraArray.from_image_sizes({
    0: (1920, 1080),
    1: (1920, 1080),
    2: (1920, 1080),
})

# From a previously saved calibration
cameras = CameraArray.from_toml(project / "camera_array.toml")

Intrinsic calibration

for cam_id, video in intrinsic_videos.items():
    points = extract_image_points({cam_id: video}, tracker)
    output = calibrate_intrinsics(points, cameras[cam_id])
    cameras[cam_id] = output.camera
    print(f"Camera {cam_id}: RMSE={output.report.rmse:.3f}px")

# Save intrinsics for reuse
cameras.to_toml(project / "camera_array.toml")

Extrinsic calibration

extrinsic_videos = {
    0: project / "extrinsic" / "cam_0.mp4",
    1: project / "extrinsic" / "cam_1.mp4",
    2: project / "extrinsic" / "cam_2.mp4",
}

points = extract_image_points(extrinsic_videos, tracker)
capture_volume = CaptureVolume.bootstrap(points, cameras)  # relative poses estimated from linked stereopairs

# Refine
capture_volume = capture_volume.optimize()  # bundle adjustment performed
capture_volume = capture_volume.filter_by_percentile_error(2.5)
capture_volume = capture_volume.optimize()

# Set real-world scale and origin using the charuco board visible at frame 0
capture_volume = capture_volume.align_to_object(sync_index=0)

# Optionally rotate to match your lab coordinate system
capture_volume = capture_volume.rotate("x", 90)

# Save everything (camera_array.toml + image_points.csv + world_points.csv)
capture_volume.save(project / "capture_volume")

Reusing intrinsics with a new extrinsic calibration

# Load cameras with existing intrinsics
cameras = CameraArray.from_toml(project / "camera_array.toml")

# New extrinsic videos from the new setup
new_extrinsic_videos = {
    0: project / "new_session" / "cam_0.mp4",
    1: project / "new_session" / "cam_1.mp4",
    2: project / "new_session" / "cam_2.mp4",
}

points = extract_image_points(new_extrinsic_videos, tracker)

# bootstrap() uses the existing intrinsics, computes new extrinsics
capture_volume = CaptureVolume.bootstrap(points, cameras)
capture_volume = capture_volume.optimize()
capture_volume.save(project / "new_session" / "capture_volume")

The key: bootstrap() reads intrinsics from the cameras you pass in, but computes extrinsics fresh from the new observations. Your lens calibration is preserved.

Checkpointing

Every intermediate result can be saved and loaded independently. This means you can stop and resume at any point, or re-run just the expensive step that changed:

# Save after tracking (the slow part)
points.to_csv(project / "checkpoints" / "extrinsic_points.csv")

# Later, resume from saved points
points = ImagePoints.from_csv(project / "checkpoints" / "extrinsic_points.csv")
capture_volume = CaptureVolume.bootstrap(points, cameras)

---