Actin®  Version 5.3.0
Software for Robotics Simulation and Control
EcOrientation Class Reference

Description of a 3D rotation. More...

#include <ecOrientation.h>

Collaboration diagram for EcOrientation:
[legend]

Public Member Functions

 EcOrientation ()
 constructor
 
 EcOrientation (EcReal w, EcReal x, EcReal y, EcReal z)
 constructor from four reals: w, x, y, and z
 
EcBoolean operator== (const EcOrientation &orig) const
 equality operator
 
EcOrientationclone () const
 clone - a constructor. This allocates memory for the new object.
 
EcOrientationoperator*= (const EcOrientation &orient2)
 transforms this orientation by another on the right More...
 
EcOrientation operator* (const EcOrientation &orient2) const
 returns a transformation equal to this transformed on the right by another More...
 
EcVector operator* (const EcVector &vec) const
 transforms a vector and return the result More...
 
void dor (const EcOrientation &orient, EcRealVector &dr)
 differential orthogonal rotation between two orientations More...
 
void transform (EcVector &inout) const
 transforms a vector in place. More...
 
void transform (const EcVector &from, EcVector &to) const
 
void transform (const EcVector &firstFrom, EcVector &firstTo, const EcVector &secondFrom, EcVector &secondTo) const
 
void alignZ (const EcVector &desiredUnitZ, EcOrientation &alignmentRotation) const
 Align the z-axis to the desired z-axis (free-spin-in-z). More...
 
EcBoolean approxEq (const EcOrientation &orient2, EcReal tol=EcTOLERANCE) const
 tests for approximate equality of orientations (note: not of quaterions, which may be +/-) More...
 
EcBoolean angleAxisBetween (const EcOrientation &q2, EcReal &theta, EcVector &axisOut) const
 finds the angle and axis between two quaternions. More...
 
void interpolation (const EcOrientation &orient1, const EcOrientation &orient2, const EcReal &factor)
 
EcOrientation inverse () const
 gets the inverse of the orientation More...
 
EcOrientationinvert ()
 inverts this in place More...
 
const EcRealw () const
 gets the first quaternion value
 
const EcRealx () const
 gets the second quaternion value
 
const EcRealy () const
 gets the third quaternion value
 
const EcRealz () const
 gets the fourth quaternion value
 
void set (const EcReal &w, const EcReal &x, const EcReal &y, const EcReal &z)
 sets a quaternion value directly
 
void set (const EcRealVector &vec)
 sets a quaternion value from an array More...
 
void setFrom321Euler (EcReal psi, EcReal theta, EcReal phi)
 Sets from yaw, pitch, roll Euler angles. More...
 
void get321Euler (EcReal &psi, EcReal &theta, EcReal &phi) const
 Gets yaw, pitch, roll Euler angles. More...
 
void setFrom123Euler (EcReal phi, EcReal theta, EcReal psi)
 Sets from roll, pitch, yaw Euler angles. More...
 
void get123Euler (EcReal &phi, EcReal &theta, EcReal &psi) const
 Gets roll, pitch, yaw Euler angles. More...
 
void setFrom231Euler (EcReal theta, EcReal psi, EcReal phi)
 sets from pitch, yaw, roll Euler angles More...
 
void setFromAngleAxis (EcReal angle, const EcVector &axis)
 
void getAngleAxis (EcReal &angle, EcVector &axisOut) const
 gets the angle and axis for an orientation More...
 
void setFromRodriguesVector (const EcVector &vector)
 
void getRodriguesVector (EcVector &vectorOut)
 
const EcRealoperator[] (EcSizeT index) const
 gets any quaternion element by index More...
 
void getDcmRows (EcVector &row0, EcVector &row1, EcVector &row2) const
 
void setFromDcmRows (const EcVector &row0, const EcVector &row1, const EcVector &row2)
 sets the orientation from DCM rows More...
 
