Quick start guide
Install FFmpeg
| System | Install |
|---|---|
| macOS | brew install ffmpeg |
| Windows | Copy ffmpeg.exe and ffprobe.exe into the same directory as the app |
| Ubuntu, Debian | sudo apt install ffmpeg |
| Fedora | sudo dnf install ffmpeg from RPM Fusion (Fedora's own ffmpeg-free works, but writes overlay.mp4 as MPEG-4 instead of H.264) |
Desktop app
-
Download the app for your system from the latest release:
System File Install macOS animalpose-gui-v<version>-macos-aarch64.dmgopen it and drag AnimalPoseto ApplicationWindows animalpose-gui-v<version>-windows-x86_64.zipextract the folder run animalpose-gui.exeUbuntu, Debian animalpose-gui_<version>_amd64.deb(orarm64)sudo apt install ./animalpose-gui_<version>_amd64.debFedora, RHEL animalpose-gui-<version>-1.x86_64.rpmsudo dnf install ./animalpose-gui-<version>-1.x86_64.rpmOther Linux animalpose-gui-v<version>-linux-x86_64.tar.gzextract and run animalpose-gui -
The app creates its library in
~/AnimalPoseand installs the sample profiles. Pick a profile in the sidebar, or keep the default to use the general models. -
To process recorded videos, drop a video (or a folder of videos), choose where results go, press Process. Each video generates a folder
<video name>-analysis/withtracks.csv,behavior.csvandoverlay.mp4; see Results. -
To record, open Live, tick the cameras, press Preview, then Record (or Timed for the profile's stages). See Desktop app for details.
Command line
- Download
animalpose-v<version>-<platform>andanimalpose-models-v<version>.zipfrom the release. -
Extract the models zip into
~/.animalpose(on Windows,%USERPROFILE%\.animalpose):With the Linux desktop package installed, the command line uses its models and this step is not needed.
-
Check it, then analyze a video:
animalpose <command> --help lists all command's options. The commands are summarized in Command line.
Python
The package does not include the models. It requires configs/pipeline.yaml and the weights/ it names from the current folder. Run it in a folder where you extracted
animalpose-models-v<version>.zip。
Install from PyPI:
pip install animalpose # Python 3.10+; installs PyTorch if it is missing
unzip animalpose-models-v<version>.zip -d animalpose-models && cd animalpose-models
animalpose predict --video ../myvideo.mp4 --out run
Install it from source:
git clone https://github.com/MarkSong535/animalpose && cd animalpose
git lfs pull # the general weights are stored with Git LFS
pip install -e ".[dev]"
From Python:
Optional extras: animalpose[behavior] (behavior clustering), [plot] (ethograms), [export]
(ONNX), [real] (public dataset converters).
Multiview
A multi-camera setup needs a camera model to fuse the views.
- Calibrate once, see help
animalpose data calibrate --help. Keep the cameras where they are afterwards. - In the app: Settings → Profiles → Camera Model → Import… your
cams.json. Name each video after its camera (Camera 1.mp4,Camera 2.mp4, or the names incams.json) and put a session's videos in one folder. - Process the folder. Each folder is fused into
animals3d.npzwith per-view tracks.
Small camera movements between sessions are corrected automatically from each camera's background; see Multiview.
An experiment's measures (assay)
Select an experiment in the profile's config, or add an assay: section to your config. Results
generate an assay/ folder with per-frame states and one row of measures per session (time in zones,
entries, distance, contact, grooming bouts, …).
To rescore finished analyses with new thresholds, without running the networks again:
See Assay and Adding an experiment setup.
Troubleshooting
| Message | Fix |
|---|---|
| "cannot run ffmpeg" / Process is disabled | install FFmpeg (above), or put ffmpeg and ffprobe in the same directory as the app |
| "… is a git-lfs pointer" | run git lfs pull in the checkout |
| "the detector checkpoint … has SHA-256 …" | the file differs from the one the config names under checksums:; download it again |
| no animals found | lower pipeline.det_thresh (default 0.3), and check the animals are not much smaller in the frame than in the training data |
| identities swap between animals | set tracker.max_animals to the number of animals |