sports2d 0.8.24__tar.gz → 0.8.26__tar.gz

sports2d-0.8.26/.github/workflows/sync_to_hf.yml.bak

@@ -0,0 +1,19 @@
+name: Sync to Hugging Face Space
+on:
+  push:
+    branches: [ main ]
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Push to Hugging Face Space
+        run: |
+          git clone https://${{ secrets.HUGGINGFACE_TOKEN }}@huggingface.co/spaces/DavidPagnon/sports2d
+          cd sports2d
+          git config --global user.name "DavidPagnon"
+          git config --global user.email "contact@david-pagnon.com"
+          cp -r ../Sports2D/* .
+          git add .
+          git commit -m "Sync from GitHub"
+          git push https://${{ secrets.HUGGINGFACE_TOKEN }}@huggingface.co/spaces/DavidPagnon/sports2d

{sports2d-0.8.24/sports2d.egg-info → sports2d-0.8.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sports2d
-Version: 0.8.24
+Version: 0.8.26
 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>
@@ -40,6 +40,8 @@ Dynamic: license-file
 [![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)
+[![Hugging Face Space](https://img.shields.io/badge/HuggingFace-Sports2D-yellow?logo=huggingface)](https://huggingface.co/spaces/DavidPagnon/sports2d)
+
 
 <!-- [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://bit.ly/Sports2D_Colab)-->
 
@@ -52,7 +54,7 @@ Dynamic: license-file
 </br>
 
 > **`Announcements:`**
-> - Generate or import a calibration file, OpenSim skeleton overlay **New in v0.9!** 
+> - Compensate for floor angle, floor height, depth perspective effects, generate a calibration file **New in v0.8.25!** 
 > - Select only the persons you want to analyze **New in v0.8!** 
 > - MarkerAugmentation and Inverse Kinematics for accurate 3D motion with OpenSim. **New in v0.7!** 
 > - Any detector and pose estimation model can be used. **New in v0.6!**
@@ -80,7 +82,7 @@ https://github.com/user-attachments/assets/2ce62012-f28c-4e23-b3b8-f68931bacb77
 <!-- https://github.com/user-attachments/assets/1c6e2d6b-d0cf-4165-864e-d9f01c0b8a0e -->
 
 `Warning:` Angle estimation is only as good as the pose estimation algorithm, i.e., it is not perfect.\
-`Warning:` Results are acceptable only if the persons move in the 2D plane (sagittal or frontal plane). The persons need to be filmed as parallel as possible to the motion plane.\
+`Warning:` Results are acceptable only if the persons move in the 2D plane (sagittal or frontal). The persons need to be filmed as parallel as possible to the motion plane.\
 If you need 3D research-grade markerless joint kinematics, consider using several cameras with **[Pose2Sim](https://github.com/perfanalytics/pose2sim)**.
 
 <!--`Warning:` Google Colab does not follow the European GDPR requirements regarding data privacy. [Install locally](#installation) if this matters.-->
@@ -90,7 +92,8 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
 
 ## Contents
 1. [Installation and Demonstration](#installation-and-demonstration)
-   1. [Installation](#installation)
+   1. [Test it on Hugging face](#test-it-on-hugging-face)
+   1. [Local installation](#local-installation)
       1. [Quick install](#quick-install)
       2. [Full install](#full-install)
    2. [Demonstration](#demonstration)
@@ -119,7 +122,16 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
 
 ## Installation and Demonstration
 
-### Installation
+
+### Test it on Hugging face
+
+Test an online, limited version [on Hugging Face](https://huggingface.co/spaces/DavidPagnon/sports2d): [![Hugging Face Space](https://img.shields.io/badge/HuggingFace-Sports2D-yellow?logo=huggingface)](https://huggingface.co/spaces/DavidPagnon/sports2d)
+
+<img src="Content/huggingface_demo.png" width="760">
+
+
+
+### Local installation
 
 <!--- OPTION 0: **Use Colab** \
   User-friendly (but full) version, also works on a phone or a tablet.\
@@ -294,30 +306,35 @@ sports2d --person_ordering_method on_click
 #### Get coordinates in meters: 
 > **N.B.:** The Z coordinate (depth) should not be overly trusted. 
 
-You may want coordinates in meters rather than pixels. 2 options to do so:
+To convert from pixels to meters, you need a minima the height of a participant. Better results can be obtained by also providing an information on depth. The camera horizon angle and the floor height are generally automatically estimated. **N.B.: A calibration file will be generated.** 
 
-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 pixel-to-meters scale is computed from the ratio between the height of the participant in meters and in pixels. The height in pixels is automatically calculated; use the `--first_person_height` parameter to specify the height in meters.
+- Depth perspective effects can be compensated either with the camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or from a calibration file. Use the `--perspective_unit` ('distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib') and `--perspective_value` parameters (resp. in m, px, deg, rad, or '').
+- The camera horizon angle can be estimated from kinematics (`auto`), from a calibration file (`from_calib`), or manually (float). Use the `--floor_angle` parameter.
+- Likewise for the floor level. Use the `--xy_origin` parameter.
 
-   ``` 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
-   ```
+If one of these parameters is set to `from_calib`, then use `--calib_file`.
 
-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
-   ```
+``` cmd
+sports2d --first_person_height 1.65
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --floor_angle auto `
+        --xy_origin auto`
+        --perspective_unit distance_m --perspective_value 10
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --floor_angle 0 `
+        --xy_origin from_calib`
+        --perspective_unit from_calib --calib_file Sports2D\Demo\Calib_demo.toml
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --perspective_unit f_px --perspective_value 2520
+```
 
 <br>
 
@@ -419,7 +436,7 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   sports2d --calculate_angles false
   ```
 - Flip angles when the person faces the other side.\
-  **N.B.:** *We consider that the person looks to the right if their toe keypoint is to the right of their heel. This is not always true when the person is sprinting, especially in the swing phase. Set it to false if you want timeseries to be continuous even when the participant switches their stance.*
+  **N.B.: Set to false when sprinting.** *We consider that each limb "looks" to the right if the toe keypoint is to the right of the heel one. This is not always true, particularly during the swing phase of sprinting. Set it to false if you want timeseries to be continuous even when the participant switches their stance.*
   ```cmd
   sports2d --flip_left_right true # Default
   ```
@@ -480,20 +497,25 @@ 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"],
+'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
 'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
 'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', '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"],
+'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)"],
+'perspective_value': ["", "Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'"],
+'perspective_unit': ["", "'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'"],
+'do_ik': ["", "do inverse kinematics. false if not specified"],
+'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
 '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"],
-'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
 'video_dir': ["d", "current directory if not specified"],
 'result_dir': ["r", "current directory if not specified"],
+'webcam_id': ["w", "webcam ID. 0 if not specified"],
 '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"],
+'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"],
@@ -514,11 +536,9 @@ sports2d --help
 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
 'save_calib': ["", "save calibration file. true if not specified"],
-'do_ik': ["", "do inverse kinematics. false if not specified"],
-'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
 'feet_on_floor': ["", "offset marker augmentation results so that feet are at floor level. true if not specified"],
-'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine. 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)"],
+'distortions': ["", "camera distortion coefficients [k1, k2, p1, p2, k3] or 'from_calib'. [0.0, 0.0, 0.0, 0.0, 0.0] if not specified"],
+'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine, no patella. false if not specified"],
 'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"], 
 '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\
@@ -528,6 +548,7 @@ sports2d --help
 'keypoint_likelihood_threshold': ["", "detected keypoints are not retained if likelihood is below this threshold. 0.3 if not specified"],
 'average_likelihood_threshold': ["", "detected persons are not retained if average keypoint likelihood is below this threshold. 0.5 if not specified"],
 'keypoint_number_threshold': ["", "detected persons are not retained if number of detected keypoints is below this threshold. 0.3 if not specified, i.e., i.e., 30 percent"],
+'max_distance': ["", "If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one. in px or None, 100 by default."],
 'fastest_frames_to_remove_percent': ["", "Frames with high speed are considered as outliers. Defaults to 0.1"],
 'close_to_zero_speed_px': ["", "Sum for all keypoints: about 50 px/frame or 0.2 m/frame. Defaults to 50"],
 'large_hip_knee_angles': ["", "Hip and knee angles below this value are considered as imprecise. Defaults to 45"],
@@ -539,15 +560,16 @@ sports2d --help
 'interp_gap_smaller_than': ["", "interpolate sequences of missing data if they are less than N frames long. 10 if not specified"],
 'fill_large_gaps_with': ["", "last_value, nan, or zeros. last_value if not specified"],
 'sections_to_keep': ["", "all, largest, first, or last.  Keep 'all' valid sections even when they are interspersed with undetected chunks, or the 'largest' valid section, or the 'first' one, or the 'last' one"],
+'min_chunk_size': ["", "Minimum number of valid frames in a row to keep a chunk of data for a person.  10 if not specified"],
 'reject_outliers': ["", "reject outliers with Hampel filter before other filtering methods. true if not specified"],
 'filter': ["", "filter results. true if not specified"],
 'filter_type': ["", "butterworth, kalman, gcv_spline, gaussian, median, or loess. butterworth if not specified"],
+'cut_off_frequency': ["", "cut-off frequency of the Butterworth filter. 6 if not specified"],
 'order': ["", "order of the Butterworth filter. 4 if not specified"],
-'cut_off_frequency': ["", "cut-off frequency of the Butterworth filter. 3 if not specified"],
+'gcv_cut_off_frequency': ["", "cut-off frequency of the GCV spline filter. 'auto' is usually better, unless the signal is too short (noise can then be considered as signal -> trajectories not filtered). 'auto' if not specified"],
+'gcv_smoothing_factor': ["", "smoothing factor of the GCV spline filter (>=0). Ignored if cut_off_frequency != 'auto'. Biases results towards more smoothing (>1) or more fidelity to data (<1). 1.0 if not specified"],
 'trust_ratio': ["", "trust ratio of the Kalman filter: How much more do you trust triangulation results (measurements), than the assumption of constant acceleration(process)? 500 if not specified"],
 'smooth': ["", "dual Kalman smoothing. true if not specified"],
-'gcv_cut_off_frequency': ["", "cut-off frequency of the GCV spline filter. 'auto' if not specified"],
-'smoothing_factor': ["", "smoothing factor of the GCV spline filter (>=0). Ignored if cut_off_frequency != 'auto'. Biases results towards more smoothing (>1) or more fidelity to data (<1). 0.1 if not specified"],
 'sigma_kernel': ["", "sigma of the gaussian filter. 1 if not specified"],
 'nb_values_used': ["", "number of values used for the loess filter. 5 if not specified"],
 'kernel_size': ["", "kernel size of the median filter. 3 if not specified"],
@@ -656,11 +678,11 @@ Sports2D:
 
 2. **Sets up pose estimation with RTMLib.** It can be run in lightweight, balanced, or performance mode, and for faster inference, the person bounding boxes can be tracked instead of detected every frame. Any RTMPose model can be used. 
 
-3. **Tracks people** so that their IDs are consistent across frames. A person is associated to another in the next frame when they are at a small distance. IDs remain consistent even if the person disappears from a few frames. We crafted a 'sports2D' tracker which gives good results and runs in real time, but it is also possible to use `deepsort` in particularly challenging situations. 
+3. **Tracks people** so that their IDs are consistent across frames. A person is associated to another in the next frame when they are at a small distance. IDs remain consistent even if the person disappears from a few frames, thanks to the 'sports2D' tracker. [See Release notes of v0.8.22 for more information](https://github.com/davidpagnon/Sports2D/releases/tag/v0.8.22). 
 
 4. **Chooses which persons to analyze.** In single-person mode, only keeps the person with the highest average scores over the sequence. In multi-person mode, you can choose the number of persons to analyze (`nb_persons_to_detect`), and how to order them (`person_ordering_method`). The ordering method can be 'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. `on_click` is default and lets the user click on the persons they are interested in, in the desired order.
 
-4. **Converts the pixel coordinates to meters.** The user can provide the size of a specified person to scale results accordingly. The floor angle and the coordinate origin can either be detected automatically from the gait sequence, or be manually specified. The depth coordinates are set to normative values, depending on whether the person is going left, right, facing the camera, or looking away.
+4. **Converts the pixel coordinates to meters.** The user can provide the size of a specified person to scale results accordingly. The camera horizon angle and the floor level can either be detected automatically from the gait sequence, be manually specified, or obtained frmm a calibration file. The depth perspective effects are compensated thanks with the distance from the camera to the subject, the focal length, the field of view, or from a calibration file. [See Release notes of v0.8.25 for more information](https://github.com/davidpagnon/Sports2D/releases/tag/v0.8.25). 
 
 5. **Computes the selected joint and segment angles**, and flips them on the left/right side if the respective foot is pointing to the left/right. 
 

{sports2d-0.8.24 → sports2d-0.8.26}/README.md

@@ -12,6 +12,8 @@
 [![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)
+[![Hugging Face Space](https://img.shields.io/badge/HuggingFace-Sports2D-yellow?logo=huggingface)](https://huggingface.co/spaces/DavidPagnon/sports2d)
+
 
 <!-- [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://bit.ly/Sports2D_Colab)-->
 
@@ -24,7 +26,7 @@
 </br>
 
 > **`Announcements:`**
-> - Generate or import a calibration file, OpenSim skeleton overlay **New in v0.9!** 
+> - Compensate for floor angle, floor height, depth perspective effects, generate a calibration file **New in v0.8.25!** 
 > - Select only the persons you want to analyze **New in v0.8!** 
 > - MarkerAugmentation and Inverse Kinematics for accurate 3D motion with OpenSim. **New in v0.7!** 
 > - Any detector and pose estimation model can be used. **New in v0.6!**
@@ -52,7 +54,7 @@ https://github.com/user-attachments/assets/2ce62012-f28c-4e23-b3b8-f68931bacb77
 <!-- https://github.com/user-attachments/assets/1c6e2d6b-d0cf-4165-864e-d9f01c0b8a0e -->
 
 `Warning:` Angle estimation is only as good as the pose estimation algorithm, i.e., it is not perfect.\
-`Warning:` Results are acceptable only if the persons move in the 2D plane (sagittal or frontal plane). The persons need to be filmed as parallel as possible to the motion plane.\
+`Warning:` Results are acceptable only if the persons move in the 2D plane (sagittal or frontal). The persons need to be filmed as parallel as possible to the motion plane.\
 If you need 3D research-grade markerless joint kinematics, consider using several cameras with **[Pose2Sim](https://github.com/perfanalytics/pose2sim)**.
 
 <!--`Warning:` Google Colab does not follow the European GDPR requirements regarding data privacy. [Install locally](#installation) if this matters.-->
@@ -62,7 +64,8 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
 
 ## Contents
 1. [Installation and Demonstration](#installation-and-demonstration)
-   1. [Installation](#installation)
+   1. [Test it on Hugging face](#test-it-on-hugging-face)
+   1. [Local installation](#local-installation)
       1. [Quick install](#quick-install)
       2. [Full install](#full-install)
    2. [Demonstration](#demonstration)
@@ -91,7 +94,16 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
 
 ## Installation and Demonstration
 
-### Installation
+
+### Test it on Hugging face
+
+Test an online, limited version [on Hugging Face](https://huggingface.co/spaces/DavidPagnon/sports2d): [![Hugging Face Space](https://img.shields.io/badge/HuggingFace-Sports2D-yellow?logo=huggingface)](https://huggingface.co/spaces/DavidPagnon/sports2d)
+
+<img src="Content/huggingface_demo.png" width="760">
+
+
+
+### Local installation
 
 <!--- OPTION 0: **Use Colab** \
   User-friendly (but full) version, also works on a phone or a tablet.\
@@ -266,30 +278,35 @@ sports2d --person_ordering_method on_click
 #### Get coordinates in meters: 
 > **N.B.:** The Z coordinate (depth) should not be overly trusted. 
 
-You may want coordinates in meters rather than pixels. 2 options to do so:
+To convert from pixels to meters, you need a minima the height of a participant. Better results can be obtained by also providing an information on depth. The camera horizon angle and the floor height are generally automatically estimated. **N.B.: A calibration file will be generated.** 
 
-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 pixel-to-meters scale is computed from the ratio between the height of the participant in meters and in pixels. The height in pixels is automatically calculated; use the `--first_person_height` parameter to specify the height in meters.
+- Depth perspective effects can be compensated either with the camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or from a calibration file. Use the `--perspective_unit` ('distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib') and `--perspective_value` parameters (resp. in m, px, deg, rad, or '').
+- The camera horizon angle can be estimated from kinematics (`auto`), from a calibration file (`from_calib`), or manually (float). Use the `--floor_angle` parameter.
+- Likewise for the floor level. Use the `--xy_origin` parameter.
 
-   ``` 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
-   ```
+If one of these parameters is set to `from_calib`, then use `--calib_file`.
 
-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
-   ```
+``` cmd
+sports2d --first_person_height 1.65
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --floor_angle auto `
+        --xy_origin auto`
+        --perspective_unit distance_m --perspective_value 10
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --floor_angle 0 `
+        --xy_origin from_calib`
+        --perspective_unit from_calib --calib_file Sports2D\Demo\Calib_demo.toml
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --perspective_unit f_px --perspective_value 2520
+```
 
 <br>
 
@@ -391,7 +408,7 @@ sports2d --video_input demo.mp4 other_video.mp4 --time_range 1.2 2.7 0 3.5
   sports2d --calculate_angles false
   ```
 - Flip angles when the person faces the other side.\
-  **N.B.:** *We consider that the person looks to the right if their toe keypoint is to the right of their heel. This is not always true when the person is sprinting, especially in the swing phase. Set it to false if you want timeseries to be continuous even when the participant switches their stance.*
+  **N.B.: Set to false when sprinting.** *We consider that each limb "looks" to the right if the toe keypoint is to the right of the heel one. This is not always true, particularly during the swing phase of sprinting. Set it to false if you want timeseries to be continuous even when the participant switches their stance.*
   ```cmd
   sports2d --flip_left_right true # Default
   ```
@@ -452,20 +469,25 @@ 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"],
+'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
 'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
 'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', '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"],
+'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)"],
+'perspective_value': ["", "Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'"],
+'perspective_unit': ["", "'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'"],
+'do_ik': ["", "do inverse kinematics. false if not specified"],
+'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
 '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"],
-'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
 'video_dir': ["d", "current directory if not specified"],
 'result_dir': ["r", "current directory if not specified"],
+'webcam_id': ["w", "webcam ID. 0 if not specified"],
 '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"],
+'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"],
@@ -486,11 +508,9 @@ sports2d --help
 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
 'save_calib': ["", "save calibration file. true if not specified"],
-'do_ik': ["", "do inverse kinematics. false if not specified"],
-'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
 'feet_on_floor': ["", "offset marker augmentation results so that feet are at floor level. true if not specified"],
-'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine. 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)"],
+'distortions': ["", "camera distortion coefficients [k1, k2, p1, p2, k3] or 'from_calib'. [0.0, 0.0, 0.0, 0.0, 0.0] if not specified"],
+'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine, no patella. false if not specified"],
 'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"], 
 '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\
@@ -500,6 +520,7 @@ sports2d --help
 'keypoint_likelihood_threshold': ["", "detected keypoints are not retained if likelihood is below this threshold. 0.3 if not specified"],
 'average_likelihood_threshold': ["", "detected persons are not retained if average keypoint likelihood is below this threshold. 0.5 if not specified"],
 'keypoint_number_threshold': ["", "detected persons are not retained if number of detected keypoints is below this threshold. 0.3 if not specified, i.e., i.e., 30 percent"],
+'max_distance': ["", "If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one. in px or None, 100 by default."],
 'fastest_frames_to_remove_percent': ["", "Frames with high speed are considered as outliers. Defaults to 0.1"],
 'close_to_zero_speed_px': ["", "Sum for all keypoints: about 50 px/frame or 0.2 m/frame. Defaults to 50"],
 'large_hip_knee_angles': ["", "Hip and knee angles below this value are considered as imprecise. Defaults to 45"],
@@ -511,15 +532,16 @@ sports2d --help
 'interp_gap_smaller_than': ["", "interpolate sequences of missing data if they are less than N frames long. 10 if not specified"],
 'fill_large_gaps_with': ["", "last_value, nan, or zeros. last_value if not specified"],
 'sections_to_keep': ["", "all, largest, first, or last.  Keep 'all' valid sections even when they are interspersed with undetected chunks, or the 'largest' valid section, or the 'first' one, or the 'last' one"],
+'min_chunk_size': ["", "Minimum number of valid frames in a row to keep a chunk of data for a person.  10 if not specified"],
 'reject_outliers': ["", "reject outliers with Hampel filter before other filtering methods. true if not specified"],
 'filter': ["", "filter results. true if not specified"],
 'filter_type': ["", "butterworth, kalman, gcv_spline, gaussian, median, or loess. butterworth if not specified"],
+'cut_off_frequency': ["", "cut-off frequency of the Butterworth filter. 6 if not specified"],
 'order': ["", "order of the Butterworth filter. 4 if not specified"],
-'cut_off_frequency': ["", "cut-off frequency of the Butterworth filter. 3 if not specified"],
+'gcv_cut_off_frequency': ["", "cut-off frequency of the GCV spline filter. 'auto' is usually better, unless the signal is too short (noise can then be considered as signal -> trajectories not filtered). 'auto' if not specified"],
+'gcv_smoothing_factor': ["", "smoothing factor of the GCV spline filter (>=0). Ignored if cut_off_frequency != 'auto'. Biases results towards more smoothing (>1) or more fidelity to data (<1). 1.0 if not specified"],
 'trust_ratio': ["", "trust ratio of the Kalman filter: How much more do you trust triangulation results (measurements), than the assumption of constant acceleration(process)? 500 if not specified"],
 'smooth': ["", "dual Kalman smoothing. true if not specified"],
-'gcv_cut_off_frequency': ["", "cut-off frequency of the GCV spline filter. 'auto' if not specified"],
-'smoothing_factor': ["", "smoothing factor of the GCV spline filter (>=0). Ignored if cut_off_frequency != 'auto'. Biases results towards more smoothing (>1) or more fidelity to data (<1). 0.1 if not specified"],
 'sigma_kernel': ["", "sigma of the gaussian filter. 1 if not specified"],
 'nb_values_used': ["", "number of values used for the loess filter. 5 if not specified"],
 'kernel_size': ["", "kernel size of the median filter. 3 if not specified"],
@@ -628,11 +650,11 @@ Sports2D:
 
 2. **Sets up pose estimation with RTMLib.** It can be run in lightweight, balanced, or performance mode, and for faster inference, the person bounding boxes can be tracked instead of detected every frame. Any RTMPose model can be used. 
 
-3. **Tracks people** so that their IDs are consistent across frames. A person is associated to another in the next frame when they are at a small distance. IDs remain consistent even if the person disappears from a few frames. We crafted a 'sports2D' tracker which gives good results and runs in real time, but it is also possible to use `deepsort` in particularly challenging situations. 
+3. **Tracks people** so that their IDs are consistent across frames. A person is associated to another in the next frame when they are at a small distance. IDs remain consistent even if the person disappears from a few frames, thanks to the 'sports2D' tracker. [See Release notes of v0.8.22 for more information](https://github.com/davidpagnon/Sports2D/releases/tag/v0.8.22). 
 
 4. **Chooses which persons to analyze.** In single-person mode, only keeps the person with the highest average scores over the sequence. In multi-person mode, you can choose the number of persons to analyze (`nb_persons_to_detect`), and how to order them (`person_ordering_method`). The ordering method can be 'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. `on_click` is default and lets the user click on the persons they are interested in, in the desired order.
 
-4. **Converts the pixel coordinates to meters.** The user can provide the size of a specified person to scale results accordingly. The floor angle and the coordinate origin can either be detected automatically from the gait sequence, or be manually specified. The depth coordinates are set to normative values, depending on whether the person is going left, right, facing the camera, or looking away.
+4. **Converts the pixel coordinates to meters.** The user can provide the size of a specified person to scale results accordingly. The camera horizon angle and the floor level can either be detected automatically from the gait sequence, be manually specified, or obtained frmm a calibration file. The depth perspective effects are compensated thanks with the distance from the camera to the subject, the focal length, the field of view, or from a calibration file. [See Release notes of v0.8.25 for more information](https://github.com/davidpagnon/Sports2D/releases/tag/v0.8.25). 
 
 5. **Computes the selected joint and segment angles**, and flips them on the left/right side if the respective foot is pointing to the left/right. 
 

{sports2d-0.8.24 → sports2d-0.8.26}/Sports2D/Demo/Config_demo.toml

@@ -97,7 +97,8 @@ tracking_mode = 'sports2d' # 'sports2d' or 'deepsort'. 'deepsort' is slower, har
 keypoint_likelihood_threshold = 0.3 # Keypoints whose likelihood is lower will not be taken into account
 average_likelihood_threshold = 0.5  # Person will be ignored if average likelihood of good keypoints is lower than this value
 keypoint_number_threshold = 0.3     # Person will be ignored if the number of good keypoints (above keypoint_likelihood_threshold) is less than this fraction
-max_distance = 100  # in px or None # If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one
+max_distance = 250  # in px or None # If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one
+
 
 [px_to_meters_conversion]
 # Pixel to meters conversion
@@ -105,15 +106,20 @@ to_meters = true
 make_c3d = true
 save_calib = true
 
-# 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
+# Compensate for camera horizon 
+floor_angle = 'auto' # float, 'from_kinematics', 'from_calib', or 'auto' # 'auto' is equivalent to 'from_kinematics', ie angle calculated from foot contacts. 'from_calib' calculates it from a toml calibration file. Use float to manually specify it in degrees
+xy_origin = ['auto'] # [px_x,px_y], or ['from kinematics'], ['from_calib'], or ['auto']. # BETWEEN BRACKETS! # ['auto'] is equivalent to ['from_kinematics'], ie origin estimated at first foot contact, direction is direction of motion. ['from_calib'] calculates it from a calibration file. Use [px_x,px_y] to manually specify it in pixels (px_y points downwards)
+
+# Compensate for perspective effects, which make the further limb look smaller. 1-2% coordinate error at 10 m, less if the camera is further away
+perspective_value = 10 # Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'
+perspective_unit = 'distance_m' # 'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'
+
+# Optional distortion coefficients
+distortions = [0.0, 0.0, 0.0, 0.0, 0.0] # [k1, k2, p1, p2, k3] or 'from_calib' (not implemented yet)
+
+# Optional calibration file
+calib_file = ''      # Calibration file in the Pose2Sim toml format, or '' if not available
 
-# If conversion from a calibration file
-calib_file = ''         # Calibration in the Pose2Sim format. 'calib_demo.toml', or '' if not available
-# subject_distance
-# focal_distance
-# recalculate_extrinsics
 
 [angles]
 display_angle_values_on = ['body', 'list'] # 'body', 'list', ['body', 'list'], 'none'. Display angle values on the body, as a list in the upper left of the image, both, or do not display them.
@@ -127,7 +133,7 @@ joint_angles = ['Right ankle', 'Left ankle', 'Right knee', 'Left knee', 'Right h
 segment_angles = ['Right foot', 'Left foot', 'Right shank', 'Left shank', 'Right thigh', 'Left thigh', 'Pelvis', 'Trunk', 'Shoulders', 'Head', 'Right arm', 'Left arm', 'Right forearm', 'Left forearm']
 
 # Processing parameters
-flip_left_right = true  # Same angles whether the participant faces left/right. Set it to false if you want timeseries to be continuous even when the participant switches their stance.
+flip_left_right = false  # Same angles whether the participant faces left/right. Set it to false if you want timeseries to be continuous even when the participant switches their stance.
 correct_segment_angles_with_floor_angle = true # If the camera is tilted, corrects segment angles as regards to the floor angle. Set to false if it is the floor which is actually tilted
 
 
@@ -209,7 +215,7 @@ use_custom_logging = false # if integrated in an API that already has logging
 # 
 # Check your model hierarchy with:  for pre, _, node in RenderTree(model): 
 #                                      print(f'{pre}{node.name} id={node.id}')
-[pose.CUSTOM]
+[[pose.CUSTOM]]
 name = "Hip"
 id = 19
   [[pose.CUSTOM.children]]

{sports2d-0.8.24 → sports2d-0.8.26}/Sports2D/Sports2D.py

@@ -152,7 +152,7 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
                                 'keypoint_likelihood_threshold': 0.3,
                                 'average_likelihood_threshold': 0.5,
                                 'keypoint_number_threshold': 0.3,
-                                'max_distance': 100,
+                                'max_distance': 250,
                                 'CUSTOM': { 'name': 'Hip',
                                             'id': 19,
                                             'children': [{'name': 'RHip',
@@ -194,10 +194,13 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
                     'px_to_meters_conversion': {
                                 'to_meters': True,
                                 'make_c3d': True,
-                                'calib_file': '',
+                                'save_calib': True,
+                                'perspective_value': 10.0,
+                                'perspective_unit': 'distance_m',
+                                'distortions': [0.0, 0.0, 0.0, 0.0, 0.0],
                                 'floor_angle': 'auto',
                                 'xy_origin': ['auto'],
-                                'save_calib': True
+                                'calib_file': '',
                                 },
                     'angles':   {'display_angle_values_on': ['body', 'list'],
                                 'fontSize': 0.3,
@@ -269,16 +272,21 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
 
 CONFIG_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"],
+                'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
                 'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
                 'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', '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"],
+                '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)"],
+                'perspective_value': ["", "Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'"],
+                'perspective_unit': ["", "'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'"],
+                'do_ik': ["", "do inverse kinematics. false if not specified"],
+                'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
                 '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"],
-                'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
                 'video_dir': ["d", "current directory if not specified"],
                 'result_dir': ["r", "current directory if not specified"],
+                'webcam_id': ["w", "webcam ID. 0 if not specified"],
                 '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"],
@@ -303,11 +311,9 @@ CONFIG_HELP =   {'config': ["C", "path to a toml configuration file"],
                 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
                 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
                 'save_calib': ["", "save calibration file. true if not specified"],
-                'do_ik': ["", "do inverse kinematics. false if not specified"],
-                'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
                 'feet_on_floor': ["", "offset marker augmentation results so that feet are at floor level. true if not specified"],
+                'distortions': ["", "camera distortion coefficients [k1, k2, p1, p2, k3] or 'from_calib'. [0.0, 0.0, 0.0, 0.0, 0.0] if not specified"],
                 'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine, no patella. 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"], 
                 '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\

{sports2d-0.8.24 → sports2d-0.8.26}/Sports2D/Utilities/common.py

@@ -36,6 +36,9 @@ __status__ = "Development"
 
 
 ## CONSTANTS
+# 4 points joint angle: between knee and ankle, and toe and heel. Add 90° offset and multiply by 1
+# 3 points joint angle: between ankle, knee, hip. -180° offset, multiply by -1
+# 2 points segment angle: between horizontal and ankle and knee, 0° offset, multiply by -1
 angle_dict = { # lowercase!
     # joint angles
     'right ankle': [['RKnee', 'RAnkle', 'RBigToe', 'RHeel'], 'dorsiflexion', 90, 1],