pose2sim 0.4.8

Perform a markerless kinematic analysis from multiple calibrated views as a unified workflow from an OpenPose input to an OpenSim result.

Pose2Sim

News: Version 0.4 released:
Calibration used to be the main stumbling block for users: it should be easier and better now!
To upgrade, type pip install pose2sim --upgrade. You will need to update your User\Config.toml file.
N.B.: As always, I am more than happy to welcome contributors (see How to contribute).

Pose2Sim provides a workflow for 3D markerless kinematics, as an alternative to the more usual marker-based motion capture methods. It aims to provide a free tool to obtain research-grade results from consumer-grade equipment. Any combination of phone, webcam, gopro, etc can be used.

Pose2Sim stands for "OpenPose to OpenSim", as it uses OpenPose inputs (2D keypoints coordinates obtained from multiple videos) and leads to an OpenSim result (full-body 3D joint angles). Other 2D pose estimators can alternatively be used as inputs.

If you can only use one single camera and don't mind losing some accuracy, please consider using Sports2D.

Contents

1. Installation and Demonstration
   1. Installation
   2. Demonstration Part-1: Build 3D TRC file on Python
   3. Demonstration Part-2: Obtain 3D joint angles with OpenSim
2. Use on your own data
   1. Prepare for running on your own data
   2. 2D pose estimation
      1. With OpenPose
      2. With Mediapipe
      3. With DeepLabCut
      4. With AlphaPose
   3. Camera calibration
      1. Convert from Qualisys, Optitrack, Vicon, OpenCap, EasyMocap, or bioCV
      2. Calculate from scratch
   4. Camera synchronization
   5. Tracking, Triangulating, Filtering
      1. Associate persons across cameras
      2. Triangulating keypoints
      3. Filtering 3D coordinates
   6. OpenSim kinematics
      1. OpenSim Scaling
      2. OpenSim Inverse kinematics
      3. Command Line
   7. Batch processing
3. Utilities
4. How to cite and how to contribute
   1. How to cite
   2. How to contribute and to-do list

Installation and Demonstration

Installation

1. Install OpenPose (instructions there).
   Windows portable demo is enough.

2. Install OpenSim 4.x (there).
   Tested up to v4.4-beta on Windows. Has to be compiled from source on Linux (see there).

3. Optional. Install Anaconda or Miniconda.
   Open an Anaconda terminal and create a virtual environment with typing:

   conda create -n Pose2Sim python=3.8 -y 
   conda activate Pose2Sim

4. Install Pose2Sim:
   If you don't use Anaconda, type python -V in terminal to make sure python>=3.8 is installed.

   • OPTION 1: Quick install: Open a terminal.

     pip install pose2sim
     

   • OPTION 2: Build from source and test the last changes: Open a terminal in the directory of your choice and Clone the Pose2Sim repository.

     git clone --depth 1 https://github.com/perfanalytics/pose2sim.git
     cd pose2sim
     pip install .
     

Demonstration Part-1: Build 3D TRC file on Python

This demonstration provides an example experiment of a person balancing on a beam, filmed with 4 calibrated cameras processed with OpenPose.

Open a terminal, enter pip show pose2sim, report package location.
Copy this path and go to the Demo folder with cd <path>\pose2sim\Demo.
Type ipython, and test the following code:

from Pose2Sim import Pose2Sim
Pose2Sim.calibration()
Pose2Sim.personAssociation()
Pose2Sim.triangulation()
Pose2Sim.filtering()

You should obtain a plot of all the 3D coordinates trajectories. You can check the logs inDemo\Users\logs.txt.
Results are stored as .trc files in the Demo/pose-3d directory.

N.B.: Default parameters have been provided in Demo\User\Config.toml but can be edited.
N.B.: Try calibration tool by changing calibration_type to calculate instead of convert (more info there).

Demonstration Part-2: Obtain 3D joint angles with OpenSim

In the same vein as you would do with marker-based kinematics, start with scaling your model, and then perform inverse kinematics.

Scaling

1. Open OpenSim.
2. Open the provided Model_Pose2Sim_Body25b.osim model from pose2sim/Demo/opensim. (File -> Open Model)
3. Load the provided Scaling_Setup_Pose2Sim_Body25b.xml scaling file from pose2sim/Demo/opensim. (Tools -> Scale model -> Load)
4. Run. You should see your skeletal model take the static pose.

Inverse kinematics

1. Load the provided IK_Setup_Pose2Sim_Body25b.xml scaling file from pose2sim/Demo/opensim. (Tools -> Inverse kinematics -> Load)
2. Run. You should see your skeletal model move in the Vizualizer window.

Use on your own data

Deeper explanations and instructions are given below.

Prepare for running on your own data

Get ready.

1. Find your Pose2Sim\Empty_project, copy-paste it where you like and give it the name of your choice.

