.TH "SbRotation" 3 "Sat Oct 12 2013" "Version 4.0.0a" "Coin" \" -*- nroff -*-
.ad l
.nh
.SH NAME
SbRotation \- 
.PP
The \fBSbRotation\fP class represents a rotation in 3D space\&.
.PP
\fBSbRotation\fP is used extensively throughout the Coin library\&.  

.SH SYNOPSIS
.br
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBSbRotation\fP (void)"
.br
.ti -1c
.RI "\fBSbRotation\fP (const \fBSbVec3f\fP &axis, const float radians)"
.br
.ti -1c
.RI "\fBSbRotation\fP (const float q[4])"
.br
.ti -1c
.RI "\fBSbRotation\fP (const float q0, const float q1, const float q2, const float q3)"
.br
.ti -1c
.RI "\fBSbRotation\fP (const \fBSbMatrix\fP &m)"
.br
.ti -1c
.RI "\fBSbRotation\fP (const \fBSbVec3f\fP &rotateFrom, const \fBSbVec3f\fP &rotateTo)"
.br
.ti -1c
.RI "const float * \fBgetValue\fP (void) const "
.br
.ti -1c
.RI "void \fBgetValue\fP (float &q0, float &q1, float &q2, float &q3) const "
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBsetValue\fP (const float q0, const float q1, const float q2, const float q3)"
.br
.ti -1c
.RI "void \fBgetValue\fP (\fBSbVec3f\fP &axis, float &radians) const "
.br
.ti -1c
.RI "void \fBgetValue\fP (\fBSbMatrix\fP &matrix) const "
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBinvert\fP (void)"
.br
.ti -1c
.RI "\fBSbRotation\fP \fBinverse\fP (void) const "
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBsetValue\fP (const float q[4])"
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBsetValue\fP (const \fBSbMatrix\fP &m)"
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBsetValue\fP (const \fBSbVec3f\fP &axis, const float radians)"
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBsetValue\fP (const \fBSbVec3f\fP &rotateFrom, const \fBSbVec3f\fP &rotateTo)"
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBoperator*=\fP (const \fBSbRotation\fP &q)"
.br
.ti -1c
.RI "\fBSbRotation\fP & \fBoperator*=\fP (const float s)"
.br
.ti -1c
.RI "float \fBoperator[]\fP (size_t n) const "
.br
.RI "\fIreturns the n'th quaternion of this rotation \fP"
.ti -1c
.RI "SbBool \fBequals\fP (const \fBSbRotation\fP &r, float tolerance) const "
.br
.ti -1c
.RI "void \fBmultVec\fP (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const "
.br
.ti -1c
.RI "void \fBscaleAngle\fP (const float scaleFactor)"
.br
.ti -1c
.RI "\fBSbString\fP \fBtoString\fP () const "
.br
.ti -1c
.RI "SbBool \fBfromString\fP (const \fBSbString\fP &str)"
.br
.ti -1c
.RI "void \fBprint\fP (FILE *fp) const "
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static \fBSbRotation\fP \fBslerp\fP (const \fBSbRotation\fP &rot0, const \fBSbRotation\fP &rot1, float t)"
.br
.ti -1c
.RI "static \fBSbRotation\fP \fBidentity\fP (void)"
.br
.in -1c
.SS "Friends"

.in +1c
.ti -1c
.RI "int \fBoperator==\fP (const \fBSbRotation\fP &q1, const \fBSbRotation\fP &q2)"
.br
.ti -1c
.RI "int \fBoperator!=\fP (const \fBSbRotation\fP &q1, const \fBSbRotation\fP &q2)"
.br
.ti -1c
.RI "\fBSbRotation\fP \fBoperator*\fP (const \fBSbRotation\fP &q1, const \fBSbRotation\fP &q2)"
.br
.in -1c
.SH "Detailed Description"
.PP 
The \fBSbRotation\fP class represents a rotation in 3D space\&.
.PP
\fBSbRotation\fP is used extensively throughout the Coin library\&. 

