===== Euler/Cardan Angles =====

^ Attribute ^ Default ^ Description ^ Required
^ name |            | name of element |  Yes  |
^ parentCoordinateSystem | | (or deprecated name basisCoordinateSystem) |  Yes  |
^ childCoordinateSystem | | (or deprecated name movingCoordinateSystem) |   Yes   |
^ orientation (axis order, rotationOrder) | xyz | This attribute can be set to a token, which defines the order in which the rotations are executed. To rotate a coordinate system from orientation 1 to orientation 2 with the Euler/Cardan convention there are twelve possible sets of euler/cardan rotation orders. The token determines which axis of the "parentCoordinateSystem" is taken as primary (flexion) axis, and which the secondary (abduction) axis. |   No   |
^ threshold | | Genauigkeit in dessen Schranken Rotations-Matrizen orthonormiert werden. Eigentlich nur relevant bei der Verwendung der "Mantissa"-Implementierung. |  No  | 
^ method | auto | **auto:** solution of the euler/cardan angles with the second rotation angle between 0 and pi (euler) or -pi/2 and pi/2 (cardanic).\\ **first10frames:** BodyBuilder nimmt die ersten 10 Frames und wählt dann die Lösung mit dem kleineren 2. Drehwinkel.\\ **fix1** bzw. **fix2:** Es wird fix immer nur eine der beiden möglichen Lösungen rausgeschrieben.\\ **framebased:** frame für frame wird entschieden welche Lösungen verwendet wird, sodass der 2. Drehwinkel der kleinere bleibt.\\ **trialbased:** Beim Wechsel der Halbkugel wird die Lösung gewechselt damit die Winkel stetig bleiben. Vielleicht brauche ich dann noch ein weiteres Attribut: condition. Das erste durch condition definierte Intervall legt fest welche Lösung verwendet werden soll. Der Rest wird dann konsistent gehalten. Problem: Die Winkel können nicht mehr Schritt für Schritt, sondern erst mit postprocess() bestimmt werden ... Wenn method="trialbased" und condition fehlt, dann könnte ich die BodyBuilder Methoden verwenden. |  No  |
^ implementation | default | This attribut is used only for testing the implementation. It is not supported and will be eliminated in the future.\\ **mantissa:** Instead using default implementation Mantissa api is used to calculate the angles. Attribut, um die Implementierung auszuwählen: mantissa, standard, simple (das ist vergleichbar mit der Matlab Implementierung von Jan Simon). Je nach dem ob ich mantissa oder default eingestellt habe, könnte ich eine Rotations-Matrix als Trajektorie oder Quaternionen als Trajektorie erzeugen ... Für die Quaternionen müsste ich vermutlich einen eigenen Datentyp erzeugen, oder aber einzelne double-Trajektorien was unschön wäre ... (werde ich vermutlich wieder abschaffen) derzeit wird das attribut method ignoriert, wenn ich als implementation mantissa ausgewählt habe. Es wird dann immer von **method="auto"** ausgegangen . |  No  |	 
^ unit | deg | **rad:** calculates the angles in radiant. |  No  |

**Notes**

The calculated cardan angles are given as a triple.\\
Corresponding to the rotation order the first value in the tripple is always the rotation angle about the axis the first rotation is around, the second value is the rotation angle about the second rotation is around and the last value is the rotation angle the third rotation es around.

The rotation from the "parentCoordinateSystem" to the "childCoordinateSystem" is expressed in angles about the axes of the moving "childCoordinateSystem". If you want to calculate angles around the fix axes of the "parentCoordinateSystem" you can simple revert  parent and child coordinate system and the sign of the resulting angles.

Instead, Vicon-BodyBuilder calculates the angles around the fix axes of the parent coordinate system.

The equations show that each rotation can be defined by two different values of the Cardan or Euler angles set. For example if Cardan angles are used, the rotation defined by the angles a1, a2 and a3 is the same as the rotation defined by the angles PI + a1, PI - a2 and PI + a3. The choice of the solution depends on the attribute method. Have a look at the following example:

<code xml>
  <!-- The first axis (x) shows to the front, the second (y) directs to left, the third (z) up -->
  <CoordinateSystem name="A"
    Position="vec(0,0,0)"
    FirstAxis="vec(1,0,0)"
    DefiningVector="vec(0,0,1)
    orientation="xyz"/>
    
  <!-- The first axis (x) shows to the back, the second (y) directs to left, the third (z) down -->
  <CoordinateSystem name="B"
    Position="vec(0,0,0)
    FirstAxis="vec(-1,0,0)"
    DefiningVector="vec(0,0,-1)"
    orientation="xyz"/>
    
  <EulerCardanAngles name="AB"
    parentCoordinateSystem="A"
    childCoordinateSystem="B"
    decompositionOrder="yxz"/>
