### Inhaltsverzeichnis

# Generic Attributes of Calc-Elements

There is a set of attributes which can be implemented by all calcmodel elements. The functionality of some generic elements should be implemented but it can happen that is not yet done. Some attributes are optional and therefore only implemented if needed.

Attribute | Default | Description | Optional |
---|---|---|---|

name | Name of the element | No | |

noise | Used to add noise. | Yes | |

noiseAmplitude | Amplitude of noise to be added. | No | |

unit | Unit in which the attributes should be given. | No | |

debug | Set to true, if additional debug info should be printed. | No | |

visible | Creates additional data for visualisation. | No | |

coordinateSystem | A coordinate system used in several calc model elements. | Yes | |

includes | A list of calc group names the element is used for. | No | |

calibrateIncludes | A list of calc group names to define the trials used for calibration. | No | |

excludes | A list of calc group element names to be excluded. | No | |

calibrateExcludes | No | ||

calibrateExcludes | No | ||

average | false | No | |

meanStd | false | No | |

intervalsExtremeValues | false | No |

This is not completed.

# CoordinateSystem

This element is used to define a cartesian coordinate system, based on (method)

- two given vectors using crossproducts or
- rotating a reference coordinate system by given angles about its axes or
- a homogeneous 4×4 matrix or
- three axes, building a non orthogonal system or
- a rotation matrix and position trajectory.

The element creates a trajectory with the name of the element respresenting the orientation matrix.

The attributes of method one works as follow:

The given FirstAxis stays as first axis. The cross product between DefiningVector and the vector defined by FirstAxis defines the second axis. The third axis is defined by the cross product between the first axis and the second axis. This behavoir corresponds to the software BodyBuilder of the company Vicon!

Also calibration can be used to create a coordinate system on a given one.

Be careful: It is not possible to use parameter names in the formula attributes for the rotation and the origin.

### Attributes

Attribute | Default | Description | Required | Method |
---|---|---|---|---|

name | Name of the element | Yes | all | |

isVisible | false | Flag to define if 3d/4d visualitation of the frame as a tripod is wanted | No | all |

visibleVectorLength | 100 | If the flag isVisible=„true“ is set, the length of the 3d vectors representing the tripod, shown in the 3d/4d view can be defined. | No | all |

FirstAxis | Defines the first axis of the frame. This can be used by the method 1 based on cross products or by the method 4 based on three independend axes to define a non orthogonal system | Yes | 1, 4 | |

DefiningVector | The crossproduct between this vector and FirstAxis defines the second axis. The third axis is defined by the crossproduct between FirstAxis and this second axis. | Yes | 1 | |

orientation | xyz | Orientation of the axes. xyz: first axis is x , second is y, third is z. Be careful in all cases a right handed coordinate system ist constructed. That means zxy is righthaned corresponding to the definition but zyx defines a left handed coordinates system corresponding to its definition. In this case by automated sign changes a righthanded coordinaten system is build automatically. | No | 1 |

Position | Origin of the coordinate system defined in coordinates of the global laboratory cartesian system. If this coordinate system is defined by calibration or by rotation of a reference system this attribute is optional and overwrites the origin defined by calibration. | Yes | 1, 4 | |

Rotation | Defines a 3×3 rotation matrix. Its colums defines the three axes of the coordinate system | No | 5 | |

Pose | Defines a homogeneous 4×4 matrix which includes rotation and translation | Yes | 3 | |

forceRightHanded | Wenn das Flag forceRightHanded=„false“ gesetzt wurde, dann wird gegebenenfalls die dritte Achse umgedreht. D.h. bei den Konfigurationen: xzy, zyx und yxz wird die y, die x bzw. die z-Achse umgedreht. Die 3. Achse zeigt damit in etwa entgegengesetzt zu DefiningVector. | No | 1 | |

SecondAxis | No | 4 | ||

ThirdAxis | No | 4 | ||