2. Edit the User\Config.toml file as needed, especially regarding the path to your project.

3. Populate the raw-2dfolder with your videos.

     Project
     │
     ├──opensim
     │    ├──Geometry
     │    ├──Model_Pose2Sim_Body25b.osim
     │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
     │    └──IK_Setup_Pose2Sim_Body25b.xml
     │        
     ├── raw
     │    ├──vid_cam1.mp4 (or other extension)
     │    ├──...
     │    └──vid_camN.mp4
     │
     └──User
         └──Config.toml
     
   
   

2D pose estimation

Estimate 2D pose from images with Openpose or another pose estimation solution.
N.B.: First film a short static pose that will be used for scaling the OpenSim model (A-pose for example), and then film your motions of interest.
N.B.: Note that the names of your camera folders must follow the same order as in the calibration file, and end with '_json'.

With OpenPose:

The accuracy and robustness of Pose2Sim have been thoroughly assessed only with OpenPose, and especially with the BODY_25B model. Consequently, we recommend using this 2D pose estimation solution. See OpenPose repository for installation and running.

• Open a command prompt in your OpenPose directory.
  Launch OpenPose for each raw image folder:

  bin\OpenPoseDemo.exe --model_pose BODY_25B --video <PATH_TO_PROJECT_DIR>\raw-2d\vid_cam1.mp4 --write_json <PATH_TO_PROJECT_DIR>\pose-2d\pose_cam1_json
  

• The BODY_25B model has more accurate results than the standard BODY_25 one and has been extensively tested for Pose2Sim.
  You can also use the BODY_135 model, which allows for the evaluation of pronation/supination, wrist flexion, and wrist deviation.
  All other OpenPose models (BODY_25, COCO, MPII) are also supported.
  Make sure you modify the User\Config.toml file accordingly.
• Use one of the json_display_with_img.py or json_display_with_img.py scripts (see Utilities) if you want to display 2D pose detections.

N.B.: OpenPose BODY_25B is the default 2D pose estimation model used in Pose2Sim. However, other skeleton models from other 2D pose estimation solutions can be used alternatively.

With MediaPipe:

Mediapipe BlazePose is very fast, fully runs under Python, handles upside-down postures and wrist movements (but no subtalar ankle angles).
However, it is less robust and accurate than OpenPose, and can only detect a single person.

• Use the script Blazepose_runsave.py (see Utilities) to run BlazePose under Python, and store the detected coordinates in OpenPose (json) or DeepLabCut (h5 or csv) format:

  python -m Blazepose_runsave -i rinput_file -dJs
  

  Type in python -m Blazepose_runsave -h for explanation on parameters.
• Make sure you changed the pose_model and the tracked_keypoint in the User\Config.toml file.

With DeepLabCut:

If you need to detect specific points on a human being, an animal, or an object, you can also train your own model with DeepLabCut.

1. Train your DeepLabCut model and run it on your images or videos (more instruction on their repository)
2. Translate the h5 2D coordinates to json files (with DLC_to_OpenPose.py script, see Utilities):

   python -m DLC_to_OpenPose -i input_h5_file
   

3. Edit pose.CUSTOM in User\Config.toml, and edit the node ids so that they correspond to the column numbers of the 2D pose file, starting from zero. Make sure you also changed the pose_model and the tracked_keypoint.
   You can visualize your skeleton's hierarchy by changing pose_model to CUSTOM and writing these lines:

    config_path = r'path_to_Config.toml'
    import toml, anytree
    config = toml.load(config_path)
    pose_model = config.get('pose').get('pose_model')
    model = DictImporter().import_(config.get('pose').get(pose_model))
    for pre, _, node in RenderTree(model): 
        print(f'{pre}{node.name} id={node.id}')
   

4. Create an OpenSim model if you need inverse kinematics.

With AlphaPose:

AlphaPose is one of the main competitors of OpenPose, and its accuracy is comparable. As a top-down approach (unlike OpenPose which is bottom-up), it is faster on single-person detection, but slower on multi-person detection.
All AlphaPose models are supported (HALPE_26, HALPE_68, HALPE_136, COCO_133, COCO, MPII).

• Install and run AlphaPose on your videos (more instruction on their repository)
• Translate the AlphaPose single json file to OpenPose frame-by-frame files (with AlphaPose_to_OpenPose.py script, see Utilities):

  python -m AlphaPose_to_OpenPose -i input_alphapose_json_file
  

• Make sure you changed the pose_model and the tracked_keypoint in the User\Config.toml file.

The project hierarchy becomes: (CLICK TO SHOW)

   Project
   │
   ├──opensim
   │    ├──Geometry
   │    ├──Model_Pose2Sim_Body25b.osim
   │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
   │    └──IK_Setup_Pose2Sim_Body25b.xml
   │
   ├──pose-2d
   │    ├──pose_cam1_json
   │    ├──...
   │    └──pose_camN_json
   │        
   ├── raw-2d
   │    ├──vid_cam1.mp4
   │    ├──...
   │    └──vid_camN.mp4
   │
   └──User
       └──Config.toml
   