void getDcmColumns (EcVector &col0, EcVector &col1, EcVector &col2) const
 
void setFromDcmColumns (const EcVector &col0, const EcVector &col1, const EcVector &col2)
 sets the orientation from DCM columns More...
 
void integrateLocalFrameAngularVelocity (const EcVector &angularVelocity, EcReal time)
 
void integrateReferenceFrameAngularVelocity (const EcVector &angularVelocity, EcReal time)
 
void quaternionRateFromLocalFrameAngularVelocity (const EcVector &angularVelocity, EcRealVector &vQuaternionRateOut) const
 calculate quaternion rate from angular velocity. More...
 
void quaternionRateFromReferenceFrameAngularVelocity (const EcVector &angularVelocity, EcRealVector &vQuaternionRateOut) const
 calculate quaternion rate from angular velocity. More...
 
void quaternionAccelerationFromLocalFrameAngularMotion (const EcVector &angularVelocity, const EcVector &angularAcceleration, EcRealVector &vQuaternionAcceleration) const
 calculate quaternion acceleration from angular velocity and acceleration expressed in the moving coordinate system. More...
 
void quaternionAccelerationFromReferenceFrameAngularMotion (const EcVector &angularVelocity, const EcVector &angularAcceleration, EcRealVector &vQuaternionAcceleration) const
 calculate quaternion acceleration from angular velocity and acceleration expressed in the reference coordinate system. More...
 
void localFrameAngularVelocityFromQuaternionRate (const EcRealVector &vQuaternionRate, EcVector &angularVelocityOut) const
 
void referenceFrameAngularVelocityFromQuaternionRate (const EcRealVector &vQuaternionRate, EcVector &angularVelocityOut) const
 
EcVector xAxis () const
 gets the outboard x-axis (the first column of the DCM matrix)
 
EcVector yAxis () const
 gets the outboard y-axis (the second column of the DCM matrix)
 
EcVector zAxis () const
 gets the outboard z-axis (the third column of the DCM matrix)
 

Static Public Member Functions

static const EcOrientationidentity ()
 gets an identity orientation
 
static EcOrientation wQuaternion ()
 returns a w quaternion (i.e., [1,0,0,0])
 
static EcOrientation xQuaternion ()
 returns a x quaternion (i.e., [0,1,0,0])
 
static EcOrientation yQuaternion ()
 returns a y quaternion (i.e., [0,0,1,0])
 
static EcOrientation zQuaternion ()
 returns a z quaternion (i.e., [0,0,0,1])
 
static EcOrientation xRotation (EcReal angle)
 returns an x rotation (i.e., a rotation by angle about the 3D x-axis)
 
static EcOrientation yRotation (EcReal angle)
 returns a y rotation (i.e., a rotation by angle about the 3D y-axis)
 
static EcOrientation zRotation (EcReal angle)
 returns a z rotation (i.e., a rotation by angle about the 3D z-axis)
 
static EcOrientation from321Euler (EcReal psi, EcReal theta, EcReal phi)
 constructs from yaw, pitch, roll Euler angles More...
 
static EcOrientation from123Euler (EcReal phi, EcReal theta, EcReal psi)
 constructs from roll, pitch, yaw Euler angles More...
 
static EcOrientation from231Euler (EcReal theta, EcReal psi, EcReal phi)
 constructs from pitch, yaw, roll Euler angles More...
 
static EcOrientation fromAngleAxis (EcReal angle, const EcVector &axis)
 
static EcBoolean averageAndStdev (const std::vector< EcOrientation > &qVec, EcOrientation &qAvg, EcReal &stdev)
 calculate approximated average and standard deviation of very close quaternions More...
 

Protected Member Functions

EcReal magSquared () const
 takes the magnitude of the internal representation
 
void normalize ()
 normalizes the internal representation
 

Protected Attributes

EcReal m_Quaternion [4]
 the internal representation of the quaternion
 

