Frame Class Reference

A frame in 3D space (position and orientation), with possible displacement constraints. More...

#include <frame.h>

Inherited by SpinningFrame.

List of all members.

World Coordinate position and orientation

Methods to set and restore the frame position and orientation (with respect to the world coordinate system).

position is the absolute position of the origin of the frame, and orientation then defines its orientation (as a rotation around the new translated frame origin).

Use translation() and rotation() to get the local (defined with respect to the referenceFrame()) frame characteristics.

 Frame (const Vec &pos, const Quaternion &orien)
void setPosition (const Vec &t)
void setPosition (const float x, const float y, const float z)
void setPositionWithConstraint (Vec &t)
void setOrientation (const float x, const float y, const float z, const float a)
void setOrientation (const Quaternion &q)
void setOrientationWithConstraint (Quaternion &q)
void setOrientationAxisAngle (const float x, const float y, const float z, const float a)
void setPositionAndOrientation (const Vec &t, const Quaternion &q)
void setPositionAndOrientationWithConstraint (Vec &t, Quaternion &q)
Vec position () const
void getPosition (float &x, float &y, float &z) const
Quaternion orientation () const
void getOrientation (float &q0, float &q1, float &q2, float &q3) const

Composition of frames

A frame is defined with respect to a given coordinate system. Default is the world coordinate system, corresponding to a NULL referenceFrame().

Setting the reference frame to non NULL will define the frame with respect to this reference frame. Hierarchical frame structures can then be represented in a tree, whose root would be the world coordinate system (NULL).

const FramereferenceFrame () const
void setReferenceFrame (const Frame *const fr)
bool settingAsReferenceFrameWillCreateALoop (const Frame *const fr)

Local frame translation and rotation

Methods to set and get the frame translation and rotation (defined with respect to the reference frame).

A frame is defined by its translation with respect to its reference frame, and then by a rotation of the coordinate system around the new translated origin. These values (translation and then rotation) are hence defined with respect to the local reference frame. Use position() and orientation() to get the world coordinates of the frame.

void setTranslation (const float x, const float y, const float z)
void setTranslation (const Vec &t)
void setTranslationWithConstraint (Vec &t)
void setRotation (const float x, const float y, const float z, const float a)
void setRotation (const Quaternion &q)
void setRotationWithConstraint (Quaternion &q)
void setRotationAxisAngle (const float x, const float y, const float z, const float a)
void setTranslationAndRotation (const Vec &t, const Quaternion &q)
void setTranslationAndRotationWithConstraint (Vec &t, Quaternion &q)
void getTranslation (float &x, float &y, float &z) const
Vec translation () const
void getRotation (float &x, float &y, float &z, float &a) const
Quaternion rotation () const

Displacement of frames

These methods translate/rotate the Frame. The associated constraint (if defined) is satisfied. The modified() signal is emitted.

void translate (Vec &t)
void translate (const Vec &t)
void translate (float t[3])
void translate (float &x, float &y, float &z)
void translate (const float x, const float y, const float z)
void rotate (Quaternion &q)
void rotate (const Quaternion &q)
void rotate (float q[4])
void rotate (float &x, float &y, float &z, float &a)
void rotate (const float x, const float y, const float z, const float a)
void rotateAroundPoint (Quaternion &q, const Vec &p)
void rotateAroundPoint (const Quaternion &q, const Vec &p)

Coordinate system transformation of 3D points

A frame is as a new coordinate system, defined with respect to a reference frame (the world coordinate system by default, see the "Composition of frame" section).

The coordinatesOf() (resp. inverseCoordinatesOf()) functions transform a 3D point from (resp. to) the world coordinates system. This section defines the 3D point transformation functions. See the Coordinate system transformation of vectors below for the transformation of 3D vectors. The difference between the two sets of functions is simple : for vectors, only the rotational part of the transformations is taken into account, while translation is also considered for 3D points.

When local is prepended to the names of the functions, the functions simply transform from (and to) the reference frame.

When In (resp. From) is appended to the names, the functions transform from (resp. To) the frame that is given as an argument. The frame does not need to be in the same branch or the hierarchical tree, and can be NULL (the world coordinates system).

Combining any of these functions with its inverse (in any order) leads to the identity.

See the frameTransform example for an illustration of some these functions.

Vec coordinatesOf (const Vec &src) const
Vec inverseCoordinatesOf (const Vec &src) const
Vec localCoordinatesOf (const Vec &src) const
Vec localInverseCoordinatesOf (const Vec &src) const
Vec coordinatesOfIn (const Vec &src, const Frame *in) const
Vec coordinatesOfFrom (const Vec &src, const Frame *from) const
void getCoordinatesOf (const float src[3], float res[3]) const
void getInverseCoordinatesOf (const float src[3], float res[3]) const
void getLocalCoordinatesOf (const float src[3], float res[3]) const
void getLocalInverseCoordinatesOf (const float src[3], float res[3]) const
void getCoordinatesOfIn (const float src[3], float res[3], const Frame *in) const
void getCoordinatesOfFrom (const float src[3], float res[3], const Frame *from) const