Camera calibration

Calculate camera intrinsic properties and extrinsic locations and positions.
Convert a preexisting calibration file, or calculate intrinsic and extrinsic parameters from scratch.
N.B.: You can visualize camera calibration in 3D with my (experimental) Maya-Mocap tool.

Open an Anaconda prompt or a terminal, type ipython.
By default, calibration() will look for Config.toml in the User folder of your current directory. If you want to store it somewhere else (e.g. in your data directory), specify this path as an argument: Pose2Sim.calibration(r'path_to_config.toml').

from Pose2Sim import Pose2Sim
Pose2Sim.calibration()

Output:

Convert from Qualisys, Optitrack, Vicon, OpenCap, EasyMocap, or bioCV

N.B.: Since Pose2Sim uses the Aniposelib format, calibration does not need to be run if you already have an AniPose or FreeMocap calibration .toml file.

If you already have a calibration file, set calibration_type type to convert in your User\Config.toml file.

• From Qualisys:
  • Export calibration to .qca.txt within QTM.
  • Copy it in the calibration Pose2Sim folder.
  • set convert_from to 'qualisys' in your User\Config.toml file. Change binning_factor to 2 if you film in 540p.
• From Optitrack: Exporting calibration will be available in Motive 3.2. In the meantime:
  • Calculate intrinsics with a board (see next section).
  • Use their C++ API to retrieve extrinsic properties. Translation can be copied as is in your Calib.toml file, but TT_CameraOrientationMatrix first needs to be converted to a Rodrigues vector with OpenCV. See instructions here.
  • Use the Calib.toml file as is and do not run Pose2Sim.calibration()
• From Vicon:
  • Copy your .xcp Vicon calibration file to the Pose2Sim calibration folder.
  • set convert_from to 'vicon' in your User\Config.toml file. No other setting is needed.
• From OpenCap:
  • Copy your .pickle OpenCap calibration files to the Pose2Sim calibration folder.
  • set convert_from to 'opencap' in your User\Config.toml file. No other setting is needed.
• From EasyMocap:
  • Copy your intri.yml and extri.yml files to the Pose2Sim calibration folder.
  • set convert_from to 'easymocap' in your User\Config.toml file. No other setting is needed.
• From bioCV:
  • Copy your bioCV calibration files (no extension) to the Pose2Sim calibration folder.
  • set convert_from to 'biocv' in your User\Config.toml file. No other setting is needed.

Calculate from scratch

Calculate calibration parameters with a board, or with points (such as detected on a wand or a human body).

• With a board:

  N.B.: Try the calibration tool on the Demo by changing calibration_type to calculate in User\Config.toml.
  For the sake of practicality, there are voluntarily few board images for intrinsic calibration, and few points to click for extrinsic calibration. In spite of this, your reprojection error should be under 1-2 cm, which does not hinder the quality of kinematic results in practice.).

  • Calculate intrinsic parameters:

    N.B.: Intrinsic parameters: camera properties (focal length, optical center, distortion), usually need to be calculated only once in their lifetime. In theory, cameras with same model and same settings will have identical intrinsic parameters.
    N.B.: If you already calculated intrinsic parameters earlier, you can skip this step. Copy your intrinsic parameters (size, mat, and dist) in a new Calib*.toml file, and set overwrite_intrinsics to false. Run Demo to obtain an example Calib.toml file.

    • Create a folder for each camera in your calibration\intrinsics folder.
    • For each camera, film a checkerboard or a charucoboard. Either the board or the camera can be moved.
    • Adjust parameters in the User\Config.toml file.
    • Make sure that the board:
      is filmed from different angles, covers a large part of the video frame, and is in focus.
      is flat, without reflections, surrounded by a white border, and is not rotationally invariant (Nrows ≠ Ncols, and Nrows odd if Ncols even).
    • A common error is to specify the external, instead of the internal number of corners. This may be one less than you would intuitively think.
    

    Intrinsic calibration error should be below 0.5 px.

  • Calculate extrinsic parameters:

    N.B.: Extrinsic parameters: camera placement in space (position and orientation), need to be calculated every time a camera is moved. Can be calculated from a board, or from points in the scene with known coordinates.

    • Create a folder for each camera in your calibration\extrinsics folder.
    • Once your cameras are in place, shortly film either a board laid on the floor, or the raw scene
      (only one frame is needed, but do not just take a photo unless you are sure it does not change the image format).
    • Adjust parameters in the User\Config.toml file.
    • Then,
      • If you film a board:
        Make sure that it is seen by all cameras.
        It should preferably be larger than the one used for intrinsics, as results will not be very accurate out of the covered zone.
      • If you film the raw scene (more flexible and potentially more accurate if points are spread out):
        Manually measure the 3D coordinates of 10 or more points in the scene (tiles, lines on wall, boxes, treadmill dimensions, etc). These points should be as spread out as possible.
        Then you will click on the corresponding image points for each view.
    

    Intrinsic calibration error should be below 1 cm, but depending on your application, results will still be potentially acceptable up to 2.5 cm.

