XML model files - ProOlympia-INAIL-UNIPD/Olympia-MATLAB GitHub Wiki

The information needed to build the *.configuration file needed to process the static and dynamic according to a specific model are stored in the following XML files:

  • <model_name>.markerlist
  • <model_name>.coord
  • <model_name>.kinematics

Shall the model foresees the use of a marker-equipped pointer to calibrate points relative to a cluster of markers, the *.configuration file contains the information of which pointer should be used and the calibration object is defined in a Wands.calobj XML file (see also Calibration objects XML file). The following sections will show their contents and structure. It is worth underlying that, should the Reader want to use the codes provided along with this manuscript to apply any other model, changing the content of the XML files will suffice and allow for computing the kinematics according to any other marker-based model.

The model definition files containing the definitions given in the present manuscript and Supplementary Materials are named:

  • Olympia.markerlist
  • Olympia.coord
  • Olympia.kinematics

Calibration objects XML file

This file contains the definition of the calibration objects that can be used by the OlympiaConfigurator to set the reconstruction of pointed markers. The file has the following structure:

<?xml version = "1.0" encoding = "UTF-8" ?>
<calibration_objects>
    <object_name>
        <TailMarker>mkr1</TailMarker>
        <TipMarker>mkr2</TipMarker>
        <Tail2RealTip>250</Tail2RealTip>
    </object_name>
</calibration_objects>

The main node is “calibration_objects”, which contains the calibration object name (e.g., arrow416 and object_name). Each object is defined by:

  • TailMarker: the closest marker to the wand handle
  • TipMarker: the most distal marker on the wand, not necessarily coincident with the palpation point
  • Tail2RealTip: the distance between the TailMarker and the actual tip of the wand used to palpate the points to be reconstructed.

Marker list XML file

The <model_name>.markerlist file contains the whole marker set having considered all its possible variations to be adapted to different configurations. The file structure has to be as follows:

<?xml version = "1.0" encoding = "UTF-8" ?>
<?xml version = "1.0" encoding = "UTF-8" ?>
<MarkerSet label="OLYMPIA">
    <Marker type="T" label="H1" segment="Head" group="General" cluster="1" static="0"
            calibrated="0" opt="0" radius="14" colorR="0.6" colorG="0.7" colorB="0.9"
            visible="1" trajectory="0" />
    <Marker ... />
    
    <!—- VIRTUAL MARKER DEF -->
    <VirtualMarkerDef label="RCLM" method="centroid" source="RCLAM,RCLPM"/>
    
    <!—- CALIBRATEDs MARKER DEF -->
    <CalibratedMarkerDef label="RCLM" wand="centroid" source=""/>
</MarkerSet>

The main node of the file is MarkerSet, whose label reports the name of the model. Each marker record must be defined using the following attributes:

  • type: marker type, with possible values:
    • A: anatomical
    • T: technical
    • M: mechanical
    • V: virtual. Each virtual marker must be complemented by a dedicated VirtualMarkerDef node
  • label: the marker name
  • segment: the segment to which the marker pertains
  • group: grouping attribute defined by the user. OlympiaSW considers left, right and general
  • cluster: is a Boolean, with 0 meaning the marker is not part of a cluster used to reconstruct other points and 1 meaning the opposite
  • static: is a Boolean, with 1 meaning the marker is removed after the static calibration trial, while 0 is used for markers to be used during both static and dynamic trials
  • calibrated: is a Boolean, with 0 being associated with standard markers and 1 with those theat have to be calibrated using marker-equipped pointers/wands. Each calibrated marker must be complemented by a dedicated CalibratedMarkerDef node

The VirtualMarkerDef node must be defined within the MarkerSet node and the label must match the one of the corresponding marker node. It must include the following attributes:

  • method: computational method used to define the virtual marker (e.g., Bell et al., 1990 method)
  • source: the list of points used to compute the virtual marker (e.g. in Bell et al., 1990 method the markers on the anterior and posterior iliac spines)

The CalibratedMarkerDef node must be defined within the MarkerSet node and the label must match the one of the corresponding marker node. It must include the following attributes:

  • wand: the name of the calibration object stored in the Wands.calobj XML file and selected with the Olympia Configurator app.
  • source: manually filled with the absolute path to the C3D file containing the pointing trial for the specific marker.

Coord XML file

The <model_name>.coord file contains the definition of the local coordinate systems given for the adopted model.

The local coordinate systems definition is grouped under the main node CoordinateSystems, which then is divided in groups (e.g., the OlympiaSW considers general, left and right grouping for the segments).