Coordinate system transformation of vectors

A frame is as a new coordinate system, defined with respect to a reference frame (the world coordinate system by default, see the "Composition of frame" section).

The transformOf() (resp. inverseTransformOf()) functions transform a 3D vector from (resp. to) the world coordinates system. This section defines the 3D vector transformation functions. See the Coordinate system transformation of 3D points above for the transformation of 3D points. The difference between the two sets of functions is simple : for vectors, only the rotational part of the transformations is taken into account, while translation is also considered for 3D points.

The length of the resulting transformed vector is identical to the one of the source vector for all the described functions.

When local is prepended to the names of the functions, the functions simply transform from (and to) the reference frame.

When In (resp. From) is appended to the names, the functions transform from (resp. To) the frame that is given as an argument. The frame does not need to be in the same branch or the hierarchical tree, and can be NULL (the world coordinates system).

Combining any of these functions with its inverse (in any order) leads to the identity.

Vec transformOf (const Vec &src) const
Vec inverseTransformOf (const Vec &src) const
Vec localTransformOf (const Vec &src) const
Vec localInverseTransformOf (const Vec &src) const
Vec transformOfIn (const Vec &src, const Frame *in) const
Vec transformOfFrom (const Vec &src, const Frame *from) const
void getTransformOf (const float src[3], float res[3]) const
void getInverseTransformOf (const float src[3], float res[3]) const
void getLocalTransformOf (const float src[3], float res[3]) const
void getLocalInverseTransformOf (const float src[3], float res[3]) const
void getTransformOfIn (const float src[3], float res[3], const Frame *in) const
void getTransformOfFrom (const float src[3], float res[3], const Frame *from) const

Constraints on the displacement

A constraint can be attached to the frame to limit its displacement. The translate() and rotate() function will satisfy this constraint. Default value is a non-constraint (NULL) constraint. See the Constraint and derived class documentation.

Constraintconstraint () const
void setConstraint (Constraint *c)

Frame associated matrices

const GLdouble * matrix () const
void getMatrix (GLdouble m[4][4]) const
void getMatrix (GLdouble m[16]) const
const GLdouble * worldMatrix () const
void getWorldMatrix (GLdouble m[4][4]) const
void getWorldMatrix (GLdouble m[16]) const
void setFromMatrix (const float m[4][4])
void alignWithFrame (const Frame *const fr, bool move=false, float threshold=0.85f)
void projectOnLine (const Vec &origin, const Vec &dir)
const GLdouble * inverseMatrix () const
void getInverseMatrix (GLdouble m[4][4]) const
void getInverseMatrix (GLdouble m[16]) const
const GLdouble * worldInverseMatrix () const
void getWorldInverseMatrix (GLdouble m[4][4]) const
void getWorldInverseMatrix (GLdouble m[16]) const

Inversion of the transformation

Frame inverse () const
void invert ()
Frame worldInverse () const
void worldInvert ()

XML representation

virtual QDomElement domElement (const QString &name, QDomDocument &doc) const
virtual void initFromDOMElement (const QDomElement &e)

Signals

void modified ()
void interpolated ()

Public Member Functions

 Frame ()
virtual ~Frame ()
Frameoperator= (const Frame &f)
 Frame (const Frame &f)


Detailed Description

A frame in 3D space (position and orientation), with possible displacement constraints.

A Frame is a 3D coordinate system, represented by a position() and an orientation(). The order of these transformations is important : in libQGLViewer, the Frame is first translated and then rotated around the new translated origin. A Frame is useful to define the position and orientation of a 3D rigid object :

Frame fr; fr.setPosition(1,0,3); fr.setOrientationAxisAngle(0,1,0, M_PI/2); // Rotation around the Y axis. glPushMatrix(); glMultMatrixd(fr.matrix()); // Draw your object here glPopMatrix();

Many functions are provided to transform a 3D point from one coordinate system to an other : see coordinatesOf(), inverseCoordinatesOf(), coordinatesOfIn(), coordinatesOfFrom()...

You may also want to transform a 3D vector from one frame to an other, which corresponds to applying only the rotational part of the frame transformation : see transformOf() and inverseTransformOf().

See the frameTransform example for an illustration.

The translation() and the rotation() that are encapsulated in a Frame can also be used to represent a solid transformation of space. Such a solid transformation can also be interpreted as a change of coordinate system, and the coordinate system conversion functions actually allow you to use a Frame as a solid transformation. Use inverseCoordinatesOf() (resp. coordinatesOf()) to apply the transformation (resp. its inverse). Note the inversion.

Hierarchy of frames

The position and the rotation of a Frame are actually defined with respect to a referenceFrame(). The default referenceFrame() is the world coordinate system, but this value can be set to any other frame using setReferenceFrame(). When a referenceFrame() is specified, one must differentiate :

