Command-line interface#

Cheese3D provides a command-line interface (CLI). All commands are accessible via the cheese3d entry point.

You can open the help by running

$ cheese3d --help
Usage: cheese3d [OPTIONS] COMMAND [ARGS]...

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --path                      TEXT  Path to project directory                                         │
│                                   [default: /data/disk1/daruwal/repos/cheese3d]                     │
│ --configs                   TEXT  Path to additional configs (relative to project)                  │
│                                   [default: configs]                                                │
│ --install-completion              Install completion for the current shell.                         │
│ --show-completion                 Show completion for the current shell, to copy it or customize    │
│                                   the installation.                                                 │
│ --help                            Show this message and exit.                                       │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────╮
│ setup            Setup a new Cheese3D project called NAME under --path.                             │
│ import           Import an existing pose model project into NAME.                                   │
│ summarize        Summarize a Cheese3D project based on its configuration file.                      │
│ sync             Synchronize the video (and possibly ephys) files in a Cheese3D project.            │
│ extract          Extract frames from video data.                                                    │
│ label            Label extracted frames for model training.                                         │
│ train            Train 2d pose model.                                                               │
│ calibrate        Extract camera calibration for triangulation.                                      │
│ track            Track 2D keypoints using trained pose estimation model.                            │
│ triangulate      Triangulate 2D pose estimation result to obtain 3D keypoints and Cheese3D          │
│                  features.                                                                          │
│ analyze          Run full analysis including: Camera calibration, 2D keypoint tracking,             │
│                  3D triangulation, and feature extraction.                                          │
│ generate-videos  Generate videos with pose estimation results overlaid.                             │
│ visualize        Visualize the output of Cheese3D using interactive GUI.                            │
│ interactive      Run interactive GUI.                                                               │
│ checkpoint       Create a checkpoint of this project.                                               │
│ restore          Restore a project from a checkpoint archive.                                       │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯

Global options and arguments#

These options are available on every command and are set before the subcommand.

Global options#
Option	Type	Default	Description
`--path`	`str`	Current working directory	Path to project directory (where `cheese3d` looks for your project).
`--configs`	`str`	`configs`	Path to additional configs (relative to project).

Several commands share the same positional arguments. They are documented here once for brevity.

Common arguments#
Argument	Type	Default	Description
`NAME`	`str`	`"."`	Name of the project (or `"."` for the current directory).
`CONFIG_OVERRIDES`	`Optional[List[str]]`	`None`	Config overrides passed to Hydra.

Commands#

setup#

cheese3d setup NAME

Setup a new Cheese3D project called NAME under --path.

`setup` arguments#
Argument	Type	Description
`NAME`	`str`	Name of the new project.

import#

cheese3d import MODEL [NAME] [--model-type TYPE]

Import an existing pose model project into NAME.

`import` arguments#
Argument	Type	Default	Description
`MODEL`	`str`	N/A	Path to existing model.
`NAME`	`str`	`"."`	Name of the project.
`CONFIG_OVERRIDES`	`Optional[List[str]]`	`None`	Config overrides passed to Hydra.

`import` options#
Option	Type	Default	Description
`--model-type`	`str`	`"dlc"`	Type of project to import (only `"dlc"` is valid for now).

summarize#

cheese3d summarize [NAME]

Summarize a Cheese3D project based on its configuration file.

This command accepts the common arguments.

sync#

cheese3d sync [NAME]

Synchronize the video (and possibly ephys) files in a Cheese3D project.

This command accepts the common arguments.

extract#

cheese3d extract [NAME] [--manual]

Extract frames from video data.

This command accepts the common arguments.

`extract` options#
Option	Type	Default	Description
`--manual`	`bool`	`False`	Set to launch manual frame picking GUI. When enabled, an interactive prompt lets you select which recording to extract frames for.

label#

cheese3d label [NAME]

Label extracted frames for model training.

This command accepts the common arguments.

train#

cheese3d train [NAME] [--gpu ID] [--iterate-dataset / --no-iterate-dataset]

Train 2D pose model.

This command accepts the common arguments.

`train` options#
Option	Type	Default	Description
`--gpu`	`int`	`0`	GPU ID(s) to use.
`--iterate-dataset` / `--no-iterate-dataset`	`bool`	`True`	Create a new dataset iteration before training.

calibrate#

cheese3d calibrate [NAME] [--session SESSION]

Extract camera calibration for triangulation.

This command accepts the common arguments.

`calibrate` options#
Option	Type	Default	Description
`--session`	`Optional[str]`	`None`	Name of a specific session subfolder to process.

track#

cheese3d track [NAME] [--session SESSION]

Track 2D keypoints using trained pose estimation model.

This command accepts the common arguments.

`track` options#
Option	Type	Default	Description
`--session`	`Optional[str]`	`None`	Name of a specific session subfolder to process.

triangulate#

cheese3d triangulate [NAME] [--session SESSION]

Triangulate 2D pose estimation results to obtain 3D keypoints and Cheese3D features.

This command accepts the common arguments.

`triangulate` options#
Option	Type	Default	Description
`--session`	`Optional[str]`	`None`	Name of a specific session subfolder to process.

analyze#

cheese3d analyze [NAME] [--session SESSION]

Run full analysis including: camera calibration, 2D keypoint tracking, 3D triangulation, and feature extraction.

This command accepts the common arguments.

`analyze` options#
Option	Type	Default	Description
`--session`	`Optional[str]`	`None`	Name of a specific session subfolder to process.

generate-videos#

cheese3d generate-videos [NAME]

Generate videos with pose estimation results overlaid.

This command accepts the common arguments.

visualize#

cheese3d visualize [NAME]

Visualize the output of Cheese3D using interactive GUI. An interactive prompt lets you select which recording to visualize.

This command accepts the common arguments.

interactive#

cheese3d interactive [--web]

Run interactive GUI.

`interactive` options#
Option	Type	Default	Description
`--web`	`bool`	`False`	Set to enable web mode UI.

checkpoint#

cheese3d checkpoint [NAME] [--skip-source] [--portable]

Create a checkpoint of this project.

This command accepts the common arguments.

`checkpoint` options#
Option	Type	Default	Description
`--skip-source`	`bool`	`False`	Skip recording directory when creating archive.
`--portable`	`bool`	`False`	Resolve all links or relative paths, ensuring that data is copied into the archive.

restore#

cheese3d restore CHECKPOINT_FILE [NAME] [--skip-source] [--portable]

Restore a project from a checkpoint archive.

This command accepts the common arguments.

`restore` arguments#
Argument	Type	Default	Description
`CHECKPOINT_FILE`	`str`	N/A	Path to checkpoint archive.

`restore` options#
Option	Type	Default	Description
`--skip-source`	`bool`	`False`	Skip recording directory when extracting archive.
`--portable`	`bool`	`False`	The archive was created with portable mode. No-op flag for API compatibility.

Command-line interface

Contents

Command-line interface#

Global options and arguments#

Commands#

setup#

import#

summarize#

sync#

extract#

label#

train#

calibrate#

track#

triangulate#

analyze#

generate-videos#

visualize#

interactive#

checkpoint#

restore#