coordinateSystem | If the attribute coordinatesSystem ist used, this coordinate system is defined by a rotation about the RotAxis by RotAngle of the coordinate system set by the coordinateSystem attribue. If you want to rotate about a axis of the given coordinate system use e.g. <name>_X for a rotation about the x axis. If you want to define the coordinate system by a sequence of two or three rotations use the attribute EulerCardanAngles. (Vielleicht sollte diese Element besser wieder eliminiert werden. Besser alternativ das Element ForwardFrame verwenden.) | Yes | 2 | |

RotAxis | Axis to rotate the three axes of the given coordinate system to determine a new one. | Yes | 2 | |

RotAngle | Angle in degree to rotation the given coordinaten system around the given axis to determine a new coordinate system. Use the right-hand-rule. If the rotation axis show in direction of the thumb of the right hand, the direction of your fingers shows in direction of positive angles. | Yes | 2 | |

EulerCardanAngles | If the attribute coordinatesSystem ist set the coordinate system can be defined by a sequence of three rotations about the axes of this coordinate system. The needed three angles are defined as mathematical formula defining a 3d vector, e.g. „vec(10.0,0.0,0.0) for defining a one step rotation about the first axis. The sequence of the corresponding axes is defined by the attribute orientation. If only one or two rotations are needed you can set the other angles to 0. (Die Syntax in unglücklich, da die Winkel keinen Vektor bilden. Schöner wäre es die Einzelkomponenten mit einzelnen Attributen zu setzen! Vielleicht sollte diese Element besser wieder eliminiert werden. Besser alternativ das Element ForwardFrame verwenden.) | No | 2 | |

average | Additional calculation of the trial average. The value is saved as a parameter with the name of the element and „Average“ as a suffix: <name of the element>Average | No | all | |

movingMeanWindowWidth (das ist obsolet, da die Methode der Ableitungsbildung geändert wurde) | 0.05 | Angegeben wird eine reele Zahl, die in der Regel ein Vielfaches der Schrittbreite ist. Sie gibt die Breite des Zeitintervalls in Sekunden an über das gemittelt wird, wenn Ableitungen bestimmt werden. Wenn movingMeanWindowWidth/2 kein Vielfaches der Schrittbreite ist, wird die nächst kleinere Zahl von Schritte bestimmt! | No | all |

differentiations | 0 | An integer, which defines how many differentiations of the trajectories are calculated. | No | all |

### Generated trajectories

Name | Type | Description |
---|---|---|

<name> | Matrix3d | Representation of the three orthogonal orientation axes of the coordinate system (columns of the matrix) |

<name>_X | Vector3d | first column of the matrix with name <name> Bug: seams not to work! Use x(<name>) instead. |

<name>_Y | Vector3d | second column of the matrix with name <name> Bug: seems not to work! Use y(<name>) instead. |

<name>_Z | Vector3d | third column of the matrix with name <name> Bug: seems not to work! Use z(<name>) instead. |

<name>Position | Vector3d | Origin of the coordinate system, only if it is not defined by a constant expression, e.g. vec(0.0,0.0,0.0).) |

### Generated calibration parameters

Name | Type | Description |
---|---|---|

<name>_XLocal | Vector3d | |

<name>_YLocal | Vector3d | |

<name>_ZLocal | Vector3d | |

<name>_PositionLocal | Vector3d |

### Examples

The following example defines a coordinate system „LHumerusHDCalB“ by rotating the coordinate system „LHumerusHDCalA“ around the upright axis about 30 degrees:

<CoordinateSystem name="LHumerusHDCalB" coordinateSystem="LHumerusHDCalA" RotAxis="LHumerusHDCalA" RotAngle="30.0" includes="ShoulderAbdAdd"/>

# LocalCoordinateSystem

This element is used to define a cartesian coordinate system in coordinates of a given reference coordinate system.

### Attributes

Attribute | Description | Required |
---|---|---|

name | Name of the element | Yes |

referenceCoordinateSystem | Defines the the reference coordinate system by its name. | Yes |

coordinateSystem | Defines the coordinate system which is transformed into the reference coordinate system (by its name). | Yes |

### Generated trajectories

Name | Type | Description |
---|---|---|

<name> | Matrix3d | Representation of the three orthogonal orientation axes of the determined local coordinate system (columns of the matrix) |