An \fBSbRotation\fP is stored internally as a quaternion for speed and storage reasons, but inquiries can be done to get and set axis and angle values for convenience\&.
.PP
Note that there is one \fIvery\fP common mistake that is easy to make when setting the value of an \fBSbRotation\fP, and that is to inadvertently use the wrong \fBSbRotation\fP constructor\&. This example should clarify the problem:
.PP
.PP
.nf
SbRotation rotation(0, 0, 1, 1\&.5707963f);
.fi
.PP
.PP
The programmer clearly tries to set a PI/2 rotation around the Z axis, but this will fail, as the \fBSbRotation\fP constructor invoked above is the one that takes as arguments the 4 floats of a \fIquaternion\fP\&. What the programmer almost certainly wanted to do was to use the \fBSbRotation\fP constructor that takes a rotation vector and a rotation angle, which is invoked like this:
.PP
.PP
.nf
SbRotation rotation(SbVec3f(0, 0, 1), 1\&.5707963f);
.fi
.PP
.PP
Another common problem is to set the rotation value to exactly 0\&.0, while wanting to store just the information about a rotation \fIangle:\fP rotations are internally handled as quaternions, and when converting from an angle and a rotation value to a quaternion representation, the information about the angle 'gets lost' if there is no actual rotation\&.
.PP
\fBSee Also:\fP
.RS 4
\fBSbMatrix\fP 
.RE
.PP

.SH "Constructor & Destructor Documentation"
.PP 
.SS "SbRotation::SbRotation (void)"
The default constructor just initializes a valid rotation\&. The actual value is unspecified, and you should not depend on it\&. 
.SS "SbRotation::SbRotation (const \fBSbVec3f\fP &axis, const floatradians)"
Construct a new \fBSbRotation\fP object initialized with the given axis-of-rotation and rotation angle\&. 
.SS "SbRotation::SbRotation (const floatq[4])"
Construct a new \fBSbRotation\fP object initialized with the given quaternion components\&.
.PP
The array must be ordered as follows:
.PP
q[0] = x, q[1] = y, q[2] = z and q[3] = w, where the quaternion is specified by q=w+xi+yj+zk\&. 
.SS "SbRotation::SbRotation (const floatq0, const floatq1, const floatq2, const floatq3)"
Construct a new \fBSbRotation\fP object initialized with the given quaternion components\&. 
.SS "SbRotation::SbRotation (const \fBSbMatrix\fP &m)"
Construct a new \fBSbRotation\fP object initialized with the given rotation matrix\&. 
.SS "SbRotation::SbRotation (const \fBSbVec3f\fP &rotateFrom, const \fBSbVec3f\fP &rotateTo)"
Construct a rotation which is the minimum rotation necessary to make vector \fIrotateFrom\fP point in the direction of vector \fIrotateTo\fP\&.
.PP
Example:
.PP
.PP
.nf
#include <Inventor/SbRotation\&.h>
#include <Inventor/SbVec3f\&.h>
#include <cstdio>

int
main(void)
{
  SbVec3f from(10, 0, 0);
  SbVec3f to(0, 10, 0);

  SbRotation rot(from, to);

  SbVec3f axis;
  float angle;
  rot\&.getValue(axis, angle);
  axis\&.print(stdout);
  printf('  angle==%f\n', angle);

  return 0;
}
.fi
.PP
 
.SH "Member Function Documentation"
.PP 
.SS "const float * SbRotation::getValue (void) const"
Return pointer to an array with the rotation expressed as four quaternion values\&.
.PP
\fBSee Also:\fP
.RS 4
\fBsetValue()\fP\&. 
.RE
.PP

.SS "void SbRotation::getValue (float &q0, float &q1, float &q2, float &q3) const"
Return the four quaternion components representing the rotation\&.
.PP
\fBSee Also:\fP
.RS 4
\fBsetValue()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::setValue (const floatq0, const floatq1, const floatq2, const floatq3)"
Set the rotation\&.
.PP
\fBSee Also:\fP
.RS 4
\fBgetValue()\fP\&. 
.RE
.PP

.SS "void SbRotation::getValue (\fBSbVec3f\fP &axis, float &radians) const"
Return the rotation in the form of an axis-of-rotation and a rotation angle\&.
.PP
\fBSee Also:\fP
.RS 4
\fBsetValue()\fP\&. 
.RE
.PP

.SS "void SbRotation::getValue (\fBSbMatrix\fP &matrix) const"
Return this rotation in the form of a matrix\&.
.PP
\fBSee Also:\fP
.RS 4
\fBsetValue()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::invert (void)"
Invert the rotation\&. Returns reference to self\&.
.PP
\fBSee Also:\fP
.RS 4
\fBinverse()\fP 
.RE
.PP