Static Protected Attributes

static const EcOrientation m_theIdentity
 an identity rotation that can be returned by const reference
 

Detailed Description

Description of a 3D rotation.

It stores the data as a quaternion but provides utility functions for working with DCM matrices and Euler angles. The quaternion representation is that for which (1,0,0,0) corresponds to no rotation.

Examples:
controlExecutiveModifierExampleMain.cpp, ecCameraViewMain.cpp, ecCirclePathExampleDirection.cpp, ecPathFollowingMain.cpp, ecPathPlanningCoreMain.cpp, ecPathPlanningMain.cpp, ecPositionControlMain.cpp, ecQuickStartKinematicsMain.cpp, ecQuickStartMain.cpp, ecRemoteCommandExampleMain.cpp, ecStatedSystemMain.cpp, and ecXmlMain.cpp.

Definition at line 25 of file ecOrientation.h.

Member Function Documentation

void EcOrientation::alignZ ( const EcVector desiredUnitZ,
EcOrientation alignmentRotation 
) const

Align the z-axis to the desired z-axis (free-spin-in-z).

After the alignment, the z-axis of this orientation will be aligned to the desired z-axis. When the two z-axes are in the opposite direction (|thisZ dot desiredZ + 1| < EcNANO), the problem becomes singular. In this case, the rotation will be a pure x or y rotation depending on if the desired z is "more" perpendicular to x or y.

Parameters
[in]desiredUnitZthe desired unit z-axis in the same reference frame as this.
[out]alignmentRotationthe alignment rotation transformation R such that: R * thisZ = desiredZ
EcBoolean EcOrientation::angleAxisBetween ( const EcOrientation q2,
EcReal theta,
EcVector axisOut 
) const

finds the angle and axis between two quaternions.

Finds the angle and axis between this orientation and another.

Parameters
[in]q2The other orientation.
[out]thetaUpon return, the angle in radians between the two orientation.
[out]axisOutUpon return, the axis between the two orientation.
EcBoolean EcOrientation::approxEq ( const EcOrientation orient2,
EcReal  tol = EcTOLERANCE 
) const

tests for approximate equality of orientations (note: not of quaterions, which may be +/-)

Parameters
[in]orient2This is the EcOrientation to be compared with this.
[in]tolThis is the numerical tolerance used in quaternion space. The difference two norm is compared.
static EcBoolean EcOrientation::averageAndStdev ( const std::vector< EcOrientation > &  qVec,
EcOrientation qAvg,
EcReal stdev 
)
static

calculate approximated average and standard deviation of very close quaternions

Parameters
[in]qVecA vector of orientations
[out]qAvgApproximated average of the orientations
[out]stdevstandard devation of the orientations
void EcOrientation::dor ( const EcOrientation orient,
EcRealVector dr 
)

differential orthogonal rotation between two orientations

This function is used to obtain the differential orthogonal rotation between two rotation matrices. It is used in the system identification toolbox

Parameters
[in]orientAn EcOrientation with respect to which the orientation difference is calculated
[out]drA 3x1 vector representing the differential orthogonal rotation.
static EcOrientation EcOrientation::from123Euler ( EcReal  phi,
EcReal  theta,
EcReal  psi 
)
static

constructs from roll, pitch, yaw Euler angles

Parameters
[in]phiRoll about x-axis.
[in]thetaPitch about y-axis.
[in]psiYaw about z-axis.
static EcOrientation EcOrientation::from231Euler ( EcReal  theta,
EcReal  psi,
EcReal  phi 
)
static

constructs from pitch, yaw, roll Euler angles

Parameters
[in]thetaPitch about y-axis.
[in]psiYaw about z-axis.
[in]phiRoll about x-axis.
static EcOrientation EcOrientation::from321Euler ( EcReal  psi,
EcReal  theta,
EcReal  phi 
)
static

constructs from yaw, pitch, roll Euler angles

