# Utility functions for angles and rotations.

## Functions
double | F3DArcSinCos (double dSinus, double dCosinus)
void | F3DLimit (double &io_dVal, double in_dMin, double in_dMax)
void | F3DQuatToMat (const CSIBCQuaterniond &in_quat, CSIBCRotMatd &out_mat)
void | F3DMatToQuat (const CSIBCRotMatd &in_mat, CSIBCQuaterniond &out_quat)
void | F3DEulerToQuat (const CSIBCVector3Dd &in_vct, CSIBCQuaterniond &out_quat)
void | F3DEulerToMat (const CSIBCVector3Dd &in_vct, CSIBCRotMatd &out_mat)
void | F3DMatToEuler (const CSIBCRotMatd &in_mat, CSIBCVector3Dd &out_vct)
void | F3DMatToEulerUsingTarget (const CSIBCRotMatd &in_mat, CSIBCVector3Dd &inout_vct)
void | F3DQuatToAxisAngle (const CSIBCQuaterniond &in_quat, CSIBCVector3Dd &out_vctAxis, double &out_dAngle)
void | F3DAxisAngleToQuat (const CSIBCVector3Dd &in_vctAxis, const double &in_dAngle, CSIBCQuaterniond &out_quat)
double | F3DBoundAngleInMinus2PITo2PI (double in_dDesiredAngle)
void | F3DBoundAngleInZeroToTwoPI (double &in_dAngle)
void | F3DBoundAngleInMinusPIToPI (double &in_dAngle)
double | F3DGetUnboundedAngle (double in_dDesiredAngle, double in_dRefAngle)
void | F3DBoundAnglesInMatrixInMinus2PITo2PI (CSIBCMatrixMNd &io_matMN, int in_nFirstRow, int in_nLastRow)
double | F3DGetClosestAngle (double in_dAngle, double in_dFirstAngle, double in_dSecondAngle)

## Function Documentation

double F3DArcSinCos | ( | double | dSinus,
|  | double | dCosinus |
| ) |  |  |

Returns the angle corresponding to the given sine and cosine values.

Parameters:

  | dSinus | The sine value of the desired angle.
  | dCosinus | The cosine value of the desired angle.

Returns:
  double The angle (in radians) corresponding to the sine and cosine values.

void F3DLimit | ( | double & | io_dVal,
|  | double | in_dMin,
|  | double | in_dMax |
| ) |  |  |

Limits `io_dVal` between `in_dMin` and `in_dMax`.

Parameters:

  | io_dVal | Value to limit, receives the result of the limiting.
  | in_dMin | The minimum value for `io_dVal`.
  | in_dMax | The maximum value for `io_dVal`.

void F3DQuatToMat | ( | const CSIBCQuaterniond & | in_quat,
|  | CSIBCRotMatd & | out_mat |
| ) |  |  |

Converts a quaternion into a rotation matrix.

Parameters:

  | in_quat | Quaternion to convert.
  | out_mat | Rotation matrix to receive the converted quaternion.

void F3DMatToQuat | ( | const CSIBCRotMatd & | in_mat,
|  | CSIBCQuaterniond & | out_quat |
| ) |  |  |

Converts a rotation matrix into a quaternion.

Parameters:

  | in_mat | Rotation matrix to convert.
  | out_quat | Quaternion to receive the converted rotation matrix.

void F3DEulerToQuat | ( | const CSIBCVector3Dd & | in_vct,
|  | CSIBCQuaterniond & | out_quat |
| ) |  |  |

Converts a set of euler angles (pitch-roll-yaw) to a quaternion.

Parameters:

  | in_vct | Vector containing euler angles to convert.
  | out_quat | Quaternion to receive the converted euler angles.

void F3DEulerToMat | ( | const CSIBCVector3Dd & | in_vct,
|  | CSIBCRotMatd & | out_mat |
| ) |  |  |

Converts a set of euler angles (pitch-roll-yaw) to a rotation matrix.

Parameters:

  | in_vct | Vector containing euler angles to convert.
  | out_mat | Rotation matrix to receive the converted euler angles.

void F3DMatToEuler | ( | const CSIBCRotMatd & | in_mat,
|  | CSIBCVector3Dd & | out_vct |
| ) |  |  |

Converts a rotation matrix into a set of euler angles (pitch-roll-yaw).

Parameters:

  | in_mat | Rotation matrix to convert.
  | out_vct | Vector to receive the euler angles for the converted rotation matrix.

void F3DMatToEulerUsingTarget | ( | const CSIBCRotMatd & | in_mat,
|  | CSIBCVector3Dd & | inout_vct |
| ) |  |  |

