API Reference

🚧 This is just reference stubs—will be replaced later with better organization.

cheese3d

cheese3d.project

class cheese3d.project.Ch3DProject(name: str, root: ~pathlib.Path, video_root: ~pathlib.Path, model_root: ~pathlib.Path, fps: int, sessions: ~typing.Dict[~cheese3d.project.RecordingKey, ~typing.Dict[str, ~pathlib.Path]], calibrations: ~typing.Dict[~cheese3d.project.RecordingKey, ~typing.Dict[str, ~pathlib.Path]], view_config: ~cheese3d.config.MultiViewConfig, view_regex: str, keypoints: ~typing.List[~cheese3d.config.KeypointConfig], keypoint_groups: ~typing.List[~cheese3d.config.KeypointGroupConfig], model: ~cheese3d.backends.core.Pose2dBackend | None, ephys_root: ~pathlib.Path | None = None, ephys_sessions: ~typing.Dict[~cheese3d.project.RecordingKey, ~pathlib.Path] | None = None, ephys_param: ~typing.Dict[str, ~typing.Any] | None = None, sync: ~cheese3d.synchronize.core.SyncConfig = <factory>, triangulation: ~cheese3d.config.TriangulationConfig = <factory>, ignore_keypoint_labels: ~typing.List[str] = <factory>)

Bases: object

A Cheese3D project.

Parameters:

• name (-) – the name of the project

• root (-) – root directory under which the project folder should be made

• sessions (-) – a list of sessions where each entry is video files organized by camera view

• keypoints (-) – a list of `KeypointConfig`s to track in this project

calibrate()

calibrations: Dict[RecordingKey, Dict[str, Path]]

ephys_param: Dict[str, Any] | None = None

property ephys_path

ephys_root: Path | None = None

ephys_sessions: Dict[RecordingKey, Path] | None = None

extract_frames(sessions: List[RecordingKey] | None = None, manual=False)

fps: int

classmethod from_cfg(cfg: ProjectConfig, root: str | Path, model_import=None)

classmethod from_path(path: str | Path, cfg_dir=None, overrides=None, model_import=None)

generate_videos()

ignore_keypoint_labels: List[str]

static initialize(name: str, root: str | Path, skip_model=False)

keypoint_groups: List[KeypointGroupConfig]

keypoints: List[KeypointConfig]

label_frames()

model: Pose2dBackend | None

property model_path

model_root: Path

name: str

property path

property recording_path

root: Path

sessions: Dict[RecordingKey, Dict[str, Path]]

summarize(pty=None)

sync: SyncConfig

synchronize()

track()

train(gpu)

triangulate()

triangulation: TriangulationConfig

property triangulation_path

video_root: Path

view_config: MultiViewConfig

view_regex: str

visualize(recording: RecordingKey)

class cheese3d.project.RecordingKey(session: str, name: str, **attributes)

Bases: RecordingKey

as_str()

matches(other)

cheese3d.project.build_model_backend(cfg: ModelConfig | str | Path, root: Path, sessions: Dict[RecordingKey, Dict[str, Path]], view_cfg: MultiViewConfig, keypoints: List[KeypointConfig])

cheese3d.project.find_ephys(dir: Path, ephys_regex: str, sessions: Dict[RecordingKey, Dict[str, Path]])

cheese3d.project.find_videos(dir: Path, recording_regex: str, calibration_keys: Dict[str, str], sessions: List[Dict[str, str]], views: MultiViewConfig)

cheese3d.project.group_by_session(recordings: Dict[RecordingKey, Any])

cheese3d.config

class cheese3d.config.KeypointConfig(label: str = '???', groups: List[str] = <factory>, views: List[str] = <factory>)

Bases: object

groups: List[str]

label: str = '???'

views: List[str]

class cheese3d.config.KeypointGroupConfig(name: str = '???', skeleton: List[List[str]] = '???')

Bases: object

name: str = '???'

skeleton: List[List[str]] = '???'

class cheese3d.config.ModelConfig(name: Optional[str] = None, backend_type: str = 'dlc', backend_options: Dict[str, Any] = <factory>)