This terminology for local (translation() and rotation()) and global (position() and orientation()) definition is used in all the functions' names and should be sufficient to prevent ambiguities. These notions are identical when there is no referenceFrame() (i.e. a NULL value, corresponding to the world coordinate system).

A Frame is actually defined by its translation() with respect to its referenceFrame(), and then by a rotation() of the coordinate system around the new translated origin.

Setting a NULL reference frame resets the world coordinate system as the referenceFrame() (default value). The world coordinate system is the one you are in at the beginning of the QGLViewer::draw() function (see the introduction page>).

Frames can hence easily be organized in a tree hierarchy, which root is the world coordinate system. A loop in the hierarchy would result in an inconsistent (multiple) frame definition. settingAsReferenceFrameWillCreateALoop() checks this and prevents setReferenceFrame() from creating such a loop.

This frame hierarchy is used in methods like coordinatesOfIn(), coordinatesOfFrom()... which allow coordinates (or vector) conversion from a frame to any other one (including the world coordinate system).

Attention:
However, one must note that this hierarchical representation is internal to the Frame classes. When the frames represent openGL coordinates system, one should map this hierarchical representation to the openGL GL_MODELVIEW matrix stack. If we define this Frame hierarchy:
Frame* body = new Frame(); Frame* leftArm = new Frame(); Frame* rightArm = new Frame(); leftArm->setReferenceFrame(body); rightArm->setReferenceFrame(body);
Then the openGL drawing code associated with this Frame representation should look like:
void Viewer::draw() { glPushMatrix(); glMultMatrixd(body->matrix()); drawBody(); glPushMatrix(); glMultMatrixd(leftArm->matrix()); drawArm(); glPopMatrix(); glPushMatrix(); glMultMatrixd(rightArm->matrix()); drawArm(); glPopMatrix(); glPopMatrix(); }
Note how we use imbricated glPushMatrix() and glPopMatrix() to represent our frame hierarchy. leftArm and rightArm are hence both defined with respect to the body coordinate system, as in the Frame hierarchy.

Constraints

An interesting feature of Frames is that their displacement can be constrained. When a Constraint is attached to a Frame, it filters the input of translate() and rotate(), and only the resulting filtered motion is applied to the frame. The default constraint() is NULL and no filter is applied. Use setConstraint() to attach a constraint to a frame.

Constraints are especially usefull for the ManipulatedFrame instances, in order to forbid some mouse motions. See the constrainedFrame, constrainedCamera and luxo examples for an illustration.

New constraints can very easily be implemented by deriving a class from the Constraint class or any of its derived classes. All you need is to provide your own implementation of the Constraint::constrainTranslation(qglviewer::Vec&, Frame* const) and Constraint::constrainRotation(qglviewer::Quaternion& , Frame* const) functions.

Classical constraints are provided for convenience : see the LocalConstraint, WorldConstraint and CameraConstraint classes for axial and plane constraints. The TriangleSetConstraint is very useful for walk through applications, in order to force the camera to remain on a given path.

Derived classes

The ManipulatedFrame class inherits Frame and implements a mouse motion convertion, so that a frame can be manipulated with the mouse. SpinningFrame are animated Frames with a rotational motion.


Constructor & Destructor Documentation

Frame  ) 
 

Creates a default frame. Positioned in (0,0,0), with an identity rotation Quaternion (0,0,0,1). The referenceFrame() is set to NULL (meaning world coordinate system). No attached constraint().

virtual ~Frame  )  [inline, virtual]
 

Virtual destructor. Empty.

Frame const Frame f  ) 
 

Copy constructor. translation(), rotation() as well as constraint() and referenceFrame() pointers are copied. Warning, signal and slot connections are not copied.

Frame const Vec pos,
const Quaternion orien
 

Creates an initialized frame, with a position and an orientation. The reference frame is set to NULL (meaning world coordinate system).


Member Function Documentation

void alignWithFrame const Frame *const  fr,
bool  move = false,
float  threshold = 0.85f
 

Align the Frame with an other Frame, so that two of their axis are parallel.

If the X, Y and Z axis of the Frame is almost parallel to any of the X, Y, or Z axis of fr, the Frame is rotated so that these two axis actually become parallel.

If, after this first rotation, two other axis are also almost parallel, a second alignment is performed. The two frames then have identical orientations, up to rotations of 90 degrees.

threshold measure how close two axis must be to be aligned. It is compared with the absolute values of the dot product of the normalized axis.

When move is set to true, the frame position will also be affected by the alignment. The new position is such that the fr's position() is identical to the previous one (as computed with coordinatesOf()).

fr may be NULL and then represents the world coordinate system (same convention than for the referenceFrame()).

ManipulatedFrame::mouseDoubleClickEvent() calls this function when the left mouse button is double clicked.

Constraint* constraint  )  const [inline]
 

Returns the current constraint. Result is of type Constraint and dynamic_cast should be used to convert it to a derived class.

A NULL value means that no Constraint is applied to filter translate() and rotate() (default value).

Vec coordinatesOf const Vec src  )  const
 

This returns the frame coordinates of a point src defined in the world coordinate system (converts from world to frame).

