This repository contains the analysis and reproducibility pipeline for the FreeMoCap validation study. Simply put, this pipeline makes transparent all of the analyses used for the gait and standing balance analyses in the paper, and will also regenerate the figures and tables reported in the study from the publicly released validation dataset.
We can roughly break this into three main components: 1. The validation dataset; 2. The analysis pipeline; and 3. The figure and table generation scripts.
The first step in reproducing the validation study is to download the public validation dataset.
The public validation dataset contains the derived 3d data from six participants, each completing:
- Two treadmill gait trials containing multiple walking-speed conditions
- Two standing balance trials containing Eyes Open/Closed × Solid/Foam conditions
This results in 24 trials in total.
For each trial, aligned 3D trajectory data are provided for:
- MediaPipe-derived 3D trajectories
- RTMPose-derived 3D trajectories
- ViTPose-derived 3D trajectories
- Qualisys marker-based reference
Within each tracking system, the canonical input file is:
aligned_3d_data/
└── freemocap_data_by_frame.parquet
The dataset does not include raw video recordings or directly identifying participant information.
The public dataset is archived on Zenodo:
FreeMoCap Validation Dataset: Multi-Camera Markerless Motion Capture of Treadmill Gait and Standing Balance
Version: 1.0
DOI: 10.5281/zenodo.23041223
Located in the validation/ directory, the validation analysis pipeline is what was used to analyze all of the gait and balance trials in the study.
The specific steps are different for each task, but in general the pipeline reads the aligned 3D trajectory data from the downloaded dataset and generates the derived gait and balance analysis outputs required by the study.
More specifically, for treadmill gait trials, the pipeline computes (per trial, per FreeMocap tracker):
- Joint angles
- Gait events (heel strikes and toe offs), which are used to define the gait cycle and compute gait metrics
- Spatio-temporal gait metrics
- Stride-level joint trajectories and stride-level joint angles
- RMSE between the FreeMoCap tracker and marker-based reference joint trajectories
For standing balance trials, the pipeline computes (per trial, per FreeMocap tracker):
- Postural sway metrics (e.g., center of mass path length, 95% confidence ellipse area, COM velocity)
The figure and table generation scripts are located in the plotting/ directory. These scripts read the outputs of the validation analysis pipeline and generate the figures and tables reported in the study.
Before generating figures and tables, the pipeline outputs are indexed in a local SQLite database (validation.db). This provides the plotting scripts with a consistent way to locate the analysis outputs generated across participants, trials, and tracking systems
This quick start goes over how to use this repository to download the dataset, run all the analyses, and regenerate all tables and figures.
- Git (or your preferred Github repo manager)
- uv
- Python 3.11
Clone the repository and enter the project directory:
git clone https://github.com/freemocap/validation.git
cd validationInstall the reproducible project environment:
uv syncDownload the public validation dataset (about 1.5GB) :
uv run validation download-dataRun the validation analyses:
uv run validation runNote: This step runs all of the gait and balance analyses for all six participants, across each of the four sets of 3D data. It may take about 20-30 minutes to fully finish all the analyses
Another note: The downloaded data is about 1.5GB. When all the analyses are run, it will be ~6GB total, so plan accordingly.
Build the artifact database used by the plotting scripts:
uv run validation build-dbGenerate all study figures and tables:
uv run validation plot-allThe complete reproduction workflow is therefore:
uv sync
uv run validation download-data
uv run validation run
uv run validation build-db
uv run validation plot-allThis workflow has been tested using version 1.0 of the published Zenodo dataset.
uv run validation download-dataDownloads the six participant archives from the published Zenodo record, verifies their SHA-256 checksums, and extracts them into:
freemocap_validation_dataset/
├── README.md
├── SHA256SUMS.txt
└── data/
├── sub-001/
├── sub-002/
├── sub-003/
├── sub-004/
├── sub-005/
└── sub-006/
By default, the dataset is downloaded into the root of the repository. The downloaded dataset is excluded from Git.
uv run validation runRuns the validation analysis pipeline across the trial configurations in configs/.
The pipeline reads the aligned 3D trajectory data from the downloaded dataset and generates the derived gait and balance analysis outputs required by the study.
By default, the command uses:
freemocap_validation_dataset/data/
as the dataset root.
uv run validation build-dbIndexes the generated validation artifacts into a local SQLite database:
validation.db
The database essentially keeps track of all the components generated by the analyses, makes sure that none are missing, and stores the path to those particular components (i.e., the actual data is not stored in the database, just a path to them). All the figures/tables will access this database to load the particular components they need. The dataset will be stored in the repository root as validation.db, and is excluded from Git.
uv run validation plot-allRuns the complete set of gait and balance plotting and table-generation scripts.
Generated study-level outputs are written under:
outputs/
├── figures/
├── tables/
└── analyses/
in the Github repostiory root. The outputs/ directory is excluded from Git.
Figures are saved without being displayed by default.
To display figures as they are generated (it's a lot of figures, be warned):
uv run validation plot-all --showTo generate only balance outputs:
uv run validation plot-all --section balanceTo generate only gait outputs:
uv run validation plot-all --section gaitFreeMoCap is a free and open-source multi-camera markerless motion-capture platform.
The FreeMoCap software release is archived on Zenodo:
DOI: 10.5281/zenodo.22131400
If you use the validation dataset, please cite the specific version of the Zenodo dataset used in your work:
FreeMoCap Validation Dataset: Multi-Camera Markerless Motion Capture of Treadmill Gait and Standing Balance. Version 1.0. DOI: 10.5281/zenodo.23041223
Citation information for the associated validation manuscript will be added when available.
The FreeMoCap Validation Dataset version 1.0 is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license. See the Zenodo record for dataset licensing information.