NMSBuilder_Tutorial_v1 (1)

NMSBuilder  Tutorial                     Create  an  OpenSim  model  from  Test  Data  

 

Giordano  Valente,  Lorenzo  Pitto,  Stefano  Perticoni   Laboratorio  di  Tecnologia  Medica,  Istituto  Ortopedico  Rizzoli,  Bologna   BioComputing  Competence  Centre,  SCS  srl,  Bologna  

1. Objectives   NMSBuilder   is   an   open-­‐source   software   package,   being   developed   within   the   NMSPhysiome   project.  It  allows  to  import  and  edit  subject-­‐specific  data  from  different  sources,  develop  OpenSim   musculoskeletal   models,   leverage   OpenSim   to   perform   dynamic   simulations   of   movement   and   store   the   results.   Next   release   features   will   also   include   statistical   post-­‐processing   and   visualization   tools,   as   well   as   import/export   facilities   of   Matlab   file   formats.   The   software   integrates  the  multimodal  data  fusion  functionalities  of  Multimod  Application  Framework  with  the   OpenSim  API.   The   purpose   of   this   tutorial   is   to   help   users   getting   started   with   the   software,   creating   a   simple   OpenSim   musculoskeletal   model   from   subject-­‐specific   data   distributed   with   the   alpha   version   released.  Only  specific  tools  to  the  purpose  will  be  described  in  this  tutorial.  For  all  other  software   capabilities  and  potential,  users  are  referred  to  the  user's  guide.    

 

  Figure  1  -­‐  Main  parts  of  a  musculoskeletal  model  in  OpenSim.  All  necessary  features  are  definable  within   NMSBuilder  operations  

 

1  

2. Test  Data   First  of  all,  download  the  test  data  from  here:   https://www.biomedtown.org/nmsphysiome/reception/alpha/   Test  data  include  models  of  the  right  thigh  and  shank  of  a  specific  normal  subject,  derived  from   MRI  images.  File  →  Open  →  Test  Data.msf  to  import  the  data.  To  visualize  and  navigate  the  data   elements,  select  View  →  Add  View  →  Surface  and  go  into  the  Data  Tree  panel.   Data   are   organized   in   a   hierarchical   tree   and   divided   into   rigid   bodies   (parent),   joints,   marker   sets   and  attachment  points  (children),  plus  Muscle  Actuator  and  OpenSim  model  source  code:    

 

Figure  2  -­‐  Test  data  visualized  in  a  surface  view.  Each  object  is  stored  in  the  hierarchical  tree  in  the  data  tree  bar  

  •

Closed  surfaces  of  hard  and  soft  tissues:                Each   part   has   an   assigned   density,   and   the   inertial   properties   have   been   calculated.   It   is   possible   to   visualize   and   edit   the   properties   from   VME   metadata   facilities   (Operations   →   Modify  →  VME  Metadata).  Note  that  multi-­‐surface  groups  R_Thigh  and  R_Shank  account   for  the  properties  of  both  hard  and  soft  tissues.  

•

Knee  Reference  Systems  in  Parent  and  in  Child:              The  two  RefSys  have  been  conveniently  defined.    

•

Marker  Sets:                Identified  with  a  virtual  palpation  procedure  on  anatomical  landmarks  [1].  

•

Attachment  Points:                Registered  from  Delp  model  [2]  onto  the  specific  anatomy.  

•

Actuator  path  and  parameters:  

