sports2d 0.7.3__tar.gz → 0.8.0__tar.gz

{sports2d-0.7.3 → sports2d-0.8.0}/PKG-INFO

@@ -1,14 +1,41 @@
 Metadata-Version: 2.4
 Name: sports2d
-Version: 0.7.3
-Summary: Detect pose and compute 2D joint angles from a video.
-Home-page: https://github.com/davidpagnon/Sports2D
-Author: David Pagnon
-Author-email: contact@david-pagnon.com
+Version: 0.8.0
+Summary: Compute 2D human pose and angles from a video or a webcam.
+Author-email: David Pagnon <contact@david-pagnon.com>
 License: 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.
+        
+Project-URL: Homepage, https://github.com/davidpagnon/Sports2D
 Project-URL: Bug Tracker, https://github.com/davidpagnon/Sports2D/issues
-Keywords: markerless,kinematics,OpenPose,BlazePose,joint angles,2D,biomechanics,sports,pose estimation,joint angles,sports analytics,kinovea
-Platform: any
+Keywords: markerless,kinematics,OpenPose,OpenSim,Mocap,biomechanics,sports coaching,pose estimation,joint angles,sports analytics,kinovea
 Classifier: Programming Language :: Python :: 3
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
@@ -21,22 +48,23 @@ Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
 Classifier: Topic :: Multimedia :: Graphics
 Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: ipython
 Requires-Dist: toml
-Requires-Dist: numpy
-Requires-Dist: pandas>=1.5
-Requires-Dist: scipy
-Requires-Dist: anytree
-Requires-Dist: opencv-python
+Requires-Dist: numpy>=1.19
 Requires-Dist: matplotlib
 Requires-Dist: PyQt5
+Requires-Dist: tqdm
+Requires-Dist: anytree
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy
 Requires-Dist: statsmodels
+Requires-Dist: ipython
 Requires-Dist: c3d
 Requires-Dist: rtmlib
 Requires-Dist: openvino
-Requires-Dist: tqdm
+Requires-Dist: opencv-python
 Requires-Dist: imageio_ffmpeg
 Requires-Dist: deep-sort-realtime
 Requires-Dist: Pose2Sim