Parameters
[out]psiYaw about z-axis.
[out]thetaPitch about y-axis.
[out]phiRoll about x-axis.
static EcOrientation EcOrientation::fromAngleAxis ( EcReal  angle,
const EcVector axis 
)
static

constructs the rotation based on an angle and an axis. The axis must be normalized before calling this function.

Parameters
[in]angleThe outboard frame is rotated this much about the axis.
[in]axisThe unit-vector axis of rotation.
void EcOrientation::get123Euler ( EcReal phi,
EcReal theta,
EcReal psi 
) const

Gets roll, pitch, yaw Euler angles.

See also
setFrom123Euler
Parameters
[in]phiRoll about x-axis.
[in]thetaPitch about y-axis.
[in]psiYaw about z-axis.
Examples:
ecPathFollowingMain.cpp, and ecQuickStartKinematicsMain.cpp.
void EcOrientation::get321Euler ( EcReal psi,
EcReal theta,
EcReal phi 
) const

Gets yaw, pitch, roll Euler angles.

See also
setFrom321Euler
Parameters
[in]psiYaw about z-axis.
[in]thetaPitch about y-axis.
[in]phiRoll about x-axis.
void EcOrientation::getAngleAxis ( EcReal angle,
EcVector axisOut 
) const

gets the angle and axis for an orientation

Parameters
[out]angleThe outboard frame is rotated this much about the axis.
[out]axisOutThe unit-vector axis of rotation.
void EcOrientation::getDcmColumns ( EcVector col0,
EcVector col1,
EcVector col2 
) const

gets the columns of a DCM matrix corresponding to the orientation. These are unit norm and orthogonal. col0 x col1 = col2.

Parameters
[out]col0The first column of the DCM representation of the rotation.
[out]col1The second column of the DCM representation of the rotation.
[out]col2The third column of the DCM representation of the rotation.
void EcOrientation::getDcmRows ( EcVector row0,
EcVector row1,
EcVector row2 
) const

gets the rows of a DCM matrix corresponding to the orientation. These are unit norm and orthogonal. row0 x row1 = row2.

Parameters
[out]row0The first row of the DCM representation of the rotation.
[out]row1The second row of the DCM representation of the rotation.
[out]row2The third row of the DCM representation of the rotation.
void EcOrientation::getRodriguesVector ( EcVector vectorOut)

gets the Rodrigues vector (also called Gibbs vector) p = k tan(theta/2), for axis k and angle theta returns an approximation when theta=Pi.

Parameters
[out]vectorOutThe Rodrigues vector.
void EcOrientation::integrateLocalFrameAngularVelocity ( const EcVector angularVelocity,
EcReal  time 
)

integrates an angular velocity. The angular velocity is expressed in the moving coordinate system. Integrates an angular velocity and then sets the result as this orientation.

Parameters
[in]angularVelocityThe angular velocity in rad/s in the moving coordinate system.
[in]timeThe time to integrate.
void EcOrientation::integrateReferenceFrameAngularVelocity ( const EcVector angularVelocity,
EcReal  time 
)

integrates an angular velocity. The angular velocity is expressed in the reference (nonmoving) coordinate system. Integrates an angular velocity and then sets the result as this orientation.

Parameters
[in]angularVelocityThe angular velocity in rad/s in the reference coordinate system.
[in]timeThe time to integrate.
void EcOrientation::interpolation ( const EcOrientation orient1,
const EcOrientation orient2,
const EcReal factor 
)

Finds hyperspherical surface interpolation between the two quaternions. Can be called on an object with self as the first argument (orient1) Finds hyperspherical surface interpolation between the two quaternions and sets the result in this orientation.

Parameters
[in]orient1The first orientation. Can be itself.
[in]orient2The second orientation.
[in]factorA real number between 0 and 1 will from orient1 to orient2. A number outside of 0 and 1 will extrapolate the two quaternions.
EcOrientation EcOrientation::inverse ( ) const

