sports2d 0.8.4__py3-none-any.whl → 0.8.5__py3-none-any.whl

Content/paper.bib

@@ -0,0 +1,298 @@
+@article{Bazarevsky_2020,
+  title={Blazepose: On-device real-time body pose tracking},
+  author={Bazarevsky, Valentin and Grishchenko, Ivan and Raveendran, Karthik and Zhu, Tyler and Zhang, Fan and Grundmann, Matthias},
+  DOI={10.48550/arXiv.2006.10204},
+  journal={arXiv preprint arXiv:2006.10204},
+  year={2020}
+}
+
+@article{Bisong_2019,
+  title={Google colaboratory},
+  author={Bisong, Ekaba and Bisong, Ekaba},
+  DOI={10.1007/978-1-4842-4470-8},
+  journal={Building machine learning and deep learning models on google cloud platform: a comprehensive guide for beginners},
+  pages={59--64},
+  year={2019},
+  publisher={Springer}
+}
+
+@article{Boswell_2023,
+  title={Smartphone videos of the sit-to-stand test predict osteoarthritis and health outcomes in a nationwide study},
+  author={Boswell, Melissa A and Kidzi{\'n}ski, {\L}ukasz and Hicks, Jennifer L and Uhlrich, Scott D and Falisse, Antoine and Delp, Scott L},
+  DOI={10.1038/s41746-023-00775-1},
+  journal={npj Digital Medicine},
+  volume={6},
+  number={1},
+  pages={32},
+  year={2023},
+  publisher={Nature Publishing Group UK London}
+}
+
+@article{Bradski_2000,
+  author = {Bradski, G.},
+  citeulike-article-id = {2236121},
+  journal = {Dr. Dobb's Journal of Software Tools},
+  keywords = {bibtex-import},
+  posted-at = {2008-01-15 19:21:54},
+  priority = {4},
+  title = {The OpenCV Library},
+  year = {2000}
+}
+
+@article{Bright_2012,
+  title={Effect of clinical decision-support systems: a systematic review},
+  author={Bright, Tiffani J and Wong, Anthony and Dhurjati, Ravi and Bristow, Erin and Bastian, Lori and Coeytaux, Remy R and Samsa, Gregory and Hasselblad, Vic and Williams, John W and Musty, Michael D and others},
+  DOI={10.7326/0003-4819-157-1-201207030-00450},
+  journal={Annals of internal medicine},
+  volume={157},
+  number={1},
+  pages={29--43},
+  year={2012},
+  publisher={American College of Physicians}
+}
+
+@article{Butterworth_1930,
+  title={On the theory of filter amplifiers},
+  author={Butterworth, Stephen},
+  journal={Wireless Engineer},
+  volume={7},
+  number={6},
+  pages={536--541},
+  year={1930}
+}
+
+@article{Cao_2019,
+  title={OpenPose: realtime multi-person 2D pose estimation using Part Affinity Fields},
+  author={Cao, Zhe and Hidalgo, Gines and Simon, Tomas and Wei, Shih-En and Sheikh, Yaser},
+  journal={IEEE transactions on pattern analysis and machine intelligence},
+  volume={43},
+  number={1},
+  pages={172--186},
+  year={2019},
+  URL = {https://arxiv.org/abs/1611.08050},
+  DOI = {10.1109/TPAMI.2019.2929257},
+  publisher={IEEE}
+}
+
+@article{Cleveland_1981,
+  title={LOWESS: A program for smoothing scatterplots by robust locally weighted regression},
+  author={Cleveland, William S},
+  DOI={10.2307/2683591},
+  journal={American Statistician},
+  volume={35},
+  number={1},
+  pages={54},
+  year={1981}
+}
+
+@article{Colyer_2018,
+  title={A review of the evolution of vision-based motion analysis and the integration of advanced computer vision methods towards developing a markerless system},
+  author={Colyer, Steffi L and Evans, Murray and Cosker, Darren P and Salo, Aki IT},
+  journal={Sports medicine-open},
+  DOI={10.1186/s40798-018-0139-y},
+  volume={4},
+  number={1},
+  pages={1--15},
+  year={2018},
+  publisher={SpringerOpen}
+}
+
+@article{Delp_2007,
+  title={OpenSim: open-source software to create and analyze dynamic simulations of movement},
+  author={Delp, Scott L and Anderson, Frank C and Arnold, Allison S and Loan, Peter and Habib, Ayman and John, Chand T and Guendelman, Eran and Thelen, Darryl G},
+  journal={IEEE transactions on biomedical engineering},
+  volume={54},
+  number={11},
+  pages={1940--1950},
+  year={2007},
+  URL = {https://ieeexplore.ieee.org/abstract/document/4352056},
+  DOI = {10.1109/TBME.2007.901024},
+  publisher={IEEE}
+}
+
+@article{Di_2021,
+  title={A 2D qualitative movement assessment of a deceleration task detects football players with high knee joint loading},
+  author={Di Paolo, Stefano and Zaffagnini, Stefano and Tosarelli, Filippo and Aggio, Fabrizio and Bragonzoni, Laura and Grassi, Alberto and Della Villa, Francesco},
+  DOI={10.1007/s00167-021-06709-2},
+  journal={Knee Surgery, Sports Traumatology, Arthroscopy},
+  volume={29},
+  pages={4032--4040},
+  year={2021},
+  publisher={Springer}
+}
+
+@article{Jiang_2023,
+  title={RTMPose: Real-Time Multi-Person Pose Estimation based on MMPose}, 
+  author={Tao Jiang and Peng Lu and Li Zhang and Ningsheng Ma and Rui Han and Chengqi Lyu and Yining Li and Kai Chen},
+  DOI={10.48550/arXiv.2303.07399},
+  journal={arXiv},
+  year={2023},
+  eprint={2303.07399},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2303.07399}, 
+}
+
+@article{Kidzinski_2020,
+  title={Deep neural networks enable quantitative movement analysis using single-camera videos},
+  author={Kidzi{\'n}ski, {\L}ukasz and Yang, Bryan and Hicks, Jennifer L and Rajagopal, Apoorva and Delp, Scott L and Schwartz, Michael H},
+  DOI={10.1038/s41467-020-17807-z},
+  journal={Nature communications},
+  volume={11},
+  number={1},
+  pages={4054},
+  year={2020},
+  publisher={Nature Publishing Group UK London}
+}
+
+@misc{Kinovea,
+  author = {Kinovea},
+  title = {Kinovea - A microscope for your videos},
+  year = {},
+  publisher = {GitHub},
+  url = {https://www.kinovea.org/features.html},
+  howpublished = {\url{https://www.kinovea.org/features.html}}
+}
+
+@article{Mathis_2018,
+  title={DeepLabCut: markerless pose estimation of user-defined body parts with deep learning},
+  author={Mathis, Alexander and Mamidanna, Pranav and Cury, Kevin M and Abe, Taiga and Murthy, Venkatesh N and Mathis, Mackenzie Weygandt and Bethge, Matthias},
+  journal={Nature neuroscience},
+  volume={21},
+  number={9},
+  pages={1281--1289},
+  year={2018},
+  URL = {https://www.nature.com/articles/s41593-018-0209-y},
+  DOI = {10.1038/s41593-018-0209-y},
+  publisher={Nature Publishing Group}
+}
+
+@article{Minssen_2020,
+  title={Clinical trial data transparency and GDPR compliance: Implications for data sharing and open innovation},
+  author={Minssen, Timo and Rajam, Neethu and Bogers, Marcel},
+  DOI={10.2139/ssrn.3413035},
+  journal={Science and Public Policy},
+  volume={47},
+  number={5},
+  pages={616--626},
+  year={2020},
+  publisher={Oxford University Press}
+}
+
+@article{ODonoghue_2008,
+  title={Principal components analysis in the selection of key performance indicators in sport},
+  author={O’Donoghue, Peter},
+  doi={10.1080/24748668.2008.11868456},
+  journal={International Journal of Performance Analysis in Sport},
+  volume={8},
+  number={3},
+  pages={145--155},
+  year={2008},
+  publisher={Taylor \& Francis}
+}
+
+@article{Pagnon_2022a, 
+  author = {Pagnon, David and {\sortcite{Pagnonb}}Domalain, Mathieu and Reveret, Lionel}, 
+  title = {Pose2Sim: An open-source Python package for multiview markerless kinematics}, 
+  journal = {Journal of Open Source Software}, 
+  publisher = {The Open Journal},
+  year = {2022},
+  doi = {10.21105/joss.04362}, 
+  url = {https://joss.theoj.org/papers/10.21105/joss.04362},
+  volume = {7}, 
+  number = {77}, 
+  pages = {4362}
+ }
+
+@inproceedings{Pagnon_2022b,
+  title = {{A 3D markerless protocol with action cameras – Key performance indicators in boxing}},
+  author = {Pagnon, David and {\sortcite{Pagnonc}}Domalain, Mathieu and Robert, Thomas and Lahkar, Bhrigu-Kumar and Moussa, Issa and Sauli{\`e}re, Guillaume and Goyallon, Thibault and Reveret, Lionel},
+  booktitle={2022 Congress of the European College of Sport Science (ECSS)},
+  url = {https://hal.archives-ouvertes.fr/hal-03790926},
+  note = {Poster},
+  year = {2022}
+}
+
+@article{Patrizi_2016,
+  title={Comparison between low-cost marker-less and high-end marker-based motion capture systems for the computer-aided assessment of working ergonomics},
+  author={Patrizi, Alfredo and Pennestr{\`\i}, Ettore and Valentini, Pier Paolo},
+  DOI={10.1080/00140139.2015.1057238},
+  journal={Ergonomics},
+  volume={59},
+  number={1},
+  pages={155--162},
+  year={2016},
+  publisher={Taylor \& Francis}
+}
+
+@article{Seth_2018,
+  DOI = {10.1371/journal.pcbi.1006223},
+  author = {Seth, Ajay AND Hicks, Jennifer L. AND Uchida, Thomas K. AND Habib, Ayman AND Dembia, Christopher L. AND Dunne, James J. AND Ong, Carmichael F. AND DeMers, Matthew S. AND Rajagopal, Apoorva AND Millard, Matthew AND Hamner, Samuel R. AND Arnold, Edith M. AND Yong, Jennifer R. AND Lakshmikanth, Shrinidhi K. AND Sherman, Michael A. AND Ku, Joy P. AND Delp, Scott L.},
+  journal = {PLOS Computational Biology},
+  publisher = {Public Library of Science},
+  title = {OpenSim: Simulating musculoskeletal dynamics and neuromuscular control to study human and animal movement},
+  year = {2018},
+  month = {07},
+  volume = {14},
+  url = {https://doi.org/10.1371/journal.pcbi.1006223},
+  pages = {1-20},
+  number = {7},
+}
+
+ @article{Uhlrich_2022,
+  title={OpenCap: 3D human movement dynamics from smartphone videos},
+  url={https://www.biorxiv.org/content/10.1101/2022.07.07.499061v1}, 
+  DOI={10.1101/2022.07.07.499061}, 
+  publisher={bioRxiv}, 
+  author={Uhlrich, Scott D. and Falisse, Antoine and Kidziński, Łukasz and Muccini, Julie and Ko, Michael and Chaudhari, Akshay S. and Hicks, Jennifer L. and Delp, Scott L.}, 
+  year={2022}, 
+  month={Jul}, 
+  pages={2022.07.07.499061}
+}
+
+@article{Venkatesh_2012,
+  title={Consumer acceptance and use of information technology: extending the unified theory of acceptance and use of technology},
+  author={Venkatesh, Viswanath and Thong, James YL and Xu, Xin},
+  DOI={10.2307/41410412},
+  journal={MIS quarterly},
+  pages={157--178},
+  year={2012},
+  publisher={JSTOR}
+}
+
+@article{Wade_2022,
+  title={Applications and limitations of current markerless motion capture methods for clinical gait biomechanics},
+  author={Wade, Logan and Needham, Laurie and McGuigan, Polly and Bilzon, James},
+  DOI={10.7717/peerj.12995},
+  journal={PeerJ},
+  volume={10},
+  pages={e12995},
+  year={2022},
+  publisher={PeerJ Inc.}
+}
+
+@book{Whittle_2014,
+  title={Gait analysis: an introduction},
+  author={Whittle, Michael W},
+  year={2014},
+  publisher={Butterworth-Heinemann}
+}
+
+@book{winter2009biomechanics,
+  title={Biomechanics and motor control of human movement},
+  author={Winter, David A},
+  year={2009},
+  publisher={John wiley \& sons}
+}
+
+@article{Zheng_2023,
+  title={Deep learning-based human pose estimation: A survey},
+  author={Zheng, Ce and Wu, Wenhan and Chen, Chen and Yang, Taojiannan and Zhu, Sijie and Shen, Ju and Kehtarnavaz, Nasser and Shah, Mubarak},
+  DOI={10.1145/3603618},
+  journal={ACM Computing Surveys},
+  volume={56},
+  number={1},
+  pages={1--37},
+  year={2023},
+  publisher={ACM New York, NY}
+}

Content/paper.md

@@ -0,0 +1,141 @@
+---
+title: 'Sports2D: Compute 2D human pose and angles from a video or a webcam'
+tags:
+  - python
+  - markerless kinematics
+  - motion capture
+  - sports performance analysis
+  - rtmpose
+  - clinical gait analysis
+authors:
+  - name: David Pagnon^[corresponding author] 
+    orcid: 0000-0002-6891-8331
+    affiliation: 1
+  - name: HunMin Kim
+    orcid: 0009-0007-7710-8051
+    affiliation: 2
+affiliations:
+ - name: Centre for the Analysis of Motion, Entertainment Research & Applications (CAMERA), University of Bath, Claverton Down, Bath, BA2 7AY, United Kingdom
+   index: 1
+ - name: Inha University, Yonghyeon Campus, 100 Inha-ro, Michuhol-gu, Incheon 22212, South Korea
+   index: 2
+date: February 14 2024
+bibliography: paper.bib
+---
+
+
+# Summary
+`Sports2D` provides a user-friendly solution for automatic and real-time analysis of multi-person human movement from a video or a webcam. This Python package uses 2D markerless pose estimation to detect joint coordinates from videos, and then computes 2D joint and segment angles. 
+<!--It can be installed either locally or on a free server, which makes it possible to run it directly from a smartphone.-->
+
+The output incorporates annotated videos and image sequences overlaid with joint locations, joint angles, and segment angles, for each of the detected persons. For further analysis, this information is also stored in files that are editable with MS Excel® or any other spreadsheet editor (.trc for locations, .mot for angles, according to the OpenSim standard [@Delp_2007; @Seth_2018]). 
+
+`Sports2D` may be useful for clinicians as a decision supports system (CDSS) [@Bright_2012], as well as for gait analysis [@Whittle_2014] or ergonomic design [@Patrizi_2016]. Sports coaches can also use it to quantify key performance indicators (KPIs) [@ODonoghue_2008; @Pagnon_2022b], or to better understand, correct, or compare athletes' movement patterns. Finally, it can be used by researchers as a simple tool for 2D biomechanical analysis on the fly. One of the multiple use cases would be to evaluate ACL injury risks from deceleration drills [@Di_2021]. 
+
+
+# Statement of need
+
+Machine learning has recently accelerated the development and availability of markerless kinematics [@Zheng_2023; @Colyer_2018], which allows for the collection of kinematic data without the use of physical markers or manual annotation. 
+
+A large part of these tools focus on 2D analysis, such as `OpenPose` [@Cao_2019], `BlazePose` [@Bazarevsky_2020], or `DeepLabCut` [@Mathis_2018]. More recently, `RTMPose` [@Jiang_2023] offered a faster, more accurate, and more flexible alternative to the previous solutions. Still, although they bear the advantage of being open-source, none of these options are easily accessible to people who do not have a programming background, and the output is not directly usable for further kinematic investigation. Yet, clinical acceptance of new technologies is known to be influenced not only by their price value and their performance, but also by their perceived ease-of-use, the social influence around the customer, and other parameters described by the Unified Theory of Acceptance and Use of Technology (UTAUT2) [@Venkatesh_2012].
+
+![Example results from a demonstration video.\label{fig:Demo_results}](Demo_results.png)
+
+![Example joint angle output.\label{fig:Demo_plots}](Demo_plots.png)
+
+In fact, there is a clear trade-off between accuracy and ease-of-use. Some open-source tools focus on the accuracy of a 3D analysis by using multiple cameras, such as `Pose2Sim` [@Pagnon_2022a] or `OpenCap` [@Uhlrich_2022]. These, however, require either a certain level of programming skills, a particular hardware setup, or to send data to a server that does not comply with the European rules of data protection (GDPR). Some other tools choose to put more emphasis on user-friendliness, and point out that 2D analysis is often sufficient when the analyzed motion mostly lies in the sagittal or frontal plane. `Sit2Stand` [@Boswell_2023] and `CP GaitLab` [@Kidzinski_2020] provide such tools, although they are focused on very specific tasks. `Kinovea` [@Kinovea], on the other hand, is a widely used software for sports performance analysis, which provides multiple additional features. However, it relies on tracking manual labels. This can be time-consuming when analyzing numerous videos, and it may also be lacking robustness when the tracked points are lost. It is also only available on Windows, and requires the user to transfer files prior to analysis.
+
+`Sports2D` is an alternative solution that aims at filling this gap: it is free and open-source, straightforward to install and to run, can be run on any platform, can be run locally for data protection, and it automatically provides 2D joint and segment angles without the need for manual annotation. It is also robust and flexible, works in real-time, supports multi-person analysis, and can process one video, several videos simultaneously, or a webcam stream. The output is provided as .trc files for locations and .mot files for angles, which makes it compatible with OpenSim [@Delp_2007; @Seth_2018] and readable by any spreadsheet software for further statistical analysis. 
+
+
+# Workflow
+
+## Installation and usage
+
+`Sports2d` is installed under Python via `pip install sports2d`. If a valid CUDA installation is found, Sports2D uses the GPU, otherwise it uses the CPU with OpenVino acceleration. 
+
+<!-- `Sports2D` can be installed and run two different ways: locally, or on a Google Colab® free server [@Bisong_2019].
+
+* *If run locally*, it is installed under Python via `pip install sports2d`. If a valid CUDA installation is found, Sports2D uses the GPU, otherwise it uses the CPU with OpenVino acceleration. 
+
+* *If run on Colab*, it can be installed in one click from any computer or smartphone device, either every time the user needs it, or once for all on Google Drive®. Results are automatically saved on Google Drive®. The arguments are the same as with the local installation. A full video tutorial can be found at this address: [https://www.youtube.com/watch?v=Er5RpcJ8o1Y](https://www.youtube.com/watch?v=Er5RpcJ8o1Y).-->
+
+A detailed installation and usage guide can be found on the repository: https://github.com/davidpagnon/Sports2D.
+
+## Sports2D method details
+
+[Sports2D]{.ul}: 
+
+1. Reads stream from a webcam, from one video, or from a list of videos. It selects an optional specified time range to process.
+2. Sets up the RTMLib pose tracker with specified parameters. It can be run in lightweight, balanced, or performance mode, and for faster inference, keypoints can be tracked for a certain number of frames instead of detected. 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 for 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 using the `tracking_mode` argument.
+4. Retrieves the keypoints with high enough confidence, and only keeps the persons with enough average high-confidence.
+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. The user can select which angles they want to compute, display, and save.
+5. Draws bounding boxes around each person and writes their IDs\
+   Draws the skeleton and the keypoints, with a green to red color scale to account for their confidence\
+   Draws joint and segment angles on the body, and writes the values either near the joint/segment, or on the upper-left of the image with a progress bar
+6. Interpolates missing pose and angle sequences if gaps are not too large. Filters them with the selected filter (among `Butterworth`, `Gaussian`, `LOESS`, or `Median`) and their parameters
+7. Optionally shows processed images, saves them, or saves them as a video\
+   Optionally plots pose and angle data before and after processing for comparison\
+   Optionally saves poses for each person as a TRC file, and angles as a MOT file 
+
+<br>
+
+[The Demo video]{.ul} that Sports2D is tested on is voluntarily challenging, in order to demonstrate the robustness of the process after sorting, interpolation and filtering. It contains:
+
+* One person walking in the sagittal plane
+*  One person in the frontal plane. This person then performs a flip while being backlit, both of which are challenging for the pose detection algorithm
+* One tiny person flickering in the background who needs to be ignored
+
+<br>
+
+[Joint and segment angle estimation]{.ul}:
+
+Specific joint and segment angles can be chosen. They are consistent regardless of the direction the participant is facing: the participant is considered to look to the left when their toes are to the left of their heels, and to the right otherwise. Resulting angles can be filtered in the same way as point coordinates, and they can also be plotted.
+
+Joint angle conventions are as follows (\autoref{fig:joint_angle_conventions}):
+
+* Ankle dorsiflexion: Between heel and big toe, and ankle and knee.\
+  *-90° when the foot is aligned with the shank.*
+* Knee flexion: Between hip, knee, and ankle.\
+  *0° when the shank is aligned with the thigh.*
+* Hip flexion: Between knee, hip, and shoulder.\
+  *0° when the trunk is aligned with the thigh.* 
+* Shoulder flexion: Between hip, shoulder, and elbow.\
+  *180° when the arm is aligned with the trunk.*
+* Elbow flexion: Between wrist, elbow, and shoulder.\
+  *0° when the forearm is aligned with the arm.*
+
+Segment angles are measured anticlockwise between the horizontal and the segment lines:
+
+* Foot: Between heel and big toe.
+* Shank: Between knee and ankle.
+* Thigh: Between hip and knee.
+* Pelvis: Between left and right hip
+* Trunk: Between hip midpoint and shoulder midpoint
+* Shoulders: Between left and right shoulder
+* Head: Between neck and top of the head
+* Arm: Between shoulder and elbow.
+* Forearm: Between elbow and wrist.
+
+![Joint angle conventions\label{fig:joint_angle_conventions}](joint_convention.png)
+
+
+# Limitations
+
+The user of `Sports2D` should be aware of the following limitations:
+
+* Results are acceptable only if the participants move in the 2D plane, either in the frontal plane or in the sagittal one. If you need research-grade markerless joint kinematics, consider using several cameras, and constraining angles to a biomechanically accurate model. See `Pose2Sim` [@Pagnon_2022a] for example.
+* Angle estimation is only as good as the pose estimation algorithm, i.e., it is not perfect [@Wade_2022], especially if motion blur is significant such as on some broadcast videos.
+<!--* Google Colab does not follow the European GDPR requirements regarding data privacy [@Minssen_2020]. Install locally if this matters.-->
+
+
+# Acknowledgements
+
+I would like to acknowledge Rob Olivar, a sports coach who enlightened me about the need for such a tool.\
+I also acknowledge the work of the dedicated people involved in the many major open-source software programs and packages used by `Sports2D`, such as `Python`, `RTMPPose`, `OpenCV` [@Bradski_2000], among others. 
+
+
+# References
+
+