Multicamera Planning, Calibration & Triangulation Gui for Insect Tracking, Derived from Caliscope - Open Source Motion Capture
Calipod is derived from Caliscope, an open-source multicamera calibration and motion capture tool created by Mac Prible. Calipod extends the foundational calibration methodology with additional features for arena simulation, camera planning, detection filtering, YOLO detection loading, background subtraction support, and other optimizations for insect behaviour tracking. The underlying bundle adjustment and calibration algorithms are based on Caliscope's work, which is documented in the Caliscope JOSS publication.
Calipod extends Caliscope's core calibration with specialized features for multi-animal tracking workflows:
- Arena Simulation & Planning - Interactive 3D workspace design with triangulatable camera frustum overlap analysis
- Advanced Post-Processing - Trajectory smoothing, gap-filling, and Kalman filtering with customizable parameters
- YOLO Integration - Support for custom ground truth and detection predictions from YOLO detection systems
- Background Subtraction - Specialized processing for motion isolation workflows
- Full Tracking Pipeline Guidance - Step-by-step GUI workflow from calibration through post-processing
Calipod is a GUI-based multicamera planning, calibration and motion tracking package, designed for insect behaviour analysis. It provides tools for camera planning optimization, intrinsic and extrinsic camera calibration, and 3D landmark triangulation.
Calipod automates complex calibration functions while providing visual feedback regarding parameter estimates at each stage of processing. Sample implementations of a Tracker class using Google's Mediapipe demonstrate how to integrate full calibration results with landmark tracking tools to achieve 3D pose estimation. Mediapipe capabilities are retained in the tracking pipeline, allowing users to test their camera rig and calibration by tracking their hand before deploying to insect tracking. While Mediapipe has limitations, it demonstrates a data processing pipeline easily extensible with more powerful tracking tools.
For a detailed description of the calibration process and workflow, see the original Caliscope documentation. For a quick video walkthrough, check out Caliscope's sample project demonstration.
- Easy creation of
png/pdffiles for ChArUco calibration boards - Board definition can be changed across intrinsic and extrinsic calibration allowing greater flexibility
- Automated calculation of camera intrinsic properties from input video
- Optical Center
- Focal Length
- Lens Distortion
- Visualization of distortion model to ensure reasonableness
- Automated bundle adjustment to estimate 6 DoF relative position of cameras
- Visualizer to inspect the estimates from the bundle adjustment
- Setting of the World Origin within the visualizer to simplify data processing
- Tracker API for integrating alternate tracking methods
- 3 sample implementations with Google Mediapipe (Hands/Pose/Holistic)
- Automated application of landmark tracking to synchronized videos
- Triangulation of 3D landmark position based on calibrated cameras
- Output to
.trcfile format for use in biomechanical modelling - Output to tidy
.csvformat with well-labelled headers for straightforward integration with other workflows - Compatible with companion project Rigmarole (a Caliscope side-project for creating animated rigs in Blender)
- Interactive 3D workspace visualization for camera placement optimization
- Triangulatable camera frustum overlap analysis to identify recording zones with sufficient multi-camera coverage
- Workspace validation and planning before hardware deployment
- RTS (Rauch-Tung-Striebel) Kalman filtering for 3D trajectory smoothing
- Intelligent gap-filling to handle occlusion or tracking failures
- Configurable Kalman filter parameters (process noise and measurement uncertainty)
- Distance-based spatial filtering with gate distance and threshold customization
- Performance metrics and visualization for filter validation
- Integrated background subtraction processing for scenarios requiring motion isolation
- Specialized triangulation workers for background-subtracted tracking workflows
- Flexible calibration board configuration with custom PDF size selection
- Board parameter management for reproducible calibration across sessions
- Automatic saving of filter parameters and calibration metrics alongside processed data
- Enables reproducibility and detailed tracking of processing history
Calipod is compatible with Python 3.10 and 3.11. Please note that given the size of some core dependencies (OpenCV, Mediapipe, and PySide6 are among them) installation and initial launch can take a while.
sudo apt-get update
sudo apt-get install --fix-missing libgl1-mesa-dev
Windows:
cd path\to\your\project
Linux/macOS:
cd path/to/your/project
uv venv --python 3.11
Windows:
.\venv\Scripts\activate
Linux/macOS:
source .venv/bin/activate
With your virtual environment activated and in the calipod directory, install Calipod using uv:
uv pip install -e .
Installation may take a moment as some dependencies are large, but uv's performance makes this process significantly faster than traditional tools.
For help organizing your project, see the directory layout guide from the original Caliscope documentation (does not include annotation folder etc though, which is required for custom detection visualisation):
ProjectDirectory/
├── config.toml # Only contains default charuco board definition
├── calibration/
│ ├── intrinsic/
│ └── extrinsic/
├── annotations/
│ ├── ground_truth/ # Ground truth YOLO annotations
│ │ ├── port_1/
│ │ │ ├── labels/train/ [txt files in YOLO format]
│ │ ├── port_2/
│ │ │ ├── labels/train/ [txt files in YOLO format]
│ ├── predictions/ # Optional YOLO predictions from models
│ │ ├── port_1/
│ │ │ ├── labels/ [txt files in YOLO format]
│ │ ├── port_2/
│ │ │ ├── labels/ [txt files in YOLO format]
└── recordings/ # Empty by default prior to user populating data
├── recording_1
│ ├── port_1.mp4...
Calipod currently uses Google's Mediapipe for tracking, which provides a relatively easy and efficient method for pose estimation. However, Mediapipe has limitations for many applications. Following Caliscope's modular Tracker API, Calipod is designed to be extensible with more powerful tools such as MMPose and DeepLabCut as they are integrated in future updates.
To report a bug or request a feature, please open an issue.
Post any questions in the Discussions section of the repo.
Calipod extends and builds upon the work of Caliscope, created by Mac Prible as an alternative calibration tool within the broader ecosystem of motion capture software.
The original Caliscope project was inspired by FreeMoCap (FMC), which is spearheaded by Jon Matthis, PhD of the HuMoN Research Lab. The FMC calibration and triangulation system is built upon Anipose, created by Lili Karushchek, PhD. Caliscope was originally envisioned as an alternative calibration tool to Anipose that would allow more granular estimation of intrinsics as well as visual feedback during the calibration process. Several lines of the original Anipose triangulation code are used in this code base, though otherwise it was written from the ground up.
Calipod is licensed under the permissive BSD 2-Clause license, as is the original Caliscope project. This allows you to freely use, modify, and distribute Calipod, provided you retain the copyright and license notices.
Copyright holders:
- 2024: Donald "Mac" Prible (Caliscope)
- 2025-2026: Oakleigh Weekes (Calipod)
The triangulation function was adapted from the Anipose code base which is also licensed under the BSD-2 Clause. A primary dependency of this project is PySide6 which provides the GUI front end. PySide6 is licensed under the LGPLv3. Calipod does not modify the underlying source code of PySide6 which is available via PyPI.