====== Compute Planar Angle ======

This command computes a planar angle between three points as diagrammed in example 1 below, or four points as diagrammed in example 2 below. The location of the points displayed corresponds to the combo boxes containing the signal.

It is possible to compute a 3D angle, or to project the vectors onto one of the principal planes. If the user wants to project onto an arbitrary plane, transform the points into another coordinate system then project onto one of the principal planes of this new coordinate system.

  * The user can select to use a Right Hand or Left Hand Rule to define the sign of the angle.
  * The user can select the range 0 - 360 degrees or -180 to 180 degrees.
  * acos is used to calculate the planar angles. atan is not used.
  * 3D angles can only be computed to 0 - 180 degrees unless a normal vector is specified.

vec1 = vector from vertex 2 to vertex 1
vec2 = vector from vertex 2 to vertex 3
normal= vec1 cross vec2
angle= acos(vec1 dot vec2)
If you select a 3D angle and do not specify a projection plane or a normal vector, the answer is simply the angle between these vectors.
If you project the vertices onto a plane, the result is a 2D angle. in order to get 3 2D angles, you would need to create 3 different commands with each command projecting onto a different plane
If you define the normal vector, you have the ability to specify the direction of the angle.
The command can be edited via text editor and dialog. The details on the dialog and command are found below:

|{{:ComputePlanarAngleDialog.jpg}}  |<code>\\ Square_Root\\ /Signal_Types=The type of signal to be evaluated\\ /Signal_Names=The name of the signal to be evaluated\\ /Signal_Folder=The name of the signal folder\\ /Result_Folder=The name of the resulting folder\\ /Result_Names=The name of the resulting signal \\ /COMPUTE_3PT_ANGLE=(TRUE=3PT, FLASE=4PT}\\ /NORMALX=The normal vector to the 3D angle\\ /NORMALY=\\ /NORMALZ=\\ /REFERENCE_SEGMENT= LAB\\ /PROJECTION_PLANE= XY\\ /USE_RIGHT_HAND_RULE=TRUE\\ /USE_0_TO_360_DEGREES=TRUE\\ </code>  |


----

==== Examples ====

=== Example 1: Projected angles - 3 Point ===

Given TARGETS labeled:

**DISTAL1**, **VERTEX**, and **DISTAL2**
and a segment

**RFT**
Project the angle onto one of the Principal Planes of the **RFT** Segment Coordinate System.

<code>
! Compute the planar angle projected on the XY plane of the RFT segment from 3 points (DISTAL1,
! VERTEX, DISTAL2). The resulting signal is named TEST_ANGLE. The Right Hand rule is used and
! the angle is between -180 to 180 degrees.

Compute_Planar_Angle
/SIGNAL_TYPES=TARGET+TARGET+TARGET
/SIGNAL_NAMES=DISTAL1+VERTEX+DISTAL2
/SIGNAL_FOLDER=PROCESSED+PROCESSED+PROCESSED
/RESULT_NAME=TEST_ANGLE
/RESULT_FOLDER=ANGLE
/COMPUTE_3PT_ANGLE=TRUE
! /NORMALX=
! /NORMALY=
! /NORMALZ=
/REFERENCE_SEGMENT=RFT
! /PROJECTION_PLANE=XY
! /USE_RIGHT_HAND_RULE=TRUE
/USE_0_TO_360_DEGREES=FALSE
;
</code>

=== Example 2: Compute Planar Angle using transform segment coordinate system ===

This example transforms the targets **DISTAL1**, **VERTEX**, **DISTAL2** into the segment **RFT** coordinate system and then computes the planar angle **TEST_ANGLE**.

<code>
! First transform the locations into the segment coordinate system 

Transform_Data_Coordinate_System
/SIGNAL_TYPES=TARGET+TARGET+TARGET
/SIGNAL_NAMES=DISTAL1+VERTEX+DISTAL2
/SIGNAL_FOLDER=PROCESSED+PROCESSED+PROCESSED
/FROM_SEGMENT_CS=LAB
/TO_SEGMENT_CS=RFT
 /RESULT_TYPE=TARGET
 /RESULT_FOLDER=RFT
/RESULT_SUFFIX=
;

! Compute the planar angle projected on the XY plane of the RFT segment.

Compute_Planar_Angle
/SIGNAL_TYPES=TARGET+TARGET+TARGET
/SIGNAL_NAMES=DISTAL1+VERTEX+DISTAL2
/SIGNAL_FOLDER=RFT+RFT+RFT
/RESULT_NAME=TEST_ANGLE
/RESULT_FOLDER=ANGLE
/COMPUTE_3PT_ANGLE=TRUE
! /NORMALX=
! /NORMALY=
! /NORMALZ=
! /REFERENCE_SEGMENT=LAB
! /PROJECTION_PLANE=XY
! /USE_RIGHT_HAND_RULE=TRUE
/USE_0_TO_360_DEGREES=FALSE
;
</code>

=== Example 3: Projected angles - 4 Point ===

Given TARGETS labeled:

**PROX1**, **PROX2**, **DISTAL1**, and **DISTAL2**
and a segment

**RFT**
Project the angle onto one of the Principal Planes of the **RFT** Segment Coordinate System.

<code>
! Compute the planar angle projected on the YZ plane of the RFT segment from 4 points
! (PROX1,PROX2,DISTAL1,DISTAL2). The resulting signal is named TEST_ANGLE. The Right Hand rule
! is used and the angle is between -180 to 180 degrees.

Compute_Planar_Angle
/SIGNAL_TYPES=TARGET+TARGET+TARGET+TARGET
/SIGNAL_NAMES=PROX1+PROX2+DISTAL1+DISTAL2
/SIGNAL_FOLDER=PROCESSED+PROCESSED+PROCESSED+PROCESSED
/RESULT_NAME=TEST_ANGLE
/RESULT_FOLDER=ANGLE
/COMPUTE_3PT_ANGLE=FALSE
! /NORMALX=
! /NORMALY=
! /NORMALZ=
! /REFERENCE_SEGMENT=LAB
/PROJECTION_PLANE=YZ
! /USE_RIGHT_HAND_RULE=TRUE
/USE_0_TO_360_DEGREES=FALSE
;
</code>