AquaPose

tests docs coverage python pypi license

Measuring 3D fish posture and kinematics in a water tank is hard because the air-water interface refracts every camera ray, so ordinary multi-view triangulation is systematically wrong. AquaPose corrects for that: it takes synchronized multi-view video from a 12-camera aquarium rig and a refractive calibration and reconstructs per-fish 3D midlines across frames — arc-length-sampled anatomical keypoints triangulated and optionally spline-fitted — producing dense 3D trajectories and midline kinematics. It is built for behavioral and neuroscience researchers running multi-camera aquarium rigs who have video plus a calibration and want quantitative 3D posture out, as used for cichlid behavioral research.

Pipeline

AquaPose processes multi-view video through a 5-stage pipeline:

  1. Detection — YOLO-based fish detection (standard or oriented bounding boxes)
  2. Tracking — Per-camera 2D temporal tracking via OC-SORT
  3. Association — Cross-camera tracklet association using ray-ray geometry and Leiden clustering
  4. Midline — 2D midline extraction via YOLO-seg or YOLO-pose backends
  5. Reconstruction — DLT triangulation of 2D midlines into 3D B-spline midlines

Long videos are processed in fixed-size temporal chunks with identity continuity across chunk boundaries.

Quick Start

pip install aquapose

PyTorch is not pinned by this install; see the Installation page for the platform-specific PyTorch step before running the pipeline.

# Scaffold a project under ~/aquapose/projects/my_project
aquapose init my_project

# Run the pipeline against it
aquapose -p my_project run

To see it run end to end against real data, follow the Tutorial, which walks a full pipeline run against the published tutorial dataset (10.5281/zenodo.22264079).

Documentation

Full documentation is at aquapose.readthedocs.io:

Citation

If you use AquaPose in your research, please cite the software via CITATION.cff or GitHub's "Cite this repository" button on the repository page. This is distinct from citing the tutorial dataset (10.5281/zenodo.22264079): cite the software when you mean the AquaPose codebase, and cite the dataset when you mean the sample data it ships with.

License

AquaPose is licensed under AGPL-3.0-or-later. See LICENSING.md for why.

Project links

Data verified by PyPI on Sep 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for ptmcgrat from gravatar.com ptmcgrat Avatar for tlancaster6 from gravatar.com tlancaster6

Credits

Author: Tucker Lancaster

GitHub Statistics

Data verified by PyPI on Sep 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

AGPL-3.0-or-later
View SPDX License List

Requires

Python >=3.11

Tags

3d-reconstruction behavioral-neuroscience computer-vision differentiable-rendering fish pose-estimation pytorch

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aquapose-4.0.0.tar.gz (813.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

aquapose-4.0.0-py3-none-any.whl (421.2 kB view details)

Uploaded Python 3

File details

Details for the file aquapose-4.0.0.tar.gz.

File metadata

  • Download URL: aquapose-4.0.0.tar.gz
  • Upload date:
  • Size: 813.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for aquapose-4.0.0.tar.gz
Algorithm Hash digest
SHA256 373ed87fa14554b6b23beb148a671e4308ca4a7baa7510459969b7788bb88960
MD5 0322204de9e6f3f431d78a6e3eaf722f
BLAKE2b-256 dea94a45e5b573c6cb6242ceb9a1415af744c226fea8883ef3c797607651f2e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for aquapose-4.0.0.tar.gz:

Publisher: publish.yml on McGrathLab/AquaPose

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file aquapose-4.0.0-py3-none-any.whl.

File metadata

  • Download URL: aquapose-4.0.0-py3-none-any.whl
  • Upload date:
  • Size: 421.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for aquapose-4.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9fed57710068645987cde9ad35a0a319324d8ed065afe81e498c5e5d21cda05c
MD5 64acbc395bf6900c4f401a91bcc9536f
BLAKE2b-256 f20004ea5b1a89f957a26400b259d2d5dd17e5c969106815c12a26ad75e5a3e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for aquapose-4.0.0-py3-none-any.whl:

Publisher: publish.yml on McGrathLab/AquaPose

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

4.0.0 This release

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page