Bases: object

backend_options: Dict[str, Any]

backend_type: str = 'dlc'

name: str | None = None

class cheese3d.config.MultiViewConfig

Bases: dict[str, VideoConfig]

Structured config specification for multi-camera setups. This behaves like dictionary of `VideoConfig`s.

Different views can be accessed as if they are attributes (e.g. myviews.topleft is equivalent to myviews[“topleft”]).

Arguments: - views: a dictionary of `VideoConfig`s with keys corresponding

to the view name.

as_dict()

as_list()

class cheese3d.config.ProjectConfig(name: str = '???', video_root: str = 'videos', ephys_root: str | None = None, model_root: str = 'model', video_regex: Any = '???', model: cheese3d.config.ModelConfig = '???', ephys_regex: Any | None = None, ephys_param: Dict[str, Any] | None = None, fps: int = 100, sync: cheese3d.synchronize.core.SyncConfig = '???', sessions: List[Dict[str, str]] = '???', triangulation: cheese3d.config.TriangulationConfig = '???', views: cheese3d.config.MultiViewConfig = '???', calibration: Dict[str, str] = '???', keypoints: List[cheese3d.config.KeypointConfig] = '???', keypoint_groups: List[cheese3d.config.KeypointGroupConfig] = '???', ignore_keypoint_labels: List[str] = '???')

Bases: object

static build_regex(regex)

calibration: Dict[str, str] = '???'

classmethod default(skip_model=False)

ephys_param: Dict[str, Any] | None = None

ephys_regex: Any | None = None

ephys_root: str | None = None

fps: int = 100

ignore_keypoint_labels: List[str] = '???'

keypoint_groups: List[KeypointGroupConfig] = '???'

keypoints: List[KeypointConfig] = '???'

classmethod load(cfg_file: str | Path, cfg_dir: str | Path | None = None, overrides: List[str] | None = None)

model: ModelConfig = '???'

model_root: str = 'model'

name: str = '???'

sessions: List[Dict[str, str]] = '???'

sync: SyncConfig = '???'

triangulation: TriangulationConfig = '???'

video_regex: Any = '???'

video_root: str = 'videos'

views: MultiViewConfig = '???'

class cheese3d.config.SixCamViewConfig

Bases: MultiViewConfig

class cheese3d.config.TriangulationConfig(axes: List[List[str]] = '???', ref_point: str = '???', filter2d: bool = False, score_threshold: float = 0.9)

Bases: object

axes: List[List[str]] = '???'

filter2d: bool = False

ref_point: str = '???'

score_threshold: float = 0.9

class cheese3d.config.VideoConfig(view: str = '???', crop: ~typing.List[int | None] = <factory>, extra_crops: ~typing.Dict[str, ~typing.List[int | None]] | None = None)

Bases: object

Structured config specification for a single camera recording.

Arguments: - path: a regex string that identifies videos recorded by this camera from filenames - crop: a bounding box of the form (xstart, xend, ystart, yend)

where any coordinate maybe set to None to accept the full bounds

• extra_crops: a dictionary of bounding boxes structured similar to crop

as_list()

crop: List[int | None]

extra_crops: Dict[str, List[int | None]] | None = None

get_crop(crop='default') → List[int | None]

view: str = '???'

cheese3d.config.keypoints_by_group(keypoints: List[KeypointConfig])

cheese3d.utils

class cheese3d.utils.VideoFrames(path, shift=0, bounds=[None, None, None, None])

Bases: object

A (potentially time shifted) video indexed by frames for a recording session cropped to a bounding box region.

Arguments: - path: a path to the video file - shift = 0: the +/- shift in units of video frames - bounds = [None, None, None, None]: a tuple of the form

[xstart, xend, ystart, yend] (set any element to None to use the max bounds)

static get_dims(path: str | Path)

opencv_capture()

shifted_index(i)

cheese3d.utils.cropframe(image, crop_coords)

cheese3d.utils.dlc_folder_to_components(folder: str | Path)

cheese3d.utils.get_group_pattern(regex: str, group_name: str)