If src is actually a vector, use the vector equivalent function transformOf() where only the rotational part of the transformation is taken into account.

inverseCoordinatesOf() performs the inverse transformation.

See the frameTransform example for an illustration.

Vec coordinatesOfFrom const Vec src,
const Frame from
const
 

This returns the frame coordinate system coordinates of the point whose position in the from coordinate system is src (converts from from to frame). from and the frame do not need to be located in the same branch of the frame tree hierarchy.

If src is actually a vector, use the vector equivalent function transformOfFrom() where only the rotational part of the transformation is taken into account.

coordinatesOfIn() performs the inverse transformation.

Vec coordinatesOfIn const Vec src,
const Frame in
const
 

This returns the in coordinate system coordinates of the point whose position in the frame coordinate system is src (converts from frame to in). in and the frame do not need to be located in the same branch of the frame tree hierarchy.

If src is actually a vector, use the vector equivalent function transformOfIn() where only the rotational part of the transformation is taken into account.

coordinatesOfFrom() performs the inverse transformation.

QDomElement domElement const QString &  name,
QDomDocument &  doc
const [virtual]
 

Creates an XML QDomElement that represents the Frame. name is the name of the QDomElement tag. You need to provide the QDomDocument doc that will hold the resulting element. Typical usage would be:

QDomDocument doc("myDocument"); Frame sunFrame; // ... anyNode.addElement(sunFrame.domElement("sunFrame", doc)); // ...

The resulting DomElement will look like:

<sunFrame> <position x="0" y="0" z="2.61313" /> <orientation q0="0" q1="0" q2="0" q3="1" /> </sunFrame>
Use initFromDOMElement() to restore the Frame state from the resulting domElement.

See also Camera::domElement(), KeyFrameInterpolator::domElement()...

Attention:
The constraint() and referenceFrame() are not (yet) saved in the domElement.

Reimplemented in ManipulatedCameraFrame, ManipulatedFrame, and SpinningFrame.

void getCoordinatesOf const float  src[3],
float  res[3]
const
 

Same as coordinatesOf(), but with float parameters.

void getCoordinatesOfFrom const float  src[3],
float  res[3],
const Frame from
const
 

Same as coordinatesOfFrom(), but with float parameters.

void getCoordinatesOfIn const float  src[3],
float  res[3],
const Frame in
const
 

Same as coordinatesOfIn(), but with float parameters.

void getInverseCoordinatesOf const float  src[3],
float  res[3]
const
 

Same as inverseCoordinatesOf(), but with float parameters.

void getInverseMatrix GLdouble  m[16]  )  const
 

double[16] parameter version of inverseMatrix(). See also getWorldInverseMatrix() and worldInverseMatrix(). This function is very similar to Quaternion::getInverseMatrix(), it simply includes the negated inverse rotated Frame translation in the last line.

void getInverseMatrix GLdouble  m[4][4]  )  const
 

double[4][4] parameter version of inverseMatrix(). See also getWorldInverseMatrix() and worldInverseMatrix(). This function is very similar to Quaternion::getInverseMatrix(), it simply includes the negated inverse rotated Frame translation in the last line.

Note:
The scaling factor of the 4x4 matrix is set to 1.0.

void getInverseTransformOf const float  src[3],
float  res[3]
const
 

Same as inverseTransformOf(), but with float parameters.

void getLocalCoordinatesOf const float  src[3],
float  res[3]
const
 

Same as localCoordinatesOf(), but with float parameters.

void getLocalInverseCoordinatesOf const float  src[3],
float  res[3]
const
 

Same as localInverseCoordinatesOf(), but with float parameters.

void getLocalInverseTransformOf const float  src[3],
float  res[3]
const
 

Same as localInverseTransformOf(), but with float parameters.

void getLocalTransformOf const float  src[3],
float  res[3]
const
 

Same as localTransformOf(), but with float parameters.

void getMatrix GLdouble  m[16]  )  const
 

double[16] parameter version of matrix(). See also getWorldMatrix() and worldMatrix(). This function is very similar to Quaternion::getMatrix(), it simply includes the Frame translation in the last line of the matrix.

void getMatrix GLdouble  m[4][4]  )  const
 

double[4][4] parameter version of matrix(). See also getWorldMatrix() and worldMatrix(). This function is very similar to Quaternion::getMatrix(), it simply includes the Frame translation in the last line.

Note:
The scaling factor of the 4x4 matrix is set to 1.0.

void getOrientation float &  q0,
float &  q1,
float &  q2,
float &  q3
const
 

Get the current orientation of the frame (same as orientation()). Parameters are the orientation Quaternion values. See also setOrientation() and setOrientationAxisAngle().

void getPosition float &  x,
float &  y,
float &  z
const
 

Get the current position of the frame (same as position()). See also setPosition().

void getRotation float &  x,
float &  y,
float &  z,
float &  a
const
 

Get the current rotation of the frame (same as rotation()). Parameters are the rotation Quaternion values. See also setRotation() and setRotationAxisAngle().