<?xml version = "1.0" encoding = "UTF-8" ?>
<?xml version="1.0" encoding="UTF-8"?>
<CoordinateSystems>
    <General>
        <Segment label="Head" group="General" points="H1,H2,H3,H4,GB,LAM,RAM,CH" opt="0"
                 angleseq="xyz" endpoints="LAM,RAM" inertialalias="Head" comlabel="HDCOM">
            <CoordSys>
                <tag>HD</tag>
                <origin>LAM</origin>
                <origin>RAM</origin>
                <axis1>
                    <axis>
                        <tail>CH</tail>
                        <tip>GB</tip>
                    </axis>
                </axis1>
                <temp_axis>
                    <axis>
                        <tail>GB</tail>
                        <tip>origin</tip>
                    </axis>
                </temp_axis>
                <seq>yzx</seq>
            </CoordSys>    
        </Segment>
    ...
    </General>
</CoordinateSystems>

Each segment node is defined by:

  • label: The name of the segment.
  • group: Any grouping the user might want to use to help defining the model (e.g., general, left and right).
  • points: The list of all the points to be used to calculate the coordinate system.
  • opt: Segment option label:
    • 0 (default): No additional specification.
    • 1: Optional segment.
    • 2: Segment used exclusively for transfemoral amputees.
    • 3: Segment used exclusively for transtibial amputees.
  • angleseq: The sequence used to decompose the segment's orientation (rotation) matrix with respect to the global reference system.
  • endpoints: List of markers used to calculate the segment length, which is required for scaling its inertial parameters.
  • inertialalias: The segment label, as defined in inertial parameter tables (de Leva, 1996).
  • comlabel: The name of the point associated with the segment’s center of mass.
  • CoordSys: containing the actual definition of the local coordinate system based on the points list, and includes:
    • tag: a shorter alternative for the segment label.
    • origin: Definition of the coordinate system origin:
      • If only one origin record is provided, the origin corresponds to the specified point label.
      • If multiple origin records are provided, the origin is computed as the centroid of the listed points.
    • axis1: Definition of the primary axis. This node can contain one or more axis records, each defined by tail and tip points:
      • If an axis is defined by one tail and one tip, it is computed as the unit vector from tail to tip.
      • If an axis is defined by two tail points and one tip, it is computed as the unit vector from the midpoint of the two tail points to tip.
      • If an axis is defined by one tail and two tip points, it is computed as the unit vector from tail to the midpoint of the two tip points.
      • If axis1 is defined by two axis records, the final axis is computed as the cross product of the first and the second axis vectors.
    • temp_axis: the definition of a temporary axis, defined as the axis1.
    • seq: the sequence which the axis definition is provided with.

In the example above, for the head coordinate system, the origin is defined as the midpoint between LAM and RAM. The primary axis (axis1) is the unit vector from CH to GB. Having set seq to yzx, the primary axis is coincident with the y axis of the local coordinate system. The temporary axis (temp_axis) is the unit vector from GB to the origin. The normal axis to the plane defined by axis1 and temp_axis is the z axis of the local coordinate system. The x is the last axis to be computed and completes the right-handed orthonormal triad.

Kinematics XML file

The <model_name>.kinematics file contains the definition of the joint models and the kinematic chain.

<?xml version = "1.0" encoding = "UTF-8" ?>
<?xml version = "1.0" encoding = "UTF-8" ?>
<kinematics>
    <General>
        <Joint label="Cervical" group="General" prox="Trunk" dist="Head" opt="0"
               angleseq="zxy" type="free" JC="C7" />
        <Joint ... />
    </General>

    <KinematicChain>
        <unaffected_lower group="Left" joints="LeftHip, LeftKnee, LeftAnkle"
                          endbody="ForcePlatform" />
        ...
    </KinematicChain>
</kinematics>

Each joint node is defined by:

  • label: The name of the joint.
  • group: Any grouping the user might want to use to help defining the model (e.g., general, left and right).
  • prox: The label of the proximal segment of the joint.
  • dist: The label of the distal segment of the joint.
  • opt: Segment option label:
    • 0 (default): No additional specification.
    • 1: Optional segment.
    • 2: Segment used exclusively for transfemoral amputees.
    • 3: Segment used exclusively for transtibial amputees.
  • angleseq: The Euler/Cardan sequence used to decompose the joint rotation matrix (relative rotation of the distal segment relative to the proximal segment).
  • type: The type of mechanical joint associated with the model. This is now used as a description, and it does not add any specification to the kinematics calculation.
  • JC: The joint center label.

The KinematicChain node contains the definition of the kinematic chain associated with the most distal limb. The KinematicChain node includes:

  • unaffected_lower: The kinematic chain associated with an unaffected lower limb.
  • tf_lower: The kinematic chain associated with a lower limb of a person with a transfemoral amputation.
  • tt_lower: The kinematic chain associated with a lower limb of a person with a transtibial amputation.

Each of these records must include the following attributes:

  • group: Any grouping the user might want to use to help defining the model (e.g., general, left and right).
  • joints: The ordered list of joint labels, from the most proximal to the most distal joint, onto which the external reactions should be projected.
  • endbody: The source body from which the measured reactions (i.e., ground reaction forces and moments) are measured and projected along the kinematic chain.
⚠️ **GitHub.com Fallback** ⚠️