<!-- [](https://bit.ly/Sports2D_Colab)-->

Sports2D

Sports2D automatically computes 2D joint positions, as well as joint and segment angles from a video or a webcam.

</br>

Announcements:

• Compensate for floor angle, floor height, depth perspective effects, generate a calibration file New in v0.8.25!
• Select only the persons you want to analyze New in v0.8!
• MarkerAugmentation and Inverse Kinematics for accurate 3D motion with OpenSim. New in v0.7!
• Any detector and pose estimation model can be used. New in v0.6!
• Results in meters rather than pixels. New in v0.5!
• Faster, more accurate
• Works from a webcam
• Better visualization output
• More flexible, easier to run

Run pip install sports2d pose2sim -U to get the latest version.

N.B.: As always, I am more than happy to welcome contributions (see How to contribute)!

<!--User-friendly Colab version released! (and latest issues fixed, too)\ Works on any smartphone!**\ [](https://bit.ly/Sports2D_Colab)--> </br>

https://github.com/user-attachments/assets/2ce62012-f28c-4e23-b3b8-f68931bacb77

<!-- https://github.com/user-attachments/assets/6a444474-4df1-4134-af0c-e9746fa433ad --> <!-- https://github.com/user-attachments/assets/1c6e2d6b-d0cf-4165-864e-d9f01c0b8a0e -->

Warning: Angle estimation is only as good as the pose estimation algorithm, i.e., it is not perfect.
Warning: Results are acceptable only if the persons move in the 2D plane (sagittal or frontal). The persons need to be filmed as parallel as possible to the motion plane.
If you need 3D research-grade markerless joint kinematics, consider using several cameras with Pose2Sim.

<!--`Warning:` Google Colab does not follow the European GDPR requirements regarding data privacy. [Install locally](#installation) if this matters.--> <!--`Know issue`: Results won't be good with some iPhone videos in portrait mode (unless you are working on Colab). This is solved by priorly converting them with `ffmpeg -i video_input.mov video_output.mp4`, or even more simply with any random online video converter such as https://video-converter.com.-->

Contents

1. Installation and Demonstration
   1. Test it on Hugging face
   2. Local installation
      1. Quick install
      2. Full install
   3. Demonstration
      1. Run the demo
      2. Visualize in OpenSim
      3. Visualize in Blender
2. Play with the parameters
   1. Run on a custom video or on a webcam
   2. Run for a specific time range
   3. Select the persons you are interested in
   4. Get coordinates in meters
   5. Run inverse kinematics
   6. Run on several videos at once
   7. Use the configuration file or run within Python
   8. Get the angles the way you want
   9. Customize your output
   10. Use a custom pose estimation model
   11. All the parameters
3. Go further
   1. Too slow for you?
   2. How it works
4. How to cite and how to contribute

<br>

Installation and Demonstration

Test it on Hugging face

Test an online, limited version on Hugging Face:

<img src="Content/huggingface_demo.png" width="760">

Local installation

<!--- OPTION 0: **Use Colab** \ User-friendly (but full) version, also works on a phone or a tablet.\ [](https://bit.ly/Sports2D_Colab)\ YouTube tutorial:\ <a href = "https://www.youtube.com/watch?v=Er5RpcJ8o1Y"><img src="Content/Video_tuto_Sports2D_Colab.png" width="380"></a> -->

Quick install

N.B.: Full install is required for OpenSim inverse kinematics.

Open a terminal. Type python -V to make sure python >=3.10 <=3.12 is installed. If not, install it from there.

Run:

pip install sports2d

Alternatively, build from source to test the last changes:

git clone https://github.com/davidpagnon/sports2d.git
cd sports2d
pip install .

<br>

Full install

N.B.: Only needed if you want to run inverse kinematics (--do_ik True).
N.B.: If you already have a Pose2Sim conda environment, you can skip this step. Just run conda activate Pose2Sim and pip install sports2d.

• Install Anaconda or Miniconda:
  Open an Anaconda prompt and create a virtual environment:

  conda create -n Sports2D python=3.12 -y
  conda activate Sports2D
  

• Install OpenSim:
  Install the OpenSim Python API (if you do not want to install via conda, refer to this page):

  conda install -c opensim-org opensim -y
  

• Install Sports2D with Pose2Sim:

  pip install sports2d
  

<br>

Demonstration

Run the demo:

Just open a command line and run:

sports2d

You should see the joint positions and angles being displayed in real time.

Check the folder where you run that command line to find the resulting video, images, TRC pose and MOT angle files (which can be opened with any spreadsheet software), and logs.

Important: If you ran the conda install, you first need to activate the environment: run conda activate sports2d in the Anaconda prompt.

<img src="Content/Demo_results.png" width="760"> <img src="Content/Demo_plots.png" width="760"> <img src="Content/Demo_terminal.png" width="760">

Note:
The Demo video is voluntarily challenging to demonstrate the robustness of the process after sorting, interpolation and filtering. It contains:

• One person walking in the sagittal plane
• One person doing jumping jacks in the frontal plane. This person then performs a flip while being backlit, both of which are challenging for the pose detection algorithm
• One tiny person flickering in the background who needs to be ignored

<br>

Visualize in Blender

1. Install the Pose2Sim_Blender add-on.
   Follow instructions on the Pose2Sim_Blender add-on page.

2. Import the camera and video.

   • Cameras -> Import: Open your demo_calib.toml file from your result_dir folder.
   • Images/Videos -> Show: open your video file (e.g., demo_Sports2D.mp4).
     -> Other tools -> See through camera

3. Open your point coordinates.
   OpenSim data -> Markers: Open your trc file(e.g., demo_Sports2D_m_person00.trc) from your result_dir folder.
   This will optionally create an animated rig based on the motion of the captured person.

4. Open your animated skeleton:
   Make sure you first set --do_ik True (full install required). See inverse kinematics section for more details.

   • OpenSim data -> Model: Open your scaled model (e.g., demo_Sports2D_m_person00_LSTM.osim).
   • OpenSim data -> Motion: Open your motion file (e.g., demo_Sports2D_m_person00_LSTM_ik.mot).

   The OpenSim skeleton is not rigged yet. Feel free to contribute! [![Discord](http