void getTransformOf const float  src[3],
float  res[3]
const
 

Same as transformOf(), but with float parameters.

void getTransformOfFrom const float  src[3],
float  res[3],
const Frame from
const
 

Same as transformOfFrom(), but with float parameters.

void getTransformOfIn const float  src[3],
float  res[3],
const Frame in
const
 

Same as transformOfIn(), but with float parameters.

void getTranslation float &  x,
float &  y,
float &  z
const
 

Get the current local translation of the frame (same as translation()). See also setTranslation().

void getWorldInverseMatrix GLdouble  m[16]  )  const
 

float[16] parameter version of worldInverseMatrix(). See also getInverseMatrix() and inverseMatrix().

void getWorldInverseMatrix GLdouble  m[4][4]  )  const
 

float[4][4] parameter version of worldInverseMatrix(). See also getInverseMatrix() and inverseMatrix().

void getWorldMatrix GLdouble  m[16]  )  const
 

float[16] parameter version of worldMatrix(). See also getMatrix() and matrix().

void getWorldMatrix GLdouble  m[4][4]  )  const
 

float[4][4] parameter version of worldMatrix(). See also getMatrix() and matrix().

void initFromDOMElement const QDomElement &  e  )  [virtual]
 

Restore the Frame state from a QDomElement created by domElement(). See Vec::initFromDOMElement() and Quaternion::initFromDOMElement() for details.

Fields that are not described in the QDomElement are set to their default values (see Frame()).

Attention:
The constraint() and referenceFrame() are not (yet) restored from the domElement.

Reimplemented in ManipulatedCameraFrame, ManipulatedFrame, and SpinningFrame.

void interpolated  )  [signal]
 

This signal is emitted when the Frame, attached to a KeyFrameInterpolator (see KeyFrameInterpolator::frame()), has its position and orientation interpolated by the KeyFrameInterpolator. Connect this signal to any object that should be notified.

This signal should not be connected to a QGLViewer, connect the KeyFrameInterpolator::interpolated() signal instead (identical, but does not depend on the interpolated Frame).

Frame inverse  )  const
 

Returns the inverse of the Frame space transformation. The original Frame is not modified. Use invert() to actually modify the Frame.

The rotation() of the new Frame is the Quaternion::inverse() of the original rotation(). Its translation() is the negated and inverse rotated image of the original translation().

The new Frame has the same referenceFrame() as the original. Hence only the local Frame transformation is inverted (see the "Hierarchy of frames" section in the Frame Detailed documentation for details on this notion). Use worldInverse() for a global inverse.

Vec inverseCoordinatesOf const Vec src  )  const
 

This returns the world coordinates of the point whose position in the frame coordinate system is src (converts from frame to world).

If src is actually a vector, use the vector equivalent function inverseTransformOf() where only the rotational part of the transformation is taken into account.

coordinatesOf() performs the inverse transformation.

See the frameTransform example for an illustration.

const GLdouble * inverseMatrix  )  const
 

Returns the current 4x4 frame inverse matrix. This matrix only represents the local inverse transformation (see referenceFrame() for frame composition). Use getWorldInverseMatrix() or worldInverseMatrix() to have the full frame inverse transformation matrix (i.e. from the world coordinate system).

worldInverseMatrix() and inverseMatrix() will return identical results when the frame is not composed (referenceFrame() == NULL). See also getInverseMatrix().

Attention:
The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. See the difference between Quaternion::getMatrix() and Quaternion::getRotationMatrix().

The result is only valid until the next call to inverseMatrix(), getInverseMatrix(), worldInverseMatrix() or getWorldInverseMatrix(). Use it immediately or store it in an other variable. Consider using getInverseMatrix() in that case.

Note:
The scaling factor of the 4x4 matrix is set to 1.0.

Vec inverseTransformOf const Vec src  )  const
 

This returns the world transform of the vector whose coordinates in the frame coordinate system is src (converts from frame to world).

For vectors, only the rotational part of the transformation is taken into account, see inverseCoordinatesOf() for the point equivalent function.

transformOf() performs the inverse transformation.

void invert  )  [inline]
 

Invert the Frame (same as inverse(), but the Frame is actually inverted). The new rotation is the inverse of the previous one. The translation is the negated inverse rotation of the original translation().

This method only inverts the local Frame transformation (see inverse() for details). Use worldInvert() for a full transformation inversion. The modified() signal is emitted.

Vec localCoordinatesOf const Vec src  )  const
 

Returns the frame coordinates of a point src defined in the reference frame (default is the world coordinates system, see referenceFrame()) (converts from reference frame to frame coordinates).

If src is actually a vector, use the vector equivalent function localTransformOf() where only the rotational part of the transformation is taken into account.

localInverseCoordinatesOf() performs the inverse transformation.

Vec localInverseCoordinatesOf const Vec src  )  const
 

Returns the reference frame coordinates (default is the world coordinates system, see referenceFrame()) of a point src defined in the frame coordinate system (converts from frame to reference frame coordinates).