.SS "\fBSbRotation\fP SbRotation::inverse (void) const"
Non-destructively inverses the rotation and returns the result\&.
.PP
\fBSee Also:\fP
.RS 4
\fBinvert()\fP 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::setValue (const floatq[4])"
Reset the rotation by the four quaternions in the array\&.
.PP
\fBSee Also:\fP
.RS 4
\fBgetValue()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::setValue (const \fBSbMatrix\fP &m)"
Set the rotation from the components of the given matrix\&. Returns reference to self\&.
.PP
\fBSee Also:\fP
.RS 4
\fBgetValue()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::setValue (const \fBSbVec3f\fP &axis, const floatradians)"
Reset rotation with the given axis-of-rotation and rotation angle\&. Returns reference to self\&.
.PP
Make sure \fIaxis\fP is not the null vector when calling this method\&.
.PP
\fBSee Also:\fP
.RS 4
\fBgetValue()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::setValue (const \fBSbVec3f\fP &rotateFrom, const \fBSbVec3f\fP &rotateTo)"
Construct a rotation which is the minimum rotation necessary to make vector \fIrotateFrom\fP point in the direction of vector \fIrotateTo\fP\&.
.PP
Returns reference to self\&.
.PP
See \fBSbRotation\fP constructor with corresponding input arguments for a simple code example\&.
.PP
\fBSee Also:\fP
.RS 4
\fBgetValue()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP & SbRotation::operator*= (const \fBSbRotation\fP &q)"
Multiplies the quaternions\&.
.PP
Note that order is important when combining quaternions with the multiplication operator\&. 
.SS "\fBSbRotation\fP & SbRotation::operator*= (const floats)"
Multiplies components of quaternion with scalar value \fIs\fP\&. Returns reference to self\&. 
.SS "SbBool SbRotation::equals (const \fBSbRotation\fP &r, floattolerance) const"
Check the internal quaternion representation vectors for equality within the given tolerance\&. 
.SS "void SbRotation::multVec (const \fBSbVec3f\fP &src, \fBSbVec3f\fP &dst) const"
Rotate the \fIsrc\fP vector and put the result in \fIdst\fP\&.
.PP
It is safe to let src and dst be the same \fBSbVec3f\fP instance\&. 
.SS "void SbRotation::scaleAngle (const floatscaleFactor)"
Scale the angle of rotation by \fIscaleFactor\fP\&. 
.SS "\fBSbRotation\fP slerp (const \fBSbRotation\fP &rot0, const \fBSbRotation\fP &rot1, floatt)\fC [static]\fP"
Interpolates along the shortest path between the two rotation positions (from \fIrot0\fP to \fIrot1\fP)\&.
.PP
Returns the \fBSbRotation\fP which will rotate \fIrot0\fP the given part \fIt\fP of the spherical distance towards \fIrot1\fP, where \fIt=0\fP will yield \fIrot0\fP and \fIt=1\fP will yield \fIrot1\fP\&.
.PP
\fIt\fP should be in the interval [0, 1]\&. 
.SS "\fBSbRotation\fP SbRotation::identity (void)\fC [static]\fP"
Returns an identity rotation\&. 
.SS "\fBSbString\fP SbRotation::toString () const"
Return a string representation of this object 
.SS "SbBool SbRotation::fromString (const \fBSbString\fP &str)"
Convert from a string representation, return wether this is a valid conversion 
.SS "void SbRotation::print (FILE *fp) const"
Dump the state of this object to the \fIfp\fP file stream\&. Only works in debug version of library, method does nothing in an optimized compile\&. 
.SH "Friends And Related Function Documentation"
.PP 
.SS "int operator== (const \fBSbRotation\fP &q1, const \fBSbRotation\fP &q2)\fC [friend]\fP"
Check if the two rotations are equal\&.
.PP
\fBSee Also:\fP
.RS 4
\fBequals()\fP\&. 
.RE
.PP

.SS "int operator!= (const \fBSbRotation\fP &q1, const \fBSbRotation\fP &q2)\fC [friend]\fP"
Check if the two rotations are unequal\&.
.PP
\fBSee Also:\fP
.RS 4
\fBequals()\fP\&. 
.RE
.PP

.SS "\fBSbRotation\fP operator* (const \fBSbRotation\fP &q1, const \fBSbRotation\fP &q2)\fC [friend]\fP"
Multiplies the two rotations and returns the result\&.
.PP
Note that order is important when combining quaternions with the multiplication operator\&. 

.SH "Author"
.PP 
Generated automatically by Doxygen for Coin from the source code\&.