@@ -44,15 +72,18 @@ Dynamic: license-file
 
 
 [![Continuous integration](https://github.com/davidpagnon/sports2d/actions/workflows/continuous-integration.yml/badge.svg?branch=main)](https://github.com/davidpagnon/sports2d/actions/workflows/continuous-integration.yml)
-[![PyPI version](https://badge.fury.io/py/Sports2D.svg)](https://badge.fury.io/py/Sports2D)\
+[![PyPI version](https://badge.fury.io/py/Sports2D.svg)](https://badge.fury.io/py/Sports2D)
+\
 [![Downloads](https://static.pepy.tech/badge/sports2d)](https://pepy.tech/project/sports2d)
 [![Stars](https://img.shields.io/github/stars/davidpagnon/sports2d)](https://github.com/davidpagnon/sports2d/stargazers)
 [![GitHub issues](https://img.shields.io/github/issues/davidpagnon/sports2d)](https://github.com/davidpagnon/sports2d/issues)
-[![GitHub issues-closed](https://img.shields.io/github/issues-closed/davidpagnon/sports2d)](https://GitHub.com/davidpagnon/sports2d/issues?q=is%3Aissue+is%3Aclosed)\
+[![GitHub issues-closed](https://img.shields.io/github/issues-closed/davidpagnon/sports2d)](https://GitHub.com/davidpagnon/sports2d/issues?q=is%3Aissue+is%3Aclosed)
+\
 [![status](https://joss.theoj.org/papers/1d525bbb2695c88c6ebbf2297bd35897/status.svg)](https://joss.theoj.org/papers/1d525bbb2695c88c6ebbf2297bd35897)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10576574.svg)](https://zenodo.org/doi/10.5281/zenodo.7903962)
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-
+\
+[![Discord](https://img.shields.io/discord/1183750225471492206?logo=Discord&label=Discord%20community)](https://discord.com/invite/4mXUdSFjmt)
 
 <!-- [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://bit.ly/Sports2D_Colab)-->
 
@@ -64,8 +95,8 @@ Dynamic: license-file
 
 </br>
 
-> **`Announcement:`\
-> Complete rewriting of the code!** Run `pip install sports2d -U` to get the latest version.
+> **`Announcements:`**
+> - 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!**
@@ -73,6 +104,8 @@ Dynamic: license-file
 > - Works from a webcam
 > - Better visualization output 
 > - More flexible, easier to run
+>
+> Run `pip install sports2d -U` to get the latest version.
 
 ***N.B.:*** As always, I am more than happy to welcome contributions (see [How to contribute](#how-to-contribute-and-to-do-list))!
 <!--User-friendly Colab version released! (and latest issues fixed, too)\
@@ -108,14 +141,15 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
    3. [Play with the parameters](#play-with-the-parameters)
       1. [Run on a custom video or on a webcam](#run-on-a-custom-video-or-on-a-webcam)
       2. [Run for a specific time range](#run-for-a-specific-time-range)
-      3. [Get coordinates in meters](#get-coordinates-in-meters)
-      4. [Run inverse kinematics](#run-inverse-kinematics)
-      5. [Run on several videos at once](#run-on-several-videos-at-once)
-      6. [Use the configuration file or run within Python](#use-the-configuration-file-or-run-within-python)
-      7. [Get the angles the way you want](#get-the-angles-the-way-you-want)
-      8. [Customize your output](#customize-your-output)
-      9. [Use a custom pose estimation model](#use-a-custom-pose-estimation-model)
-      10. [All the parameters](#all-the-parameters)
+      3. [Select the persons you are interested in](#select-the-persons-you-are-interested-in)
+      4. [Get coordinates in meters](#get-coordinates-in-meters)
+      5. [Run inverse kinematics](#run-inverse-kinematics)
+      6. [Run on several videos at once](#run-on-several-videos-at-once)
+      7. [Use the configuration file or run within Python](#use-the-configuration-file-or-run-within-python)
+      8. [Get the angles the way you want](#get-the-angles-the-way-you-want)
+      9. [Customize your output](#customize-your-output)
+      10. [Use a custom pose estimation model](#use-a-custom-pose-estimation-model)
+      11. [All the parameters](#all-the-parameters)
 2. [Go further](#go-further)
    1. [Too slow for you?](#too-slow-for-you)
    3. [Run inverse kinematics](#run-inverse-kinematics)
@@ -263,7 +297,6 @@ sports2d --video_input webcam
 
 <br>
 
-
 #### Run for a specific time range:
 ```cmd
 sports2d --time_range 1.2 2.7
@@ -272,6 +305,28 @@ sports2d --time_range 1.2 2.7
 <br>
 
 
+#### Select the persons you are interested in:
+If you only want to analyze a subset of the detected persons, you can use the `--nb_persons_to_detect` and `--person_ordering_method` parameters. The order matters if you want to [convert coordinates in meters](#get-coordinates-in-meters) or [run inverse kinematics](#run-inverse-kinematics). 
+
+
+``` cmd
+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.
+
+``` cmd
+sports2d --person_ordering_method on_click
+```
+
+
+
+<img src="Content/Person_selection.png" width="760">
+
+
+<br>
+
+
 #### Get coordinates in meters: 
 > **N.B.:** Depth is estimated from a neutral pose. 
 
@@ -288,11 +343,12 @@ Also note that distortions are not taken into account, and that results will be
 sports2d --to_meters True --calib_file calib_demo.toml
 ``` -->
 ``` cmd
-sports2d --to_meters True --px_to_m_person_height 1.65 --px_to_m_from_person_id 2
+sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none
 ```
 ``` cmd
-sports2d --to_meters True --px_to_m_person_height 1.65 --px_to_m_from_person_id 2 `
-         --visible_side front none auto --floor_angle 0 --xy_origin 0 940
+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
 ```
 
 <br>
@@ -310,9 +366,7 @@ Model scaling is done according to the mean of the segment lengths, across a sub
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
-         --do_ik true `
-         --px_to_m_from_person_id 1 --px_to_m_person_height 1.65 `
-         --visible_side front auto 
+         --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.\
@@ -320,9 +374,8 @@ You can also optionally give the participants proper masses. Mass has no influen
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
-         --do_ik true --use_augmentation True `
-         --px_to_m_from_person_id 1 --px_to_m_person_height 1.65 `
-         --visible_side front left --participant_mass 67.0 55.0
+         --do_ik true --first_person_height 1.65 --visible_side left front `
+         --use_augmentation True --participant_mass 55.0 67.0
 ```
 
 <br>
@@ -382,10 +435,6 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
 
 
 #### Customize your output:
-- Only analyze the most prominent person:
-  ``` cmd
-  sports2d --multiperson false
-  ```
 - Choose whether you want video, images, trc pose file, angle mot file, real-time display, and plots:
   ```cmd
   sports2d --save_vid false --save_img true `
@@ -431,8 +480,10 @@ sports2d --help
 'config': ["C", "path to a toml configuration file"],
 
 'video_input': ["i", "webcam, or video_path.mp4, or video1_path.avi video2_path.mp4 ... Beware that images won't be saved if paths contain non ASCII characters"],
-'px_to_m_person_height': ["H", "height of the person in meters. 1.70 if not specified"],
-'visible_side': ["", "front, back, left, right, auto, or none. 'front none auto' if not specified. If 'auto', will be either left or right depending on the direction of the motion. If 'none', no IK for this person"],
+'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
+'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. 'on_click' if not specified"],
+'first_person_height': ["H", "height of the reference person in meters. 1.65 if not specified. Not used if a calibration file is provided"],
+'visible_side': ["", "front, back, left, right, auto, or none. 'auto front none' if not specified. If 'auto', will be either left or right depending on the direction of the motion. If 'none', no IK for this person"],
 'load_trc_px': ["", "load trc file to avaid running pose estimation again. false if not specified"],
 'compare': ["", "visually compare motion with trc file. false if not specified"],
 'webcam_id': ["w", "webcam ID. 0 if not specified"],
@@ -458,7 +509,6 @@ sports2d --help
 'device': ["", "Device for pose estimatino can be 'auto', 'openvino', 'onnxruntime', 'opencv'"],
 'to_meters': ["M", "convert pixels to meters. true if not specified"],
 'make_c3d': ["", "Convert trc to c3d file. true if not specified"],
-'px_to_m_from_person_id': ["", "person ID to calibrate on. 0 if not specified"],
 'floor_angle': ["", "angle of the floor. 'auto' if not specified"],
 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
@@ -468,7 +518,6 @@ sports2d --help
 'use_contacts_muscles': ["", "Use model with contact spheres and muscles. false if not specified"],
 'participant_mass': ["", "mass of the participant in kg or none. Defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)"],
 'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"], 
-'multiperson': ["", "multiperson involves tracking: will be faster if set to false. true if not specified"],
 'tracking_mode': ["", "'sports2d' or 'deepsort'. 'deepsort' is slower, harder to parametrize but can be more robust if correctly tuned"],
 'deepsort_params': ["", 'Deepsort tracking parameters: """{dictionary between 3 double quotes}""". \n\
                     Default: max_age:30, n_init:3, nms_max_overlap:0.8, max_cosine_distance:0.3, nn_budget:200, max_iou_distance:0.8, embedder_gpu: True\n\
@@ -500,7 +549,8 @@ sports2d --help
 'remove_individual_scaling_setup': ["", "remove individual scaling setup files generated during scaling. true if not specified"],
 'remove_individual_ik_setup': ["", "remove individual IK setup files generated during IK. true if not specified"],
 'fastest_frames_to_remove_percent': ["", "Frames with high speed are considered as outliers. Defaults to 0.1"],
-'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"],
+'close_to_zero_speed_m': ["","Sum for all keypoints: about 0.2 m/frame. Defaults to 0.2"],
+'close_to_zero_speed_px': ["", "Sum for all keypoints: about 50 px/frame. Defaults to 50"],
 'large_hip_knee_angles': ["", "Hip and knee angles below this value are considered as imprecise and ignored. Defaults to 45"],
 'trimmed_extrema_percent': ["", "Proportion of the most extreme segment values to remove before calculating their mean. Defaults to 50"],
 'use_custom_logging': ["", "use custom logging. false if not specified"]
@@ -526,7 +576,6 @@ Note that any detection and pose models can be used (first [deploy them with MMP
           'pose_input_size':[192,256]}"""
   ```
 - Use `--det_frequency 50`: Will detect poses only every 50 frames, and track keypoints in between, which is faster.
-- Use `--multiperson false`: Can be used if one single person is present in the video. Otherwise, persons' IDs may be mixed up.
 - Use `--load_trc_px <path_to_file_px.trc>`: Will use pose estimation results from a file. Useful if you want to use different parameters for pixel to meter conversion or angle calculation without running detection and pose estimation all over.
 - Make sure you use `--tracking_mode sports2d`: Will use the default Sports2D tracker. Unlike DeepSort, it is faster, does not require any parametrization, and is as good in non-crowded scenes. 
 
@@ -680,10 +729,9 @@ You will be proposed a to-do list, but please feel absolutely free to propose yo
 - [x] Run again without pose estimation with the option `--load_trc_px` for px .trc file.
 - [x] **Convert positions to meters** by providing the person height, a calibration file, or 3D points [to click on the image](https://stackoverflow.com/questions/74248955/how-to-display-the-coordinates-of-the-points-clicked-on-the-image-in-google-cola)
 - [x] Support any detection and/or pose estimation model.
+- [x]  Optionally let user select the persons of interest.
+- [x] Perform **Inverse kinematics and dynamics** with OpenSim (cf. [Pose2Sim](https://github.com/perfanalytics/pose2sim), but in 2D). Update [this model](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Utilities/2D_gait.osim) (add arms, markers, remove muscles and contact spheres). Add pipeline example.
 
-- [ ] Perform **Inverse kinematics and dynamics** with OpenSim (cf. [Pose2Sim](https://github.com/perfanalytics/pose2sim), but in 2D). Update [this model](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Utilities/2D_gait.osim) (add arms, markers, remove muscles and contact spheres). Add pipeline example.
-- [ ]  Optionally let user select the person of interest in single_person mode:\
-`multiperson = true # true, or 'single_auto', or 'single_click'. 'single_auto' selects the person with highest average likelihood, and 'single_click' lets the user manually select the person of interest.`
 - [ ] Run with the option `--compare_to` to visually compare motion with a trc file. If run with a webcam input, the user can follow the motion of the trc file. Further calculation can then be done to compare specific variables.
 - [ ] **Colab version**: more user-friendly, usable on a smartphone.
 - [ ] **GUI applications** for Windows, Mac, and Linux, as well as for Android and iOS.
@@ -694,33 +742,3 @@ You will be proposed a to-do list, but please feel absolutely free to propose yo
 - [ ] **Pose refinement**. Click and move badly estimated 2D points. See [DeepLabCut](https://www.youtube.com/watch?v=bEuBKB7eqmk) for inspiration.
 - [ ] Add tools for annotating images, undistort them, take perspective into account, etc. (cf. [Kinovea](https://www.kinovea.org/features.html)).
 
-
-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.

{sports2d-0.7.3 → sports2d-0.8.0}/README.md

@@ -1,14 +1,17 @@
 
 [![Continuous integration](https://github.com/davidpagnon/sports2d/actions/workflows/continuous-integration.yml/badge.svg?branch=main)](https://github.com/davidpagnon/sports2d/actions/workflows/continuous-integration.yml)
-[![PyPI version](https://badge.fury.io/py/Sports2D.svg)](https://badge.fury.io/py/Sports2D)\
+[![PyPI version](https://badge.fury.io/py/Sports2D.svg)](https://badge.fury.io/py/Sports2D)
+\
 [![Downloads](https://static.pepy.tech/badge/sports2d)](https://pepy.tech/project/sports2d)
 [![Stars](https://img.shields.io/github/stars/davidpagnon/sports2d)](https://github.com/davidpagnon/sports2d/stargazers)
 [![GitHub issues](https://img.shields.io/github/issues/davidpagnon/sports2d)](https://github.com/davidpagnon/sports2d/issues)
-[![GitHub issues-closed](https://img.shields.io/github/issues-closed/davidpagnon/sports2d)](https://GitHub.com/davidpagnon/sports2d/issues?q=is%3Aissue+is%3Aclosed)\
+[![GitHub issues-closed](https://img.shields.io/github/issues-closed/davidpagnon/sports2d)](https://GitHub.com/davidpagnon/sports2d/issues?q=is%3Aissue+is%3Aclosed)
+\
 [![status](https://joss.theoj.org/papers/1d525bbb2695c88c6ebbf2297bd35897/status.svg)](https://joss.theoj.org/papers/1d525bbb2695c88c6ebbf2297bd35897)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10576574.svg)](https://zenodo.org/doi/10.5281/zenodo.7903962)
 [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-
+\
+[![Discord](https://img.shields.io/discord/1183750225471492206?logo=Discord&label=Discord%20community)](https://discord.com/invite/4mXUdSFjmt)
 
 <!-- [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://bit.ly/Sports2D_Colab)-->
 
@@ -20,8 +23,8 @@
 
 </br>
 
-> **`Announcement:`\
-> Complete rewriting of the code!** Run `pip install sports2d -U` to get the latest version.
+> **`Announcements:`**
+> - 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!**
@@ -29,6 +32,8 @@
 > - Works from a webcam
 > - Better visualization output 
 > - More flexible, easier to run
+>
+> Run `pip install sports2d -U` to get the latest version.
 
 ***N.B.:*** As always, I am more than happy to welcome contributions (see [How to contribute](#how-to-contribute-and-to-do-list))!
 <!--User-friendly Colab version released! (and latest issues fixed, too)\
@@ -64,14 +69,15 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
    3. [Play with the parameters](#play-with-the-parameters)
       1. [Run on a custom video or on a webcam](#run-on-a-custom-video-or-on-a-webcam)
       2. [Run for a specific time range](#run-for-a-specific-time-range)
-      3. [Get coordinates in meters](#get-coordinates-in-meters)
-      4. [Run inverse kinematics](#run-inverse-kinematics)
-      5. [Run on several videos at once](#run-on-several-videos-at-once)
-      6. [Use the configuration file or run within Python](#use-the-configuration-file-or-run-within-python)
-      7. [Get the angles the way you want](#get-the-angles-the-way-you-want)
-      8. [Customize your output](#customize-your-output)
-      9. [Use a custom pose estimation model](#use-a-custom-pose-estimation-model)
-      10. [All the parameters](#all-the-parameters)
+      3. [Select the persons you are interested in](#select-the-persons-you-are-interested-in)
+      4. [Get coordinates in meters](#get-coordinates-in-meters)
+      5. [Run inverse kinematics](#run-inverse-kinematics)
+      6. [Run on several videos at once](#run-on-several-videos-at-once)
+      7. [Use the configuration file or run within Python](#use-the-configuration-file-or-run-within-python)
+      8. [Get the angles the way you want](#get-the-angles-the-way-you-want)
+      9. [Customize your output](#customize-your-output)
+      10. [Use a custom pose estimation model](#use-a-custom-pose-estimation-model)
+      11. [All the parameters](#all-the-parameters)
 2. [Go further](#go-further)
    1. [Too slow for you?](#too-slow-for-you)
    3. [Run inverse kinematics](#run-inverse-kinematics)
@@ -219,7 +225,6 @@ sports2d --video_input webcam
 
 <br>
 
-
 #### Run for a specific time range:
 ```cmd
 sports2d --time_range 1.2 2.7
@@ -228,6 +233,28 @@ sports2d --time_range 1.2 2.7
 <br>
 
 
+#### Select the persons you are interested in:
+If you only want to analyze a subset of the detected persons, you can use the `--nb_persons_to_detect` and `--person_ordering_method` parameters. The order matters if you want to [convert coordinates in meters](#get-coordinates-in-meters) or [run inverse kinematics](#run-inverse-kinematics). 
+
+
+``` cmd
+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.
+
+``` cmd
+sports2d --person_ordering_method on_click
+```
+
+
+
+<img src="Content/Person_selection.png" width="760">
+
+
+<br>
+
+
 #### Get coordinates in meters: 
 > **N.B.:** Depth is estimated from a neutral pose. 
 
@@ -244,11 +271,12 @@ Also note that distortions are not taken into account, and that results will be
 sports2d --to_meters True --calib_file calib_demo.toml
 ``` -->
 ``` cmd
-sports2d --to_meters True --px_to_m_person_height 1.65 --px_to_m_from_person_id 2
+sports2d --to_meters True --first_person_height 1.65 --visible_side auto front none
 ```
 ``` cmd
-sports2d --to_meters True --px_to_m_person_height 1.65 --px_to_m_from_person_id 2 `
-         --visible_side front none auto --floor_angle 0 --xy_origin 0 940
+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
 ```
 
 <br>
@@ -266,9 +294,7 @@ Model scaling is done according to the mean of the segment lengths, across a sub
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
-         --do_ik true `
-         --px_to_m_from_person_id 1 --px_to_m_person_height 1.65 `
-         --visible_side front auto 
+         --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.\
@@ -276,9 +302,8 @@ You can also optionally give the participants proper masses. Mass has no influen
 
 ```cmd
 sports2d --time_range 1.2 2.7 `
-         --do_ik true --use_augmentation True `
-         --px_to_m_from_person_id 1 --px_to_m_person_height 1.65 `
-         --visible_side front left --participant_mass 67.0 55.0
+         --do_ik true --first_person_height 1.65 --visible_side left front `
+         --use_augmentation True --participant_mass 55.0 67.0
 ```
 
 <br>
@@ -338,10 +363,6 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
 
 
 #### Customize your output:
-- Only analyze the most prominent person:
-  ``` cmd
-  sports2d --multiperson false
-  ```
 - Choose whether you want video, images, trc pose file, angle mot file, real-time display, and plots:
   ```cmd
   sports2d --save_vid false --save_img true `
@@ -387,8 +408,10 @@ sports2d --help
 'config': ["C", "path to a toml configuration file"],
 
 'video_input': ["i", "webcam, or video_path.mp4, or video1_path.avi video2_path.mp4 ... Beware that images won't be saved if paths contain non ASCII characters"],
-'px_to_m_person_height': ["H", "height of the person in meters. 1.70 if not specified"],
-'visible_side': ["", "front, back, left, right, auto, or none. 'front none auto' if not specified. If 'auto', will be either left or right depending on the direction of the motion. If 'none', no IK for this person"],
+'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
+'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. 'on_click' if not specified"],
+'first_person_height': ["H", "height of the reference person in meters. 1.65 if not specified. Not used if a calibration file is provided"],
+'visible_side': ["", "front, back, left, right, auto, or none. 'auto front none' if not specified. If 'auto', will be either left or right depending on the direction of the motion. If 'none', no IK for this person"],
 'load_trc_px': ["", "load trc file to avaid running pose estimation again. false if not specified"],
 'compare': ["", "visually compare motion with trc file. false if not specified"],
 'webcam_id': ["w", "webcam ID. 0 if not specified"],
@@ -414,7 +437,6 @@ sports2d --help
 'device': ["", "Device for pose estimatino can be 'auto', 'openvino', 'onnxruntime', 'opencv'"],
 'to_meters': ["M", "convert pixels to meters. true if not specified"],
 'make_c3d': ["", "Convert trc to c3d file. true if not specified"],
-'px_to_m_from_person_id': ["", "person ID to calibrate on. 0 if not specified"],
 'floor_angle': ["", "angle of the floor. 'auto' if not specified"],
 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
@@ -424,7 +446,6 @@ sports2d --help
 'use_contacts_muscles': ["", "Use model with contact spheres and muscles. false if not specified"],
 'participant_mass': ["", "mass of the participant in kg or none. Defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)"],
 'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"], 
-'multiperson': ["", "multiperson involves tracking: will be faster if set to false. true if not specified"],
 'tracking_mode': ["", "'sports2d' or 'deepsort'. 'deepsort' is slower, harder to parametrize but can be more robust if correctly tuned"],
 'deepsort_params': ["", 'Deepsort tracking parameters: """{dictionary between 3 double quotes}""". \n\
                     Default: max_age:30, n_init:3, nms_max_overlap:0.8, max_cosine_distance:0.3, nn_budget:200, max_iou_distance:0.8, embedder_gpu: True\n\
@@ -456,7 +477,8 @@ sports2d --help
 'remove_individual_scaling_setup': ["", "remove individual scaling setup files generated during scaling. true if not specified"],
 'remove_individual_ik_setup': ["", "remove individual IK setup files generated during IK. true if not specified"],
 'fastest_frames_to_remove_percent': ["", "Frames with high speed are considered as outliers. Defaults to 0.1"],
-'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"],
+'close_to_zero_speed_m': ["","Sum for all keypoints: about 0.2 m/frame. Defaults to 0.2"],
+'close_to_zero_speed_px': ["", "Sum for all keypoints: about 50 px/frame. Defaults to 50"],
 'large_hip_knee_angles': ["", "Hip and knee angles below this value are considered as imprecise and ignored. Defaults to 45"],
 'trimmed_extrema_percent': ["", "Proportion of the most extreme segment values to remove before calculating their mean. Defaults to 50"],
 'use_custom_logging': ["", "use custom logging. false if not specified"]
@@ -482,7 +504,6 @@ Note that any detection and pose models can be used (first [deploy them with MMP
           'pose_input_size':[192,256]}"""
   ```
 - Use `--det_frequency 50`: Will detect poses only every 50 frames, and track keypoints in between, which is faster.
-- Use `--multiperson false`: Can be used if one single person is present in the video. Otherwise, persons' IDs may be mixed up.
 - Use `--load_trc_px <path_to_file_px.trc>`: Will use pose estimation results from a file. Useful if you want to use different parameters for pixel to meter conversion or angle calculation without running detection and pose estimation all over.
 - Make sure you use `--tracking_mode sports2d`: Will use the default Sports2D tracker. Unlike DeepSort, it is faster, does not require any parametrization, and is as good in non-crowded scenes. 
 
@@ -636,10 +657,9 @@ You will be proposed a to-do list, but please feel absolutely free to propose yo
 - [x] Run again without pose estimation with the option `--load_trc_px` for px .trc file.
 - [x] **Convert positions to meters** by providing the person height, a calibration file, or 3D points [to click on the image](https://stackoverflow.com/questions/74248955/how-to-display-the-coordinates-of-the-points-clicked-on-the-image-in-google-cola)
 - [x] Support any detection and/or pose estimation model.
+- [x]  Optionally let user select the persons of interest.
+- [x] Perform **Inverse kinematics and dynamics** with OpenSim (cf. [Pose2Sim](https://github.com/perfanalytics/pose2sim), but in 2D). Update [this model](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Utilities/2D_gait.osim) (add arms, markers, remove muscles and contact spheres). Add pipeline example.
 
-- [ ] Perform **Inverse kinematics and dynamics** with OpenSim (cf. [Pose2Sim](https://github.com/perfanalytics/pose2sim), but in 2D). Update [this model](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Utilities/2D_gait.osim) (add arms, markers, remove muscles and contact spheres). Add pipeline example.
-- [ ]  Optionally let user select the person of interest in single_person mode:\
-`multiperson = true # true, or 'single_auto', or 'single_click'. 'single_auto' selects the person with highest average likelihood, and 'single_click' lets the user manually select the person of interest.`
 - [ ] Run with the option `--compare_to` to visually compare motion with a trc file. If run with a webcam input, the user can follow the motion of the trc file. Further calculation can then be done to compare specific variables.
 - [ ] **Colab version**: more user-friendly, usable on a smartphone.
 - [ ] **GUI applications** for Windows, Mac, and Linux, as well as for Android and iOS.

{sports2d-0.7.3 → sports2d-0.8.0}/Sports2D/Demo/Config_demo.toml

@@ -11,15 +11,18 @@
 # Sports2D.process('Config_demo.toml')
 
 
-[project]
+[base]
 video_input = 'demo.mp4'   # 'webcam' or '<video_path.ext>', or ['video1_path.mp4', 'video2_path.avi>', ...]
                            # On Windows, replace '\' with '/'
                            # Beware that images won't be saved if paths contain non ASCII characters.
-px_to_m_from_person_id = 2    # Person to use for pixels to meters conversion (not used if a calibration file is provided)
-px_to_m_person_height = 1.65  # Height of the reference person in meters (for pixels -> meters conversion). 
-visible_side = ['front', 'none', 'auto']  # Choose visible side among ['right', 'left', 'front', 'back', 'auto', 'none']. String or list of strings.
+
+nb_persons_to_detect = 'all'   # int or 'all' # Limiting or not the number of persons to be analyzed
+person_ordering_method = 'highest_likelihood' # 'on_click', 'highest_likelihood', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'
+first_person_height = 1.65  # Height of the reference person in meters (for pixels -> meters conversion: not used if a calibration file is provided)
+visible_side = ['auto', 'front', 'none']  # Choose visible side among ['right', 'left', 'front', 'back', 'auto', 'none']. String or list of strings.
                   # if 'auto', will be either 'left', 'right', or 'front' depending on the direction of the motion
                   # if 'none', coordinates will be left in 2D rather than 3D
+
 load_trc_px = ''  # If you do not want to recalculate pose, load it from a trc file (in px, not in m)
 compare = false   # Not implemented yet
 
@@ -32,10 +35,6 @@ video_dir = ''    # If empty, video dir is current dir
 webcam_id = 0 # your webcam id (0 is default)
 input_size = [1280, 720] # [W, H]. Lower resolution will be faster but less precise.
 
-
-[process]
-multiperson = true   # Saving the motions of all the persons detected and tracked in the video. 
-                     # If false, the person saved will be the one with the highest sum of keypoint scores over the video
 show_realtime_results = true
 save_vid = true
 save_img = true
@@ -107,7 +106,7 @@ to_meters = true
 make_c3d = true
 save_calib = true # Coming soon!
 
-# If conversion from px_to_m_person_height
+# 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)
 xy_origin = ['auto']    # ['auto'] or [px_x,px_y]. N.B.: px_y points downwards. If ['auto'], direction estimated from the start to the end of the line formed by the toes when they are on the ground
 
@@ -154,7 +153,7 @@ filter_type = 'butterworth'   # butterworth, gaussian, LOESS, median
 do_ik = false # Do scaling and inverse kinematics?
 use_augmentation = false  # true or false (lowercase) # Set to true if you want to use the model with augmented markers
 use_contacts_muscles = true # true or false (lowercase) # If true, contact spheres and muscles are added to the model
-participant_mass = [67.0, 55.0] # kg # defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)
+participant_mass = [55.0, 67.0] # kg # defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)
 right_left_symmetry = true # true or false (lowercase) # Set to false only if you have good reasons to think the participant is not symmetrical (e.g. prosthetic limb)
 
 # Choosing best frames to scale the model