MoCap Processing Application (Bogna)

Python application for processing marker-based mouse motion capture data from Qualisys Track Manager (QTM): load .mat exports, trim, compute general locomotion and step kinematics, and export for collaborators.

→ For detailed step-by-step install and run instructions (including for new machines and AI agents), see INSTALL_AND_RUN.md.

References

• Paper: eNeuro 2025 — Ignatowska-Jankowska et al., Accurate tracking of locomotory kinematics in mice moving freely in three-dimensional environments.
• Data: Zenodo 15493339, Code: GitHub nRIM-OIST/Marker-based-Mouse-MoCap-eNeuro-2025.

Installation from a private GitHub repository

A good way to set up the app on another computer (e.g. for a colleague) is to use a private GitHub repository:

1. Create the repo (on GitHub: New repository → Private → do not add a README if you already have one).
2. Push this project (from your machine): see step-by-step in the repo or below.
3. Colleague: clone and install (on the other computer):

   git clone https://github.com/kirillmitrofanov/mocap-app.git
   cd mocap-app
   conda env create -f environment.yml
   conda activate app
   pip install -e .

4. Data: The repo does not include data/ or results/ (they are in .gitignore). Your colleague should place their Qualisys .mat files in a folder (e.g. data/my_study/) or pass any path to --input when running batch. You can share sample data via Zenodo, Dropbox, or another channel.

After that, they can run python -m mocap_app batch --config config/default.yaml --input <path> --output results/run1 and python -m mocap_app view --output results/run1.

Setup (local development)

Use the conda environment app:

conda env create -f environment.yml   # first time
conda activate app

Install the package in development mode (from repo root):

pip install -e .

Or add the src directory to PYTHONPATH when running or testing.

Usage

• Load a Qualisys .mat file:

from mocap_app.io import load_qualisys_mat

data = load_qualisys_mat("data/test1/INH1A_open_field_proc/INH1A_S1_M1_MC6_FL2_17_04_2019_proc_bij_6_08_19_A.mat")
# data.data: (n_markers, 4, n_frames), data.labels, data.frame_rate, data.n_frames

• Trim (e.g. drop first 5 s, use 60 s):

from mocap_app.preprocess.trim import trim_trajectories

trimmed = trim_trajectories(data, drop_first_seconds=5.0, max_duration_seconds=60.0)

• General locomotion (speed, distance):

from mocap_app.locomotion.general import center_of_mass, compute_speed, compute_distance

com = center_of_mass(trimmed, marker_names=["left_coord", "right_coord", "left_hip", "right_hip", "left_back", "right_back"])
speed = compute_speed(com, trimmed.frame_rate, smooth_frames=9)
dist_cum, total_mm = compute_distance(speed, trimmed.frame_rate)

• Step detection and kinematics:

from mocap_app.steps.detection import detect_steps_ankle_vertical_velocity
from mocap_app.steps.kinematics import step_kinematics

events = detect_steps_ankle_vertical_velocity(trimmed, ankle_markers=["left_ankle", "right_ankle"])
steps_df = step_kinematics(trimmed, events, ["left_ankle", "right_ankle"])

• Full pipeline (single file) and batch processing:

from mocap_app.pipeline import run_pipeline

results = run_pipeline("path/to/file.mat", config_path="config/default.yaml")
# results: data, com, speed, step_events, step_kinematics, trial_summary, ...

# Batch: process all .mat files in a folder (or a single file)
conda activate app
python -m mocap_app batch --config config/default.yaml --input data/test1/INH1A_open_field_proc --output results/my_run

# Skip tremor-format export
python -m mocap_app batch --input data/test1/INH1A_open_field_proc --output results/my_run --no-tremor

Expected output files (after batch):

File or folder	Description
trial_summary.csv	One row per trial: source_file, total_distance_mm, mean_speed_mm_s, duration_s, n_steps_*, mean_stride_length_mm, etc. Open in Excel or any spreadsheet.
report.txt	Run summary: command, config, input/output paths, file counts, and how to view results.
processed_mat/*.mat	One .mat per input. For MATLAB: trajectories, speed_mm_s, distance, step events (ev_), step kinematics (sk_), trial summary (ts_*). Load with load('...mat'); use m.processed.
step_kinematics/*_steps.csv	Per-trial step table (when steps were detected): marker, step_idx, stride_length_mm, stance/swing duration, step_frequency_hz.
cleaned_tremor/*_cleaned_tremor.mat	For tremor pipeline: cleaned_data, labels, sampling_rate. Omitted if you use --no-tremor.

How to view results (Python interface):

# Print report.txt and open an HTML report in your browser
python -m mocap_app view --output results/my_run

# Generate report.html but do not open the browser
python -m mocap_app view --output results/my_run --no-open

The view command prints the text report, shows a preview of trial_summary.csv, and generates report.html in the same folder. Opening report.html in a browser gives you a readable trial summary table and the list of output files. You can also open trial_summary.csv directly in Excel.

Project layout

• INSTALL_AND_RUN.md — Detailed install and run instructions (for humans and automated agents).
• docs/IMPLEMENTATION_PLAN.md — Full implementation plan and phase breakdown.
• config/default.yaml — Default trim and marker config.
• src/mocap_app/ — Package: io, preprocess, locomotion, steps, export, cli, report.
• tests/ — Pytest tests (use data/test1 for integration tests).

Tests

From repo root with conda activate app:

pytest tests/ -v

Test data is under data/test1/ (processed and unprocessed .mat files).

License

Compatible with the eNeuro 2025 repository (MIT for code, CC BY for data). See the paper and Zenodo/README for citation.