2  

             Vastus   lateralis   muscle,   including   the   origin/via/insertion   points   and   maximum   isometric   force   parameter.   Other   muscle   parameters   can   be   defined   from   VME   metadata   facilities   (Operations  →  Modify  →  VME  Metadata,  also  refer  to  user's  guide).   •

Source  code  of  the  OpenSim  model  created:  

Additional  files,  distributed  in  the  Geometries  and  output  model  folder,  include  the  vtp  geometry   files  and  the  osim  model  file,  created  as  result  of  this  tutorial.    

3. Create  OpenSim  model     The  purpose  is  to  create,  from  subject-­‐specific  surfaces  segmented  from  MRI  images,  a  multibody-­‐ dynamics  model  of  two  rigid  bodies  (thigh  and  shank),  connected  by  a  1  DOF  pin  joint,  moved  by   one  muscle  actuator,  and  with  a  6  DOF  free  joint  connecting  the  thigh  to  the  ground.   First,   the   user   must   define   the   necessary   features   to   build   the   model   (Figure   1   and   following   3   paragraphs  in  this  section):  inertial  properties  of  bodies,  joint  reference  frames,  muscle  actuator   paths   and   parameters.   Then   it   is   possible   to   build   the   OpenSim   model:   1)   from   Wizard   or   2)   creating  cpp  command  blocks  for  each  model  part,  to  be  pasted  (and  modified  if  necessary)  into   the  source  code  template  (advanced  users).   Definition  of  bodies   Each  rigid  body  is  made  of  multi-­‐surfaces  defining  hard  and  soft  tissues.  Beyond  the  geometry,  the   inertial  properties  need  to  be  calculated.  First,  the  density  of  each  sub-­‐part  composing  the  body   can  be  assigned  from  VME  metadata  facilities  (Operations  →  Modify  →  VME  Metadata),  defining   the  tag  'DENSITY'  and  typing  the  numerical  value.  If  density  is  not  defined,  a  default  unitary  value   is   assumed.   Then,   the   inertial   properties   can   be   calculated   with   the   appropriate   operation   (Operations  →  Measure  →  Compute  Inertial  Tensor)  on  each  multi-­‐surface  body.  This  will  return   the   mass,   center   of   mass,   inertial   matrix   in   the   local   reference   frame   and   principal   moments   of   inertia,  that  will  be  automatically  stored  as  VME  attributes  in  the  VME  Metadata  properties.    

 

Figure  3  -­‐  VME  Metadata  parameters  of  R_Thigh  multi-­‐surface  after  performing  the  compute  Inertial  Tensor   operation   3  