Return the raw regex subpattern text for the named group group_name, if present. Supports common syntaxes:

• (?P<name>…)

• (?<name>…)

• (?’name’…)

Handles nesting, escapes, character classes, and (?#…) comments. Returns None if the named group is not found or is malformed.

cheese3d.utils.maybe(this, that)

cheese3d.utils.read_3d_data(data_dir: str | Path, extra_cols=None)

Load 3D landmark data from Anipose.

### Arguments - data_dir: the Anipose directory for the video to load - extra_cols: optional, a list of extra columns to include in the output

where each extra column is a string appended to a landmark name (e.g. “error” in this list becomes “lowerlip_error” for the 3D CSV header)

### Returns A dictionary of 3D data where each key is a landmark name and the associated value is an array of shape (time, 3). If extra_cols is provided, an additional dictionary is returned where each entry corresponds to an extra column and the value is dictionary of landmarks to arrays of shape (time,).

cheese3d.utils.reglob(pattern, path=None, recursive=False)

glob a filesystem using regex patterns.

Arguments: - pattern: a regex pattern compatible with Python’s re - path: the root under which to search - recursive: set to true to search the path recursively

cheese3d.utils.relative_path(path: str | Path, start: str | Path)

cheese3d.utils.tiny_cmap(center, delta, n)

cheese3d.utils.unzip(iter)

cheese3d.cli

cheese3d.cli.analyze(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76977ce1a0>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76977cc2e0>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76977cd000>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76977cf9d0>] | None = None)

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

cheese3d.cli.calibrate(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976b9c00>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976ba8f0>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b99f0>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976bb9d0>] | None = None)

Extract camera calibration for triangulation.

cheese3d.cli.extract(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976ba380>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b9a80>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b9060>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976b9120>] | None = None, manual: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7f76976b8cd0>] = False)

Extract frames from video data.

cheese3d.cli.generate_videos(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76977cf970>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76977cd450>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76977ce020>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76977cdcf0>] | None = None)

Generate videos with pose estimation results overlaid.

cheese3d.cli.import_model(model: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976ba050>], name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976b9b40>] = '.', model_type: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb760>] = 'dlc', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb460>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b9ba0>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976b9db0>] | None = None)

Import an existing pose model project into NAME.

cheese3d.cli.interactive(web: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7f76977ceb00>] = False)

Run interactive GUI.

cheese3d.cli.label(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976b94e0>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b8b80>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976ba200>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976b8580>] | None = None)

Label extracted frames for model training.

cheese3d.cli.setup(name: str, path='/home/runner/work/cheese3d/cheese3d/docs')

Setup a new Cheese3D project called NAME under –path.

cheese3d.cli.summarize(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976ba6e0>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b95d0>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b8340>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976bbbb0>] | None = None)

Summarize a Cheese3D project based on its configuration file.

cheese3d.cli.sync(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976bba90>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976b86a0>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb670>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976b9390>] | None = None)

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

cheese3d.cli.track(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976b8b20>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb550>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb610>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976b8610>] | None = None)

Track 2D keypoints using trained pose estimation model.

cheese3d.cli.train(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976b8700>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb340>] = '/home/runner/work/cheese3d/cheese3d/docs', gpu: ~typing.Annotated[int, <typer.models.OptionInfo object at 0x7f76976ba290>] = 0, configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976ba560>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976bbee0>] | None = None)

Train 2d pose model.

cheese3d.cli.triangulate(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76976b8a60>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bbcd0>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76976bb190>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76976ba590>] | None = None)

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

cheese3d.cli.visualize(name: ~typing.Annotated[str, <typer.models.ArgumentInfo object at 0x7f76977cc4c0>] = '.', path: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76977cc3a0>] = '/home/runner/work/cheese3d/cheese3d/docs', configs: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7f76977cc7f0>] = 'configs', config_overrides: ~typing.Annotated[~typing.List[str] | None, <typer.models.ArgumentInfo object at 0x7f76977cf1c0>] | None = None)

Visualize the output of Cheese3D using interactive GUI.