Process Configuration

This component arranges the processing of multiple measurement trials by the Math Engine based on a model description. Typically all of these trials are saved in a single folder in the filesystem. For each trial more than one file with the same name but different suffixes can exist.

E.g. there is a 001.c3d file which includes timeseries of marker positions of a 3d motion analysis system, a 001.mpg file with a synchronous measured video, 001.enf (Vicon file type) with meta data and so on. The file types are free configurable.

How this session of trials is processed, is defined by the XML Process Configuration file. The principle processing arrangement steps are the following:

The trials are grouped based on arbitray information readable from the files of each trial. E.g. in the case of a Vicon session the .enf file includes meta data, which can be used to descide if a trial is a calibration trial or a motion trial. Also the file names themselfes can be used as a criterium.
The session can include special files with parameters, which are used by the model for processing of the trials, e.g the file can include subject specific anthropometric data like foot length, the age of a patient or what ever. These parameters are called Model Parameters.
A labelset XML file is referenced for each group, which defines which timeseries must be read to process.
A model XML file must be referenced for each group, which defines the calculation steps. This results in new calculated timeseries.
Switches can be defined to switch on/off different calculation steps defined in the model, depending on the processed trial. These switches are independed from the group definition for maximum flexibility.
A labelset for the output must be defined for each group. This defines, which timeseries and single parameters should be written to an output file. Also the file format of the output file can be configured. And it is possible to create more than one output file for each trial or also only one output file for all of the (input) trials. Specialized Output handling can be plugged in by implementation of so called OutputHandler.

All of the configurations that are needed for processing sessions of trials is bundled to a so called project. An application can include one or more fix such projects or it can be modelling tool for user defined projects.

Project folder structure

A project corresponds to a folder with subfolders, which include different configuration files inside. Also the output of the processing can be saved inside this project folder structure.

sub-folder name	Description
cmlproject	Internally used to save project configurations in a file named as cmlproject.properties (.properties file format) and to recognize the folder as Nimue projects folder. This folder is typically not shown to the user.
datasets	One or more files which includes a set of paths to the sessions to process. One file is defined as main dataset file.
jobs	One or more process configuration files. One file is defined as main process configuration file.
models	One or more model description XML files.
labelsets	One or more XML labelset configuration files
constants	One or more files with constants referenced by the model. (.properties file format).
output	Files which include the output of the processing, typically in the .d3d file format.
classes	optional folder which can include plugged in output handlers for third-party file formats
mfiles	optional folder which can includes additional matlab function files (.m files)
sheets	One or more XML configuration files to define sheets of plot for different groups of trials.
views	One ore more XML configuration files to define 3d visualizations.
masks	One or more XML configuration files to configure the visualization of the trials meta data. This corresponds to the eclipse database .enf configuration files from Vicon Workstation.
normdata	One or more .d3d-files including normal data for the project.

In some folder a main file is defined. In the GUI these main files are shown with bold face.

Process Config XML: Default Values

The folder "jobs" can include one or more XML process configurate files. Always one file is marked as the main file. This defines all of the processing steps. The root element <CalcMLProcessConfig> allows to define some default values:

name	Description
defaultmodel	Name of a model file which is used, if for a CalcGroup no model file is defined.
defaultmarkerset	Name of markerset file which is used, if for a CalcGroup no markerset file is defined.
defaultconstants	Name of constants file, which is used, if for a CalcGrop no constants file is defined.
defaultsheet	Name of file with a sheet definition. It is used if data determined by different CalcGroups should be visualized in a sheet.
defaultview4d	Name of file with a view4d definition. It is used, if data determined by different CalcGroups shoulb be visualiszed or a CalcGroup does not define it.
defaultnormaldata	Name of the file with default normal data. For the structure of this file have a look at the explaination of the Process Configuration.

Process Config XML: Groups of Trials

The <CalcGroup>-element defines a group of trials. One or more groups can be defined. It is recommended to define a minimum of one groups. If no group is explicitly defined, a default group is automatically created which includes all trials.

Attributes of the <CalcGroup>-element:

name	Default	Description	Needed
name		Name of this group
sheet		A Sheet definition which is used to plot sheets of time series of data assigned to this group.
view		A View 4d defintion which is used to visualize time series of data assigned to this group.
normaldatagroup		If normaldata based on an other CalcGroup should be used. If this attribute is not set, it is assumed that the group on his self is the normdata group.
normaldata		(not implemented yet) Explicit name of a normal data file if the default is not sufficient.
calibrationstep	-1	(not implemented yet) Used if this group is used for calibration. -1 if it is not used. Small numbers, starting with 0, the numbers must be different for different groups. If there is no group with calibrationstep != -1, then single trials can be processes. The defined order cauld be used instead of the implicit order in the <CalcGroups> sequence attribute. Oder besser statt dessen zusätzliche Attribute in <CalcGroups> definieren? ja! calibrationsequence zusätzlich einführen

To define which trials are assigned to a group the element <identification> is used. It is possible to assign a trial to different groups but this is not recommended.

Identification of trials:

The <identification>-element includes one or more <entry>-Elements. Each of these elements describe a condition. The key-attribute is the name of a property which is attached to the trial e.g. in the case of Vicon data it is the name of a property saved in the trials corresponding .enf-file. There are some special additional keys which exist independed from the third-partys measurement data files:

The keys and the values are case sensitive. Have a look at the following example:

<identification>
 <entry key="CLASS">Static_Cal"</entry>
 <entry key="SIDE">bds|links|rechts|Side R|Side L|Both"</entry>
</identification>

