======Main process configuration======

The subfolder **msprocesses** of a Nimue platforms project includes the so called **process configuration file** with the default name **DefaultConfig.xml**. This file defines the data sources and the details about how to get data from the sources (measurement systems configuration). The main structure of such a file looks as follow:





<code xml>
<?xml version="1.0" encoding="iso-8859-1" ?>

<MeasurementProcess name="Upperlimb Measurement">
   <MeasurementSystem id="default" system="ROS" fileSuffix="r3d">
            <TransducerUnitGroup name="vicon/RightHumerus" 
                                 displayName="RightHumerus">
                <TransducerUnit name="RightHumerus" 
                                displayName="RightHumerus" 
                                sampleRate="120">
                   <Channel name="q0"/>
                   <Channel name="q1"/>
                   <Channel name="q2"/>
                   <Channel name="q3"/>
                   <Channel name="v0"/>
                   <Channel name="v1"/>
                   <Channel name="v2"/>
                   <Channel name="T"/>
                </TransducerUnit>
                ...
            </TransducerUnitGroup>
            ...
      
   </Measurementsystem>
   <TrialType name="takeover" duration="2"
              labelset="Input.xml" measurementSystemConfigIds="default">
              <PropertyGroup name="ROSTrigger">
                  <Property name="robot_cmd_node_name" value="robot_command_server"/>
                  <Property name="robot_cmd_service_name" value="robotCommand"/>
                  <Property name="nextcycle_cmd_node_name" value="robot_nextcycle"/>
                  <Property name="nextcycle_cmd_service_name" value="nextCycle"/>
              </PropertyGroup>
              <PropertyGroup name="multicycles">
                  <Property name="cycles" value="5"/>
              </PropertyGroup>
              <PropertyGroup name="modalities">
                  <Property name="cycle_nr" value="*"/>
              </PropertyGroup>
              ...
    </TrialType>
    ...
</MeasurementProcess>
</code>

=====Configuration of the measurement system=====
The most important element is **<MeasurementSystem>** with the following attributes:

^ Attribute name 	^ Description |
^ id | unique identifier of the measurement system used in the trialType definitions |
^ system | Name of the measurement system type as defined in their implementations. |
^ fileSuffix | file suffix of the default output file written in the motiondata file format. |

Multiple <MeasurementSystem>-elements are possible to define one or more measurement systems. Properties which are specific for a measurement system can be added by <Property>-elements:

<code xml>
<?xml version="1.0" encoding="iso-8859-1" ?>

<MeasurementProcess name="Upperlimb Measurement">
   <MeasurementSystem id="default" system="ROS" fileSuffix="r3d">
      <Property name="sampleRate" value="120.0"/>
   ...
</code>

The data sources are defined as a hierarchy of **<TransducerGroup>**- and **<TransducerUnit>**-children-elements. In the current implementation it is not allowed that **<TransducerGroup>**-elements can contain further **<TransducerGroup>**-elements.

**Attributes of <TransducerUnitGroup>:**

^ Attribute name 	^ Description |
^ name | name of the measurement unit group. |
^ dispayName | Name shown in the nodes hierarchie after loading the configuration. |


A **<TransducerUnit>**-element defines a sequence of **channels** streaming double-data. If the sequence of channels is not defined by the appropriate **<channel>**-elements, a default sequence is used. But it is recommend to explicitly define the channels sequence to be sure about the data.

**Attributes of <TransducerUnit>:**

^ Attribute name 	^ Description |
^ name | name of the measurement unit. |
^ dispayName | Name shown in the nodes hierarchie after loading the configuration. |
^ sampleRate | Sample rate of the data streamed by this measurement unit. |

**<Channel>-elements of the <TransducerUnit>:**

The <TransducerUnit>-elements should have <Channel>-elements for each channel of the unit. Its attribute "name" must match with the channel name as defined in the TransducerUnit implementation. Channel which are not configured are automatically disabled.

**<TransducerUnit>**- and **<TransducerUnitGroup>**-elements can have **<Property>**-elements as children to define specific properties.
=====Configuration of the trial types=====
A trial type defines general aspects of the recording and especially which data should be written into files. 

