Dies ist eine alte Version des Dokuments!
Inhaltsverzeichnis
Process Configuration
General features
This component arranges the processing of multiple measurement trials by the Math Engine based on a Model description. Typically trial data is 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 so called „model parameter files“, which are used by the model for processing of the trials, e.g these files can include subject specific anthropometric data like foot length, age of a patient or what ever. These parameters are called Model Parameters. From which files in which formats model parameters are loaded depends on the used iTrialSet-Implementation. Different implementations exist, e.g. for Sessions determined by Vicon Workstation.
- 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 configuration files. Always one file is marked as the main file. This file defines all of the processing steps. The main structure of such a file looks as follow:
<?xml version="1.0" encoding="iso-8859-1" ?> <CalcMLProcessConfig name="UEGeneral2 HUX + Cluster" version="1.0" defaultmodel="UEGeneral2+Cluster_without-SHO-markers.xml" defaultmarkerset="Input.xml" defaultconstants="constants.properties" defaultview="StickFigure.xml" useEventsFromSessionMetaDataFile="false"> ... </CalcMLProcessConfig>
The root element <CalcMLProcessConfig> can include default values for some properties:
property 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 |
---|---|---|
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>-element can have children
<entry key="A">a</entry>
to control specific properties of the output handler.
Process Config XML: Model Switches
With a switch, the calculation of a modelling element can be switched of or on for specific trial types.
<Switches used="static_calibrate dynamic"> <switch name="static_calibrate"> <entry key="TRIALCATEGORY">static_calibrate</entry> </switch> ...
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>