<name>Position | Vector3d | Origin of the coordinate system |

If calibration is used the following parameters are created:

### Generated parameters

Name | Type | Description |
---|---|---|

<name>Rotation | Matrix3d | Representation of the three orthogonal orientation axes of the determined local coordinate system (columns of the matrix) from the calibration trial. |

<name>Origin | Vector3d | Origin of the coordinate system of the calibration trial |

Simple example without usage of calibration:

<LocalCoordinateSystem name="TCPA" referenceCoordinateSystem="TCP" coordinateSystem="TCPDH1" includes="kirkdefault"/>

the above code snipset defines a coordinate system by tranforming the given coordinate system „TCPDH1“ into the reference coordinate system „TCP“. The result coordinate system is then given in coordinates of the reference coordinate system.

# GlobalCoordinateSystem

This element is used to define a cartesian coordinate system based on a given coordinate system in local coordinates of a given reference coordinate system.

### Attributes

Attribute | Description | Required |
---|---|---|

name | Name of the element | Yes |

referenceCoordinateSystem | Defines the the reference coordinate system by its name. | Yes |

localCoordinateSystem | Defines a local coordinate system which is based on the given reference coordinate system. This is is transformed into the global system. | Yes |

### Generated trajectories

Name | Type | Description |
---|---|---|

<name> | Matrix3d | Representation of the three orthogonal orientation axes of the determined local coordinate system (columns of the matrix) |

<name>Position | Vector3d | Origin of the coordinate system |

# Point

A point element defines es spatial 3d point defined by coordinates of the laboratory/global system or by coordinates in a given local coordinate system. The element creates a trajectory with the name of the element and the type of a 3d-Vector of double values.

## Attributes

Attribute | Default | Description | Required |
---|---|---|---|

name | Name of the element | Yes | |

localPoint | Instead of defining the point by coordinates in the laboratory/global system, it is possible to define the point by arbitrary local coordinates. The global coordinates of the point are then calculated by transforming with the given coordinate system. Note: This attribute needs the use of the attribute coordinateSystem. | No | |

coordinateSystem | Name of the coordinate system element which is used in two cases: 1. If the point is defined in local coordinates with the attribut „localPoint“ it defines the corresponding coordinate system. 2. If calibration is used, than for static trial which is defined by switches given with the attributes calibrateIncludes/calibrateExcludes the point is transformed in local coordinates of the coordinate system which is given with this element. For all other trials the local coordinates are back transformed to the global coordinates using the current value of the coordinate system defined by this attribute. | No | |

phase | If the calibration is used, but the trial is no static-only one, set this attribute to a phase type name to use only frames, which are included into the phase. This allows to use only static frames. If there are more than one calibration trial, only the first one is used. This behavoir should be changed to use all available calibration trials. | No |

### Generic Attributes

Attribute | Default | Description | Required |
---|---|---|---|

referencePoint | In a static trial the distance to this point is calculated as a trial mean. In no calibration trials this distance is used to translate the current position of the point to hold this fix distance. Note: This feature is not available in combination with the use of localPoint. | No | |

noise | No | ||

noiseAmplitude | No | ||

debug | No | ||

visible | No | ||

includes | A comma seperated list of switches to define for which trial the element is used. | No | |

excludes | A comma seperated list of switches to define for which trial the element is not used. | No | |

calibrateIncludes | No | ||

calibrateExcludes | No | ||

average | false | Additional calculation of the trial average. The value is saved as a parameter with the name of the element and „Average“ as a suffix: <name of the element>Average, if this attribute is set to „true“. | No |

## Deprecated attributes

Attribute | Description | Required |
---|---|---|

expr | Mathematical formula which defnines the point. Note: Typically this attribut is not used. The formula is given as elements content instead. | No |

x, y, z | These attributes allows an alternative definition of the point by seperate mathematical formulas for each of the three components. | No |

## Examples

In the calibration trial defined by the switch „static“ A is calculated as B+C in coordinates of the global laboratory system. The absolute coordinates are transformed in the given local coordinate system „Thorax“. In all of the following trials A is calculated by the fixed local coordinates by transforming to global coordinates by the current attitude of the „Thorax“ coordinate system.