• With points:

  • Points can be detected from a wand.
    Want to contribute?
  • For a more automatic calibration, OpenPose keypoints could also be used for calibration.
    Want to contribute?

The project hierarchy becomes: (CLICK TO SHOW)

   Project
   │
   ├──calibration
   │   ├──intrinsics
   │   │  ├──int_cam1_img
   │   │  ├──...
   │   │  └──int_camN_img
   │   ├──extrinsics
   │   │  ├──ext_cam1_img
   │   │  ├──...
   │   │  └──ext_camN_img
   │   └──Calib.toml
   │
   ├──opensim
   │    ├──Geometry
   │    ├──Model_Pose2Sim_Body25b.osim
   │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
   │    └──IK_Setup_Pose2Sim_Body25b.xml
   │
   ├──pose-2d
   │    ├──pose_cam1_json
   │    ├──...
   │    └──pose_camN_json
   │        
   ├── raw-2d
   │    ├──vid_cam1.mp4
   │    ├──...
   │    └──vid_camN.mp4
   │
   └──User
       └──Config.toml
   

Camera synchronization

Cameras need to be synchronized, so that 2D points correspond to the same position across cameras.
N.B.: Skip this step if your cameras are already synchronized.

If your cameras are not natively synchronized, you can use this script.
Alternatively, use a clap, a flash, or a beep noise to synchronize them.

Tracking, Triangulating, Filtering

Associate persons across cameras

Track the person viewed by the most cameras, in case of several detections by OpenPose.
N.B.: Skip this step if only one person is in the field of view.
Want to contribute? Allow for multiple person analysis.

Open an Anaconda prompt or a terminal, type ipython.
By default, personAssociation() will look for Config.toml in the User folder of your current directory. If you want to store it somewhere else (e.g. in your data directory), specify this path as an argument: Pose2Sim.personAssociation(r'path_to_config.toml').

from Pose2Sim import Pose2Sim
Pose2Sim.personAssociation()

Check printed output. If results are not satisfying, try and release the constraints in the User\Config.toml file.

Output:

The project hierarchy becomes: (CLICK TO SHOW)

   Project
   │
   ├──calibration
   │   ├──intrinsics
   │   │  ├──int_cam1_img
   │   │  ├──...
   │   │  └──int_camN_img
   │   ├──extrinsics
   │   │  ├──ext_cam1_img
   │   │  ├──...
   │   │  └──ext_camN_img
   │   └──Calib.toml
   │
   ├──opensim
   │    ├──Geometry
   │    ├──Model_Pose2Sim_Body25b.osim
   │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
   │    └──IK_Setup_Pose2Sim_Body25b.xml
   │
   ├──pose-2d
   │   ├──pose_cam1_json
   │   ├──...
   │   └──pose_camN_json
   │
   ├──pose-2d-tracked
   │   ├──tracked_cam1_json
   │   ├──...
   │   └──tracked_camN_json
   │        
   ├── raw-2d
   │    ├──vid_cam1.mp4
   │    ├──...
   │    └──vid_camN.mp4
   │
   └──User
       └──Config.toml
   

Triangulating keypoints

Triangulate your 2D coordinates in a robust way.
N.B.: You can visualize your resulting 3D coordinates with my (experimental) Maya-Mocap tool.

Open an Anaconda prompt or a terminal, type ipython.
By default, triangulation() will look for Config.toml in the User folder of your current directory. If you want to store it somewhere else (e.g. in your data directory), specify this path as an argument: Pose2Sim.triangulation(r'path_to_config.toml').

from Pose2Sim import Pose2Sim
Pose2Sim.triangulation()

Check printed output, and vizualise your trc in OpenSim: File -> Preview experimental data.
If your triangulation is not satisfying, try and release the constraints in the Config.toml file.

Output:

The project hierarchy becomes: (CLICK TO SHOW)

   Project
   │
   ├──calibration
   │   ├──intrinsics
   │   │  ├──int_cam1_img
   │   │  ├──...
   │   │  └──int_camN_img
   │   ├──extrinsics
   │   │  ├──ext_cam1_img
   │   │  ├──...
   │   │  └──ext_camN_img
   │   └──Calib.toml
   │
   ├──opensim
   │    ├──Geometry
   │    ├──Model_Pose2Sim_Body25b.osim
   │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
   │    └──IK_Setup_Pose2Sim_Body25b.xml
   │
   ├──pose-2d
   │   ├──pose_cam1_json
   │   ├──...
   │   └──pose_camN_json
   │
   ├──pose-2d-tracked
   │   ├──tracked_cam1_json
   │   ├──...
   │   └──tracked_camN_json
   │
   ├──pose-3d
       └──Pose-3d.trc>
   │        
   ├── raw-2d
   │    ├──vid_cam1.mp4
   │    ├──...
   │    └──vid_camN.mp4
   │
   └──User
       └──Config.toml
   