gets the inverse of the orientation

Returns
The inverse of this orientation.
EcOrientation& EcOrientation::invert ( )

inverts this in place

Returns
This orientation after inversion.
void EcOrientation::localFrameAngularVelocityFromQuaternionRate ( const EcRealVector vQuaternionRate,
EcVector angularVelocityOut 
) const

calculate angular velocity from quaternion rate. The angular velocity is expressed in the moving coordinate system.

Parameters
[in]vQuaternionRateA vector representing the quaternion rate. Must be of size 4.
[out]angularVelocityOutUpon return, an EcVector object containing the angular velocity in rad/s in the moving coordinate frame.
EcOrientation EcOrientation::operator* ( const EcOrientation orient2) const

returns a transformation equal to this transformed on the right by another

Parameters
[in]orient2The orientation used in transformation with this orientation.
Returns
An orientation = this * orient2.
EcVector EcOrientation::operator* ( const EcVector vec) const

transforms a vector and return the result

Parameters
[in]vecA vector used in transformation.
Returns
The transformed vector.
EcOrientation& EcOrientation::operator*= ( const EcOrientation orient2)

transforms this orientation by another on the right

Transforms this orientation by another as in this = this * orient2.

Parameters
[in]orient2The orientation used to transform this orientation.
Returns
This EcOrientation object after transformation.
const EcReal& EcOrientation::operator[] ( EcSizeT  index) const

gets any quaternion element by index

Parameters
[in]index{0=w, 1=x, 2=y, 3=z}
void EcOrientation::quaternionAccelerationFromLocalFrameAngularMotion ( const EcVector angularVelocity,
const EcVector angularAcceleration,
EcRealVector vQuaternionAcceleration 
) const

calculate quaternion acceleration from angular velocity and acceleration expressed in the moving coordinate system.

Parameters
[in]angularVelocityThe angular velocity in rad/s in the moving coordinate system.
[in]angularAccelerationThe angular acceleration in rad/s in the moving coordinate system.
[out]vQuaternionAccelerationUpon return, the vector of size 4 containing the quaternion acceleration
void EcOrientation::quaternionAccelerationFromReferenceFrameAngularMotion ( const EcVector angularVelocity,
const EcVector angularAcceleration,
EcRealVector vQuaternionAcceleration 
) const

calculate quaternion acceleration from angular velocity and acceleration expressed in the reference coordinate system.

Parameters
[in]angularVelocityThe angular velocity in rad/s in the reference coordinate system.
[in]angularAccelerationThe angular acceleration in rad/s in the reference coordinate system.
[out]vQuaternionAccelerationUpon return, the vector of size 4 containing the quaternion acceleration
void EcOrientation::quaternionRateFromLocalFrameAngularVelocity ( const EcVector angularVelocity,
EcRealVector vQuaternionRateOut 
) const

calculate quaternion rate from angular velocity.

Parameters
[in]angularVelocityThe angular velocity in rad/s in the moving coordinate system.
[out]vQuaternionRateOutUpon return, the vector of size 4 containing the quaternion rate
void EcOrientation::quaternionRateFromReferenceFrameAngularVelocity ( const EcVector angularVelocity,
EcRealVector vQuaternionRateOut 
) const

calculate quaternion rate from angular velocity.

Parameters
[in]angularVelocityThe angular velocity in rad/s in the reference coordinate system.
[out]vQuaternionRateOutUpon return, the vector of size 4 containing the quaternion rate
void EcOrientation::referenceFrameAngularVelocityFromQuaternionRate ( const EcRealVector vQuaternionRate,
EcVector angularVelocityOut 
) const

calculate angular velocity from quaternion rate. The angular velocity is expressed in the stationary reference coordinate system.