<Point name="A" average="true" excludes="static">B+C</Point>

Calculates the point A as B+C in coordinates of the global laboratory system. If the switch „static“ is set for a trial nothing is calculated.

<Point name="A" localPoint="B+C" coordinateSystem="Thorax"/>

Calculates the point A as B+C in local coordinates and than thransform them by the coordinate system „Thorax“ in global coordinates.

<Point name="A" coordinateSystem="Thorax" calibrateIncludes="static">B+C</Point>

## Created trajectories and parameters

Name | Type | Condition | Description |
---|---|---|---|

<name> | Vector3d | always | the point values |

<name>LocalPoint | Vector3d | if the attribute „localPoint“ is used | trajectorie or parameter as defined by the formula given with the „localPoint“ attribute |

<name>Local | Vector3d | if calibration is used | |

<name>ReferencePoint | Vector3d | if calibration is used | |

<name>ReferencePointDistance | Vector3d | only for calibration trials | |

<name>ReferencePointDistanceCalibrate | Vector3d | only for calibration trials if the reference point attribute is used | distance to a given referencePoint |

# LocalPoint

A <LocalPoint>-element defines es spatial 3d point defined by coordinates of a given local coordinate system. The element creates a trajectory with the name of the element an the type of a 3d-Vector of double values.

#### Attributes

Attribute | Description | Required |
---|---|---|

name | Name of the element | Yes |

coordinateSystem | If this attribute is set, the elements content is interpreted in global coordinates which are transformed with the given coordinate system in local coordinates. | No |

**Note:** If calibration is used: all frames of the calibration trial are averaged and a Parameter <name> is saved in the modelParamenters file. This parameter can be used directly in a formula e.g from a forward-model.

<LocalPoint name="A" coordinateSystem="Thorax">B+C</LocalPoint>

# Vector

A <Vector>-element defines a 3d vector in coordinates of the laboratory global system or in coordinates of a given local coordinate system. The element creates a trajectory with the name of the element and the type of a 3d vector of double values.

## Attributes

Attribute | Default | Description | Required |
---|---|---|---|

name | Name of the element | Yes | |

localVector | Instead of defining the vector by coordinates in the laboratory/global system, it is possible to define the vector by arbitrary local coordinates. The global coordinates of the vector are then calculated by transforming with the given coordinate system. Note: This attribute needs the use of the attribute coordinateSystem. | No | |

coordinateSystem | Name of the coordinate system element which is used in two cases: 1. If the point is defined in local coordinates with the attribut „localPoint“ it defines the corresponding coordinate system. 2. If calibration is used, than for static trial which is defined by switches given with the attributes calibrateIncludes/calibrateExcludes the point is transformed in local coordinates of the coordinate system which is given with this element. For all other trials the local coordinates are back transformed to the global coordinates using the current value of the coordinate system defined by this attribute. | No |

**Note:** The Parameter <name>Local is created, if calibration is used. It contains the mean vector of the calibration trial in the coordinates of the given coordinate system.

**Examples**

<Vector name="A" coordinateSystem="Thorax" calibrateIncludes="static">B+C</Vector>

In the calibration trial defined by the switch „static“ A is calculated as B+C in coordinates of the global laboratory system. The absolute coordinates are transformed in the given local coordinate system „Thorax“. In all of the following trials A is calculated by the fixed local coordinates by transforming to global coordinates by the current attitude of the „Thorax“ coordinate system.

# LocalVector

A <LocalVector>-element defines es spatial 3d vector defined by coordinates of a given local coordinate system. The element creates a trajectory with the name of the element an the type of a 3d-Vector of double values.

#### Attributes

Attribute | Default | Description | Required |
---|---|---|---|

name | Name of the element | Yes | |

coordinateSystem | If this attribute is set, the elements content is intpreted in global coordinates which are transformed with the given coordinate system in local coordinates. | No |

**Note:** If calibration is used: all frames of the calibration trial are averaged and a Parameter <name> is saved in the modelParamenters file. This parameter can be used directly in a formula e.g from a forward-model.

