Directory Structure Changelog

This document details the schema changes to the directory structure over time.

v2.1.2 | June 11, 2026

• Label CSV files now support an optional visible column after each x, y pair (columns become x, y, visible, x, y, visible, …). Values: 0 = not labeled (exclude from loss), 1 = occluded (uniform heatmap target), 2 = visible (Gaussian heatmap target). This allows mixing visibility behaviors within a single dataset. When the column is absent, behavior is unchanged and is controlled by training.uniform_heatmaps_for_nan_keypoints. See Label CSV File Format for full details.

v2.1.1 | May 15, 2026

• Calibration files are now auto-discovered from image paths for the CLI 3D loss — no camera_params_file config entry is required. Frames must follow the path structure labeled-data/<session>_<view>/<filename>.ext; the session is extracted by stripping the last _<view> suffix from the subfolder name (e.g., labeled-data/session0_view0/frame00001.png → session session0). The CLI then looks for calibrations/<session>.toml first, then falls back to calibration.toml at the project root. The camera_params_file config field remains supported as an explicit override for per-frame calibration control.

v2.0.7.0 | Feb 26, 2026

• Added creation_datetime to the model config file, for display in the model list page. The app backfills the field for existing models on startup.

• Videos must be stored in DATA_DIR/videos to be viewable in the viewer. Previously the app supported viewing videos anywhere in the data directory.

• Label files must be stored at the top-level of DATA_DIR to be accessible in the labeler. Previously the app supported viewing label files anywhere in the data directory.

v2.0.5.3 | Feb 8, 2026

This version changed the unlabeled sidecar file to jsonl format. E.g. CollectedData_top.unlabeled was converted to CollectedData_top.unlabeled.jsonl. This was done to support embedding model predictions when extracting a frame from the viewer.

v2.0.5-app-compatible | Jan 14, 2026

v2.0.5 includes a new app. The App-compatible directory structure is a subset of what’s supported when using just the command-line. The main differences are documented here.

Over time, the App and CLI directory structures will converge towards the App’s requirements. Directory structures that are only supported via the CLI will be deprecated.

Data directory

1. A project.yaml file in data directory is required. Without this, a project is CLI-only.

2. The default label file should be named CollectedData_<View>.csv (CollectedData.csv for singleview). The general format required by the app is <LabelFileKey>_<View>.csv. <View>.csv without a LabelFileKey is CLI-only..

3. Multiview calibration files should be stored as calibrations/<SessionKey>.toml where SessionKey is matches the video files <SessionKey>_<View>.mp4. In case a calibration file is not found, the app will fall back on the project-level calibration file, DATA_DIR/calibration.toml.

Alternative file paths for calibration files are CLI-only.

Model directory

1. The models directory should immediately contain model directories, instead of subdirectories used for organization. Specifically, you should move away from the default depth of 2 structure generated the CLI when –output_dir is unspecified. For now, maximum depth of 2 structure is supported but discouraged in the App.

Example of depth of 2 structure:

/models-directory/
└── YYYY-MM-DD/
    └── HH-MM-SS/
        ├── config.yaml
        ├── tb_logs/
        └── ...

Preferred structure:

/models-directory/
└── ModelName/
    ├── config.yaml
    ├── tb_logs/
    └── ...

Note

Migrating from the old Pose-app requires further changes. See the Migrating to the App.