sports2d 0.5.6__py3-none-any.whl → 0.6.2__py3-none-any.whl

{sports2d-0.5.6.dist-info → sports2d-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: sports2d
-Version: 0.5.6
+Version: 0.6.2
 Summary: Detect pose and compute 2D joint angles from a video.
 Home-page: https://github.com/davidpagnon/Sports2D
 Author: David Pagnon
@@ -37,6 +37,7 @@ Requires-Dist: rtmlib
 Requires-Dist: openvino
 Requires-Dist: tqdm
 Requires-Dist: imageio_ffmpeg
+Requires-Dist: deep-sort-realtime
 
 
 [![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)
@@ -96,7 +97,8 @@ If you need 3D research-grade markerless joint kinematics, consider using severa
 2. [Go further](#go-further)
    1. [Too slow for you?](#too-slow-for-you)
    2. [What you need is what you get](#what-you-need-is-what-you-get)
-   3. [How it works](#how-it-works)
+   3. [All the parameters](#all-the-parameters)
+   4. [How it works](#how-it-works)
 3. [How to cite and how to contribute](#how-to-cite-and-how-to-contribute)
 
 <br>
@@ -160,12 +162,13 @@ The Demo video is voluntarily challenging to demonstrate the robustness of the p
 - One person walking in the sagittal plane
 - One person doing jumping jacks in the frontal plane. This person then performs a flip while being backlit, both of which are challenging for the pose detection algorithm
 - One tiny person flickering in the background who needs to be ignored
+- The first person is starting high and ending low on the image, which messes up the automatic floor angle calculation. You can set it up manually with the parameter `--floor_angle 0`
 
 <br>
 
 ### Play with the parameters
 
-For a full list of the available parameters, check the [Config_Demo.toml](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Demo/Config_demo.toml) file or type:
+For a full list of the available parameters, see [this section](#all-the-parameters) of the documentation, check the [Config_Demo.toml](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Demo/Config_demo.toml) file, or type:
 ``` cmd
 sports2d --help
 ```
@@ -208,7 +211,10 @@ Note that it does not take distortions into account, and that it will be less ac
   sports2d --show_graphs False --time_range 1.2 2.7 --result_dir path_to_result_dir --slowmo_factor 4
   ```
   ``` cmd
-  sports2d --multiperson false --mode lightweight --det_frequency 50 
+  sports2d --multiperson false --pose_model Body --mode lightweight --det_frequency 50 
+  ```
+  ``` cmd
+  sports2d --tracking_mode deepsort --deepsort_params """{'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}"""
   ```
 <br>
 
@@ -234,10 +240,20 @@ Note that it does not take distortions into account, and that it will be less ac
 
 **Quick fixes:**
 - Use ` --save_vid false --save_img false --show_realtime_results false`: Will not save images or videos, and will not display the results in real time. 
-- Use `--mode lightweight`: Will use a lighter version of RTMPose, which is faster but less accurate.
+- Use `--mode lightweight`: Will use a lighter version of RTMPose, which is faster but less accurate.\
+Note that any detection and pose models can be used (first [deploy them with MMPose](https://mmpose.readthedocs.io/en/latest/user_guides/how_to_deploy.html#onnx) if you do not have their .onnx or .zip files), with the following formalism:
+  ```
+  --mode """{'det_class':'YOLOX',
+          'det_model':'https://download.openmmlab.com/mmpose/v1/projects/rtmposev1/onnx_sdk/yolox_nano_8xb8-300e_humanart-40f6f0d0.zip',
+          'det_input_size':[416,416],
+          'pose_class':'RTMPose',
+          'pose_model':'https://download.openmmlab.com/mmpose/v1/projects/rtmposev1/onnx_sdk/rtmpose-t_simcc-body7_pt-body7_420e-256x192-026a1439_20230504.zip',
+          '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 <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.
+- 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. 
 
 <br> 
 
@@ -278,9 +294,9 @@ Will be much faster, with no impact on accuracy. However, the installation takes
 <br>
 
 #### Customize your output:
-- Choose whether you want video, images, trc pose file, angle mot file, and real-time display:
+- 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 --save_pose false --save_angles true --show_realtime_results false
+  sports2d --save_vid false --save_img true --save_pose false --save_angles true --show_realtime_results false --show_graphs false
   ```
 - Choose which angles you need:
   ```cmd
@@ -355,6 +371,85 @@ sports2d --time_range 1.2 2.7 --ik true --person_orientation front none left
 
 <br>
 
+
+### All the parameters
+
+For a full list of the available parameters, have a look at the [Config_Demo.toml](https://github.com/davidpagnon/Sports2D/blob/main/Sports2D/Demo/Config_demo.toml) file or type:
+
+``` cmd
+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"],
+'person_height': ["H", "height of the person in meters. 1.70 if not specified"],
+'load_trc': ["", "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"],
+'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"],
+'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"],
+'save_img': ["I", "save processed images. true if not specified"],
+'save_pose': ["P", "save pose as trc files. true if not specified"],
+'calculate_angles': ["c", "calculate joint and segment angles. true if not specified"],
+'save_angles': ["A", "save angles as mot files. true if not specified"],
+'slowmo_factor': ["", "slow-motion factor. For a video recorded at 240 fps and exported to 30 fps, it would be 240/30 = 8. 1 if not specified"],
+'pose_model': ["p", "only body_with_feet is available for now. body_with_feet if not specified"],
+'mode': ["m", "light, balanced, or performance. balanced if not specified"],
+'det_frequency': ["f", "run person detection only every N frames, and inbetween track previously detected bounding boxes. keypoint detection is still run on all frames.\n\
+                 Equal to or greater than 1, can be as high as you want in simple uncrowded cases. Much faster, but might be less accurate. 1 if not specified: detection runs on all frames"],
+'to_meters': ["M", "convert pixels to meters. true if not specified"],
+
+'backend': ["", "Backend for pose estimation can be 'auto', 'cpu', 'cuda', 'mps' (for MacOS), or 'rocm' (for AMD GPUs)"],
+'device': ["", "Device for pose estimatino can be 'auto', 'openvino', 'onnxruntime', 'opencv'"],
+'calib_on_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"],
+'save_calib': ["", "save calibration file. true if not specified"],
+'do_ik': ["", "do inverse kinematics. false if not specified"],
+'osim_setup_path': ["", "path to OpenSim setup. '../OpenSim_setup' if not specified"],
+'person_orientation': ["", "front, back, left, right, auto, or none. 'front none left' if not specified. If 'auto', will be either left or right depending on the direction of the motion."],
+'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 rtmlib. sports2d is generally much more accurate and comparable in speed. sports2d if not specified"],
+'deepsort_params': ["", 'Deepsort tracking parameters: """{dictionary between 3 double quotes}""". \n\
+                    More information there: https://github.com/levan92/deep_sort_realtime/blob/master/deep_sort_realtime/deepsort_tracker.py#L51'],     
+'input_size': ["", "width, height. 1280, 720 if not specified. Lower resolution will be faster but less precise"],
+'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"],
+'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"],
+'trimmed_extrema_percent': ["", "Proportion of the most extreme segment values to remove before calculating their mean. Defaults to 50"],
+'fontSize': ["", "font size for angle values. 0.3 if not specified"],
+'flip_left_right': ["", "true or false. true to get consistent angles with people facing both left and right sides. Set it to false if you want timeseries to be continuous even when the participent switches their stance. true if not specified"],
+'correct_segment_angles_with_floor_angle': ["", "true or false. If the camera is tilted, corrects segment angles as regards to the floor angle. Set to false is the floor is tilted instead. True if not specified"],
+'interpolate': ["", "interpolate missing data. true if not specified"],
+'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"],
+'filter': ["", "filter results. true if not specified"],
+'filter_type': ["", "butterworth, gaussian, median, or loess. butterworth 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"],
+'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"],
+'use_custom_logging': ["", "use custom logging. false if not specified"]
+```
+
+<br>
+
+
 ### How it works
 
 Sports2D:
@@ -372,7 +467,7 @@ Sports2D:
 
 2. **Sets up pose estimation with RTMLib.** It can be run in lightweight, balanced, or performance mode, and for faster inference, keypoints can be tracked instead of detected for a certain number of frames. 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. This carefully crafted `sports2d` tracker runs at a comparable speed as the RTMlib one but is much more robust. The user can still choose the RTMLib method if they need it by specifying it in the Config.toml file.
+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. 
 
 4. **Chooses the right persons to keep.** In single-person mode, only keeps the person with the highest average scores over the sequence. In multi-person mode, only retrieves the keypoints with high enough confidence, and only keeps the persons with high enough average confidence over each frame.
 
@@ -455,7 +550,11 @@ If you want to contribute to Sports2D, please follow [this guide](https://docs.g
 - [x] Option to only save one person (with the highest average score, or with the most frames and fastest speed)
 - [x] Run again without pose estimation with the option `--load_trc` 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.
+
 - [ ] 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.6.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+Sports2D/Sports2D.py,sha256=8h8LJiClAPMTrgNyu5MXJaLMk0H3cuCVb5AfjlNqcnQ,27881
+Sports2D/__init__.py,sha256=TyCP7Uuuy6CNklhPf8W84MbYoO1_-1dxowSYAJyk_OI,102
+Sports2D/process.py,sha256=Q2kOkijxT-vxc2bVNHlNmW89G5AMUxUAgR3Ld0_Gbx8,77761
+Sports2D/Demo/Config_demo.toml,sha256=D9DKslAExcjeGyGM96Iergd9GzABbDfkrvIZ6WkR5qA,12039
+Sports2D/Demo/demo.mp4,sha256=2aZkFxhWR7ESMEtXCT8MGA83p2jmoU2sp1ylQfO3gDk,3968304
+Sports2D/Utilities/__init__.py,sha256=TyCP7Uuuy6CNklhPf8W84MbYoO1_-1dxowSYAJyk_OI,102
+Sports2D/Utilities/common.py,sha256=Pmv_meJaQ-H4deWtr3y5paLEq4kc4w1W_L94eQVTtvg,42723
+Sports2D/Utilities/filter.py,sha256=8mVefMjDzxmh9a30eNtIrUuK_mUKoOJ2Nr-OzcQKkKM,4922
+Sports2D/Utilities/skeletons.py,sha256=-EtpcoGxwAtJLr02_svLhdkFoNaQiUGj7cfK_aazgB0,40290
+Sports2D/Utilities/tests.py,sha256=U0uwhPgcDY7HavI5f3HmfWydFi8eOfn_h4FIRCRhFcc,3104
+sports2d-0.6.2.dist-info/LICENSE,sha256=f4qe3nE0Y7ltJho5w-xAR0jI5PUox5Xl-MsYiY7ZRM8,1521
+sports2d-0.6.2.dist-info/METADATA,sha256=crFUyUqG5CrRZ6RxVZaqnPrgg9QQiX6tPrbg1JX6muo,31884
+sports2d-0.6.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+sports2d-0.6.2.dist-info/entry_points.txt,sha256=h2CJTuydtNf8JyaLoWxWl5HTSIxx5Ra_FSiSGQsf7Sk,52
+sports2d-0.6.2.dist-info/top_level.txt,sha256=DoURf9UDB8lQ_9lMUPQMQqhXCvWPFFjJco9NzPlHJ6I,9
+sports2d-0.6.2.dist-info/RECORD,,

{sports2d-0.5.6.dist-info → sports2d-0.6.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

sports2d-0.5.6.dist-info/RECORD

@@ -1,16 +0,0 @@
-Sports2D/Sports2D.py,sha256=dZv4xglguFJZDu9Zv0AZKAGu1TQIW9ynmY8pMsNHw14,26377
-Sports2D/__init__.py,sha256=TyCP7Uuuy6CNklhPf8W84MbYoO1_-1dxowSYAJyk_OI,102
-Sports2D/process.py,sha256=uX35szjJ6T7tOcqXQsljnS6xD1T9ufo2_hhJFI29cKo,89117
-Sports2D/Demo/Config_demo.toml,sha256=CeHY91RXrt26TzvtXnCq7Hp2gMdu3EX-flZxaH0DqyA,6768
-Sports2D/Demo/demo.mp4,sha256=2aZkFxhWR7ESMEtXCT8MGA83p2jmoU2sp1ylQfO3gDk,3968304
-Sports2D/Utilities/__init__.py,sha256=TyCP7Uuuy6CNklhPf8W84MbYoO1_-1dxowSYAJyk_OI,102
-Sports2D/Utilities/common.py,sha256=FEWmlq9HNlHzA2ioV5MPPOeC-5Py4JaDbIIxQgq9hGE,14128
-Sports2D/Utilities/filter.py,sha256=8mVefMjDzxmh9a30eNtIrUuK_mUKoOJ2Nr-OzcQKkKM,4922
-Sports2D/Utilities/skeletons.py,sha256=44IWpz47zjh_6YDqkwaJnSysaGi7ovgYE25ji-hC-Kw,15660
-Sports2D/Utilities/tests.py,sha256=g06HBExGkvZrhZpNXN19G9Shisfgp1cqjAp0kFxiKEc,2574
-sports2d-0.5.6.dist-info/LICENSE,sha256=f4qe3nE0Y7ltJho5w-xAR0jI5PUox5Xl-MsYiY7ZRM8,1521
-sports2d-0.5.6.dist-info/METADATA,sha256=X6YrqZQnm0k9MG59MJe3pguWBwxR0mJ7-c0SWc-67FY,23221
-sports2d-0.5.6.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-sports2d-0.5.6.dist-info/entry_points.txt,sha256=h2CJTuydtNf8JyaLoWxWl5HTSIxx5Ra_FSiSGQsf7Sk,52
-sports2d-0.5.6.dist-info/top_level.txt,sha256=DoURf9UDB8lQ_9lMUPQMQqhXCvWPFFjJco9NzPlHJ6I,9
-sports2d-0.5.6.dist-info/RECORD,,