^ Attribute name 	^ Unit ^ Type ^ Description ^ Optional |
^ name | | String | The name of the trial type. It is visible in the list of available trial types in the record UI. | No |
^ duration | seconds | float | The duration of the recording. If not set variable-length-recording should be used. But this is currently not implemented. | No |
^ offset | seconds | float | An offset/time interval to wait after start triggering bevor starting the recording | Yes |
^ closeOffset | seconds | float | An offset/time interval to wait after recording and before closing the recording.This can be useful if a sequence of trials is recorded and after the last trial the trigger has to wait before a closing procedure is executed, e.g. a robot needs time to move to a start position before the robot program is closed. | Yes |
^ measurementSystemConfigIds | | String | A list of measurement system IDs to be used. All measurementsystem which are not listed here are automatically disabled. | No |
^ labelset | | String | The name of the labelset to define, which data should be written into files. Details are described in the chapter "Configuration of the output" (filename with suffix xml).| Yes |
^ overwrite | | boolean | Default==true, if set to true, than if a trial is saved an existing file with the  the same file name is overwritten without any question. If set to false and a file exists a index is automatically added before the file suffix "_<index>". Also all existing files with such indizes are recognized and the index is choosed as a the last found index +1. If this index is bigger than a max index than the index starts agains with 1 and an existing trial is overwritten withoug any question. The max index can be overwritten with the next attribute. | Yes |
^ maxindex | | int | Max index to be used as a suffix if a trial exists. Default==9 | Yes |

Further e.g. trigger or multicycle specific trial type configurations are defined in property-groups. This is described in the following sub chapters.

====Multicycle configuration====
There are two types of multicycles configuration available. The first one defines only how many cycles should be measured. The following attributes are used as children from the property group **multicycles**:

^ Attribute name 	^ Description |
^ cycles | The number of cycles |

The second type defines a sequence of trial types. The following attributes are used as children from the property group **multicycles**:

^ Attribute name 	^ Description |
^ cyclesSequence | A space separated list of trial type names |
^ pressButtonForNextCycle | if set to "true" between switching to an other trial type a dialog box is opended and a butto must be pressed. This cancel option allows to cancel the complete measurement process. |
====Trigger configuration====
=====Configuration of the output=====
Each trial is saved into a seperate file in the motion data object file format. The default suffix of such files is ".r3d". 

====Timeseries====
Which data to be saved is defined in a labelset xml file as follows:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<LabelSet name="Vicon Objects and Markers.">
  <Labels name="ROS" baseFile="true">
          <Label sensorName="Thorax" name="ThoraxQ" mathType="QUATERNION_D"/>
          <Label sensorName="Thorax" name="ThoraxP" mathType="COLUMN_VECTOR_3D"/>
          <Label sensorName="Thorax" name="ThoraxT" mathType="REAL"/>
          ...      
</code>

**The sequence of the labels is used to connect to the corresponding channels, if every mathtype is used only once.**

To make this possible default channels names are used for the following math types:

^ Math type ^ Default channel names |
^ REAL | T |
^ COLUMN_VECTOR_3D | v<n> n={0,1,2} |
^ MATRIX_3X3D | m<i><j> i={0,1,2}, j) j={0,1,2} |
^ QUATERNION_D | q<i> i={0,1,2,3} |

If the unit contains a specific type more than once than the label must define the attribute "channelNames" which contains a list of channel names for each channel of the given type. In the case of type REAL this attribute must contain only one channel name. 

The channel name must be the name as defined in the corresponding transducer unit implementation. This can be different to the name, given for the <Channel>-element as defined in the measurement system configuration!

<code xml>
<Label sensorName="joint_temperatures" channelNames="URt0" name="Temperature0" mathType="REAL"/>
<Label sensorName="joint_temperatures" channelNames="URt1" name="Temperature1" mathType="REAL"/>
<Label sensorName="joint_temperatures" channelNames="URt2" name="Temperature2" mathType="REAL"/>
<Label sensorName="joint_temperatures" channelNames="URt3" name="Temperature3" mathType="REAL"/>
<Label sensorName="joint_temperatures" channelNames="URt4" name="Temperature4" mathType="REAL"/>
<Label sensorName="joint_temperatures" channelNames="URt5" name="Temperature5" mathType="REAL"/>
<Label sensorName="joint_temperatures" channelNames="URtT" name="TemperatureT" mathType="REAL"/>
  