The propertys value are defined as content of the <entry>-element. It is a regular expression.
A trial is assigned to the group of trials, if the conditions defined by all <entry>-elements are achieved.

Process Configurations:

The <process> element allows to declare properties, which can be read to configure the read of input data from specific files. E.g. for reading data from c3d-files the properties EVENTS, FORCES and POINTS are used. Set the property value to "false" to inhibit to read the specific data, e.g

<process>
 <entry key="EVENTS">false</entry>
 <entry key="FORCES">false/entry>
</process>

Input:

Output:

Attributes of the <output>-element:
Attribute Default Description Required
labelset
The labelset which defines which parts of the data should be written to the output and also meta data e.g. the mime type and the file suffix.

Yes
mimetype
(deprectated)
Mimetype to define the output file format.
This is set normally inside the labelset file.

No
filesuffix
suffix of the outputfile
normally this is defined inside the labelset
(deprecated)

No
dir
dir of the input session of trials

Absolute path of the directory, where the outfile should be written.

No
name
Can be used to define the name of the output file.
(currently not used)

No
append
false

If set to true the data is appended to file if is exists.

No
handlerclass
Use a customer defined output handler class.
(changes are needed to be able to use more than one handler class)

No
If the <output>-element is not set, than all time series and parameters are written to a file located in the input trials session folder. If a file exists this file is overwritten (append="false").
The <output>-elemement can have childs
<entry key="A">a</entry>
These Properties can be used from the output handler. But this feature is currently not used.

Process Config XML: Model Switches

Process Config XML: Model Parameters

Process Config XML: Normal Data Definition

Example XML Process Configuration fragment

<?xml version="1.0" encoding="iso-8859-1" ?>
<!-- DOCTYPE CalcMLConfig PUBLIC "-//CalcML//DTD CalcML 1.0//EN" "http://www.orat.de/CalcML/dtds/calcML-ProcessConfig_1.0.dtd"-->

<CalcMLProcessConfig name="Test"
 defaultmodel="codman_model.xml"
 defaultmarkerset="codman_markerset.xml"
 defaultconstants="constants.xml"
 defaultsheet="defaultSheetDef.xml">
 
 <CalcGroups sequence="static_calibrate static_calibrate_shoulder static dynamic">
 
 <!-- Kathegorien fuer Calibrations-Zwecke -->
 
 <CalcGroup name="static_calibrate">
 <identification>
 <entry key="CLASS">Static_Cal"</entry>
 <entry key="SIDE">bds|links|rechts|Side R|Side L|Both"</entry>
 </identification>

 <process>
 <entry key=""></entry>
 </process>

 <input labelset="" 
 eventssource="TRIAL=default|sessionMetaDataFile|trialMetaDataFile"/>
 <output labelset="" append="false">
 <entry key="A">a</entry>
 </output>
 </CalcGroup>
 
 <CalcGroup name="static_calibrate_shoulder">
 <identification>
 <entry key="CLASS">Static_Cal</entry>
 <entry key="SIDE">bds|links|rechts|Side R|Side L|Both</entry>
 </identification>
 </CalcGroup>
 
 ...

 <!--category name="dynamic">
 <identification>
 <CLASS>Dynamic|ShoulderAnte/Retro|ShoulderAbd/Add</CLASS>
 <SIDE>bds|links|rechts|Side R|Side L|Both</SIDE>
 </identification>
 </category-->
 
 <!--category name="static">
 <identification>
 <CLASS>Static|Static_cal</CLASS>
 <SIDE>bds|links|rechts|Side R|Side L|Both</SIDE>
 </identification>
 </category-->
 
 </CalcGroups>
 
 <Switches used="static_calibrate static_calibrate_shoulder left right static dynamic">
 
 <switch name="static_calibrate">
 <entry key="TRIALCATEGORY">static_calibrate</entry>
 </switch>
 <switch name="static_calibrate_shoulder">
 <entry key="TRIALCATEGORY">static_calibrate_shoulder</entry>
 </switch>
 
 <switch name="left">
 <entry key="SIDE">bds|links|Side L|Both</entry>
 </switch>
 <switch name="right">
 <entry key="SIDE">bds|rechts|Side R|Both</entry>
 </switch>
 
 <switch name="static">
 <entry key="TRIALCATEGORY">static</entry>
 </switch>
 <switch name="dynamic">
 <entry key="TRIALCATEGORY">dynamic</entry>
 </switch>
 
 </Switches>
 
 <ModelParameters>
 <input filename="" filetype="" needed="a b c">
 <defaultValues>
 <entry key="abc">100</entry>
 </defaultValues>
 </input>
 <output filename="" filetype=""/>
 </ModelParameters> 
 
</CalcMLProcessConfig>

Branding

Some default values of the process configuration can be changed by branding, for a custom specific application:

<folder name="ProcessConfig">
	<folder name="defaults">
    		<file name="output">
			<attr name="mimeType" stringvalue="text/x-hd-asc"/>
  			<attr name="fileSuffix" stringvalue="out"/>
    		</file>
  	</folder>
</folder>

Attribute	Default	Description	Required
labelset		The labelset which defines which parts of the data should be written to the output and also meta data e.g. the mime type and the file suffix.	Yes
mimetype		(deprectated) Mimetype to define the output file format. This is set normally inside the labelset file.	No
filesuffix		suffix of the outputfile normally this is defined inside the labelset (deprecated)	No
dir	dir of the input session of trials	Absolute path of the directory, where the outfile should be written.	No
name		Can be used to define the name of the output file. (currently not used)	No
append	false	If set to true the data is appended to file if is exists.	No
handlerclass		Use a customer defined output handler class. (changes are needed to be able to use more than one handler class)	No