If src is actually a vector, use the vector equivalent function localInverseTransformOf() where only the rotational part of the transformation is taken into account.

localCoordinatesOf() performs the inverse transformation.

Vec localInverseTransformOf const Vec src  )  const
 

Returns the reference frame transform (default is the world coordinates system, see referenceFrame()) of a vector src defined in the frame coordinate system (converts from frame to reference frame).

For vectors, only the rotational part of the transformation is taken into account, see localCoordinatesOf() for the point equivalent function.

localTransformOf() performs the inverse transformation.

Vec localTransformOf const Vec src  )  const
 

Returns the frame transform of a vector src defined in the reference frame (default is the world coordinates system, see referenceFrame()) (converts from reference frame to frame).

For vectors, only the rotational part of the transformation is taken into account, see localCoordinatesOf() for the point equivalent function.

localInverseTransformOf() performs the inverse transformation.

const GLdouble * matrix  )  const
 

Returns the current 4x4 frame matrix. Can be used with glMultMatrixd(fr.matrix()) or glLoadMatrixd(fr.matrix()). This matrix only represents the local transformation (i.e. with respect to the referenceFrame()). Use worldMatrix() or getWorldMatrix() to have the full frame transformation matrix (i.e. from the world coordinate system to the Frame).

worldMatrix() and matrix() will return identical results when the frame is not composed (referenceFrame() == NULL). See also getMatrix().

Attention:
The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. See the difference between Quaternion::getMatrix() and Quaternion::getRotationMatrix().

The result is only valid until the next call to matrix(), getMatrix(), worldMatrix() or getWorldMatrix(). Use it immediately (as in glLoadMatrixd(fr.matrix()) or glLoadMatrixd(fr.matrix())) or store it in an other variable. Consider using getMatrix() if needed.

Note:
The scaling factor of the 4x4 matrix is set to 1.0.

void modified  )  [signal]
 

This signal is emitted whenever the position or the orientation of the Frame is modified. Connect this signal to any object that must be notified.

QObject::connect(myFrame, SIGNAL(modified()), myObject, SLOT(update()));

This signal can also be connected to all the viewers using QGLViewer::connectSignalToAllViewers().

Note:
If your Frame is part of a Frame hierarchy (see referenceFrame()), a modification of one of the parents of this Frame will not emit this Frame modified() signal. Use code like this to change this behavior (you can do this recursively for all the referenceFrame() until the NULL world root frame is encountered):
// Emits the frame modified() signal when its referenceFrame() is modified(). connect(myFrame->referenceFrame(), SIGNAL(modified()), myFrame, SIGNAL(modified()));
Attention:
Connecting this signal to a QGLWidget::updateGL() function (or a function that calls it) will prevent you from modifying the frame inside your QGLViewer::draw() function as it would result in an infinite loop.

Frame & operator= const Frame f  ) 
 

operator= : referenceFrame() and constraint() pointers are copied. Warning, signal and slot connections are not copied.

Quaternion orientation  )  const
 

Returns the current frame orientation (defined with respect to the world coordinate system). See setOrientation().

Vec position  )  const [inline]
 

Returns the current frame origin position (defined in the world coordinate system). See setPosition().

void projectOnLine const Vec origin,
const Vec dir
 

Translates the frame so that its position is on the line defined by origin and axis. Simply uses an orthogonal projection.

const Frame* referenceFrame  )  const [inline]
 

Returns the current reference frame, defined with setReferenceFrame().

The frame is "child" of the referenceFrame(), meaning that its position and orientation are defined with respect to the referenceFrame(). A NULL referenceFrame() (default value) means that the frame is defined is the world coordinate system. Chaining frames like this allows you to easily create a hierarchy of frames.

Convenient functions allow you to convert 3D coordinates from one frame to an other : coordinatesOf(), localCoordinatesOf(), coordinatesOfIn() and their inverse functions.

Vectors can also be converted from one frame to an other using transformOf(), transformOfIn, localTransformOf() and the inverse functions.

A warning is printed if setting fr as a reference frame would create a loop in the frame hierarchy (see settingAsReferenceFrameWillCreateALoop()), as this hierarchy needs to be a tree.

void rotate const float  x,
const float  y,
const float  z,
const float  a
 

Same as rotate(), but with float parameters (Quaternion values). Actual rotation may differ from these values in order to satisfy the rotation constraint(). Use the non-const parameter version of this function to get the filtered values back.

void rotate float &  x,
float &  y,
float &  z,
float &  a
 

Same as rotate(), but with float parameters (Quaternion values). Parameters may be modified to satisfy rotation constraint(). See also the const parameter version of this function.

void rotate float  q[4]  ) 
 

Same as rotate(), but parameter is given as a float[4]. Quaternion q may be modified to satisfy rotation constraint().

void rotate const Quaternion q  ) 
 

Compose current frame rotation with q (R = R*q). The actual rotation may differ from q in order to satisfy the rotation constraint(). Consider using the non-const parameter version of this function to get the filtered values back.