<Label sensorName="target_q" channelNames="URAngle0" name="Angle0" mathType="REAL"/>        
<Label sensorName="target_q" channelNames="URAngle1" name="Angle1" mathType="REAL"/>
<Label sensorName="target_q" channelNames="URAngle2" name="Angle2" mathType="REAL"/>
<Label sensorName="target_q" channelNames="URAngle3" name="Angle3" mathType="REAL"/>
<Label sensorName="target_q" channelNames="URAngle4" name="Angle4" mathType="REAL"/>
<Label sensorName="target_q" channelNames="URAngle5" name="Angle5" mathType="REAL"/>
<Label sensorName="target_q" channelNames="URAngleT" name="AngleT" mathType="REAL"/>
</code>

**The <Label>-elements can have the following attributes:**

^ Attribute name 	^ Description ^ Optional |
^ channelNames | If a specified math type is available more than once for a unit than this attribute must be used to define which channels should be used with the label. | Yes |
^ name | A unique label name. It is not needed that this name matches with the corresponding channel name of the sensor. Only the sequence of labels is used to match the sequence of channels of the sensor.| No |
^ sensorName | The name of the sensor to collect data from. Be careful: This name must match the sensor name. If it does not match no data is saved for this label without any error message.| Yes |
^ mathType | The math type of the data to collect. | Yes |
^ differentiations | The count of differentiations to be created. Each differentiation creates a timeserie with an additional prefix "d". | Yes |
^ interpolatorType | Interpolation can be used to fill gaps and for resampling. Per default interpolation is done with mathe LINEAR and also resampling is done if needed | Yes |
^ maxgap | Maximum width of gamps (measured in frames, int). Not yet implemented. | Yes |

Possible interpolation methods:

^ Interpolation type name ^ Description | 
^ NONE | No interpolation to fill gaps and also no resampling, even if needed. | 
^ DIVIDED | |
^ DIVIDED_DIFFERENCE | |
^ LINEAR | | 
^ LOESS | |
^ NEVILLE | | 
^ SPLINE | |

===Filter===
The timeseries can be filtered automatically before saved. 

Sometimes all values of Vector3d-tripples are zero but should be NaN. This can be reached by including:

<code xml>
<Filter name="zero2nan"/>
</code>

as a child-element of the <Labels>-element.

====Additionel export of subsets of the data====
Optional a subset of this data can be saved into additional files of different file formats. To do this, the labelset must include an additional <Labels>-element for each file to write.

<code xml>
<Labels name="ROS" mimeType="text/x-csv" fileSuffix="csv">
        
          <Label name="RightScapulaQ" mathType="QUATERNION_D"/>
          ...
</code>

The following file formats are available:

^ Mimetype ^ Description ^
^ text/x-csv | A CSV-file with timeseries. The delimiter can be configured in the Options-Pane. A header is given. No metadata are saved. |

====Output files for multiple measurement systems====
If more than one measurementsystem is used, for each a separate labelgroup has to be defined in the labelset. Each labelgroup must define the property "fileSuffix" with the system name of the measurement system as its value. The value is identical to the value of the "name"-attribute of the labelgroup. It is not used as a real file suffix. The file suffix is overwritten by the configuration in the in the measuremetsystem configuration.

This strange behavoir should be changed in further versions of the software.
==== Metadata====

For each trial meta data is saved into the **modalities** property group for further postprocessing steps. 

There are some properties which are automatically saved:

^ Property name ^ Description ^
^ TrialType | The name of the used trial type | 
^ SUBJECT | The name of the subject, as configured in the recording UI |
^ SESSION | The name of the session. Per default this is the name of the session folder. It can be overwritten by the recording UI. |
^ SIDE | This can be used if the trial is focussed of left, right or both sides of a human body. |

Additional properties are available but must be explicitly configured to be saved as follow:

<code xml>
<PropertyGroup name="modalities">
      <Property name="cycle_nr" value="*"/>
</PropertyGroup>
</code>

The value "*" is used, if the value is overwritten, e.g. by the nextCycle() response of an iTrigger-SPI implementation.