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

==== Configuration ====
A <ProjectionAngle>-element defines the angle between two vectors, after a projection of these vectors into a plane, defined by its normal vector.

There are two possiblities to define the two vectors.

In the old (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 new/current 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, the hand shows the direction around the thumb).

It is assumed that the vectors are given in coordinates in a right-handed coordinate system. If this is not the case you can determine the expected values by pi minus the result. 

If all vectors are defined in a left-handed coordinate system than you can switch the signs of all z-components of the "input"-vectors to get the expected result directly.

==== Attributes ====

^ Attribute ^ Description ^ Default ^ Required ^
^ name | name of the element | |  Yes  |
^ unsigned | true: Values are [0;360deg], else [-180;180] | true |  No  |
^ forceContinuousValues | If set to true 2pi periondic jumps are automatically eliminated. Its experimentelly. | false |  No  |
^ 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 |

==== Created trajectories  ====

^ Name ^ Type ^ Description ^ 
| <name>FirstVector | Vector3d | The first direction vector. |
| <name>SecondVector | Vector3d | The second direction vector. | 
| <name>Axis | Vector3d | The projection axis vector. | 
| <name>Angle | double | The projection angle values. | 

==== Created parameters ====

^ Name ^ Type ^ Description ^ 
| <name>AngleAverage | double | The average of the angle timeserie. |
| <name>AngleMeanStd | double | The standard deviation corresponding to the average angle. | 
| <name>IntervalsMinAverage | double | Created only if the attribute intervalsExtremeValues=true. | 
| <name>IntervalsMaxAverage | double | Created only if the attribute intervalsExtremeValues=true. | 
| <name>IntervalsAverage | double | Created only if the attribute intervalsExtremeValues=true.| 
| <name>IntervalsUnsignedROMAverage| double | Created only if the attribute intervalsUnsignedROM=true.| 

**Example:**

<code xml>
  <CoordinateSystem name="A"
                    Position="vec(0,0,0)
                    FirstAxis="vec(-1,0,0)"
                    DefiningVector="vec(0,0,-1)"
                    orientation="xyz"/>
    
  <ProjectionAngle name="Ax"
                     FirstVector="y(A)"
                     SecondVector="test"
                     ProjectionAxis="x(A)"/>
</code>