Filtering 3D coordinates

Filter your 3D coordinates.
N.B.: You can visualize your resulting filtered 3D coordinates with my (experimental) Maya-Mocap tool.

Open an Anaconda prompt or a terminal, type ipython.
By default, filtering() will look for Config.toml in the User folder of your current directory. If you want to store it somewhere else (e.g. in your data directory), specify this path as an argument: Pose2Sim.filtering(r'path_to_config.toml').

from Pose2Sim import Pose2Sim
Pose2Sim.filtering()

Check your filtration with the displayed figures, and vizualise your trc in OpenSim. If your filtering is not satisfying, try and change the parameters in the Config.toml file.

Output:

The project hierarchy becomes: (CLICK TO SHOW)

   Project
   │
   ├──calibration
   │   ├──intrinsics
   │   │  ├──int_cam1_img
   │   │  ├──...
   │   │  └──int_camN_img
   │   ├──extrinsics
   │   │  ├──ext_cam1_img
   │   │  ├──...
   │   │  └──ext_camN_img
   │   └──Calib.toml
   │
   ├──opensim
   │    ├──Geometry
   │    ├──Model_Pose2Sim_Body25b.osim
   │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
   │    └──IK_Setup_Pose2Sim_Body25b.xml
   │
   ├──pose-2d
   │   ├──pose_cam1_json
   │   ├──...
   │   └──pose_camN_json
   │
   ├──pose-2d-tracked
   │   ├──tracked_cam1_json
   │   ├──...
   │   └──tracked_camN_json
   │
   ├──pose-3d
   │   ├──Pose-3d.trc
   │   └──Pose-3d-filtered.trc
   │        
   ├── raw-2d
   │    ├──vid_cam1.mp4
   │    ├──...
   │    └──vid_camN.mp4
   │
   └──User
       └──Config.toml
   

OpenSim kinematics

Obtain 3D joint angles.

OpenSim Scaling

1. Use the previous steps to capture a static pose, typically an A-pose or a T-pose.
2. Open OpenSim.
3. Open the provided Model_Pose2Sim_Body25b.osim model from pose2sim/Empty_project/opensim. (File -> Open Model)
4. Load the provided Scaling_Setup_Pose2Sim_Body25b.xml scaling file from pose2sim/Empty_project/opensim. (Tools -> Scale model -> Load)
5. Replace the example static .trc file with your own data.
6. Run
7. Save the new scaled OpenSim model.

OpenSim Inverse kinematics

1. Use Pose2Sim to generate 3D trajectories.
2. Open OpenSim.
3. Load the provided IK_Setup_Pose2Sim_Body25b.xml scaling file from pose2sim/Empty_project/opensim. (Tools -> Inverse kinematics -> Load)
4. Replace the example .trc file with your own data, and specify the path to your angle kinematics output file.
5. Run
6. Motion results will appear as .mot file in the pose2sim/Empty_project/opensim directory (automatically saved).

Command line

Alternatively, you can use command-line tools:

• Open an Anaconda terminal in your OpenSim/bin directory, typically C:\OpenSim <Version>\bin.
  You'll need to adjust the time_range, output_motion_file, and enter the full paths to the input and output .osim, .trc, and .mot files in your setup file.

  opensim-cmd run-tool <PATH TO YOUR SCALING OR IK SETUP FILE>.xml
  

• You can also run OpenSim directly in Python:

  import subprocess
  subprocess.call(["opensim-cmd", "run-tool", r"<PATH TO YOUR SCALING OR IK SETUP FILE>.xml"])
  

• Or take advantage of the full the OpenSim Python API. See there for installation instructions (conda install may take a while).
  Make sure to replace py38np120 with your Python version (3.8 in this case) and with your numpy version (1.20 here).

  conda install -c opensim-org opensim-moco=4.4=py38np120 -y
  

  If you run into a DLL error while importing opensim, open the file <Pose2Sim-env>\Lib\opensim\__init__.py and replace condaby conda-meta line 4. <Pose2Sim-env> location can be found with conda env list.
  Then run: ipython

  import opensim
  opensim.ScaleTool("<PATH TO YOUR SCALING OR IK SETUP FILE>.xml").run()
  opensim.InverseKinematicsTool("<PATH TO YOUR SCALING OR IK SETUP FILE>.xml").run()
  

  You can also run other API commands. See there for more instructions on how to use it.