Converts a rotation matrix into a set of euler angles (pitch-roll-yaw), which are closest to `inout_vct`. This is provided because a single rotation matrix produces an infinite number of possible euler angle representations. The result is stored in `in_outvct`.

Parameters:

  | in_mat | Rotation matrix to convert.
  | inout_vct | Vector containing the euler angles that most closely represent the desired output euler angles. Receives the output of the converted rotation matrix.

void F3DQuatToAxisAngle | ( | const CSIBCQuaterniond & | in_quat,
|  | CSIBCVector3Dd & | out_vctAxis,
|  | double & | out_dAngle |
| ) |  |  |

Converts a quaternion to a angle rotation about an axis.

Parameters:

  | in_quat | Quaternion to convert.
  | out_vctAxis | Vector to receive the rotation axis given by the quaternion.
  | out_dAngle | double to receive the rotation about `out_dAngle` (in radians).

void F3DAxisAngleToQuat | ( | const CSIBCVector3Dd & | in_vctAxis,
|  | const double & | in_dAngle,
|  | CSIBCQuaterniond & | out_quat |
| ) |  |  |

Converts a rotation angle about a given axis to a quaternion.

Parameters:

  | in_vctAxis | Axis of rotation.
  | in_dAngle | Rotation angle (in radians) of rotation about `in_vctAngle`
  | out_quat | Quaternion to receive the converted axis rotation.

double F3DBoundAngleInMinus2PITo2PI | ( | double | in_dDesiredAngle | ) |

Returns an angle corresponding to `in_dDesiredAngle`, in the range [-M_2PI, M_2PI].

Parameters:

  | in_dDesiredAngle | Angle to be bounded.

Returns:
  double Angle corresponding to `in_dDesiredAngle`, bounded between [-M_2PI and M_2PI].

void F3DBoundAngleInZeroToTwoPI | ( | double & | in_dAngle | ) |

Returns an angle corresponding to `in_dAngle`, in the range [0.0f, M_2PI].

Parameters:

  | in_dAngle | Angle to be bounded.

Returns:
  double Angle corresponding to `in_dDesiredAngle`, bounded between [0.0f,M_2PI].

void F3DBoundAngleInMinusPIToPI | ( | double & | in_dAngle | ) |

Returns an angle corresponding to `in_dAngle`, in the range [-M_2PI, M_2PI]

Parameters:

  | in_dAngle | Angle to be bounded.

Returns:
  double Angle corresponding to `in_dDesiredAngle`, bounded between p-M_PI, M_PI].

double F3DGetUnboundedAngle | ( | double | in_dDesiredAngle,
|  | double | in_dRefAngle |
| ) |  |  |

Returns an angle corresponding to `in_dDesiredAngle`, which is as close as possible to `in_dRefAngle`.

Parameters:

  | in_dDesiredAngle | Desired angle, bounded by [-M_PI, M_PI].
  | in_dRefAngle | Reference angle, unbounded.

Returns:
  double The angle corresponding to `in_dDesiredAngle`, which is as close as possible to `in_dRefAngle`

void F3DBoundAnglesInMatrixInMinus2PITo2PI | ( | CSIBCMatrixMNd & | io_matMN,
|  | int | in_nFirstRow,
|  | int | in_nLastRow |
| ) |  |  |

Bounds the angles in the first column of `io_matMN`, beginning at row , and ending at row `in_nLastRow` to angles in the range [-M_2PI, M_2PI].

Parameters:

  | io_matMN | Matrix containing angles in the first column to be bounded.
  | in_nFirstRow | First row of `io_matMN` containing angles to be bound, zero-indexed (if negative, starts at the first row).
  | in_nLastRow | Last row of `io_matMN` containing angles to be bound, zero-indexed (if negative, ends at the last row).

double F3DGetClosestAngle | ( | double | in_dAngle,
|  | double | in_dFirstAngle,
|  | double | in_dSecondAngle |
| ) |  |  |

Determines which angle `in_dAngle` is closest to, `in_dFirstAngle`, or `in_dSecondAngle`. Note that in_dAngle should not be between `in_dFirstAngle` and `in_dSecondAngle` (in counter-clockwise order).

Parameters:

  | in_dAngle | Angle for comparison.
  | in_dFirstAngle | First angle for close-ness comparison.
  | in_dSecondAngle | Second angle for close-ness comparison.

Returns:
  double `in_dFirstAngle` or `in_dSecondAngle`, whichever is closest to `in_dAngle`.