Parameters
[in]vQuaternionRateA vector representing the quaternion rate. Must be of size 4.
[out]angularVelocityOutUpon return, an EcVector object containing the angular velocity in rad/s in the reference coordinate frame.
void EcOrientation::set ( const EcRealVector vec)

sets a quaternion value from an array

Parameters
[in]vecA vector of four values mapped to quaterion w, x, y, and z.
void EcOrientation::setFrom123Euler ( EcReal  phi,
EcReal  theta,
EcReal  psi 
)

Sets from roll, pitch, yaw Euler angles.

The resulting rotation = R_{x,phi} * R_{y,theta} * R_{z,psi}

Parameters
[in]phiRoll about x-axis.
[in]thetaPitch about y-axis.
[in]psiYaw about z-axis.
Examples:
controlExecutiveModifierExampleMain.cpp, ecPathPlanningCoreMain.cpp, ecPathPlanningMain.cpp, and ecQuickStartKinematicsMain.cpp.
void EcOrientation::setFrom231Euler ( EcReal  theta,
EcReal  psi,
EcReal  phi 
)

sets from pitch, yaw, roll Euler angles

Parameters
[in]thetaPitch about y-axis.
[in]psiYaw about z-axis.
[in]phiRoll about x-axis.
void EcOrientation::setFrom321Euler ( EcReal  psi,
EcReal  theta,
EcReal  phi 
)

Sets from yaw, pitch, roll Euler angles.

The resulting rotation = R_{z,psi} * R_{y,theta} * R_{x,phi}

Parameters
[in]psiYaw about z-axis.
[in]thetaPitch about y-axis.
[in]phiRoll about x-axis.
Examples:
ecCameraViewMain.cpp, and ecRemoteCommandExampleMain.cpp.
void EcOrientation::setFromAngleAxis ( EcReal  angle,
const EcVector axis 
)

sets the rotation based on an angle and an axis. The axis must be normalized before calling this function.

Parameters
[in]angleThe outboard frame is rotated this much about the axis.
[in]axisThe unit-vector axis of rotation.
void EcOrientation::setFromDcmColumns ( const EcVector col0,
const EcVector col1,
const EcVector col2 
)

sets the orientation from DCM columns

Parameters
[out]col0The first column of the DCM representation of the rotation.
[out]col1The second column of the DCM representation of the rotation.
[out]col2The third column of the DCM representation of the rotation.
void EcOrientation::setFromDcmRows ( const EcVector row0,
const EcVector row1,
const EcVector row2 
)

sets the orientation from DCM rows

Parameters
[in]row0The first row of the DCM representation of the rotation.
[in]row1The second row of the DCM representation of the rotation.
[in]row2The third row of the DCM representation of the rotation.
void EcOrientation::setFromRodriguesVector ( const EcVector vector)

sets the rotation from a Rodrigues vector (also called Gibbs vector) p = k tan(theta/2), for axis k and angle theta

Parameters
[in]vectorThe Rodrigues vector.
void EcOrientation::transform ( EcVector inout) const

transforms a vector in place.

Parameters
[in,out]inoutA vector to be transformed.
void EcOrientation::transform ( const EcVector from,
EcVector to 
) const

transforms a vector and puts the result in the second argument The same vector may be used for to and from.

Parameters
[in]fromA vector used in transformation.
[out]toThe result of the transformation.
void EcOrientation::transform ( const EcVector firstFrom,
EcVector firstTo,
const EcVector secondFrom,
EcVector secondTo 
) const

transforms two vectors - more efficient than transforming individually The same vector object may be used for both to and from to transform in place.

Parameters
[in]firstFromThis is the first vector to be transformed.
[out]firstToThis is the transformation of firstFrom.
[in]secondFromThis is the second vector to be transformed.
[out]secondToThis is the transformation of secondFrom.

The documentation for this class was generated from the following file:
Created by Energid Technologies www.energid.com
Copyright © 2016 Energid. All trademarks mentioned in this document are property of their respective owners.