</code>
In principle there exists two solution to rotation coordinate system A into B:

With no further attributes set in the EulerCardanAngles element this results in the solutiuon [-180 0 -180]. But also the solution [180 0 0] is correct. You can get it by set of further attributes. 

**Created trajectories and parameters**

^ Name ^ Type ^ Description  ^ Timeserie ^
^ Angles |3d vector | |  Yes  |
^ Average | | if average="true" |  No  |
^ MeanStd | double  | |  No  |

**Examples**

<code xml>
    <EulerCardanAngles name="A"
    	parentCoordinateSystem="B"
    	childCoordinateSystem="C"/>
</code>

ToDo: Schön wäre es wenn ich in der Nähe des GimbalLock eine entsprechende Phase erzeugen könnte. Dafür dann am besten ein zusätzliches Attribut einführen das definiert wann ich in der Nähe des Gimbal Locks bin, also z.B einen Winkelabstand in Grad z.B. 1 Grad ... 

===== Projection Angles =====

A ProjectionAngle element defines the angle between two vectors which are projected into a plane defined by its normal vector.

There are two possiblities to defined the two vectors.

In the first (deprectated) version the two vectors are defined by a common point laying in the projection plane (JointCenter) and two other points given in absolute coordinates which were projected into the plane before the angle is calculated.

In the second version the two vectors are given directly by directed vectors also given in the global coordinate system.

The angle is defined from the second to the first vector with the left(?) hand rule (thumb in direction of the normal vector of the projection plane).
Es wird davon ausgegangen, dass die angegebenen Vektoren in einem rechtshändigem Koordinatensystem formuliert sind. Ist das nicht der Fall bekommt man pi minus dem Winkel zurück.
 
Liegen die Vektoren in einem linkshändigem Koordinatensystem vor, dann ist es am einfachsten das Vorzeichen aller z-Kompoenten zu wechseln d.h. sowohl die der Hebelarme als auch die der angegebenen Achse für die Orientierung (Normalenvektor der Projektionsebene).

**Attributes**

^ Attribute ^ Description ^ Default ^ Required ^
^ name | name of the element | |  Yes  |
^ ProjectionAxis\\ (oder der alte name Axis) | normal vector defining the plane in which in the angle is calculated. | |  No  |
^ JointCenter\\ (deprecated) | A point defining together with the Axis the plane in which the angle is calculated. This point is also the start point of the two vectors between the angle is calculated. | No, but if these three arguments are not used, FirstVector and SecondVector must be used instead. |  No  |
^ LeverArmPoint1\\ (deprecated) | This point defines the end point of a first vector which starts at the position of the JointCenter. The vector is projected into the plane before the angle is calculated. | | |
^ LeverArmPoint2\\ (deprecated) | This point defines the end point of second vector which starts at the position of the JointCenter. The vector is projected into the plane before the angle is calculated. | | |
^ FirstVector | The two vectors between the angle is calculated after its projection to the plane with ProjectionAxis as normal vector. | No, but if these three arguments are not used, JointCenter, LeverArmPoint1 and LeverArmPoint2 must be used instead. | |
^ SecondVector | | | |
^ useOffset | Die Implementierung scheint auskommentiert zu sein!!! | true, than the value of the attribut Offset is added to the resulting projection angle. |  No  |
^ Offset | angle offset value which is added to the resulting projection angle, if the attribute flag useOffset is set to true. | unsigned, if set to "true" the angle is calculated in the range from 0 to 360 degrees. If this attribute is set to "false" the angle is calculated in the range from -180  to +180 degrees. |  No  |
^ noiseAmplitude | | No | |

    forceContinuousValues

    	If set to "true" jumps in the values based on the circular behavoir of angles are eliminated by adding an offset value of 180 or 360 degree depending on the unsigned flag after leaving the cycle ranges.
    	false
    	No

    debug

    	  	false
    	No

    visible

    	  	
    	No

    includes

    	comma seperated list of switches 	
    	No

    excludes

    	  	
    	No

    calibrateIncludes

    	  	
    	No

    calibrateExcludes

    	  	
    	No

    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

    unit

    	"deg" oder "rad" (not implemented yet)
    	deg
    	No