Skip to content

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

  1. Download the app for your system from the latest release:

    System File Install
    macOS animalpose-gui-v<version>-macos-aarch64.dmg open it and drag AnimalPose to Application
    Windows animalpose-gui-v<version>-windows-x86_64.zip extract the folder run animalpose-gui.exe
    Ubuntu, Debian animalpose-gui_<version>_amd64.deb (or arm64) sudo apt install ./animalpose-gui_<version>_amd64.deb
    Fedora, RHEL animalpose-gui-<version>-1.x86_64.rpm sudo dnf install ./animalpose-gui-<version>-1.x86_64.rpm
    Other Linux animalpose-gui-v<version>-linux-x86_64.tar.gz extract and run animalpose-gui
  2. The app creates its library in ~/AnimalPose and installs the sample profiles. Pick a profile in the sidebar, or keep the default to use the general models.

  3. 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/ with tracks.csv, behavior.csv and overlay.mp4; see Results.

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

  1. Download animalpose-v<version>-<platform> and animalpose-models-v<version>.zip from the release.
  2. Extract the models zip into ~/.animalpose (on Windows, %USERPROFILE%\.animalpose):

    mkdir -p ~/.animalpose && unzip animalpose-models-v<version>.zip -d ~/.animalpose
    

    With the Linux desktop package installed, the command line uses its models and this step is not needed.

  3. Check it, then analyze a video:

    animalpose predict --synthetic --max-frames 30 --out demo          # a rendered two-mouse clip
    animalpose predict --video myvideo.mp4 --out outputs/myvideo
    

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:

from animalpose import api

api.predict(video="myvideo.mp4", out="outputs/run")

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.

  1. Calibrate once, see help animalpose data calibrate --help. Keep the cameras where they are afterwards.
  2. 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 in cams.json) and put a session's videos in one folder.
  3. Process the folder. Each folder is fused into animals3d.npz with 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:

animalpose assay --config configs/assay_example.yaml --analysis outputs/run1 outputs/run2

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