Table of contents

• Bone deformation tool
• Requirements and setup
• How to use the bone deformation tool
• How the bone deformation tool works
• Which models can I deform with this MATLAB tool?
• Definition of femoral version and tibial torsion angles
  • Baseline angles for the Rajagopal full body model
• Examples of use
  • Femoral anteversion
  • Femoral torsion
  • Tibial torsion
• Provided example scripts
• Video summary of the associated publication
• How to contribute
• Contributors

Bone deformation tool

This repository is used for sharing a MATLAB toolbox that enables researcher in biomechanics to modify their generic musculoskeletal models by applying arbitrary torsional profiles to the long axis of the bone model.

The MATLAB tool works with musculoskeletal models in the format provided for the software for biomechanical analyses OpenSim.

The tool is introduced and described in the following publication, which we invite you to cite if you are using the content of this repository for your research or teaching:

@article{Modenese2021bonedef,
  title={Dependency of Lower Limb Joint Reaction Forces on Femoral Version},
  author={Luca Modenese, Martina Barzan and Christopher P. Carty},
  journal={Gait & Posture},
  volume = {88},
  pages = {318-321},
  doi = {https://doi.org/10.1016/j.gaitpost.2021.06.014},
  year={2021},
  keywords = {Femoral version, Femoral anteversion, Musculoskeletal modeling, Tibiofemoral contact force, Knee Loading, Femur, Walking}
}

The paper is open access and all the materials and scripts used for that manuscript are available at this repository. Please note that version of the tool used in the reproducibility repository is v0.1, while the latest version is always recommended for new users.

Requirements and setup

In order to use the bone deformation tool you will need to:

1. download OpenSim 4.1 or more recent. OpenSim 3.3 is also supported but the examples refer to the latest version.
2. have MATLAB installed in your machine. The development of the paper was done using R2020a.
3. set up the OpenSim API (Application User Interface) for MATLAB. Please refer to the OpenSim documentation.

The tool should be able to detect the version of your installed OpenSim API automatically, so you do not have to modify anything related to this toolbox if you are using OpenSim 3.3.

How to use the bone deformation tool

In order to run the bone deformation tool you will need to specify variable in the example scripts, or in your own scripts:

1. where the OpenSim bone geometries are stored (variable OpenSim_Geometry_folder)
2. which segment of the OpenSim model you want to deform (variable bone_to_deform)
3. along which axis the torsional profile will be applied(variable torsionAxis)
4. the points defining the torsional profile, i.e. the torsion applied to the proximal and distal joint centres (variable TorsionProfilePointsDeg)
5. if you want the torsional to be applied just to the bone or also to the joints, i.e. if you want the kinematic model to be altered by the torsion (variable apply_torsion_to_joints)
6. where the resulting model will be saved (variable altered_models_folder)

How the bone deformation tool works

The bone deformation tool will execute the following operations:

1. read and modify the bone geometry described in the OpenSim vtp file according to the specified rotational profile
2. generate a new bone geometry in vtp format and save it in the same folder
3. adjust all the muscle attachments and virtual markers attached to the bone of interest
4. rotate the joints axes according to the specified torsional profile if the user decides to do that (see examples below). This will modify the kinematic model.
5. generate a new OpenSim model that includes all the previous modifications.

Which models can I deform with this MATLAB tool?

We tested the MATLAB tool with two popular lower limb models:

• the gait2392 model distributed with OpenSim
• the Rajagopal full-body model published by Rajagopal et al. (2016). The latter model was used in the publication associated with this repository and to produce the images in this document.

Please consider that the formulation of the tool is however completely generic in its managing the OpenSim model components, so nothing prevents you from testing it on other bones and models, including upper limb models.

Definition of femoral version and tibial torsion angles

The generic OpenSim model are provided with bone geometry for visualization purposes, and it is possible to estimate the femoral version and tibial rotation using their geometry. We have estimated the following angles as in Strecker et al. (1997)

Baseline angles for the Rajagopal full body model

For the full-body model by Rajagopal et al. we found:

• femoral version: 12 degrees
• tibial rotation: 28 degrees

The reference systems that we constructed for the estimation of these angles are available in the folder baseline-angles-estimation-Rajagopal and can be visualized using NMSBuilder.

WARNING the bone geometries provided with the OpenSim models are normally of low quality, not comparable with those obtainable from segmentation of CT scans, for example. Estimation of these rotational angle is therefore challenging.

Knowledge of the bone rotation for the baseline model is essential because the bone deformation prescribed with this deformation tool will be added to the existing bone rotation.

Examples of use

Femoral anteversion

It is possible to modify the femoral anteversion of a generic model as in the figure below.

If you want, for example, to generate a model with 40 degrees of femoral anteversion, you can apply a 28 degrees of rotation to the proximal femur of generic model, which we have estimated to have a baseline femoral anteversion of 12 degrees.

The typical setting in the main script would then be:

%---------------  MAIN SETTINGS -----------
% Model to deform
modelFileName = './test_models/Rajagopal2015.osim';

% where the bone geometries are stored
OSGeometry_folder = './Geometry';

% body to deform
bone_to_deform = 'femur_l';

% axis of deformation
torsionAxis = 'y';

% define the rotation at the joint centre of the specified bone
% TorsionProfilePointsDeg = [ proximalTorsion DistalTorsion ];
TorsionProfilePointsDeg = [ 28  0 ];

% decide if you want to apply the rotation to joint as well as other objects.
apply_torsion_to_joints = 'no';

Femoral torsion

For applying a distal femoral torsion it is necessary to specify also that the torsion will be applied to the joints with the setting apply_torsion_to_joints = 'yes'.

The typical setting would be:

%---------------  MAIN SETTINGS -----------
% Model to deform
modelFileName = './test_models/Rajagopal2015.osim';

% where the bone geometries are stored
OSGeometry_folder = './Geometry';

% body to deform
bone_to_deform = 'femur_l';

% axis of deformation
torsionAxis = 'y';

% define the torsion at the joint centre of the specified bone
% TorsionProfilePointsDeg = [ proximalTorsion DistalTorsion ];
TorsionProfilePointsDeg = [ 0  -30 ];

% decide if you want to apply torsion to joint as well as other objects.
apply_torsion_to_joints = 'yes';

Tibial torsion

Exactly the same setting can be used for applying a distal tibial torsion, with the only difference being

% body to deform
bone_to_deform = 'tibia_l';

The resulting tibial torsion will be 2 degrees.

Provided example scripts

We have provided example scripts that demonstrate how to modify the geometry of femur and tibia in the gait2392 and Rajagopal models:

• Example_deform_distal_femur_gait2392.m
• Example_deform_distal_femur_Rajagopal.m
• Example_deform_distal_tibia_gait2392.m
• Example_deform_distal_tibia_Rajagopal.m

The models resulting from these scripts, together with the bone geometries for visualizing the Rajagopal model, are available in the `examples' folder.

Video summary of the associated publication

Luca gave a talk at the 26th Congress of the European Society of Biomechanics presenting the paper associated with the bone deformation tool. Click on the image below to see the recorded:

How to contribute

We welcome any contribution from the biomechanical and open source community, in any form. Few tips for contributing:

• To report a bug, or anomalous behaviour of the toolbox, please open an issue on this page. Ideally, if you could make the issue reproducile with some data that you can share with us.
• To contributing to the project with new code please use a standard GitHub workflow: a) fork this repository, b) create your own branch, where you make your modifications and improvements, c) once you are happy with the new feature that you have implemented you can create a pull request. We will review your code and potentially include it in the main repository.
• To propose feature requests, please open an issue on this page, label it as feature request using the Labels panel on the right and describe your desired new feature. We will review the proposal regularly but work on them depending on the planned development.

Contributors

Many thanks to Axel Koussou and Emmanuelle Renoul from Fondation Ellen Poidatz (St-Fargeau-Ponthierry, France) for helping with the tool upgrade to OpenSim 4.1.