Definition  of  joints   Two  joint   reference   frames   (RefSys)   define   position   and   orientation   of   the   joint   in   each   of   the   two   connected  bodies.  The  origin  of  the  RefSys  will  be  the  center/axis  of  rotation  of  the  joint,  and  the   degree  of  freedom  will  take  place  along  its  axes  (Pin  Joint  rotates  along  the  blue  Z-­‐axis).     The  two  RefSys  have  to  be  created  from  anatomical  landmarks  defined.  This  can  be  done  in  two   ways:   1. Select  a  landmark  cloud  (Marker  Set)  representing  the  anatomical  landmarks  of  the  bone   corresponding   to   the   desired   body,   then   Operation   →   Create   →   Derive   →   AFRefsys   and   then  select  the  acronym  corresponding  to  the  bone.  This  will  create  a  RefSys  child  of  the   landmark  cloud.  Select  it,  go  to  the  vme  tab  and  assign  the  requested  landmarks.   2. Operation   →   Create   →   RefSys.   Select   it,   go   to   the   vme   tab,   check   Select   Plane.   The   first   landmark   to   feed   will   be   the   origin,   the   second   one   will   define   the   X   axis   and   the   third   will   define  the  plane  and  direction  of  the  Y  axis.     The   RefSys   can   be   moved   (rotated   and   translated)   using   the   Move   facilities   (refer   to   user's   guide):   select   it,   Operation   →   Create   →   Derive   →   Freeze   VME.   This   will   create   an   object   that   can   be   moved  as  any  other  VME  object.   In   the   Test   Data,   the   knee   joint   is   modelled   as   a   pin   joint   with   the   axis   of   rotation   passing   through   the  RME  and  RLE  markers.  The  RefSys  in  Parent  is  defined  using  RME  and  RLE  as  origin  and  point1,   and   then   rotating   the   RefSys   to   make   this   axis   the   Z-­‐axis.   From   this,   RefSys   in   Child   is   defined   such   to  have  the  knee  neutral  pose  according  to  ISB  standard  [3].       Definition  of  muscle  actuators   An  action  line  representing  the  muscle  needs  to  be  created:  select  Operation  →  Create  →  Derive   →  Wrapped  Action  Line,  go  to  vme  tag,  select  Pivot-­‐set  method  and  set  wrap  to  manual,  feed  the   start   and   end   points   and   a   list   of   ordered   midpoints.   Physiological   muscle   parameters   can   be   assigned   through   VME   Metadata   facilities   (Operation   →   Modify   →   VME   Metadata):   the   maximum   isometric  force  parameter  can  be  assigned  adding  a  "maxIsometricForce"  numeric  tag  and  typing   the   value.   To   see   other   valid   muscle   parameter   tags,   please   refer   to   the   user's   guide.   If   muscle   parameters  are  not  defined,  default  values  will  be  assumed.       Create  OpenSim  model  from  Wizard   Once  all  necessary  model  objects  have  been  defined  (body  properties,  RefSys,  muscle  action  lines),   the  user  is  ready  to  create  the  OpenSim  model.  The  more  user-­‐friendly  way  is  to  use  the  Wizard   facility:   Operations   →   Create   →   New   →   OpenSim   model   from   Wizard   will   guide   users   through   a   step-­‐by-­‐step   procedure   in   selecting   all   the   necessary   model   objects   and   create   the   OpenSim   model  source  code  to  be  compiled  later.   1. Create  Bodies  from  Surfaces   Select   Add   Groups   to   define   multi-­‐surface   bodies   and   pick   "R_Thigh"   and   "R_Shank"   groups.   Bodies  will  be  automatically  added  to  the  model.  In  addition,  this  operation  creates  and  saves   all  geometry  vtp  files  in  the  default  model  directory.  

4  

 

Figure  4  -­‐  First  step  of  creating  OpenSim  model  from  Wizard:  create  bodies  from  multi-­‐surfaces  

  2. Create  Joints   To   define   the   free   joint   with   the   ground,   select   the   Child   Body,   pick  "R_Thigh"  and  Add  Joint.  To  define  the  hinge  joint  at  the  knee,   select  Pin  Joint  from  the  drop-­‐down  menu  and  pick  the  necessary   bodies   and   reference   frames   corresponding   to   Parent   Body,   RefSys  in  Parent,  Child  Body,  RefSys  in  Child,  and  then  Add  Joint.   3. Create  Marker  Sets   To   attribute   the   two   defined   marker   sets   to   the   corresponding   bodies,  select  Source  Landmark  Cloud  and  pick  the  corresponding   Marker  Set,  to  then  select  Target  Body  and  pick  the  corresponding   body.  Select  Add  Marker  Set  each  time  to  add  the  markers  to  the   model.   4. Add  Muscles   Select   Add   Muscle   and   simply   pick   the   wrapped   action   line   corresponding  to  the  "R_vas_lat"  muscle.   Selecting   continue   in   the   last   step   of   the   procedure   (Wizard   Done!)   will  automatically  add  the  model  source  code  to  the  data  tree,  and  an   Figure 5 - Create Pin Joint from Create OpenSim automatic   pop-­‐up   window   will   show   the   created   cpp   file   in   a   modelfrom Wizard Notepad++  text  editor.     Now   this   file   needs   to   be   compiled   to   create   the   corresponding   .osim   model.   Select   the   OpenSimModel  from  the  data  tree  and  go  to  Operations  →  Modify  →  OpenSim  Model  →  Editing   Tools:   selecting   Generate   Model,   the   source   code   will   be   compiled   and   the   model   file   will   automatically   show   up   in   the   text   editor.   The   "outputmodel.osim"   will   be   saved   in   the   default   directory,  editable  from  the  Editing  Tool  panel.   The  created  .osim  model  can  now  be  imported  in  OpenSim.      

5  

Alternative:  Create  OpenSim  model   As   alternative   to   creating   the   model   from   Wizard,   a   possibility   for   advanced   users   is   to   create   the   model   by   generating   all   cpp   command   blocks   separately.   This   allows   to   edit   any   model   parameter   working   directly  on  source  codes.  

Figure 6 - Editing Tools for the OpenSim model source code

To  create  the  same  model  described,  first  go  to  Operations  →  Create  →   New   →   OpenSim   model:   this   will   create   and   add   to   the   data   tree   a   template  model  source  code,  which  corresponds  to  an  empty  OpenSim   model.  After  selecting  this  model  from  the  data  tree,  go  to  Operations  →   Modify   →   OpenSim   model,   where   users   can   find   all   the   necessary   operations,   previously   described,   to   create   the   different   model   parts.   Each   operation   allows   to   create   a   corresponding   cpp   command   block   that  need  to  be  pasted  into  the  template  model  file.  When  all  operations   will   be   concluded,   users   can   save   and   compile   the   final   model   source   code  file.    

References   [1]  Taddei  et  al.,  2007.  Virtual  palpation  of  skeletal  landmarks  with  multimodal  display  interfaces.   Medical  informatics  and  the  Internet  in  medicine,  32(3):  191-­‐8   [2]   Delp   et   al.,   1990.   An   interactive   graphics-­‐based   model   of   the   lower   extremity   to   study   orthopaedic  surgical  procedures.  IEEE  transactions  on  bio-­‐medical  engineering,  37(8):  757-­‐67   [3]  Wu  et  al.,  2002.  ISB  recommendation  on  definitions  of  joint  coordinate  system  of  various  joints   for   the   reporting   of   human   joint   motion-­‐-­‐part   I:   ankle,   hip,   and   spine.   International   Society   of   Biomechanics.  J  Biomech,  35(4):543-­‐8  

6