eXperiment robotics framework

[OpenGL utilities]

Collaboration diagram for Frame:
The Frame class represents a coordinate system, defined by a position and an orientation. More...


class  Frame
 A position and orientation in the world. More...

Detailed Description

The Frame class represents a coordinate system, defined by a position and an orientation.

A Frame is a 3D coordinate system, represented by a position() and an orientation(). The order of these transformations is important: 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, using its matrix() method, as shown below:

// Builds a Frame at position (0.5,0,0) and oriented such that its Y axis is along the (1,1,1)
// direction. One could also have used setPosition() and setOrientation().
Frame fr(Vec3(0.5,0,0), Quaternion(Vec3(0,1,0), Vec3(1,1,1)));
// Draw your object here, in the local fr coordinate system.

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

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

The translation() and the rotation() that are encapsulated in a Frame can also be used to represent a rigid transformation of space. Such a 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 rigid transformation. Use inverseCoordinatesOf() (resp. coordinatesOf()) to apply the transformation (resp. its inverse). Note the inversion.

Hierarchy of Frames

The position and the orientation of a Frame are actually defined with respect to a referenceFrame(). The default referenceFrame() is the world coordinate system (represented by a NULL referenceFrame()). If you setReferenceFrame() to a different Frame, you must then differentiate:

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.

This terminology for local (translation() and rotation()) and global (position() and orientation()) definitions is used in all the methods' names and should be sufficient to prevent ambiguities. These notions are obviously identical when the referenceFrame() is NULL, i.e. when the Frame is defined in the world coordinate system (the one you are in at the beginning.

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) conversions from a Frame to any other one (including the world coordinate system).

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. See the matrix() documentation for details.


An interesting feature of Frames is that their displacements 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 resulting in no filtering. Use setConstraint() to attach a Constraint to a frame.

The miarn project - written by Joao Xavier