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.
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:
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.