deeperfly

Markerless 3D pose estimation of tethered Drosophila from a multi-camera rig. It estimates camera parameters and 2D/3D keypoint locations from behavioral recordings through one linear pipeline: 2D pose → bundle adjustment → triangulation → visualization.

deeperfly is both a command-line tool and a Python library, and a modern rewrite of DeepFly3D, DeepFly2D and PyBundleAdjustment.

📖 Documentation

Installation

Install the CLI with uv:

uv tool install git+https://github.com/NeLy-EPFL/deeperfly --python 3.13 --torch-backend=auto

--torch-backend=auto picks the right PyTorch wheel for your machine.

Development installation

To hack on deeperfly, install the CLI from a local clone in editable mode so your source changes take effect without reinstalling:

git clone https://github.com/NeLy-EPFL/deeperfly
cd deeperfly
uv tool install ./ --editable --python 3.13 --torch-backend=auto

See CONTRIBUTING.md for tests, linting, and the docs site.

Updating

Upgrade a normal install to the latest main:

uv tool upgrade deeperfly

For a development install, pull the latest source — editable code is picked up automatically. Re-run the install command only if dependencies changed:

git pull
uv tool install ./ --editable --python 3.13 --torch-backend=auto   # only if deps changed

Usage

deeperfly doctor                        # check installation
deeperfly init config.toml              # generate a config template
deeperfly run examples/data/ -c config.toml # run the pipeline
deeperfly inspect examples/data/deeperfly_outputs/results.h5   # summarize the result

deeperfly run does everything in one command: detect 2D pose in every view, bundle-adjust the cameras, triangulate to 3D, then render skeleton videos. By default, outputs land in recording/deeperfly_outputs/ (override with -o): results.h5, the rendered videos, and a snapshot of the config used. deeperfly doctor reports whether the detector will run on the GPU and where the weights are cached.

Documentation

Full docs are at nely-epfl.github.io/deeperfly:

• Getting started — run the bundled example end to end.
• CLI usage and Writing configs.
• How it works — the pipeline, stage by stage.
• Library API and the complete reference.
• CONTRIBUTING.md — development install, tests, linting.

License

GPL-3.0-only. See LICENSE.