Workspace Setup¶

This document explains how to structure your workspace for multicamera calibration and motion capture with Caliscope.

Initial Project Structure¶

When you create a new project, Caliscope automatically creates the necessary directory structure:

workspace/
├── calibration/
│   ├── targets/          # Auto-created calibration target configurations
│   ├── intrinsic/        # Per-camera calibration videos (unsynchronized)
│   └── extrinsic/        # Multi-camera calibration videos (synchronized)
└── recordings/           # Motion capture sessions

The application monitors these directories and automatically updates when files are added or changed.

Camera Identification¶

Cameras are identified by integer IDs assigned through your video file naming. Video files must follow the naming convention cam_N.mp4, where N is the camera ID (e.g., cam_0.mp4, cam_1.mp4, cam_2.mp4).

Camera IDs can be any non-negative integer
Camera IDs do not need to be contiguous (e.g., cam_0.mp4, cam_3.mp4, cam_7.mp4 is valid)
The camera set is determined from the files present in the extrinsic calibration directory
Camera IDs must remain consistent across intrinsic calibration, extrinsic calibration, and recording sessions

Stage 1: Intrinsic Calibration¶

Intrinsic calibration determines each camera's internal properties (focal length, principal point, lens distortion).

Place one video per camera in calibration/intrinsic/. These videos do not need to be synchronized. Each video should show a calibration target (ChArUco board or chessboard) being moved throughout the camera's field of view.

workspace/
└── calibration/
    └── intrinsic/
        ├── cam_0.mp4     # Individual camera recordings
        ├── cam_1.mp4     # No synchronization required
        └── cam_2.mp4

After calibration, each camera's intrinsic parameters are stored internally for use in extrinsic calibration.

Extrinsic-Only Projects¶

The calibration/intrinsic/ directory can be left empty. Caliscope can recover camera intrinsics during extrinsic calibration, provided the capture meets the prerequisites, most notably a target moved toward and away from each camera, and no fisheye cameras. The minimal project layout is then:

workspace/
├── calibration/
│   ├── targets/
│   └── extrinsic/
│       ├── cam_0.mp4
│       ├── cam_1.mp4
│       └── cam_2.mp4
└── recordings/

The camera set is always derived from the files in calibration/extrinsic/, so nothing else changes: synchronization, extraction, and calibration work the same way.

Stage 2: Extrinsic Calibration¶

Extrinsic calibration determines the spatial relationship between cameras (their positions and orientations in 3D space).

Place synchronized videos in calibration/extrinsic/. All cameras must observe the same physical space during the same time period.

workspace/
└── calibration/
    └── extrinsic/
        ├── cam_0.mp4
        ├── cam_1.mp4
        ├── cam_2.mp4
        └── timestamps.csv      # Optional: per-frame timing data

Frame Synchronization¶

If your cameras are hardware-synchronized (same frame count in every file), Caliscope aligns them automatically.

Non-synchronized cameras

If your cameras are not hardware-synchronized, include a timestamps.csv with per-frame timing. Without it, the calibration will suffer from misaligned frames.

`timestamps.csv` Format¶

The file must have two columns: cam_id and frame_time.

cam_id,frame_time
0,927387.33536115
1,927387.50128975
2,927387.3530109001
0,927387.50643105
1,927387.51819965
2,927387.5063038999
0,927387.6684489499
1,927387.66848565
...

cam_id: Must match the camera IDs from your video filenames
frame_time: Numerical timestamp for when the frame was captured (e.g., from Python's time.perf_counter())
Rows can be in any order
Cameras do not need the same number of frames or the same start time

Caliscope automatically aligns the videos during processing, inserting blank frames where necessary to maintain temporal correspondence.

Calibration Output¶

After successful extrinsic calibration, Caliscope creates output in subdirectories:

workspace/
└── calibration/
    └── extrinsic/
        ├── cam_0.mp4
        ├── cam_1.mp4
        ├── cam_2.mp4
        ├── timestamps.csv           # If per-frame timing was provided
        ├── inferred_timestamps.csv  # Caliscope's timing assumptions when no timestamps.csv provided (not read back)
        ├── CHARUCO/                 # Extraction output (tracker name varies)
        │   └── image_points.csv
        └── capture_volume/          # Calibration result
            ├── camera_array.toml
            ├── image_points.csv
            └── world_points.csv

The capture_volume/ directory contains the complete calibrated camera system and can be used for 3D reconstruction of motion capture data. This workspace structure works with both the GUI and scripting workflows. Scripts can load calibration results with CameraArray.from_toml() and save with CaptureVolume.save().

Stage 3: Recording and Reconstruction¶

For each motion capture session, create a subfolder within recordings/ and populate it with synchronized videos. The same synchronization rules apply: provide a timestamps.csv if you have per-frame timing, or Caliscope infers from the video files (see Frame Synchronization).

workspace/
└── recordings/
    └── walking_trial/              # Name the folder descriptively
        ├── cam_0.mp4
        ├── cam_1.mp4
        ├── cam_2.mp4
        └── timestamps.csv          # Optional: same format as extrinsic

After processing with a motion tracking system, output files are created in a tracker-named subdirectory:

workspace/
└── recordings/
    └── walking_trial/
        ├── cam_0.mp4
        ├── cam_1.mp4
        ├── cam_2.mp4
        ├── timestamps.csv                  # If provided
        └── ONNX_rtmpose_t_halpe26/          # Output subdirectory (tracker name)
            ├── camera_array.toml            # Snapshot of calibration used
            ├── xy_ONNX_rtmpose_t_halpe26.csv
            ├── xyz_ONNX_rtmpose_t_halpe26.csv
            ├── xyz_ONNX_rtmpose_t_halpe26_labelled.csv
            └── xyz_ONNX_rtmpose_t_halpe26.trc

Output Files¶

See Reconstruction for output file format details.