Clone OpenCap IK Data with Other Video-based Markerless Solutions

This repository provides a MATLAB script to generate Inverse Kinematics (IK) results in OpenSim using .trc marker data exported from alternative video-based markerless motion capture solutions, e.g., CameraHMR.

The script mirrors the OpenCap folder structure, integrates external marker data, and reproduces an OpenSim scaling + IK pipeline for direct comparison to OpenCap results.

---

Features

• Automatically searches for MarkerData_* subfolders (e.g., MarkerData_cameraHMR) inside an OpenCap results folder.
• Creates a cloned copy of the original OpenCap folder tree, tagged with the chosen suffix (e.g., _cameraHMR).
• Runs a two-step OpenSim workflow:
  1. Scaling of the subject-specific musculoskeletal model.
  2. Inverse Kinematics (IK) for all dynamic trials.
• Produces comparable kinematics to OpenCap using predefined XML setup files.

---

Folder Structure

OpenCapProject/
│
├─ Subject01/
│   ├─ MarkerData/               # Original OpenCap marker data
│   ├─ MarkerData_cameraHMR/     # Alternative markerless solution (.trc files)
│   └─ sessionMetadata.yaml      # Subject metadata

When the script runs, a cloned folder (e.g., Subject01_cameraHMR/) will be created containing OpenSim outputs:

• Model/ → Scaled model and geometry
• Kinematics/ → IK results for all dynamic trials
• _input/ → Setup files used during processing

---

Requirements

• MATLAB (tested with R2023b or later)
• OpenSim installed and accessible via opensim-cmd
• OpenCap results folder containing at least:
  • MarkerData/ (original OpenCap data)
  • sessionMetadata.yaml (with subject mass information)
• .trc files from another markerless motion capture solution stored in a MarkerData_* folder.

Optional:

• SMPL to TRC Converter if starting from SMPL meshes.

---

Usage

1. Clone or download this repository.

2. Edit the User Settings section in the script:

   %% === User Settings ==================================
   opencapBaseFolder = 'D:\Testfolder\';
   dataTag = 'cameraHMR'; % or 'moverse'

3. Run the script in MATLAB.

4. Processed results will be created in a cloned folder:

   'D:\Testfolder_cameraHMR\'
   

---

Notes

• The static trial is expected to be named neutral.trc.
• The script automatically edits OpenSim setup XML files (scaling, IK).
• Log files and scaled models are written into the cloned folder structure.
• You can modify the used model or marker set inside the Hardcoded Settings section and the input xml settings file located in the setupFiles folder(s).

---

Contact

Developed by Brian Horsak
FH St. Pölten, Center for Digital Health and Social Innovation
Email: brian.horsak@fhstp.ac.at

---

Citation

Please cite the following reference(s) if you use this code:

Horsak, B., Simonlehner, M., Quehenberger, V., Dumphart, B., Slijepčević, D., Kranzl, A., 2025. A gait lab in your pocket? Accuracy and reliability of monocular smartphone-based markerless 3D gait analysis in pathological gait. Gait & Posture, ESMAC 2025 Abstract 121, 91–92. https://doi.org/10.1016/j.gaitpost.2025.07.102

@article{horsakGaitLabYour2025,
  title = {A Gait Lab in Your Pocket? {{Accuracy}} and Reliability of Monocular Smartphone-Based Markerless {{3D}} Gait Analysis in Pathological Gait},
  shorttitle = {A Gait Lab in Your Pocket?},
  author = {Horsak, Brian and Simonlehner, Mark and Quehenberger, Viktoria and Dumphart, Bernhard and Slijep{\v c}evi{\'c}, Djordje and Kranzl, Andreas},
  year = {2025},
  journal = {Gait \& Posture},
  series = {{{ESMAC}} 2025 {{Abstract}}},
  volume = {121},
  pages = {91--92},
  issn = {0966-6362},
  doi = {10.1016/j.gaitpost.2025.07.102}
}