<LocalVector name="A" coordinateSystem="Thorax">B+C</LocalVector>

# Real

Calculation of a double trajectorie. The element creates a trajectory with the name of the element and the type of double.

Attribute | Default | Description | Required |
---|---|---|---|

name | name of the element | Yes | |

process | Available values: stepbystep, post; The „process phase“, in which the calculations are done. | stepbystep | No |

noiseAmplitude | |||

expr | Mathematical formula defining a double. This attribute can be used instead of defining the formula as elements content. | ||

debug | false | No | |

visible | |||

includes | Comma seperated list of switches to define which trials are included. | No | |

excludes | Comma seperated list of swithces to define which trials are excluded. | No | |

calibrateIncludes | |||

calibrateExcludes | |||

average (in Mean umbenennen) | Additional calculation of the trial average. The value is saved as a parameter with the name of the element and „Average“ as a suffix: <name of the element>Average | No | |

meanStd (in MeanStd umbennen) | If set to true, mean average is calculated and saved in the parameter <name>MeanStd. | ||

differentiations | 0 | If this attribute is set to a integer value bigger than 0, the differentiations of the trajectorie <name> are calculated in the after step by step calculation (calculateOnCompleteTrajectories()) |

### Calculated Parameters

Parameters are calculated, if calibration is used or one or both of the flags „average“ and „meanStd“ are set to „true“:

Name | Description | trial parameter | model parameter | trajectorie | Availability |
---|---|---|---|---|---|

<name> | X | ||||

<name>Average | In the case of calibration the parameters saves the average about one or more calibration trials. In a first step each trial is averaged and than these average values are averaged. | X | If the average=„true“ or meanStd=„true“ or if calibration is used and a calibration trial is processed | ||

<name>Mean, <name>Mean_<Trial number> | Determines a trial average. If more than one trial is in the group of trials to be processed for this elemement than the trial number is append as an suffix. | X | X | The parameter is saved in the trial if there is no calibration. If calibration is used the parameter is saved in the sessions parameter file. | |

<name>MeanStd | If mean std determination is switched on (meanStd=„true“) the calculated values is saved | X |

### Examples

<Real name="A">B+C</Real>

# Matrix3x3

Calculation of a 3×3 marix trajectorie. The element creates a trajectory with the name of the element and the type of Matrix3x3.

Attribute | Default | Description | Required |
---|---|---|---|

name | name of the element | Yes | |

q0 | „w“-value of a quaternion to define the matrix elements | No | |

q1 | „q1“-value of a quaternion to define the matrix elements | No | |

q2 | „q2“-value of a quaternion to define the matrix elements | No | |

q3 | „q3“-value of a quaternion to define the matrix elements | No | |

x | columnvector defining the x-direction of the of a coordinate system, corresponding to the first column of the matrix | No | |

y | columnvector defining the y-direction of the of a coordinate system, corresponding to the first column of the matrix | No | |

z | columnvector defining the z-direction of the of a coordinate system, corresponding to the first column of the matrix | No | |

process | Planed values: stepbystep, post; The „process phase“, in which the calculations are done. | stepbystep. Not yet implemented | No |

noiseAmplitude | Not yet implemented. | No | |

expr | (deprecated) Mathematical formula defining a double. This attribute can be used instead of defining the formula as elements content. | ||

debug | false | No | |

visible | |||

includes | Comma seperated list of switches to define which trials are included. | No | |

excludes | Comma seperated list of swithces to define which trials are excluded. | No | |

calibrateIncludes | Not yet implemented. | No | |

calibrateExcludes | Not yet implemented. | No | |

average (in Mean umbenennen) | Additional calculation of the trial average. The value is saved as a parameter with the name of the element and „Average“ as a suffix: <name of the element>Average | No | |

meanStd (in MeanStd umbennen) | |||

m<ij> with i,j=0,1,2; e.g. m00, m01, … | defining all 9 matrix elements seperately | No | |

localMatrix | Not yet implemented. The idea is that the given local matrix is tranformed into the given coordinate system. | No | |

