Shoulder Model Personalization

This respository contains python scripts to scale and personalize a generic OpenSim upper body model [1, 2, 3]. The unscaled muskuloskeletal model and example data to run the scripts can be downloaded from SimTK.

The two main files for scaling and personalizing the shoulder rhythm constraints of the model are ModelScaling.py and ModelPersonalization.py.

ModelScaling.py

This file reads the input parameters from settings_scaling.xml, scales the muskoluskeletal model, and saves the scaled model. The scaling process entails an OpenSim scaling, a correction of the humerus scale factors using SCoRE [4], and a correction of the position of the tracking markers on the upper arm and forearm.

Inputs:

• Unscaled OpenSim model (provided on SimTK)
• OpenSim scaling setup .xml-file (provided on SimTK)
• static recording in anatomic pose that includes measurements of both left and right scapula. The scalingfile.trc files provided on SimTK are generated by combining two static recordings where the right scapula is palpated and measured in one, and the left scapula is palpated and measured in the other.
• time range in static scaling file to use for scaling
• 5 static calibration recordings per shoulder in which the scapula is palpated and its postition is measured with an L-shaped scapula location tool that has three markers on AA, AI, and TS (provided on SimTK). Here used for glenohumeral joint rotation center estimation.
• names of the markers in the recording (default values represent marker names in data provided on SimTK). Only change the marker names for the AA, AI, and TS markers on the left and right scapula if 'move_scapula_markers_to_skin' is set to False (e.g. when you have already done the translation in preprocessing).
• In case 'move_scapula_markers_to_skin' is set to True: distance of the scapula markers on the scapula location tool from the skin (in case there are orthogonal pins on the tool for locating the palpated points).
• In case 'move_scapula_markers_to_skin' is set to True: names of the markers on the scapula location tool with pins pointing to AA, AI, TS.

Outputs: Scaled model with generic shoulder rhythm constraints.

ModelPersonalization.py

This file reads the input parameters from settings_scaling.xml, performs a personalization of the shoulder rhythm constraints, and saves the personalized model. The personalization process uses five calibration poses per shoulder and fits a bilinear function to the joint angles to update the model. If enabled, a second model with independent clavicle elevation is generated in which the constraint is disabled and the coordinate ranges are set to pyhsiological values.

Inputs:

• scaled OpenSim model (as generated by ModelScaling.py)
• 5 static calibration recordings per shoulder in which the scapula is palpated and its postition is measured with an L-shaped scapula location tool that has three markers on AA, AI, and TS (provided on SimTK). The algorithm has been developed with the following poses: Anatomical pose, maximal shoulder abduction, maximal shoulder flexion, maximal shoulder adduction at 90 degrees flexion, maximal shoulder abduction at 90 degrees flexion. The approach might work with other poses, but this hasn't been tested, yet.
• names of the markers in the recording (default values represent marker names in data provided on SimTK). Only change the marker names for the AA, AI, and TS markers on the left and right scapula if 'move_scapula_markers_to_skin' is set to False (e.g. when you have already done the translation in preprocessing).
• In case 'move_scapula_markers_to_skin' is set to True: distance of the scapula markers on the scapula location tool from the skin (in case there are orthogonal pins on the tool for locating the palpated points).
• In case 'move_scapula_markers_to_skin' is set to True: names of the markers on the scapula location tool with pins pointing to AA, AI, TS.

Outputs: Model with personalized shoulder rhythm constraints; optional: Model with personalized shoulder rhythm constraints and independent clavicle elevation motion.

Usage

1. Download the generic model from SimTK. Use your own motion capture data or download the provided dataset.
2. Download or clone this repository, and setup your environment using the provided environment.yaml or requirements.txt files.
3. Model scaling: update the file settings_scaling.xml with your paths, filenames, and parameters. Run ModelScaling.py using settings_scaling.xml as input argument
4. Model personalization: update the file settings_personalization.xml with your paths, filenames, and parameters. Run ModelPersonalization.py using settings_personalization.xml as input argument

References

[1] Holzbaur KR, Murray WM, Delp SL.: A model of the upper extremity for simulating musculoskeletal surgery and analyzing neuromuscular control., Ann Biomed Eng. 2005 Jun;33(6):829-40. (2005)
[2] Saul KR, Hu X, Goehler CM, Daly M, Vidt ME, Velisar A, Murray WM. Benchmarking of dynamic simulation predictions in two software platforms using an upper limb musculoskeletal model. Computer Methods in Biomechanics and Biomedical Engineering. 2015; 18:1445-58. 10.1080/10255842.2014.916698 (2015)
[3] McFarland, D. C., McCain, E. M., Poppo, M. N., and Saul, K. R. (March 25, 2019). "Spatial Dependency of Glenohumeral Joint Stability During Dynamic Unimanual and Bimanual Pushing and Pulling." ASME. J Biomech Eng. May 2019; 141(5): 051006. https://doi.org/10.1115/1.4043035 (2019)
[4] Monnet, T., Desailly, E., Begon, M., Vallee, C., Lacouture, P., 2007. Comparison of the score and ha methods for locating in vivo the glenohumeral joint centre. Journal of Biomechanics 40, 3487–3492.