Skip to content

Configuration

Every run reads one pipeline config, a YAML file: which networks to load, how detection, tracking and smoothing behave, how multiview cameras are corrected, and which experiment rules to score. The Python package and the Rust program read the same files.

← Overview · Backend

Which config is used

Program Default
animalpose predict (Rust) configs/pipeline.yaml in the current folder, else the one shipped with the program (beside it, in the macOS app's Resources, or in a Linux package's /usr/share/animalpose), else ~/.animalpose/configs/pipeline.yaml, else the checkout's
animalpose predict (Python) configs/pipeline.yaml relative to the current folder
Desktop app the profile's config; the default pipeline is the shipped pipeline.yaml

--config <file> picks another. Checkpoint paths inside a config are relative to the current folder. The Rust program and the apps then also look beside the config and, when the config sits in a configs/ folder, in the folder above it, so a configs/ + weights/ pair works wherever it is copied.

Inheritance and overrides

A config can build on others with extends::

# configs/my_lab.yaml
extends: pipeline.yaml          # one file or a list, relative to this file
pipeline:
  det_thresh: 0.25              # mappings merge key by key; other values replace the base's
tracker:
  max_animals: 2

Any key can also be set on the command line, after the other arguments, as block.key=value:

animalpose predict --video clip.mp4 --out run tracker.max_animals=2 drift.enabled=false

Values are read as YAML (true, 0.4, [480, 640]). The Python package rejects a key it does not know and suggests the nearest valid name, so a typo never silently runs with defaults; check spelling carefully with the Rust program, which ignores unknown keys.

Blocks

checkpoints and checksums

checkpoints:
  detector: weights/detector_general.pt   # required
  pose: weights/pose_general.pt           # required; ResNet-18
  temporal: weights/temporal_general.pt   # optional: refinement of each track
  behavior: weights/behavior_general.pt   # optional: 7 behavior classes including "other"
checksums:                                # optional: SHA-256 each file must have
  detector: 0a1b…

Checkpoints may be PyTorch .pt files or .safetensors. With checksums, a file whose SHA-256 differs stops the run before any video is read.

pipeline

Key Default Meaning
det_size [256, 320] detector input (height, width), multiples of 32; larger finds smaller animals, slower
det_thresh 0.3 detection score needed to keep an animal
max_det 20 detections kept per frame at most
crop_size 192 the square crop the pose network sees, in pixels
crop_padding 1.25 crop size relative to the detected box
kp_conf_thresh 0.3 keypoints below this confidence are treated as unseen
pair_decoding true keep left/right keypoint pairs on different heatmap peaks
pair_identity true fix left/right swaps along each track
embedder model appearance used to re-identify animals: model (pose-network features), color, none
temporal_window 64 frames the temporal network sees at once
background_filter false fixed camera: drop detections that look like the static background
detector_candidates [network] add blob to also propose boxes from the silhouette against the background
behavior_conf 0.6 below this, a frame's behavior is other
behavior_smooth 5 moving-median window over behavior labels, in frames

configs/pipeline_robust.yaml is an example for poor recordings (blurry, small animals): larger det_size, lower det_thresh, background filtering and blob candidates.

tracker

Key Default Meaning
high_thresh 0.5 detections above this start and continue tracks
low_thresh 0.2 detections between the two only continue existing tracks
max_animals null the number of animals; set it to forbid new identities
max_lost 90 frames a track survives without a match

See Backend → Tracking for the rest.

drift

How multiview cameras are re-registered against their reference pictures before fusion (Multiview → Camera drift). These keys set how the registration runs, not how far a camera may move.

Key Default Meaning
enabled true correct drift before fusing
coarsest 64 width of the smallest pyramid level, in pixels
iterations 30 refinement steps per level
samples 40000 pixels used per level at most
huber 1.345 robust weighting, so moved objects count less than walls and desk

assay

The experiment and its rules. Every key at its default is in configs/assay_example.yaml; a summary:

assay:
  experiment: open_field          # open_field | plus_maze | three_chamber | grooming, or your own
  modules: [open_field, grooming, rearing]   # the experiment's preset when left out
  priority: [mutual_contact, social, grooming, rearing]
  arena: {rig: open_field}        # arena layouts are cached as zones/<rig>.json
  contact: {dist_bl: 0.05, facing_deg: 60, min_bout_s: 0.2}
  openfield: {center_frac: 0.5}
  groom: {min_bout_s: 1.5}
  rear: {nose_z_bl: 0.65}

Distances are in body lengths (BL: the median nose-to-tail-base length while walking) or a share of the arena, never pixels, so the same thresholds work at any camera distance. Adding an experiment is described in Adding an experiment setup.

Shipped configs

File Use
configs/pipeline.yaml the default: general networks
configs/pipeline_robust.yaml poor recordings: larger input, background filtering
configs/assay_example.yaml pipeline.yaml plus every assay: key at its default
configs/detector.yaml, pose.yaml, temporal.yaml, temporal3d.yaml, behavior.yaml, behavior3d.yaml training configs for each network (Training)
configs/arenas/*.yaml arena definitions (Adding an experiment setup)

In the desktop app, Settings → Configs edits these blocks with controls; the shipped pipeline is read-only, so duplicate it first.