<<TableOfContents>>
= Target Outcome =
Customized knee model for finite element analysis in FEBio format (.feb, XML based text file) including the following details relevant to knee mechanics:
* tissue specific constitutive models
* In situ (reference) ligament strains
* joint stabilizers and convenience structures
* anatomically based coordinate systems and kinematic chains
* loading and boundary conditions for simulation of passive knee flexion
----
= Prerequisites =
<<Include(Infrastructure/AuxiliarySoftware, "Infrastructure", 2, from="= Geometry & Mesh Generation & Manipulation =", to="= Scripting & Numerical Analysis =")>>
== Previous Protocols ==
For more details, see [[Specifications/TemplateModelGeneration]].
----
= Protocols =
== Input ==
Template Model in FEBio format (.feb, XML based text file) including all relevant tissues, and the ties and contacts between the tissues.
== Overview ==
This page describes the process for converting a template model (see [[Specifications/TemplateModelGeneration]]) to a customized knee model including material properties, in situ ligament strain, joint stabilizers and convenience structures, joint coordinate systems, and loading and boundary conditions.
The customization is performed in a scripted procedure, where the inputs to the script are the template model FEBio file, and a model properties file. The model properties file includes the constitutive models for all deformable tissues in the knee model, and manually chosen anatomical landmark coordinates.
== Creating the Model Properties File ==
The Model Properties file is an xml file to be used as input for the customization script. Included in the Model Properties File are Material section, which gives the material properties for each non-rigid material, and the Landmarks section, which gives the coordinates of the manually chosen anatomical lankmarks.
=== Material Section ===
For each non-rigid tissue included in the template model, material properties must be provided in the model properties file (see sample below for details). Currently, the supported material type options are "trans iso Mooney-Rivlin", or "Mooney-Rivlin" (based on our [[Specifications/ModelingConstitutive]] recommendations). There is an option to include ligament prestrain in the model. In order to be included, one may simply add a material property called <initial_stretch> to the material xml element. If there are no <initial_stretch> properties, or their values are listed as None, no prestrain will be included in the model (see sample below for details).
'''NOTE:''' The material names for all tissues, both in the template model, and in the model properties file must follow the naming convention outlined in [[Specifications/DataManagement]] page. For example, the femur bone must be named "FMB" in order for the customization script to properly recognize the tissues.
=== Landmarks Section ===
Locate the following anatomical landmarks manually, and save their coordinates (in the MRI coordinate system) in the Landmarks element of the Model Properties file (see sample below for details). Use the naming convention in the brackets below.
*medial tibial spine (MTS)
*lateral tibial spine (LTS)
*approximate center of medial tibial plateau (MTP)
*approximate center of lateral tibial plateau (LTP)
*most distal point on the posterior surface of the femur, midway between the medial and lateral condyles (DFP)
*medial femoral condyle (most distal point on posterior surface) (MFC)
*lateral femoral condyle (most distal point on posterior surface) (LFC)
*Medial Patella Ridge (MPR)
*Lateral Patella Ridge (LPR)
=== Sample Model Properties file ===
The following is a sample of the xml structure required in the Model properties file:
<ModelProperties>
<Material>
<material name="MCL" type="trans iso Mooney-Rivlin">
<lam_max>1.063</lam_max>
<density>1e-09</density>
<k>793.65</k>
<initial_stretch>1.034</initial_stretch>
<c3>0.57</c3>
<c2>0</c2>
<c1>1.44</c1>
<c5>467.1</c5>
<c4>48.0</c4>
</material>
<material name="MNS-L" type="trans iso Mooney-Rivlin">
<lam_max>1.019</lam_max>
<density>1e-09</density>
<k>92.16</k>
<initial_stretch>None</initial_stretch>
<c3>0.1197</c3>
<c2>0</c2>
<c1>4.61</c1>
<c5>400.0</c5>
<c4>150.0</c4>
</material>
<material name="PTC" type="Mooney-Rivlin">
<c2>0</c2>
<c1>2.54</c1>
<k>100</k>
<density>1e-09</density>
</material>
</Material>
<Landmarks>
<LTS>2.5,-7.16,-15.92</LTS>
<LTP>21.9,-2.5,-21.86</LTP>
<LFC>22.4,-23.2,12.5</LFC>
<MTS>-8.1,-9.9,-16.5</MTS>
<MTP>-20.8,-9.2,-26.5</MTP>
<LPR>7.0,53.2,22.8</LPR>
<DFP>-5.2,-10.6,14.5</DFP>
<MFC>-26.9,-31.6,4.15</MFC>
<MPR>-33.5,44.9,12.5</MPR>
</ModelProperties>
== Scripted Customization Procedure ==
=== What the script does ===
The customization script converts the template febio model to to a customized knee model. The following customizations are made to the template model:
1. Customization for material definitions: The template model has each material defined as either rigid or deformable. The customization process assigns the tissue specific properties from the model properties file to all deformeable materials. For more information on the choice of constitutive models for the knee tissues, see [[Specifications/ModelingConstitutive]]
2. Customization for other stabilizing components:
a. A spring is added connecting the top of the quadriceps tendon to the femur bone.
a. two springs each to represent the MPFL, LPFL are added connecting the patella bone to the femur bone
3. Customization for In Situ Ligament Strain: In Situ strain is applied to ligaments prior to passive flexion.
4. Customization for Joint Coordinate System Definitions: Joint coordinate systems are defined for the tibiofemoral and patellofemoral joints. A Grood and Suntay Joint Coordinate System [1] is used to define the tibiofemoral joint. A similar joint, as described by Bull et Al [2] is used to define the patellofemoral joint. Both joints are modeled using a system of three cylindrical joints, connected via "imaginary rigid bodies".
5. Customization for Loading and Boundary Conditions: The Tibia, and Fibula Bones are fixed in all degree of freedom. Passive flexion to 90 degrees is applied by prescribing the rotation along the Flexion-Extension cylindrical joint. All other degrees of freedom in the model remain free.
=== Directions for Running Customization Script ===
1. Save the scripts [[https://simtk.org/svn/openknee/app/KneeHub/src/FebCustomization.py|FebCustomization.py]], and [[https://simtk.org/svn/openknee/app/KneeHub/src/AnatomicalLandmarks.py|AnatomicalLandmarks.py]] in the same directory on your computer.
1. Run FebCustomization.py from python in the terminal with the first argument as the Febio file, and the second argument the Model Properties xml file:
$ python FebCustomization.py FeBio.feb ModelProperties.xml
1. You will be prompted to enter 'R', or 'L', for right knee or left knee.
The script generates two files:
a. The customized febio file FeBio_custom.feb, in the same location as the original FeBio.feb template file
a. The customized geometry file Geometry_custom.feb, in the same location as the original Geometry.feb template file (created in the template model generation process)
The script also adds landmarks that were calculated to the Model Properties xml, such as joint origins and axes, it is recommended to check the added landmarks to ensure that their locations and direction make sense.
----
= References =
[1] Grood, E. S. & Suntay, W. J. A joint coordinate system for the clinical description of three-dimensional motions: application to the knee. J Biomech Eng 105, 136–144 (1983).
[2] Bull, A. M. J., Katchburian, M. V., Shih, Y.-F. & Amis, A. A. Standardisation of the description of patellofemoral motion and comparison between different techniques. Knee Surg Sports Traumatol Arthrosc 10, 184–193 (2002).