The project hierarchy becomes: (CLICK TO SHOW)

   Project
   │
   ├──calibration
   │   ├──intrinsics
   │   │  ├──int_cam1_img
   │   │  ├──...
   │   │  └──int_camN_img
   │   ├──extrinsics
   │   │  ├──ext_cam1_img
   │   │  ├──...
   │   │  └──ext_camN_img
   │   └──Calib.toml
   │
   ├──opensim  
   │    ├──Geometry
   │    ├──Model_Pose2Sim_Body25b.osim
   │    ├──Scaling_Setup_Pose2Sim_Body25b.xml
   │    ├──Model_Pose2Sim_Body25b_Scaled.osim  
   │    ├──IK_Setup_Pose2Sim_Body25b.xml
   │    └──IK_result.mot   
   │
   ├──pose
   │   ├──pose_cam1_json
   │   ├──...
   │   └──pose_camN_json
   │
   ├──pose-associated
   │   ├──tracked_cam1_json
   │   ├──...
   │   └──tracked_camN_json
   │
   ├──triangulation
   │   ├──triangulation.trc
   │   └──triangulation-filtered.trc
   │        
   ├── raw
   │    ├──vid_cam1.mp4
   │    ├──...
   │    └──vid_camN.mp4
   │
   └──User
       └──Config.toml
   

Batch processing

If you need to batch process multiple data or with multiple different parameters, you can run any Pose2Sim function with a config dictionary instead of a file. For example:

from Pose2Sim import Pose2Sim
import toml

config_dict = toml.load('User/Config.toml')
config_dict['project']['pose_folder_name'] = new_project_path
Pose2Sim.triangulate(config_dict)

Or into a loop:

from Pose2Sim import Pose2Sim
import toml
config_dict = toml.load('User/Config.toml')

# Change project_path
for new_project_path in new_project_paths:
  config_dict['project']['project_dir'] = new_project_path
  config_dict['filtering']['display_figures'] = False

  # Run any Pose2Sim function with config_dict instead of a path
  Pose2Sim.triangulation(config_dict)
  
  # Now change filtering type
  for new_filter in ['butterworth', 'kalman', 'gaussian']:
    config_dict['filtering']['type'] = new_filter
    Pose2Sim.filtering(config_dict)

Utilities

A list of standalone tools (see Utilities), which can be either run as scripts, or imported as functions. Check usage in the docstrings of each Python file. The figure below shows how some of these toolscan be used to further extend Pose2Sim usage.

Converting calibration files (CLICK TO SHOW)

Blazepose_runsave.py
Runs BlazePose on a video, and saves coordinates in OpenPose (json) or DeepLabCut (h5 or csv) format.
DLC_to_OpenPose.py
Converts a DeepLabCut (h5) 2D pose estimation file into OpenPose (json) files.
AlphaPose_to_OpenPose.py
Converts AlphaPose single json file to OpenPose frame-by-frame files.
calib_from_checkerboard.py
Calibrates cameras with images or a video of a checkerboard, saves calibration in a Pose2Sim .toml calibration file.
You should probably use Pose2Sim.calibration() instead, which is much easier and better.
calib_qca_to_toml.py
Converts a Qualisys .qca.txt calibration file to the Pose2Sim .toml calibration file (similar to what is used in AniPose).
calib_toml_to_qca.py
Converts a Pose2Sim .toml calibration file (e.g., from a checkerboard) to a Qualisys .qca.txt calibration file.
calib_easymocap_to_toml.py
Converts EasyMocap intrinsic and extrinsic .yml calibration files to an OpenCV .toml calibration file.
calib_toml_to_easymocap.py
Converts an OpenCV .toml calibration file to EasyMocap intrinsic and extrinsic .yml calibration files.
calib_toml_to_opencap.py
Converts an OpenCV .toml calibration file to OpenCap .pickle calibration files.
calib_toml_to_opencap.py
To convert OpenCap calibration tiles to a .toml file, please use Pose2Sim.calibration() and set convert_from = 'opencap' in Config.toml.

Plotting tools (CLICK TO SHOW)

json_display_with_img.py
Overlays 2D detected json coordinates on original raw images. High confidence keypoints are green, low confidence ones are red.
json_display_without_img.py
Plots an animation of 2D detected json coordinates.
trc_plot.py
Displays X, Y, Z coordinates of each 3D keypoint of a TRC file in a different matplotlib tab.

Other trc tools (CLICK TO SHOW)

