sports2d 0.8.19__tar.gz → 0.8.21__tar.gz

{sports2d-0.8.19 → sports2d-0.8.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sports2d
-Version: 0.8.19
+Version: 0.8.21
 Summary: Compute 2D human pose and angles from a video or a webcam.
 Author-email: David Pagnon <contact@david-pagnon.com>
 Maintainer-email: David Pagnon <contact@david-pagnon.com>
@@ -38,7 +38,7 @@ Requires-Dist: openvino
 Requires-Dist: opencv-python<4.12
 Requires-Dist: imageio_ffmpeg
 Requires-Dist: deep-sort-realtime
-Requires-Dist: Pose2Sim>=0.10.33
+Requires-Dist: Pose2Sim>=0.10.36
 Dynamic: license-file
 
 
@@ -67,6 +67,7 @@ Dynamic: license-file
 </br>
 
 > **`Announcements:`**
+> - Generate or import a calibration file, OpenSim skeleton overlay **New in v0.9!** 
 > - 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!**
@@ -218,16 +219,19 @@ The Demo video is voluntarily challenging to demonstrate the robustness of the p
 
 1. **Install the Pose2Sim_Blender add-on.**\
    Follow instructions on the [Pose2Sim_Blender](https://github.com/davidpagnon/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**
 2. **Open your point coordinates.**\
-   **Add Markers**: open your trc file(e.g., `coords_m.trc`) from your `result_dir` folder.
-   
+   **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.
 3. **Open your animated skeleton:**\
    Make sure you first set `--do_ik True` ([full install](#full-install) required). See [inverse kinematics](#run-inverse-kinematics) section for more details.
-   - **Add Model**: Open your scaled model (e.g., `Model_Pose2Sim_LSTM.osim`). 
-   - **Add Motion**: Open your motion file (e.g., `angles.mot`). Make sure the skeleton is selected in the outliner.
+   - **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!](https://github.com/perfanalytics/pose2sim/issues/40)**
+   The OpenSim skeleton is not rigged yet. **[Feel free to contribute!](https://github.com/perfanalytics/pose2sim/issues/40)** [![Discord](https://img.shields.io/discord/1183750225471492206?logo=Discord&label=Discord%20community)](https://discord.com/invite/4mXUdSFjmt)
 
 <img src="Content/sports2d_blender.gif" width="760">
 
@@ -284,7 +288,7 @@ If you only want to analyze a subset of the detected persons, you can use the `-
 sports2d --nb_persons_to_detect 2 --person_ordering_method highest_likelihood
 ```
 
-We recommend to use the `on_click` method if you can afford a manual input. This lets the user handle both the person number and their order in the same stage. When prompted, select the persons you are interested in in the desired order. In our case, lets slide to a frame where both people are visible, and select the woman first, then the man.
+We recommend using the `on_click` method if you can afford a manual input. This lets the user handle both the person number and their order in the same stage. When prompted, select the persons you are interested in in the desired order. In our case, lets slide to a frame where both people are visible, and select the woman first, then the man.
 
 Otherwise, if you want to run Sports2D automatically for example, you can choose other ordering methods such as 'highest_likelihood', 'largest_size', 'smallest_size',  'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'.
 
@@ -301,28 +305,32 @@ sports2d --person_ordering_method on_click
 
 
 #### Get coordinates in meters: 
-> **N.B.:** Depth is estimated from a neutral pose. 
+> **N.B.:** The Z coordinate (depth) should not be overly trusted. 
 
-<!-- You either need to provide a calibration file, or simply the height of a person (Note that the latter will not take distortions into account, and that it will be less accurate for motion in the frontal plane).\-->
-You may need to convert pixel coordinates to meters.\
-Just provide the height of the reference person (and their ID in case of multiple person detection).
+You may want coordinates in meters rather than pixels. 2 options to do so:
 
-You can also specify whether the visible side of the person is left, right, front, or back. Set it to 'auto' if you do not want to find it automatically (only works for motion in the sagittal plane), or to 'none' if you want to keep 2D instead of 3D coordinates (if the person goes right, and then left for example).
+1. **Just provide the height of a reference person**:
+   - Their height in meters is be compared with their height in pixels to get a pixel-to-meter conversion factor.
+   - To estimate the depth coordinates, specify which side of the person is visible: `left`, `right`, `front`, or `back`. Use `auto` if you want it to be automatically determined (only works for motions in the sagittal plane), or `none` if you want to keep 2D coordinates instead of 3D (if the person turns around, for example).
+   - The floor angle is automatically estimated from gait, as well as the origin of the xy axis. The person trajectory is corrected accordingly. You can use the `--floor_angle` and `--xy_origin` parameters to manually specify them if your subject is not travelling horizontally or if you want the origin not to be under their feet (note that the `y` axis points down).
+   
+   **N.B.: A calibration file will be generated.** By convention, the camera-to-subject distance is set to 10 meters.
 
-The floor angle and the origin of the xy axis are computed automatically from gait. If you analyze another type of motion, you can manually specify them. Note that `y` points down.\
-Also note that distortions are not taken into account, and that results will be less accurate for motions in the frontal plane.
+   ``` cmd
+   sports2d --first_person_height 1.65 --visible_side auto front none
+   ```
+   ``` cmd
+   sports2d --first_person_height 1.65 --visible_side auto front none `
+            --person_ordering_method on_click `
+            --floor_angle 0 --xy_origin 0 940
+   ```
 
-<!-- ``` cmd
-sports2d --to_meters True --calib_file calib_demo.toml
-``` -->
-``` cmd
-sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none
-```
-``` cmd
-sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none `
-         --person_ordering_method on_click `
-         --floor_angle 0 --xy_origin 0 940
-```
+2. **Or use a calibration file**:\
+  It can either be a `.toml` calibration file previously generated by Sports2D, or a more accurate one coming from another system. For example, [Pose2Sim](https://github.com/perfanalytics/pose2sim) can be used to accurately calculate calibration, or to convert calibration files from Qualisys, Vicon, OpenCap, FreeMoCap, etc.
+
+   ``` cmd
+   sports2d --calib_file Calib_demo.toml --visible_side auto front none
+   ```
 
 <br>
 
@@ -337,18 +345,22 @@ OpenSim inverse kinematics allows you to set joint constraints, joint angle limi
 This is done via [Pose2Sim](https://github.com/perfanalytics/pose2sim).\
 Model scaling is done according to the mean of the segment lengths, across a subset of frames. We remove the 10% fastest frames (potential outliers), the frames where the speed is 0 (person probably out of frame), the frames where the average knee and hip flexion angles are above 45° (pose estimation is not precise when the person is crouching) and the 20% most extreme segment values after the previous operations (potential outliers). All these parameters can be edited in your Config.toml file.
 
+**N.B.: This will not work on sections where the person is not moving in a single plane. You can split your video into several time ranges if needed.**
+
 ```cmd
 sports2d --time_range 1.2 2.7 `
          --do_ik true --first_person_height 1.65 --visible_side auto front
 ```
 
 You can optionally use the LSTM marker augmentation to improve the quality of the output motion.\
-You can also optionally give the participants proper masses. Mass has no influence on motion, only on forces (if you decide to further pursue kinetics analysis).
+You can also optionally give the participants proper masses. Mass has no influence on motion, only on forces (if you decide to further pursue kinetics analysis).\
+Optionally again, you can [visualize the overlaid results in Blender](#visualize-in-blender). The automatic calibration won't be accurate with such a small time range, so you need to use the provided calibration file (or one that has been generated from the full walk).
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
          --do_ik true --first_person_height 1.65 --visible_side left front `
-         --use_augmentation True --participant_mass 55.0 67.0
+         --use_augmentation True --participant_mass 55.0 67.0 `
+         --calib_file Calib_demo.toml
 ```
 
 <br>
@@ -376,14 +388,31 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   ``` cmd
   sports2d --config Config_demo.toml
   ```
-- Run within Python: 
-  ``` python
-  from Sports2D import Sports2D; Sports2D.process('Config_demo.toml')
-  ```
-- Run within Python with a dictionary (for example, `config_dict = toml.load('Config_demo.toml')`):
-  ``` python
-  from Sports2D import Sports2D; Sports2D.process(config_dict)
-  ```
+- Run within Python, for example:\
+  - Edit `Demo/Config_demo.toml` and run:
+    ```python
+    from Sports2D import Sports2D
+    from pathlib import Path
+    import toml
+
+    config_path = Path(Sports2D.__file__).parent / 'Demo'/'Config_demo.toml'
+    config_dict = toml.load(config_path)
+    Sports2D.process(config_dict)
+    ```
+  - Or you can pass the non default values only: 
+    ```python
+    from Sports2D import Sports2D
+    config_dict = {
+      'base': {
+        'nb_persons_to_detect': 1,
+        'person_ordering_method': 'greatest_displacement'
+        },
+      'pose': {
+        'mode': 'lightweight', 
+        'det_frequency': 50
+        }}
+    Sports2D.process(config_dict)
+    ```
 
 <br>
 
@@ -407,7 +436,7 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   ```cmd
   sports2d --flip_left_right true # Default
   ```
-- Correct segment angles according to the estimated camera tild angle.\
+- Correct segment angles according to the estimated camera tilt angle.\
   **N.B.:** *The camera tilt angle is automatically estimated. Set to false if it is actually the floor which is tilted rather than the camera.*
   ```cmd
   sports2d --correct_segment_angles_with_floor_angle true # Default
@@ -477,6 +506,7 @@ sports2d --help
 'show_realtime_results': ["R", "show results in real-time. true if not specified"],
 'display_angle_values_on': ["a", '"body", "list", "body" "list", or "none". body list if not specified'],
 'show_graphs': ["G", "show plots of raw and processed results. true if not specified"],
+'save_graphs': ["", "save position and angle plots of raw and processed results. false if not specified"],
 'joint_angles': ["j", '"Right ankle" "Left ankle" "Right knee" "Left knee" "Right hip" "Left hip" "Right shoulder" "Left shoulder" "Right elbow" "Left elbow" if not specified'],
 'segment_angles': ["s", '"Right foot" "Left foot" "Right shank" "Left shank" "Right thigh" "Left thigh" "Pelvis" "Trunk" "Shoulders" "Head" "Right arm" "Left arm" "Right forearm" "Left forearm" if not specified'],
 'save_vid': ["V", "save processed video. true if not specified"],

{sports2d-0.8.19 → sports2d-0.8.21}/README.md

@@ -24,6 +24,7 @@
 </br>
 
 > **`Announcements:`**
+> - Generate or import a calibration file, OpenSim skeleton overlay **New in v0.9!** 
 > - 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!**
@@ -175,16 +176,19 @@ The Demo video is voluntarily challenging to demonstrate the robustness of the p
 
 1. **Install the Pose2Sim_Blender add-on.**\
    Follow instructions on the [Pose2Sim_Blender](https://github.com/davidpagnon/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**
 2. **Open your point coordinates.**\
-   **Add Markers**: open your trc file(e.g., `coords_m.trc`) from your `result_dir` folder.
-   
+   **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.
 3. **Open your animated skeleton:**\
    Make sure you first set `--do_ik True` ([full install](#full-install) required). See [inverse kinematics](#run-inverse-kinematics) section for more details.
-   - **Add Model**: Open your scaled model (e.g., `Model_Pose2Sim_LSTM.osim`). 
-   - **Add Motion**: Open your motion file (e.g., `angles.mot`). Make sure the skeleton is selected in the outliner.
+   - **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!](https://github.com/perfanalytics/pose2sim/issues/40)**
+   The OpenSim skeleton is not rigged yet. **[Feel free to contribute!](https://github.com/perfanalytics/pose2sim/issues/40)** [![Discord](https://img.shields.io/discord/1183750225471492206?logo=Discord&label=Discord%20community)](https://discord.com/invite/4mXUdSFjmt)
 
 <img src="Content/sports2d_blender.gif" width="760">
 
@@ -241,7 +245,7 @@ If you only want to analyze a subset of the detected persons, you can use the `-
 sports2d --nb_persons_to_detect 2 --person_ordering_method highest_likelihood
 ```
 
-We recommend to use the `on_click` method if you can afford a manual input. This lets the user handle both the person number and their order in the same stage. When prompted, select the persons you are interested in in the desired order. In our case, lets slide to a frame where both people are visible, and select the woman first, then the man.
+We recommend using the `on_click` method if you can afford a manual input. This lets the user handle both the person number and their order in the same stage. When prompted, select the persons you are interested in in the desired order. In our case, lets slide to a frame where both people are visible, and select the woman first, then the man.
 
 Otherwise, if you want to run Sports2D automatically for example, you can choose other ordering methods such as 'highest_likelihood', 'largest_size', 'smallest_size',  'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'.
 
@@ -258,28 +262,32 @@ sports2d --person_ordering_method on_click
 
 
 #### Get coordinates in meters: 
-> **N.B.:** Depth is estimated from a neutral pose. 
+> **N.B.:** The Z coordinate (depth) should not be overly trusted. 
 
-<!-- You either need to provide a calibration file, or simply the height of a person (Note that the latter will not take distortions into account, and that it will be less accurate for motion in the frontal plane).\-->
-You may need to convert pixel coordinates to meters.\
-Just provide the height of the reference person (and their ID in case of multiple person detection).
+You may want coordinates in meters rather than pixels. 2 options to do so:
 
-You can also specify whether the visible side of the person is left, right, front, or back. Set it to 'auto' if you do not want to find it automatically (only works for motion in the sagittal plane), or to 'none' if you want to keep 2D instead of 3D coordinates (if the person goes right, and then left for example).
+1. **Just provide the height of a reference person**:
+   - Their height in meters is be compared with their height in pixels to get a pixel-to-meter conversion factor.
+   - To estimate the depth coordinates, specify which side of the person is visible: `left`, `right`, `front`, or `back`. Use `auto` if you want it to be automatically determined (only works for motions in the sagittal plane), or `none` if you want to keep 2D coordinates instead of 3D (if the person turns around, for example).
+   - The floor angle is automatically estimated from gait, as well as the origin of the xy axis. The person trajectory is corrected accordingly. You can use the `--floor_angle` and `--xy_origin` parameters to manually specify them if your subject is not travelling horizontally or if you want the origin not to be under their feet (note that the `y` axis points down).
+   
+   **N.B.: A calibration file will be generated.** By convention, the camera-to-subject distance is set to 10 meters.
 
-The floor angle and the origin of the xy axis are computed automatically from gait. If you analyze another type of motion, you can manually specify them. Note that `y` points down.\
-Also note that distortions are not taken into account, and that results will be less accurate for motions in the frontal plane.
+   ``` cmd
+   sports2d --first_person_height 1.65 --visible_side auto front none
+   ```
+   ``` cmd
+   sports2d --first_person_height 1.65 --visible_side auto front none `
+            --person_ordering_method on_click `
+            --floor_angle 0 --xy_origin 0 940
+   ```
 
-<!-- ``` cmd
-sports2d --to_meters True --calib_file calib_demo.toml
-``` -->
-``` cmd
-sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none
-```
-``` cmd
-sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none `
-         --person_ordering_method on_click `
-         --floor_angle 0 --xy_origin 0 940
-```
+2. **Or use a calibration file**:\
+  It can either be a `.toml` calibration file previously generated by Sports2D, or a more accurate one coming from another system. For example, [Pose2Sim](https://github.com/perfanalytics/pose2sim) can be used to accurately calculate calibration, or to convert calibration files from Qualisys, Vicon, OpenCap, FreeMoCap, etc.
+
+   ``` cmd
+   sports2d --calib_file Calib_demo.toml --visible_side auto front none
+   ```
 
 <br>
 
@@ -294,18 +302,22 @@ OpenSim inverse kinematics allows you to set joint constraints, joint angle limi
 This is done via [Pose2Sim](https://github.com/perfanalytics/pose2sim).\
 Model scaling is done according to the mean of the segment lengths, across a subset of frames. We remove the 10% fastest frames (potential outliers), the frames where the speed is 0 (person probably out of frame), the frames where the average knee and hip flexion angles are above 45° (pose estimation is not precise when the person is crouching) and the 20% most extreme segment values after the previous operations (potential outliers). All these parameters can be edited in your Config.toml file.
 
+**N.B.: This will not work on sections where the person is not moving in a single plane. You can split your video into several time ranges if needed.**
+
 ```cmd
 sports2d --time_range 1.2 2.7 `
          --do_ik true --first_person_height 1.65 --visible_side auto front
 ```
 
 You can optionally use the LSTM marker augmentation to improve the quality of the output motion.\
-You can also optionally give the participants proper masses. Mass has no influence on motion, only on forces (if you decide to further pursue kinetics analysis).
+You can also optionally give the participants proper masses. Mass has no influence on motion, only on forces (if you decide to further pursue kinetics analysis).\
+Optionally again, you can [visualize the overlaid results in Blender](#visualize-in-blender). The automatic calibration won't be accurate with such a small time range, so you need to use the provided calibration file (or one that has been generated from the full walk).
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
          --do_ik true --first_person_height 1.65 --visible_side left front `
-         --use_augmentation True --participant_mass 55.0 67.0
+         --use_augmentation True --participant_mass 55.0 67.0 `
+         --calib_file Calib_demo.toml
 ```
 
 <br>
@@ -333,14 +345,31 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   ``` cmd
   sports2d --config Config_demo.toml
   ```
-- Run within Python: 
-  ``` python
-  from Sports2D import Sports2D; Sports2D.process('Config_demo.toml')
-  ```
-- Run within Python with a dictionary (for example, `config_dict = toml.load('Config_demo.toml')`):
-  ``` python
-  from Sports2D import Sports2D; Sports2D.process(config_dict)
-  ```
+- Run within Python, for example:\
+  - Edit `Demo/Config_demo.toml` and run:
+    ```python
+    from Sports2D import Sports2D
+    from pathlib import Path
+    import toml
+
+    config_path = Path(Sports2D.__file__).parent / 'Demo'/'Config_demo.toml'
+    config_dict = toml.load(config_path)
+    Sports2D.process(config_dict)
+    ```
+  - Or you can pass the non default values only: 
+    ```python
+    from Sports2D import Sports2D
+    config_dict = {
+      'base': {
+        'nb_persons_to_detect': 1,
+        'person_ordering_method': 'greatest_displacement'
+        },
+      'pose': {
+        'mode': 'lightweight', 
+        'det_frequency': 50
+        }}
+    Sports2D.process(config_dict)
+    ```
 
 <br>
 
@@ -364,7 +393,7 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   ```cmd
   sports2d --flip_left_right true # Default
   ```
-- Correct segment angles according to the estimated camera tild angle.\
+- Correct segment angles according to the estimated camera tilt angle.\
   **N.B.:** *The camera tilt angle is automatically estimated. Set to false if it is actually the floor which is tilted rather than the camera.*
   ```cmd
   sports2d --correct_segment_angles_with_floor_angle true # Default
@@ -434,6 +463,7 @@ sports2d --help
 'show_realtime_results': ["R", "show results in real-time. true if not specified"],
 'display_angle_values_on': ["a", '"body", "list", "body" "list", or "none". body list if not specified'],
 'show_graphs': ["G", "show plots of raw and processed results. true if not specified"],
+'save_graphs': ["", "save position and angle plots of raw and processed results. false if not specified"],
 'joint_angles': ["j", '"Right ankle" "Left ankle" "Right knee" "Left knee" "Right hip" "Left hip" "Right shoulder" "Left shoulder" "Right elbow" "Left elbow" if not specified'],
 'segment_angles': ["s", '"Right foot" "Left foot" "Right shank" "Left shank" "Right thigh" "Left thigh" "Pelvis" "Trunk" "Shoulders" "Head" "Right arm" "Left arm" "Right forearm" "Left forearm" if not specified'],
 'save_vid': ["V", "save processed video. true if not specified"],

sports2d-0.8.21/Sports2D/Demo/Calib_demo.toml

@@ -0,0 +1,12 @@
+[demo]
+name = "demo"
+size = [ 1768, 994]
+matrix = [ [ 2520.0897058227038, 0.0, 884.0], [ 0.0, 2520.0897058227038, 497.0], [ 0.0, 0.0, 1.0]]
+distortions = [ 0.0, 0.0, 0.0, 0.0]
+rotation = [ 1.2082126924727719, 1.2098328575850605, -1.2082126924727719]
+translation = [ -3.510103521992233, 1.7079310029359385, 10.0]
+fisheye = false
+
+[metadata]
+adjusted = false
+error = 0.0

{sports2d-0.8.19 → sports2d-0.8.21}/Sports2D/Demo/Config_demo.toml

@@ -60,8 +60,8 @@ pose_model = 'Body_with_feet'  #With RTMLib:
                          # - Hand (HAND_21, only lightweight mode. Potentially better results with Whole_body), 
                          # - Face (FACE_106), 
                          # - Animal (ANIMAL2D_17)
-                         # /!\ Only RTMPose is natively embeded in Pose2Sim. For all other pose estimation methods, you will have to run them yourself, and then refer to the documentation to convert the output files if needed
-                         # /!\ For Face and Animal, use mode="""{dictionary}""", and find the corresponding .onnx model there https://github.com/open-mmlab/mmpose/tree/main/projects/rtmpose
+                         # ⚠ Only RTMPose is natively embeded in Pose2Sim. For all other pose estimation methods, you will have to run them yourself, and then refer to the documentation to convert the output files if needed
+                         # ⚠ For Face and Animal, use mode="""{dictionary}""", and find the corresponding .onnx model there https://github.com/open-mmlab/mmpose/tree/main/projects/rtmpose
 mode = 'balanced' # 'lightweight', 'balanced', 'performance', or """{dictionary}""" (see below)
 
 # A dictionary (WITHIN THREE DOUBLE QUOTES) allows you to manually select the person detection (if top_down approach) and/or pose estimation models (see https://github.com/Tau-J/rtmlib). 
@@ -103,7 +103,7 @@ keypoint_number_threshold = 0.3     # Person will be ignored if the number of go
 # Pixel to meters conversion
 to_meters = true
 make_c3d = true
-save_calib = true # Coming soon!
+save_calib = false
 
 # If conversion from first_person_height
 floor_angle = 'auto'    # 'auto' or a value in degrees, eg 2.3. If 'auto', estimated from the line formed by the toes when they are on the ground (where speed = 0)
@@ -139,6 +139,7 @@ reject_outliers = true      # Hampel filter for outlier rejection before other f
 
 filter = true
 show_graphs = true         # Show plots of raw and processed results
+save_graphs = true         # Save position and angle plots of raw and processed results
 filter_type = 'butterworth'     # butterworth, kalman, gcv_spline, gaussian, loess, median, butterworth_on_speed
    
    # Most intuitive and standard filter in biomechanics

{sports2d-0.8.19 → sports2d-0.8.21}/Sports2D/Sports2D.py

@@ -28,7 +28,7 @@
     - Run on webcam with default parameters: 
         sports2d --video_input webcam
     - Run with custom parameters (all non specified are set to default): 
-        sports2d --show_plots False --time_range 0 2.1 --result_dir path_to_result_dir
+        sports2d --show_graphs False --time_range 0 2.1 --result_dir path_to_result_dir
         sports2d --person_detection_method highest_likelihood --mode lightweight --det_frequency 50
     - Run with a toml configuration file: 
         sports2d --config path_to_config.toml
@@ -44,7 +44,7 @@
     pip install .
     
     -----
-    /!\ Warning /!\
+    ⚠ Warning ⚠
     -----
     - The angle estimation is only as good as the pose estimation algorithm, i.e., it is not perfect.
     - It will only lead to acceptable results if the persons move in the 2D plane (sagittal plane).
@@ -196,7 +196,7 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
                                 'calib_file': '',
                                 'floor_angle': 'auto',
                                 'xy_origin': ['auto'],
-                                'save_calib': True
+                                'save_calib': False
                                 },
                     'angles':   {'display_angle_values_on': ['body', 'list'],
                                 'fontSize': 0.3,
@@ -236,6 +236,7 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
                                         'reject_outliers': True,
                                         'filter': True,
                                         'show_graphs': True,
+                                        'save_graphs': True,
                                         'filter_type': 'butterworth',
                                         'butterworth': {'order': 4, 'cut_off_frequency': 6.0},
                                         'kalman': {'trust_ratio': 500.0, 'smooth':True},
@@ -279,6 +280,7 @@ CONFIG_HELP =   {'config': ["C", "path to a toml configuration file"],
                 'show_realtime_results': ["R", "show results in real-time. true if not specified"],
                 'display_angle_values_on': ["a", '"body", "list", "body" "list", or "none". body list if not specified'],
                 'show_graphs': ["G", "show plots of raw and processed results. true if not specified"],
+                'save_graphs': ["", "save position and angle plots of raw and processed results. true if not specified"],
                 'joint_angles': ["j", '"Right ankle" "Left ankle" "Right knee" "Left knee" "Right hip" "Left hip" "Right shoulder" "Left shoulder" "Right elbow" "Left elbow" if not specified'],
                 'segment_angles': ["s", '"Right foot" "Left foot" "Right shank" "Left shank" "Right thigh" "Left thigh" "Pelvis" "Trunk" "Shoulders" "Head" "Right arm" "Left arm" "Right forearm" "Left forearm" if not specified'],
                 'save_vid': ["V", "save processed video. true if not specified"],
@@ -471,6 +473,14 @@ def set_nested_value(config, flat_key, value):
     d[keys[-1]] = value
 
 
+def merge_dicts(original, overrides):
+    for key, value in overrides.items():
+        if isinstance(value, dict) and isinstance(original.get(key), dict):
+            merge_dicts(original[key], value)
+        else:
+            original[key] = value
+            
+
 def str2bool(v):
     '''
     Convert a string to a boolean value.
@@ -498,7 +508,8 @@ def process(config='Config_demo.toml'):
     from Sports2D.process import process_fun
     
     if type(config) == dict:
-        config_dict = config
+        config_dict = DEFAULT_CONFIG.copy()
+        merge_dicts(config_dict, config)
     else:
         config_dict = read_config_file(config)
     video_dir, video_files, frame_rates, time_ranges, result_dir = base_params(config_dict)
@@ -546,7 +557,7 @@ def main():
     - Run on webcam with default parameters: 
         sports2d --video_input webcam
     - Run with custom parameters (all non specified are set to default): 
-        sports2d --show_plots False --time_range 0 2.1 --result_dir path_to_result_dir
+        sports2d --show_graphs False --time_range 0 2.1 --result_dir path_to_result_dir
         sports2d --mode lightweight --det_frequency 50
     - Run with a toml configuration file: 
         sports2d --config path_to_config.toml

{sports2d-0.8.19 → sports2d-0.8.21}/Sports2D/Utilities/tests.py

@@ -45,7 +45,7 @@ def test_workflow():
     ## From Python             ##
     #############################
 
-    # Default
+    # Default from the demo config file
     config_path = Path(__file__).resolve().parent.parent / 'Demo' / 'Config_demo.toml'
     config_dict = toml.load(config_path)
     video_dir = Path(__file__).resolve().parent.parent / 'Demo'
@@ -53,6 +53,28 @@ def test_workflow():
     config_dict.get("base").update({"person_ordering_method": "highest_likelihood"})
     config_dict.get("base").update({"show_realtime_results":False})
     config_dict.get("post-processing").update({"show_graphs":False})
+    config_dict.get("post-processing").update({"save_graphs":False})
+    
+    Sports2D.process(config_dict)
+
+
+    # Only passing the updated values
+    video_dir = Path(__file__).resolve().parent.parent / 'Demo'
+    config_dict = {
+      'base': {
+        'nb_persons_to_detect': 1,
+        'person_ordering_method': 'greatest_displacement',
+        "show_realtime_results":False
+        },
+      'pose': {
+        'mode': 'lightweight', 
+        'det_frequency': 50
+        },
+      'post-processing': {
+        'show_graphs':False,
+        'save_graphs':False
+        }
+    }
     
     Sports2D.process(config_dict)
 
@@ -62,28 +84,28 @@ def test_workflow():
     #############################
 
     # Default
-    demo_cmd = ["sports2d", "--person_ordering_method", "highest_likelihood", "--show_realtime_results", "False", "--show_graphs", "False"]
+    demo_cmd = ["sports2d", "--person_ordering_method", "highest_likelihood", "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False"]
     subprocess.run(demo_cmd, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace')
 
     # With loading a trc file, visible_side 'front', first_person_height '1.76", floor_angle 0, xy_origin [0, 928]
-    demo_cmd2 = ["sports2d", "--show_realtime_results", "False", "--show_graphs", "False",
+    demo_cmd2 = ["sports2d", "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False",
                  "--load_trc_px", os.path.join(root_dir, "demo_Sports2D", "demo_Sports2D_px_person01.trc"),
                  "--visible_side", "front", "--first_person_height", "1.76", "--time_range", "1.2", "2.7",
                  "--floor_angle", "0", "--xy_origin", "0", "928"]
     subprocess.run(demo_cmd2, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace')
 
     # With no pixels to meters conversion, one person to select, lightweight mode, detection frequency, slowmo factor, gaussian filter, RTMO body pose model
-    demo_cmd3 = ["sports2d", "--show_realtime_results", "False", "--show_graphs", "False", 
-                 "--to_meters", "False", 
+    demo_cmd3 = ["sports2d", "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False",
+                #  "--calib_file", "calib_demo.toml", 
                  "--nb_persons_to_detect", "1", "--person_ordering_method", "greatest_displacement", 
                  "--mode", "lightweight", "--det_frequency", "50", 
                  "--slowmo_factor", "4",
-                 "--filter_type", "gaussian",
+                 "--filter_type", "gaussian", "--use_augmentation", "False",
                  "--pose_model", "body", "--mode", """{'pose_class':'RTMO', 'pose_model':'https://download.openmmlab.com/mmpose/v1/projects/rtmo/onnx_sdk/rtmo-m_16xb16-600e_body7-640x640-39e78cc4_20231211.zip', 'pose_input_size':[640, 640]}"""]
     subprocess.run(demo_cmd3, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace')
     
     # With a time range, inverse kinematics, marker augmentation
-    demo_cmd4 = ["sports2d", "--person_ordering_method", "greatest_displacement", "--show_realtime_results", "False", "--show_graphs", "False",
+    demo_cmd4 = ["sports2d", "--person_ordering_method", "greatest_displacement", "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False",
                  "--time_range", "1.2", "2.7",
                  "--do_ik", "True", "--use_augmentation", "True", 
                  "--nb_persons_to_detect", "all", "--first_person_height", "1.65",
@@ -97,7 +119,7 @@ def test_workflow():
     config_dict.get("base").update({"video_dir": str(video_dir)})
     config_dict.get("base").update({"person_ordering_method": "highest_likelihood"})
     with open(config_path, 'w') as f: toml.dump(config_dict, f)
-    demo_cmd5 = ["sports2d", "--config", str(config_path), "--show_realtime_results", "False", "--show_graphs", "False"]
+    demo_cmd5 = ["sports2d", "--config", str(config_path), "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False",]
     subprocess.run(demo_cmd5, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace')
 
 

{sports2d-0.8.19 → sports2d-0.8.21}/Sports2D/process.py

@@ -29,7 +29,7 @@
     - optionally plots pose and angle data before and after processing for comparison
     - optionally saves poses for each person as a trc file, and angles as a mot file
         
-    /!\ Warning /!\
+    ⚠ Warning ⚠ 
     - The pose detection is only as good as the pose estimation algorithm, i.e., it is not perfect.
     - It will lead to reliable results only if the persons move in the 2D plane (sagittal or frontal plane).
     - The persons need to be filmed as perpendicularly as possible from their side.
@@ -77,6 +77,7 @@ from matplotlib.widgets import Slider, Button
 from matplotlib import patheffects
 
 from rtmlib import PoseTracker, BodyWithFeet, Wholebody, Body, Hand, Custom
+from rtmlib.tools.object_detection.post_processings import nms
 from deep_sort_realtime.deepsort_tracker import DeepSort
 
 from Sports2D.Utilities.common import *
@@ -789,10 +790,10 @@ def make_mot_with_angles(angles, time, mot_path):
     return angles
 
 
-def pose_plots(trc_data_unfiltered, trc_data, person_id):
+def pose_plots(trc_data_unfiltered, trc_data, person_id, show=True):
     '''
     Displays trc filtered and unfiltered data for comparison
-    /!\ Often crashes on the third window...
+    ⚠ Often crashes on the third window...
 
     INPUTS:
     - trc_data_unfiltered: pd.DataFrame. The unfiltered trc data
@@ -835,13 +836,16 @@ def pose_plots(trc_data_unfiltered, trc_data, person_id):
 
         pw.addPlot(keypoint, f)
     
-    pw.show()
+    if show:
+        pw.show()
 
+    return pw
 
-def angle_plots(angle_data_unfiltered, angle_data, person_id):
+
+def angle_plots(angle_data_unfiltered, angle_data, person_id, show=True):
     '''
     Displays angle filtered and unfiltered data for comparison
-    /!\ Often crashes on the third window...
+    ⚠ Often crashes on the third window...
 
     INPUTS:
     - angle_data_unfiltered: pd.DataFrame. The unfiltered angle data
@@ -878,7 +882,10 @@ def angle_plots(angle_data_unfiltered, angle_data, person_id):
 
         pw.addPlot(angle, f)
 
-    pw.show()
+    if show:
+        pw.show()
+
+    return pw
 
 
 def get_personIDs_with_highest_scores(all_frames_scores, nb_persons_to_detect):
@@ -1374,7 +1381,7 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
     - optionally plots pose and angle data before and after processing for comparison
     - optionally saves poses for each person as a trc file, and angles as a mot file
         
-    /!\ Warning /!\d
+    ⚠ Warning ⚠ 
     - The pose detection is only as good as the pose estimation algorithm, i.e., it is not perfect.
     - It will lead to reliable results only if the persons move in the 2D plane (sagittal or frontal plane).
     - The persons need to be filmed as perpendicularly as possible from their side.
@@ -1490,6 +1497,7 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
     handle_LR_swap = config_dict.get('post-processing').get('handle_LR_swap', False)
     reject_outliers = config_dict.get('post-processing').get('reject_outliers', False)
     show_plots = config_dict.get('post-processing').get('show_graphs')
+    save_plots = config_dict.get('post-processing').get('save_graphs')
     filter_type = config_dict.get('post-processing').get('filter_type')
     butterworth_filter_order = config_dict.get('post-processing').get('butterworth', {}).get('order')
     butterworth_filter_cutoff = config_dict.get('post-processing').get('butterworth', {}).get('cut_off_frequency')
@@ -1513,6 +1521,7 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
         output_dir_name = f'{video_file_stem}_Sports2D'    
         video_file_path = video_dir / video_file
     output_dir = result_dir / output_dir_name
+    plots_output_dir = output_dir / f'{output_dir_name}_graphs'
     img_output_dir = output_dir / f'{output_dir_name}_img'
     vid_output_path = output_dir / f'{output_dir_name}.mp4'
     pose_output_path = output_dir / f'{output_dir_name}_px.trc'
@@ -1521,6 +1530,8 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
     output_dir.mkdir(parents=True, exist_ok=True)
     if save_img:
         img_output_dir.mkdir(parents=True, exist_ok=True)
+    if save_plots:
+        plots_output_dir.mkdir(parents=True, exist_ok=True)
 
     # Inverse kinematics settings
     do_ik = config_dict.get('kinematics').get('do_ik')
@@ -1721,6 +1732,13 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                 # Detect poses
                 keypoints, scores = pose_tracker(frame)
 
+                # Non maximum suppression (at pose level, not detection)
+                frame_shape = frame.shape
+                bboxes = bbox_xyxy_compute(frame_shape, keypoints, padding=0)
+                score_bboxes = np.array([np.mean(s) for s in scores])
+                keep = nms(bboxes, score_bboxes, nms_thr=0.45)
+                keypoints, scores = keypoints[keep], scores[keep]
+                
                 # Track poses across frames
                 if tracking_mode == 'deepsort':
                     keypoints, scores = sort_people_deepsort(keypoints, scores, deepsort_tracker, frame, frame_count)
@@ -1999,9 +2017,17 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                     columns_to_concat.extend([all_frames_X_person.iloc[:,kpt], all_frames_Y_person.iloc[:,kpt], all_frames_Z_homog.iloc[:,kpt]])
                 trc_data_unfiltered_i = pd.concat([all_frames_time] + columns_to_concat, axis=1)
                 trc_data_unfiltered.append(trc_data_unfiltered_i)
-                if show_plots and not to_meters:
-                    pose_plots(trc_data_unfiltered_i, trc_data_i, i)
-                
+                if not to_meters and (show_plots or save_plots):
+                    pw = pose_plots(trc_data_unfiltered_i, trc_data_i, i, show=show_plots)
+                    if save_plots:
+                        for n, f in enumerate(pw.figure_handles):
+                            dpi = pw.canvases[i].figure.dpi
+                            f.set_size_inches(1280/dpi, 720/dpi)
+                            title = pw.tabs.tabText(n)
+                            plot_path = plots_output_dir / (pose_output_path.stem + f'_person{i:02d}_px_{title.replace(" ","_").replace("/","_")}.png')
+                            f.savefig(plot_path, dpi=dpi, bbox_inches='tight')
+                        logging.info(f'Pose plots (px) saved in {plots_output_dir}.')
+                        
                 all_frames_X_processed[:,idx_person,:], all_frames_Y_processed[:,idx_person,:] = all_frames_X_person_filt, all_frames_Y_person_filt
                 if calculate_angles or save_angles:
                     all_frames_X_flipped_processed[:,idx_person,:] = all_frames_X_flipped_person
@@ -2087,9 +2113,17 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                     px_to_m_unfiltered_i = [convert_px_to_meters(trc_data_unfiltered[i][kpt_name], first_person_height, height_px, cx, cy, -floor_angle_estim) for kpt_name in new_keypoints_names]
                     trc_data_unfiltered_m_i = pd.concat([all_frames_time.rename('time')]+px_to_m_unfiltered_i, axis=1)
 
-                    if to_meters and show_plots:
-                        pose_plots(trc_data_unfiltered_m_i, trc_data_m_i, i)
-                    
+                    if to_meters and (show_plots or save_plots):
+                        pw = pose_plots(trc_data_unfiltered_m_i, trc_data_m_i, i, show=show_plots)
+                        if save_plots:
+                            for n, f in enumerate(pw.figure_handles):
+                                dpi = pw.canvases[i].figure.dpi
+                                f.set_size_inches(1280/dpi, 720/dpi)
+                                title = pw.tabs.tabText(n)
+                                plot_path = plots_output_dir / (pose_output_path_m.stem + f'_person{i:02d}_m_{title.replace(" ","_").replace("/","_")}.png')
+                                f.savefig(plot_path, dpi=dpi, bbox_inches='tight')
+                            logging.info(f'Pose plots (m) saved in {plots_output_dir}.')
+
                     # Write to trc file
                     trc_data_m.append(trc_data_m_i)
                     pose_path_person_m_i = (pose_output_path.parent / (pose_output_path_m.stem + f'_person{i:02d}.trc'))
@@ -2248,9 +2282,16 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                 logging.info(f'Angles saved to {angles_path_person.resolve()}.')
 
                 # Plotting angles before and after interpolation and filtering
-                if show_plots:
-                    all_frames_angles_person.insert(0, 'time', all_frames_time)
-                    angle_plots(all_frames_angles_person, angle_data, i) # i = current person
+                all_frames_angles_person.insert(0, 'time', all_frames_time)
+                if save_plots and (show_plots or save_plots):
+                    pw = angle_plots(all_frames_angles_person, angle_data, i, show=show_plots) # i = current person
+                    for n, f in enumerate(pw.figure_handles):
+                        dpi = pw.canvases[i].figure.dpi
+                        f.set_size_inches(1280/dpi, 720/dpi)
+                        title = pw.tabs.tabText(n)
+                        plot_path = plots_output_dir / (pose_output_path_m.stem + f'_person{i:02d}_ang_{title.replace(" ","_").replace("/","_")}.png')
+                        f.savefig(plot_path, dpi=dpi, bbox_inches='tight')
+                    logging.info(f'Pose plots (m) saved in {plots_output_dir}.')
 
 
     #%% ==================================================

{sports2d-0.8.19 → sports2d-0.8.21}/pyproject.toml

@@ -46,10 +46,10 @@ dependencies = [
     "c3d",
     "rtmlib",
     "openvino",
-    "opencv-python<4.12", # or forces numpy>=2.0, which is incompatible with some opensim/python combinations
+    "opencv-python<4.12", # otherwise forces numpy>=2.0, which is incompatible with some opensim/python combinations
     "imageio_ffmpeg",
     "deep-sort-realtime",
-    "Pose2Sim>=0.10.33"
+    "Pose2Sim>=0.10.36"
 ]
 
 [tool.setuptools_scm]

{sports2d-0.8.19 → sports2d-0.8.21}/sports2d.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sports2d
-Version: 0.8.19
+Version: 0.8.21
 Summary: Compute 2D human pose and angles from a video or a webcam.
 Author-email: David Pagnon <contact@david-pagnon.com>
 Maintainer-email: David Pagnon <contact@david-pagnon.com>
@@ -38,7 +38,7 @@ Requires-Dist: openvino
 Requires-Dist: opencv-python<4.12
 Requires-Dist: imageio_ffmpeg
 Requires-Dist: deep-sort-realtime
-Requires-Dist: Pose2Sim>=0.10.33
+Requires-Dist: Pose2Sim>=0.10.36
 Dynamic: license-file
 
 
@@ -67,6 +67,7 @@ Dynamic: license-file
 </br>
 
 > **`Announcements:`**
+> - Generate or import a calibration file, OpenSim skeleton overlay **New in v0.9!** 
 > - 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!**
@@ -218,16 +219,19 @@ The Demo video is voluntarily challenging to demonstrate the robustness of the p
 
 1. **Install the Pose2Sim_Blender add-on.**\
    Follow instructions on the [Pose2Sim_Blender](https://github.com/davidpagnon/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**
 2. **Open your point coordinates.**\
-   **Add Markers**: open your trc file(e.g., `coords_m.trc`) from your `result_dir` folder.
-   
+   **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.
 3. **Open your animated skeleton:**\
    Make sure you first set `--do_ik True` ([full install](#full-install) required). See [inverse kinematics](#run-inverse-kinematics) section for more details.
-   - **Add Model**: Open your scaled model (e.g., `Model_Pose2Sim_LSTM.osim`). 
-   - **Add Motion**: Open your motion file (e.g., `angles.mot`). Make sure the skeleton is selected in the outliner.
+   - **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!](https://github.com/perfanalytics/pose2sim/issues/40)**
+   The OpenSim skeleton is not rigged yet. **[Feel free to contribute!](https://github.com/perfanalytics/pose2sim/issues/40)** [![Discord](https://img.shields.io/discord/1183750225471492206?logo=Discord&label=Discord%20community)](https://discord.com/invite/4mXUdSFjmt)
 
 <img src="Content/sports2d_blender.gif" width="760">
 
@@ -284,7 +288,7 @@ If you only want to analyze a subset of the detected persons, you can use the `-
 sports2d --nb_persons_to_detect 2 --person_ordering_method highest_likelihood
 ```
 
-We recommend to use the `on_click` method if you can afford a manual input. This lets the user handle both the person number and their order in the same stage. When prompted, select the persons you are interested in in the desired order. In our case, lets slide to a frame where both people are visible, and select the woman first, then the man.
+We recommend using the `on_click` method if you can afford a manual input. This lets the user handle both the person number and their order in the same stage. When prompted, select the persons you are interested in in the desired order. In our case, lets slide to a frame where both people are visible, and select the woman first, then the man.
 
 Otherwise, if you want to run Sports2D automatically for example, you can choose other ordering methods such as 'highest_likelihood', 'largest_size', 'smallest_size',  'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'.
 
@@ -301,28 +305,32 @@ sports2d --person_ordering_method on_click
 
 
 #### Get coordinates in meters: 
-> **N.B.:** Depth is estimated from a neutral pose. 
+> **N.B.:** The Z coordinate (depth) should not be overly trusted. 
 
-<!-- You either need to provide a calibration file, or simply the height of a person (Note that the latter will not take distortions into account, and that it will be less accurate for motion in the frontal plane).\-->
-You may need to convert pixel coordinates to meters.\
-Just provide the height of the reference person (and their ID in case of multiple person detection).
+You may want coordinates in meters rather than pixels. 2 options to do so:
 
-You can also specify whether the visible side of the person is left, right, front, or back. Set it to 'auto' if you do not want to find it automatically (only works for motion in the sagittal plane), or to 'none' if you want to keep 2D instead of 3D coordinates (if the person goes right, and then left for example).
+1. **Just provide the height of a reference person**:
+   - Their height in meters is be compared with their height in pixels to get a pixel-to-meter conversion factor.
+   - To estimate the depth coordinates, specify which side of the person is visible: `left`, `right`, `front`, or `back`. Use `auto` if you want it to be automatically determined (only works for motions in the sagittal plane), or `none` if you want to keep 2D coordinates instead of 3D (if the person turns around, for example).
+   - The floor angle is automatically estimated from gait, as well as the origin of the xy axis. The person trajectory is corrected accordingly. You can use the `--floor_angle` and `--xy_origin` parameters to manually specify them if your subject is not travelling horizontally or if you want the origin not to be under their feet (note that the `y` axis points down).
+   
+   **N.B.: A calibration file will be generated.** By convention, the camera-to-subject distance is set to 10 meters.
 
-The floor angle and the origin of the xy axis are computed automatically from gait. If you analyze another type of motion, you can manually specify them. Note that `y` points down.\
-Also note that distortions are not taken into account, and that results will be less accurate for motions in the frontal plane.
+   ``` cmd
+   sports2d --first_person_height 1.65 --visible_side auto front none
+   ```
+   ``` cmd
+   sports2d --first_person_height 1.65 --visible_side auto front none `
+            --person_ordering_method on_click `
+            --floor_angle 0 --xy_origin 0 940
+   ```
 
-<!-- ``` cmd
-sports2d --to_meters True --calib_file calib_demo.toml
-``` -->
-``` cmd
-sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none
-```
-``` cmd
-sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none `
-         --person_ordering_method on_click `
-         --floor_angle 0 --xy_origin 0 940
-```
+2. **Or use a calibration file**:\
+  It can either be a `.toml` calibration file previously generated by Sports2D, or a more accurate one coming from another system. For example, [Pose2Sim](https://github.com/perfanalytics/pose2sim) can be used to accurately calculate calibration, or to convert calibration files from Qualisys, Vicon, OpenCap, FreeMoCap, etc.
+
+   ``` cmd
+   sports2d --calib_file Calib_demo.toml --visible_side auto front none
+   ```
 
 <br>
 
@@ -337,18 +345,22 @@ OpenSim inverse kinematics allows you to set joint constraints, joint angle limi
 This is done via [Pose2Sim](https://github.com/perfanalytics/pose2sim).\
 Model scaling is done according to the mean of the segment lengths, across a subset of frames. We remove the 10% fastest frames (potential outliers), the frames where the speed is 0 (person probably out of frame), the frames where the average knee and hip flexion angles are above 45° (pose estimation is not precise when the person is crouching) and the 20% most extreme segment values after the previous operations (potential outliers). All these parameters can be edited in your Config.toml file.
 
+**N.B.: This will not work on sections where the person is not moving in a single plane. You can split your video into several time ranges if needed.**
+
 ```cmd
 sports2d --time_range 1.2 2.7 `
          --do_ik true --first_person_height 1.65 --visible_side auto front
 ```
 
 You can optionally use the LSTM marker augmentation to improve the quality of the output motion.\
-You can also optionally give the participants proper masses. Mass has no influence on motion, only on forces (if you decide to further pursue kinetics analysis).
+You can also optionally give the participants proper masses. Mass has no influence on motion, only on forces (if you decide to further pursue kinetics analysis).\
+Optionally again, you can [visualize the overlaid results in Blender](#visualize-in-blender). The automatic calibration won't be accurate with such a small time range, so you need to use the provided calibration file (or one that has been generated from the full walk).
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
          --do_ik true --first_person_height 1.65 --visible_side left front `
-         --use_augmentation True --participant_mass 55.0 67.0
+         --use_augmentation True --participant_mass 55.0 67.0 `
+         --calib_file Calib_demo.toml
 ```
 
 <br>
@@ -376,14 +388,31 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   ``` cmd
   sports2d --config Config_demo.toml
   ```
-- Run within Python: 
-  ``` python
-  from Sports2D import Sports2D; Sports2D.process('Config_demo.toml')
-  ```
-- Run within Python with a dictionary (for example, `config_dict = toml.load('Config_demo.toml')`):
-  ``` python
-  from Sports2D import Sports2D; Sports2D.process(config_dict)
-  ```
+- Run within Python, for example:\
+  - Edit `Demo/Config_demo.toml` and run:
+    ```python
+    from Sports2D import Sports2D
+    from pathlib import Path
+    import toml
+
+    config_path = Path(Sports2D.__file__).parent / 'Demo'/'Config_demo.toml'
+    config_dict = toml.load(config_path)
+    Sports2D.process(config_dict)
+    ```
+  - Or you can pass the non default values only: 
+    ```python
+    from Sports2D import Sports2D
+    config_dict = {
+      'base': {
+        'nb_persons_to_detect': 1,
+        'person_ordering_method': 'greatest_displacement'
+        },
+      'pose': {
+        'mode': 'lightweight', 
+        'det_frequency': 50
+        }}
+    Sports2D.process(config_dict)
+    ```
 
 <br>
 
@@ -407,7 +436,7 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   ```cmd
   sports2d --flip_left_right true # Default
   ```
-- Correct segment angles according to the estimated camera tild angle.\
+- Correct segment angles according to the estimated camera tilt angle.\
   **N.B.:** *The camera tilt angle is automatically estimated. Set to false if it is actually the floor which is tilted rather than the camera.*
   ```cmd
   sports2d --correct_segment_angles_with_floor_angle true # Default
@@ -477,6 +506,7 @@ sports2d --help
 'show_realtime_results': ["R", "show results in real-time. true if not specified"],
 'display_angle_values_on': ["a", '"body", "list", "body" "list", or "none". body list if not specified'],
 'show_graphs': ["G", "show plots of raw and processed results. true if not specified"],
+'save_graphs': ["", "save position and angle plots of raw and processed results. false if not specified"],
 'joint_angles': ["j", '"Right ankle" "Left ankle" "Right knee" "Left knee" "Right hip" "Left hip" "Right shoulder" "Left shoulder" "Right elbow" "Left elbow" if not specified'],
 'segment_angles': ["s", '"Right foot" "Left foot" "Right shank" "Left shank" "Right thigh" "Left thigh" "Pelvis" "Trunk" "Shoulders" "Head" "Right arm" "Left arm" "Right forearm" "Left forearm" if not specified'],
 'save_vid': ["V", "save processed video. true if not specified"],

{sports2d-0.8.19 → sports2d-0.8.21}/sports2d.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ Sports2D/Sports2D.ipynb
 Sports2D/Sports2D.py
 Sports2D/__init__.py
 Sports2D/process.py
+Sports2D/Demo/Calib_demo.toml
 Sports2D/Demo/Config_demo.toml
 Sports2D/Demo/demo.mp4
 Sports2D/Utilities/__init__.py

{sports2d-0.8.19 → sports2d-0.8.21}/sports2d.egg-info/requires.txt

@@ -14,4 +14,4 @@ openvino
 opencv-python<4.12
 imageio_ffmpeg
 deep-sort-realtime
-Pose2Sim>=0.10.33
+Pose2Sim>=0.10.36