void rotate Quaternion q  ) 
 

Compose current frame rotation with q (R = R*q). q may be modified to satisfy rotation constraint(). Use setConstraint() to (un)set rotational constraints. Emits the modified() signal.

void rotateAroundPoint const Quaternion q,
const Vec p
 

Same as rotateAroundPoint(), but the rotation Quaternion is const. Note however that the actual rotation may differ according to local constraints.

void rotateAroundPoint Quaternion q,
const Vec p
 

Same as rotate(), but position() is modified as if the Frame was rotated of q around the point p. Emits the modified() signal.

If the frame is constrained (see setConstraint()), q is first constrained using Constraint::constrainRotation(). The translation which results from the filtered rotation around is then computed and filtered using Constraint::constrainTranslation().

Quaternion rotation  )  const [inline]
 

Returns the current Quaternion orientation. See setRotation().

void setConstraint Constraint c  )  [inline]
 

Set the constraint attached with the frame. A NULL value means no constraint, i.e. a Constraint instance. The previous constraint pointer should be deleted by the calling function if needed. Use constraint() to get this value.

void setFromMatrix const float  m[4][4]  ) 
 

Set the frame state from a matrix representation. Matrix has to be a proper row-major order transformation representation (rotation is in the upper left 3x3 matrix, while translation is on the last line). matrix() returns the current matrix value.

Attention:
A Frame does not handle a scale factor. The possible scaling in m will be ignored by this method.

void setOrientation const Quaternion q  ) 
 

Set the current orientation of the frame (with respect to the world coordinate system). See orientation() and setOrientationWithConstraint().

void setOrientation const float  x,
const float  y,
const float  z,
const float  a
 

Same as setOrientation(), but with float parameters.

void setOrientationAxisAngle const float  x,
const float  y,
const float  z,
const float  a
 

Set the current orientation of the frame. Parameters are the rotation axis vector and its angle (in radians).

void setOrientationWithConstraint Quaternion q  ) 
 

Same as setOrientation(), but the possible constraint() of the Frame is enforced. q is modified to satisfy the constraint. Emits the modified() signal.

void setPosition const float  x,
const float  y,
const float  z
 

Same as setPosition(), but with float parameters.

void setPosition const Vec t  ) 
 

Set the position of the origin of the frame, with respect to the world coordinate system. Use setTranslation() to defined to local frame translation (with respect to the reference frame). See also position(), orientation() and setPositionWithConstraint().

void setPositionAndOrientation const Vec p,
const Quaternion q
 

Same as successive calls to setPosition() and then setOrientation().

Only one modified() signal is emitted, which is convenient if this signal is connected to a viewer updateGL() slot. See also setTranslationAndRotation() and setPositionAndOrientationWithConstraint().

void setPositionAndOrientationWithConstraint Vec p,
Quaternion q
 

Same as setPositionAndOrientation() but the position and orientation increments are filtered by the possible constraint(). p and q are modified to satisfy the constraint. Emits the modified() signal.

void setPositionWithConstraint Vec p  ) 
 

Same as setPosition(), but the possible constraint() of the Frame is enforced. p is modified to satisfy the constraint. Emits the modified() signal.

void setReferenceFrame const Frame *const  fr  ) 
 

Set the current reference frame. The frame then becomes a "child" of the referenceFrame(), meaning that its position and orientation are defined with respect to the referenceFrame().

void setRotation const Quaternion q  )  [inline]
 

Set the current rotation Quaternion. See rotation() and the different Quaternion constructors. Emits the modified() signal. See also setTranslation() and setRotationWithConstraint().

void setRotation const float  x,
const float  y,
const float  z,
const float  a
 

Set the current rotation of the frame. Parameters are the rotation Quaternion float values. Get current rotation with rotation().

void setRotationAxisAngle const float  x,
const float  y,
const float  z,
const float  a
 

Set the current rotation of the frame. Parameters are the rotation axis vector and its angle (in radians).

void setRotationWithConstraint Quaternion q  ) 
 

Same as setRotation(), but the possible constraint() of the Frame is enforced. q is modified to satisfy the constraint. Emits the modified() signal.

bool settingAsReferenceFrameWillCreateALoop const Frame *const  fr  ) 
 

Returns true if setting fr as the reference frame would create a loop in the frame hierarchy.

void setTranslation const Vec t  )  [inline]
 

Set the current local translation of the frame. Use translation() to get the current frame position. See setPosition() and position() to get the world position of the frame. Emits the modified() signal. See also setRotation() and setTranslationWithConstraint().

void setTranslation const float  x,
const float  y,
const float  z
 

Set the current translation of the frame. Same as setTranslation(), but with float parameters. translation() returns the current frame position.

void setTranslationAndRotation const Vec t,
const Quaternion q
 

Same as successive calls to setPosition() and then setOrientation().

Only one modified() signal is emitted, which is convenient if this signal is connected to a viewer updateGL() slot. See also setPositionAndOrientation() and setTranslationAndRotationWithConstraint().