c3d_to_trc.py
Converts 3D point data of a .c3d file to a .trc file compatible with OpenSim. No analog data (force plates, emg) nor computed data (angles, powers, etc) are retrieved.
trc_desample.py
Undersamples a trc file.
trc_Zup_to_Yup.py
Changes Z-up system coordinates to Y-up system coordinates.
trc_filter.py
Filters trc files. Available filters: Butterworth, Kalman, Butterworth on speed, Gaussian, LOESS, Median.
trc_gaitevents.py
Detects gait events from point coordinates according to Zeni et al. (2008).
trc_combine.py
Combine two trc files, for example a triangulated DeepLabCut trc file and a triangulated OpenPose trc file.
trc_from_mot_osim.py
Build a trc file from a .mot motion file and a .osim model file.
csv_from_mot_osim.py
Converts a mot file to a .csv file with rotation and orientation of all segments.
   

How to cite and how to contribute

How to cite

If you use this code or data, please cite Pagnon et al., 2022b, Pagnon et al., 2022a, or Pagnon et al., 2021.

@Article{Pagnon_2022_JOSS, 
  AUTHOR = {Pagnon, David and Domalain, Mathieu and Reveret, Lionel}, 
  TITLE = {Pose2Sim: An open-source Python package for multiview markerless kinematics}, 
  JOURNAL = {Journal of Open Source Software}, 
  YEAR = {2022},
  DOI = {10.21105/joss.04362}, 
  URL = {https://joss.theoj.org/papers/10.21105/joss.04362}
 }

@Article{Pagnon_2022_Accuracy,
  AUTHOR = {Pagnon, David and Domalain, Mathieu and Reveret, Lionel},
  TITLE = {Pose2Sim: An End-to-End Workflow for 3D Markerless Sports Kinematics—Part 2: Accuracy},
  JOURNAL = {Sensors},
  YEAR = {2022},
  DOI = {10.3390/s22072712},
  URL = {https://www.mdpi.com/1424-8220/22/7/2712}
}

@Article{Pagnon_2021_Robustness,
  AUTHOR = {Pagnon, David and Domalain, Mathieu and Reveret, Lionel},
  TITLE = {Pose2Sim: An End-to-End Workflow for 3D Markerless Sports Kinematics—Part 1: Robustness},
  JOURNAL = {Sensors},
  YEAR = {2021},
  DOI = {10.3390/s21196530},
  URL = {https://www.mdpi.com/1424-8220/21/19/6530}
}

How to contribute and to-do list

I would happily welcome any proposal for new features, code improvement, and more!
If you want to contribute to Pose2Sim, please follow this guide on how to fork, modify and push code, and submit a pull request. I would appreciate it if you provided as much useful information as possible about how you modified the code, and a rationale for why you're making this pull request. Please also specify on which operating system and on which Python version you have tested the code.

Main to-do list

• Graphical User Interface
• Multiple person triangulation
• Synchronization
• Self-calibration based on keypoint detection

Detailed to-do list (CLICK TO SHOW)

✔ Pose: Support OpenPose body_25b for more accuracy, body_135 for pronation/supination.
✔ Pose: Support BlazePose for faster inference (on mobile device).
✔ Pose: Support DeepLabCut for training on custom datasets.
✔ Pose: Support AlphaPose as an alternative to OpenPose.
▢ Pose: Support MMPose, SLEAP, etc.
▢ Pose: Access skeletons more easily by storing them in skeletons.toml.
✔ Calibration: Convert Qualisys .qca.txt calibration file.
✔ Calibration: Convert Optitrack extrinsic calibration file.
✔ Calibration: Convert Vicon .xcp calibration file.
✔ Calibration: Convert OpenCap .pickle calibration files.
✔ Calibration: Convert EasyMocap .yml calibration files.
✔ Calibration: Convert bioCV calibration files.
✔ Calibration: Easier and clearer calibration procedure: separate intrinsic and extrinsic parameter calculation, edit corner detection if some are wrongly detected (or not visible).
✔ Calibration: Possibility to evaluate extrinsic parameters from cues on scene.
▢ Calibration: Once object points have been detected or clicked once, track them for live calibration of moving cameras. Propose to click again when they are lost.
▢ Calibration: Calibrate cameras by pairs and compute average extrinsic calibration with aniposelib.
▢ Calibration: Fine-tune calibration with bundle adjustment.
▢ Calibration: Support ChArUco board detection (see there).
▢ Calibration: Calculate calibration with points rather than board. (1) SBA calibration with wand (cf Argus, see converter here). Set world reference frame in the end.
▢ Calibration: Alternatively, self-calibrate with OpenPose keypoints. Set world reference frame in the end.
▢ Synchronization: Synchronize cameras on 2D keypoint speeds. Cf this draft script.
✔ Person Association: Automatically choose the main person to triangulate.
▢ Person Association: Multiple persons association. 1. Triangulate all the persons whose reprojection error is below a certain threshold (instead of only the one with minimum error), and then track in time with speed cf Slembrouck 2020? or 2. Based on affinity matrices Dong 2021? or 3. Based on occupancy maps Yildiz 2012? or 4. With a neural network Huang 2023?
✔ Triangulation: Triangulation weighted with confidence.
✔ Triangulation: Set a likelihood threshold below which a camera should not be used, a reprojection error threshold, and a minimum number of remaining cameras below which triangulation is skipped for this frame.
✔ Triangulation: Interpolate missing frames (cubic, bezier, linear, slinear, quadratic)
✔ Triangulation: Show mean reprojection error in px and in mm for each keypoint.
✔ Triangulation: Show how many cameras on average had to be excluded for each keypoint.
✔ Triangulation: Evaluate which cameras were the least reliable.
✔ Triangulation: Show which frames had to be interpolated for each keypoint.
▢ Triangulation: Undistort 2D points before triangulating (and distort them before computing reprojection error).
▢ Triangulation: Multiple person kinematics (output multiple .trc coordinates files). Triangulate all persons with reprojection error above threshold, and identify them by minimizing their displacement across frames.
▢ Triangulation: Pre-compile weighted_traingulation and reprojection with @jit(nopython=True, parallel=True) for faster execution.
▢ Triangulation: Offer the possibility of triangulating with Sparse Bundle Adjustment (SBA), Extended Kalman Filter (EKF), Full Trajectory Estimation (FTE) (see AcinoSet).
▢ Triangulation: Solve limb swapping (although not really an issue with Body_25b). Try triangulating with opposite side if reprojection error too large. Alternatively, ignore right and left sides, use RANSAC or SDS triangulation, and then choose right or left by majority voting. More confidence can be given to cameras whose plane is the most coplanar to the right/left line.
▢ Triangulation: Implement normalized DLT and RANSAC triangulation, Outlier rejection (sliding z-score?), as well as a triangulation refinement step.
✔ Filtering: Available filtering methods: Butterworth, Butterworth on speed, Gaussian, Median, LOESS (polynomial smoothing).
✔ Filtering: Implement Kalman filter and Kalman smoother.
▢ Filtering: Implement smoothNet
✔ OpenSim: Integrate better spine from lifting fullbody model to the gait full-body model, more accurate for the knee.
✔ OpenSim: Optimize model marker positions as compared to ground-truth marker-based positions.
✔ OpenSim: Add scaling and inverse kinematics setup files.
✔ OpenSim: Add full model with contact spheres (SmoothSphereHalfSpaceForce) and full-body muscles (DeGrooteFregly2016Muscle), for Moco for example.
▢ OpenSim: Add model with ISB shoulder.
▢ OpenSim: Implement optimal fixed-interval Kalman smoothing for inverse kinematics (this OpenSim fork), or Biorbd)
▢ GUI: 3D plot of cameras and of triangulated keypoints.
▢ GUI: Demo on Google Colab (see Sports2D for OpenPose and Python package installation on Google Drive).
▢ GUI: Blender add-on (cf MPP2SOS), or webapp (e.g., with Napari. See my draft project Maya-Mocap and BlendOsim.
✔ Demo: Provide Demo data for users to test the code.
▢ Demo: Add videos for users to experiment with other pose detection frameworks
▢ Demo: Time shift videos and json to demonstrate synchronization
▢ Demo: Add another virtual person to demonstrate personAssociation
▢ Tutorials: Make video tutorials.
▢ Doc: Use Sphinx, MkDocs, or (maybe better), github.io for clearer documentation.
▢ Catch errors
✔ Pip package
▢ Conda package
▢ Docker image
▢ Run pose estimation and OpenSim from within Pose2Sim
▢ Run from command line via click or typer
▢ Utilities: Export other data from c3d files into .mot or .sto files (angles, powers, forces, moments, GRF, EMG...)
▢ Bug: common.py, class plotWindow(). Python crashes after a few runs of Pose2Sim.filtering() when display_figures=true. See there.
▢ Bug: calibration.py. FFMPEG error message when calibration files are images. See there.

Acknowledgements:

• Supervised my PhD: @lreveret (INRIA, Université Grenoble Alpes), and @mdomalai (Université de Poitiers).
• Provided the Demo data: @aaiaueil from Université Gustave Eiffel.
• Tested the code and provided feedback: @simonozan, @daeyongyang, @ANaaim, @rlagnsals
• Provided a code snippet for Optitrack calibration: @claraaudap (Université Bretagne Sud).
• Issued MPP2SOS, a (non-free) Blender extension based on Pose2Sim: @carlosedubarreto

Pose2Sim releases:

• v0.1: Published online
• v0.2: Published associated paper
• v0.3: Supported other pose estimation algorithms
• v0.4: New calibration tool
• v0.5: Supports multi-person analysis
• v0.6: New synchronization tool
• v0.7: Graphical User Interface
• v1.0: First accomplished release

BSD 3-Clause License

Copyright (c) 2022, perfanalytics All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.