coordinateSystem | Not yet implemented. The be used in combination with the localMatrix attribute. The given matrix is transformed into the given coordinate system. | No |

# Mean and Standard Deviation

A <MeanStd> element determines mean and std of a mathematical formula over all frames of all trials defined by includes/includes.

# Parameter

A <Parameter>-element calculates time distance parameters for each trial.

### Attributes

Attribute | Default | Description | Required |
---|---|---|---|

name | name of the element | Yes | |

mathType | real | Possible values are real and 3d. The existence of this attribute is a workaround because automatic detection of the mathtype is not yet available. | No |

process | stepbystep | pre or post | No |

**Examples**

<Parameter name="ABC" method="min" includes="dynamic">c+d</Parameter>

# PointSetFit

Determines rotation and translation for best fit mapping of two given point sets based on a singular value decomposition. The first pointset is defined as the elements content and the second by the attribute „PointSet“. The element implements the interface iCoordinateSystem. So the determined corresponding coordinate system can be referenced by any AoR/CoR-Calc-Element.

### References

Arun KS, Huang TS, Blostein SD

IEEE Trans Pattern Anal Mach Intell9p698-700(1987 May)

### Specific Attributes

Attribute | Description | Required |
---|---|---|

phase | Type name of phases to defines the frames to be used. For each phase the mean values of the two (optional only for the first one) pointset-trajectories are calculated and used as a set of points. | Yes |

phase2 | Type name of a second set of phases to defines the frames to be used for the second timeserie. For each phase the mean values of the seconds pointset-trajectory is calculated and used as a set of points. | No |

PointSet | Name of the trajectory to get the second point set points. The trajectorie to define the first point set is defined by the elements content. | Yes |

maxVariation | If the values of the points of the two given pointsets inside a phase exceeds the value defined by this attribute the complete phase is excluded. | No |

### Examples

<PointSetFit name="Vicon2UR5e" phase="Pose" PointSet="TCPURP*1000.0" calibrateIncludes="calibrate_take_reference_svd" includes="kirkdefault,reference_test">TCPP</PointSetFit>

In the case the two timeseries (TCPUR5e and TCPP) are not perfectly sychronized, especially a delay is between them the following expamples implements the usage of phases seperately defined for each timeeries. The phases are used only, if in a trial the count of phases for each of the two timeseries is equal.

<PointSetFit name="TCP2UR5eFit" phase="Pose" PointSet="TCPUR5eP" phase2="Pose5e" calibrateIncludes="calibrate_take_reference_svd" includes="kirkdefault,reference_test">TCPP</PointSetFit>

### Created trajectories

Name | Type | Description |
---|---|---|

<name> | Vector3d | Points of the given first point set (1) transformed into the least squares fittet system based on the seconds point set (2) (defined by the attribute PointSet). |

<name>PointSet | Vector3d | Trajectory, which defines the points of the point set 2. |

### Created calibration parameters

Name | Type | Description |
---|---|---|

<name>R | Matrix3d | Rotation from pointset 1 to 2. |

<name>T | Vector3d | Translation from pointset set 1 to 2. |

<name>Scale | Double | Scale of the transformation between the two pointsets. Seems o be always 1.0. Maybe the fit algorithms must be extended. |

Remember: Calibration parameters are saved in the session parameter file and are not available to be used in formulas of further calc-elements.

### Created parameters

Name | Type | Description |
---|---|---|

<name>Orientation | Matrix3d | Orientation of the coordinatesystem the points of pointset 2 are given in. The orientation is given in coordinates the points of the first pointset are given in. |

<name>Origin | Vector3d | Origin of the coordinatesystem, the points of pointset 2 are given in. The origin is given in coordinates the points of the first pointset are given in. |

These parameters are created for non calibration files to make them availble in furher formula, e.g.:

<CoordinateSystem name="Mediapipe2ViconFit" Position="Mediapipe2ViconOrigin*1.0" Rotation="Mediapipe2ViconOrientation*1.0" excludes="static_calibrate,locator,dynamic_calibrate,calibrate_mediapipe"/>