void setTranslationAndRotationWithConstraint Vec t,
Quaternion q
 

Same as setTranslationAndRotation(), but the possible constraint() of the Frame is enforced. t and q are modified to satisfy the constraint. Emits the modified() signal.

void setTranslationWithConstraint Vec t  ) 
 

Same as setTranslation(), but the possible constraint() of the Frame is enforced. t is modified to satisfy the constraint. Emits the modified() signal.

Vec transformOf const Vec src  )  const
 

This returns the frame transform of a vector src defined in the world coordinate system (converts from world to frame).

For vectors, only the rotational part of the transformation is taken into account, see coordinatesOf() for the point equivalent function.

inverseTransformOf() performs the inverse transformation.

Vec transformOfFrom const Vec src,
const Frame from
const
 

This returns the frame coordinate system transform of the vector whose coordinates in the from coordinate system is src (converts from from to frame). from and the frame do not need to be located in the same branch of the frame tree hierarchy.

For vectors, only the rotational part of the transformation is taken into account, see coordinatesOfFrom() for the point equivalent function.

transformOfIn() performs the inverse transformation.

Vec transformOfIn const Vec src,
const Frame in
const
 

This returns the in coordinate system transform of the vector whose coordinates in the frame coordinate system is src (converts from frame to in). in and the frame do not need to be located in the same branch of the frame tree hierarchy.

For vectors, only the rotational part of the transformation is taken into account, see coordinatesOfIn() for the point equivalent function.

transformOfFrom() performs the inverse transformation.

void translate const float  x,
const float  y,
const float  z
 

Same as translate() but with const float parameter. The actual translation may differ from the given parameters in order to satisfy the constraint(). Use the non-const version to get the filtered values back.

void translate float &  x,
float &  y,
float &  z
 

Same as translate() but with float parameters. Parameters are modified to satisfy translation constraints (see constraint()). See also the non-const parameters version of this version, if you are not interested in the filtered values.

void translate float  t[3]  ) 
 

Same as translate() but with a float[3] parameter. t can be modified to fit translation constraint().

void translate const Vec t  ) 
 

Translate the frame of t. The actual applied translation may differ from t as the constraint will filter t (see constraint()). Use the non-const version of translate() to get back the filtered translation value.

void translate Vec t  ) 
 

Translate the frame of t. t may be modified to satisfy translation constraint(). Use setConstraint() to (un)set the translation constraints. Emits the modified() signal.

Vec translation  )  const [inline]
 

Returns the current frame position. See setTranslation().

Frame worldInverse  )  const [inline]
 

Returns the world inverse of the Frame transformation. The original Frame is not modified. Use worldInvert() to actually modify the Frame.

The orientation() of the new Frame is the Quaternion::inverse() of the original orientation(). Its position() is the negated and inverse rotated image of the original position().

The new Frame has no (i.e. NULL) referenceFrame(). Hence the complete Frame transformation (including its referenceFrame() transformations) is inverted (see the "Hierarchy of frames" section in the Frame Detailed documentation for details on this notion). Use inverse() for a local inverse.

const GLdouble * worldInverseMatrix  )  const
 

Returns the 4x4 frame inverse matrix, defined in the world coordinate system. This matrix is simply the inverse of worldMatrix(). worldInverseMatrix() and inverseMatrix() are actually identical when the Frame has no (i.e. NULL) referenceFrame().

Attention:
The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation.

The result is only valid until the next call to inverseMatrix() or getWorldInverseMatrix(). Use it immediately or store it in an other variable. Consider using getWorldInverseMatrix() in that case.

void worldInvert  ) 
 

Invert the Frame world transformations (same as worldInverse(), but the Frame is actually inverted). The new orientation is the inverse of the previous one. The position() is the negated inverse rotation of the original position().

This method only inverts the local Frame transformation (see inverse() for details). Use invert() for a local transformation inversion. The modified() signal is emitted.

const GLdouble * worldMatrix  )  const
 

Returns the 4x4 frame matrix, defined in the world coordinate system. Can be used with glMultMatrixd(fr.worldMatrix()) or glLoadMatrixd(fr.worldMatrix()). This matrix represents the global transformation from the world coordinate system to the frame coordinate system, including the entire frame composition chain (see referenceFrame() for frame composition). Use getMatrix() or matrix() to have the local frame transformation matrix (i.e. the translation() and rotation() part). See also worldInverseMatrix().

worldMatrix() and matrix() will return identical results when the frame is not composed (referenceFrame() == NULL). See also getWorldMatrix() and getWorldInverseMatrix().

Attention:
The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation.

The result is only valid until the next call to matrix(), getMatrix(), worldMatrix() or getWorldMatrix(). Use it immediately (as in glLoadMatrixd(fr.worldMatrix()) or glLoadMatrixd(fr.worldMatrix())) or store it in an other variable. Consider using getWorldMatrix() in that case.


Generated on Wed Dec 1 12:41:26 2004 for libQGLViewer by doxygen 1.3.7