A keyFrame Catmull-Rom Frame interpolator. More...

Inheritance diagram for KeyFrameInterpolator:

Signals
void	endReached ()
	This signal is emitted when the interpolation reaches the first (when interpolationSpeed() is negative) or the last keyFrame.

void	interpolated ()
	This signal is emitted whenever the frame() state is interpolated.

Public Member Functions
	KeyFrameInterpolator (Frame *fr=NULL)
	Creates a KeyFrameInterpolator, with `frame` as associated frame().

virtual	~KeyFrameInterpolator ()
	Virtual destructor.

Path creation
void	addKeyFrame (const Frame &frame)
	Appends a new keyFrame to the path.

void	addKeyFrame (const Frame &frame, float time)
	Appends a new keyFrame to the path, with its associated `time` (in seconds).

void	addKeyFrame (const Frame *const frame)
	Appends a new keyFrame to the path.

void	addKeyFrame (const Frame *const frame, float time)
	Appends a new keyFrame to the path, with its associated `time` (in seconds).

void	deletePath ()
	Removes all keyFrames from the path.

Associated Frame
Frame *	frame () const
	Returns the associated Frame and that is interpolated by the KeyFrameInterpolator.

void	setFrame (Frame *const frame)
	Sets the frame() associated to the KeyFrameInterpolator.

Path parameters
Frame	keyFrame (int index) const
	Returns the Frame associated with the keyFrame at index `index`.

float	keyFrameTime (int index) const
	Returns the time corresponding to the `index` keyFrame.

int	numberOfKeyFrames () const
	Returns the number of keyFrames used by the interpolation.

float	duration () const
	Returns the duration of the KeyFrameInterpolator path, expressed in seconds.

float	firstTime () const
	Returns the time corresponding to the first keyFrame, expressed in seconds.

float	lastTime () const
	Returns the time corresponding to the last keyFrame, expressed in seconds.

Interpolation parameters
float	interpolationTime () const
	Returns the current interpolation time (in seconds) along the KeyFrameInterpolator path.

float	interpolationSpeed () const
	Returns the current interpolation speed.

int	interpolationPeriod () const
	Returns the current interpolation period, expressed in milliseconds.

bool	loopInterpolation () const
	Returns `true` when the interpolation is played in an infinite loop.

bool	closedPath () const
	Whether or not (default) the path defined by the keyFrames is a closed loop.

void	setInterpolationTime (float time)
	Sets the interpolationTime().

void	setInterpolationSpeed (float speed)
	Sets the interpolationSpeed().

void	setInterpolationPeriod (int period)
	Sets the interpolationPeriod().

void	setLoopInterpolation (bool loop=true)
	Sets the loopInterpolation() value.

void	setClosedPath (bool closed=true)
	Sets the closedPath() value.

Interpolation
bool	interpolationIsStarted () const
	Returns `true` when the interpolation is being performed.

void	startInterpolation (int period=-1)
	Starts the interpolation process.

void	stopInterpolation ()
	Stops an interpolation started with startInterpolation().

void	resetInterpolation ()
	Stops the interpolation and resets interpolationTime() to the firstTime().

void	toggleInterpolation ()
	Calls startInterpolation() or stopInterpolation(), depending on interpolationIsStarted().

virtual void	interpolateAtTime (float time)
	Interpolate frame() at time `time` (expressed in seconds).

Path drawing
virtual void	drawPath (int mask=1, int nbFrames=6, float scale=1.0f)
	Draws the path used to interpolate the frame().

XML representation
virtual QDomElement	domElement (const QString &name, QDomDocument &document) const
	Returns an XML `QDomElement` that represents the KeyFrameInterpolator.

virtual void	initFromDOMElement (const QDomElement &element)
	Restores the KeyFrameInterpolator state from a `QDomElement` created by domElement().

Detailed Description

A keyFrame Catmull-Rom Frame interpolator.

A KeyFrameInterpolator holds keyFrames (that define a path) and a pointer to a Frame of your application (which will be interpolated). When the user startInterpolation(), the KeyFrameInterpolator regularly updates the frame() position and orientation along the path.

Here is a typical utilization example (see also the keyFrames example):

init()
{
  // The KeyFrameInterpolator kfi is given the Frame that it will drive over time.
  kfi = new KeyFrameInterpolator( new Frame() );
  kfi->addKeyFrame( Frame( Vec(1,0,0), Quaternion() ) );
  kfi->addKeyFrame( new Frame( Vec(2,1,0), Quaternion() ) );
  // ...and so on for all the keyFrames.
  // Ask for a display update after each update of the KeyFrameInterpolator
  connect(kfi, SIGNAL(interpolated()), SLOT(updateGL()));
  kfi->startInterpolation();
}
draw()
{
  glPushMatrix();
  glMultMatrixd( kfi->frame()->matrix() );
  // Draw your object here. Its position and orientation are interpolated.
  glPopMatrix();
}

The keyFrames are defined by a Frame and a time, expressed in seconds. The Frame can be provided as a const reference or as a pointer to a Frame (see the addKeyFrame() methods). In the latter case, the path will automatically be updated when the Frame is modified (using the Frame::modified() signal).

The time has to be monotonously increasing over keyFrames. When interpolationSpeed() equals 1.0 (default value), these times correspond to actual user's seconds during interpolation (provided that your main loop is fast enough). The interpolation is then real-time: the keyFrames will be reached at their keyFrameTime().

Interpolation details

When the user startInterpolation(), a timer is started which will update the frame()'s position and orientation every interpolationPeriod() milliseconds. This update increases the interpolationTime() by interpolationPeriod() * interpolationSpeed() milliseconds.

Note that this mechanism ensures that the number of interpolation steps is constant and equal to the total path duration() divided by the interpolationPeriod() * interpolationSpeed(). This is especially useful for benchmarking or movie creation (constant number of snapshots).

During the interpolation, the KeyFrameInterpolator emits an interpolated() signal, which will usually be connected to the QGLViewer::updateGL() slot. The interpolation is stopped when interpolationTime() is greater than the lastTime() (unless loopInterpolation() is true) and the endReached() signal is then emitted.

Note that a Camera has Camera::keyFrameInterpolator(), that can be used to drive the Camera along a path, or to restore a saved position (a path made of a single keyFrame). Press Alt+Fx to define a new keyFrame for path x. Pressing Fx plays/pauses path interpolation. See QGLViewer::pathKey() and the keyboard page for details.

Attention: If a Constraint is attached to the frame() (see Frame::constraint()), it should be deactivated before interpolationIsStarted(), otherwise the interpolated motion (computed as if there was no constraint) will probably be erroneous.

Retrieving interpolated values

This code defines a KeyFrameInterpolator, and displays the positions that will be followed by the frame() along the path:

KeyFrameInterpolator kfi( new Frame() );
// calls to kfi.addKeyFrame() to define the path.
const float deltaTime = 0.04; // output a position every deltaTime seconds
for (float time=kfi.firstTime(); time<=kfi.lastTime(); time += deltaTime)
{
  kfi.interpolateAtTime(time);
  cout << "t=" << time << "\tpos=" << kfi.frame()->position() << endl;
}

You may want to temporally disconnect the kfi interpolated() signal from the QGLViewer::updateGL() slot before calling this code.

Definition at line 131 of file keyFrameInterpolator.h.

Constructor & Destructor Documentation

KeyFrameInterpolator ( Frame * frame = NULL )

Creates a KeyFrameInterpolator, with frame as associated frame().

The frame() can be set or changed using setFrame().

interpolationTime(), interpolationSpeed() and interpolationPeriod() are set to their default values.

Definition at line 40 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::setFrame().

~KeyFrameInterpolator ( )

virtual

Virtual destructor.

Clears the keyFrame path.

Definition at line 59 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::deletePath().

Member Function Documentation

void addKeyFrame ( const Frame & frame )

slot

Appends a new keyFrame to the path.

Same as addKeyFrame(const Frame& frame, float), except that the keyFrameTime() is automatically set to previous keyFrameTime() plus one second (or 0.0 if there is no previous keyFrame).

Definition at line 248 of file keyFrameInterpolator.cpp.

Referenced by KeyFrameInterpolator::addKeyFrame(), KeyFrameInterpolator::initFromDOMElement(), Camera::interpolateTo(), Camera::interpolateToFitScene(), and Camera::interpolateToZoomOnPixel().

void addKeyFrame	(	const Frame &	frame,
		float	time
	)

slot

Appends a new keyFrame to the path, with its associated time (in seconds).

The path will use the current frame state. If you want the path to change when frame is modified, you need to pass a pointer to the Frame instead (see addKeyFrame(const Frame*, float)).

The keyFrameTime() have to be monotonously increasing over keyFrames.

Definition at line 212 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::resetInterpolation().

void addKeyFrame ( const Frame *const frame )

slot

Appends a new keyFrame to the path.

Same as addKeyFrame(const Frame* frame, float), except that the keyFrameTime() is set to the previous keyFrameTime() plus one second (or 0.0 if there is no previous keyFrame).

Definition at line 233 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::addKeyFrame(), and KeyFrameInterpolator::lastTime().

void addKeyFrame	(	const Frame *const	frame,
		float	time
	)

slot

Appends a new keyFrame to the path, with its associated time (in seconds).

The keyFrame is given as a pointer to a Frame, which will be connected to the KeyFrameInterpolator: when frame is modified, the KeyFrameInterpolator path is updated accordingly. This allows for dynamic paths, where keyFrame can be edited, even during the interpolation. See the keyFrames example for an illustration.

NULL frame pointers are silently ignored. The keyFrameTime() has to be monotonously increasing over keyFrames.

Use addKeyFrame(const Frame&, float) to add keyFrame by values.

Definition at line 186 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::resetInterpolation().

bool closedPath ( ) const

inline

Whether or not (default) the path defined by the keyFrames is a closed loop.

When true, the last and the first KeyFrame are linked by a new spline segment.

Use setLoopInterpolation() to create a continuous animation over the entire path.

Attention: The closed path feature is not yet implemented.

Definition at line 244 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::domElement().

void deletePath ( )

slot

Removes all keyFrames from the path.

The numberOfKeyFrames() is set to 0.

Definition at line 260 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::stopInterpolation().

Referenced by Camera::interpolateTo(), Camera::interpolateToFitScene(), Camera::interpolateToZoomOnPixel(), and KeyFrameInterpolator::~KeyFrameInterpolator().

QDomElement domElement	(	const QString &	name,
		QDomDocument &	document
	)		const

virtual

Returns an XML QDomElement that represents the KeyFrameInterpolator.

The resulting QDomElement holds the KeyFrameInterpolator parameters as well as the path keyFrames (if the keyFrame is defined by a pointer to a Frame, use its current value).

name is the name of the QDomElement tag. doc is the QDomDocument factory used to create QDomElement.

Use initFromDOMElement() to restore the ManipulatedFrame state from the resulting QDomElement.

See Vec::domElement() for a complete example. See also Quaternion::domElement(), Camera::domElement()...

Note that the Camera::keyFrameInterpolator() are automatically saved by QGLViewer::saveStateToFile() when a QGLViewer is closed.

Definition at line 715 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::closedPath(), Frame::domElement(), KeyFrameInterpolator::interpolationPeriod(), KeyFrameInterpolator::interpolationSpeed(), KeyFrameInterpolator::interpolationTime(), and KeyFrameInterpolator::loopInterpolation().

void drawPath	(	int	mask = `1`,
		int	nbFrames = `6`,
		float	scale = `1.0f`
	)

virtual

Draws the path used to interpolate the frame().

mask controls what is drawn: if (mask & 1) (default), the position path is drawn. If (mask & 2), a camera representation is regularly drawn and if (mask & 4), an oriented axis is regularly drawn. Examples:

drawPath();  // Simply draws the interpolation path
drawPath(3); // Draws path and cameras
drawPath(5); // Draws path and axis

In the case where camera or axis is drawn, nbFrames controls the number of objects (axis or camera) drawn between two successive keyFrames. When nbFrames=1, only the path KeyFrames are drawn. nbFrames=2 also draws the intermediate orientation, etc. The maximum value is 30. nbFrames should divide 30 so that an object is drawn for each KeyFrame. Default value is 6.

scale (default=1.0) controls the scaling of the camera and axis drawing. A value of QGLViewer::sceneRadius() should give good results.

See the keyFrames example for an illustration.

The color of the path is the current glColor().

Attention: The OpenGL state is modified by this method: GL_LIGHTING is disabled and line width set to 2. Use this code to preserve your current OpenGL state:
glPushAttrib(GL_ALL_ATTRIB_BITS);

drawPathModifyGLState(mask, nbFrames, scale);

glPopAttrib();

Definition at line 351 of file keyFrameInterpolator.cpp.

References QGLViewer::drawAxis(), Frame::matrix(), Frame::position(), Frame::setOrientation(), Frame::setPosition(), and Quaternion::squad().

float duration ( ) const

Returns the duration of the KeyFrameInterpolator path, expressed in seconds.

Simply corresponds to lastTime() - firstTime(). Returns 0.0 if the path has less than 2 keyFrames. See also keyFrameTime().

Definition at line 540 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::firstTime(), and KeyFrameInterpolator::lastTime().

void endReached ( )

signal

This signal is emitted when the interpolation reaches the first (when interpolationSpeed() is negative) or the last keyFrame.

When loopInterpolation() is true, interpolationTime() is reset and the interpolation continues. It otherwise stops.

float firstTime ( ) const

Returns the time corresponding to the first keyFrame, expressed in seconds.

Returns 0.0 if the path is empty. See also lastTime(), duration() and keyFrameTime().

Definition at line 548 of file keyFrameInterpolator.cpp.

Referenced by KeyFrameInterpolator::duration(), and KeyFrameInterpolator::resetInterpolation().

Frame* frame ( ) const

inline

Returns the associated Frame and that is interpolated by the KeyFrameInterpolator.

When interpolationIsStarted(), this Frame's position and orientation will regularly be updated by a timer, so that they follow the KeyFrameInterpolator path.

Set using setFrame() or with the KeyFrameInterpolator constructor.

Definition at line 185 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::interpolateAtTime(), and KeyFrameInterpolator::setFrame().

void initFromDOMElement ( const QDomElement & element )

virtual

Restores the KeyFrameInterpolator state from a QDomElement created by domElement().

Note that the frame() pointer is not included in the domElement(): you need to setFrame() after this method to attach a Frame to the KeyFrameInterpolator.

See Vec::initFromDOMElement() for a complete code example.

Definition at line 749 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::addKeyFrame(), Frame::initFromDOMElement(), KeyFrameInterpolator::setClosedPath(), KeyFrameInterpolator::setInterpolationPeriod(), KeyFrameInterpolator::setInterpolationSpeed(), KeyFrameInterpolator::setInterpolationTime(), KeyFrameInterpolator::setLoopInterpolation(), and KeyFrameInterpolator::stopInterpolation().

Referenced by Camera::initFromDOMElement().

void interpolateAtTime ( float time )

virtualslot

Interpolate frame() at time time (expressed in seconds).

interpolationTime() is set to time and frame() is set accordingly.

If you simply want to change interpolationTime() but not the frame() state, use setInterpolationTime() instead.

Emits the interpolated() signal and makes the frame() emit the Frame::interpolated() signal.

Definition at line 668 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::frame(), KeyFrameInterpolator::interpolated(), KeyFrameInterpolator::setInterpolationTime(), Frame::setPositionAndOrientationWithConstraint(), and Quaternion::squad().

void interpolated ( )

signal

This signal is emitted whenever the frame() state is interpolated.

The emission of this signal triggers the synchronous emission of the frame() Frame::interpolated() signal, which may also be useful.

This signal should especially be connected to your QGLViewer::updateGL() slot, so that the display is updated after every update of the KeyFrameInterpolator frame():

connect(myKeyFrameInterpolator, SIGNAL(interpolated()), SLOT(updateGL()));

Use the QGLViewer::QGLViewerPool() to connect the signal to all the viewers.

Note that the QGLViewer::camera() Camera::keyFrameInterpolator() created using QGLViewer::pathKey() have their interpolated() signals automatically connected to the QGLViewer::updateGL() slot.

Referenced by KeyFrameInterpolator::interpolateAtTime(), and KeyFrameInterpolator::setFrame().

bool interpolationIsStarted ( ) const

inline

Returns true when the interpolation is being performed.

Use startInterpolation(), stopInterpolation() or toggleInterpolation() to modify this state.

Definition at line 271 of file keyFrameInterpolator.h.

Referenced by Camera::interpolateTo(), Camera::interpolateToFitScene(), Camera::interpolateToZoomOnPixel(), and QGLViewer::keyPressEvent().

int interpolationPeriod ( ) const

inline

Returns the current interpolation period, expressed in milliseconds.

The update of the frame() state will be done by a timer at this period when interpolationIsStarted().

This period (multiplied by interpolationSpeed()) is added to the interpolationTime() at each update, and the frame() state is modified accordingly (see interpolateAtTime()). Default value is 40 milliseconds.

Definition at line 227 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::domElement(), and KeyFrameInterpolator::startInterpolation().

float interpolationSpeed ( ) const

inline

Returns the current interpolation speed.

Default value is 1.0, which means keyFrameTime() will be matched during the interpolation (provided that your main loop is fast enough).

A negative value will result in a reverse interpolation of the keyFrames. See also interpolationPeriod().

Definition at line 218 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::domElement(), and KeyFrameInterpolator::startInterpolation().

float interpolationTime ( ) const

inline

Returns the current interpolation time (in seconds) along the KeyFrameInterpolator path.

This time is regularly updated when interpolationIsStarted(). Can be set directly with setInterpolationTime() or interpolateAtTime().

Definition at line 210 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::domElement(), and KeyFrameInterpolator::startInterpolation().

Frame keyFrame ( int index ) const

Returns the Frame associated with the keyFrame at index index.

See also keyFrameTime(). index has to be in the range 0..numberOfKeyFrames()-1.

Note: If this keyFrame was defined using a pointer to a Frame (see addKeyFrame(const Frame* const)), the current pointed Frame state is returned.

Definition at line 522 of file keyFrameInterpolator.cpp.

float keyFrameTime ( int index ) const

Returns the time corresponding to the index keyFrame.

See also keyFrame(). index has to be in the range 0..numberOfKeyFrames()-1.

Definition at line 531 of file keyFrameInterpolator.cpp.

float lastTime ( ) const

Returns the time corresponding to the last keyFrame, expressed in seconds.

Returns 0.0 if the path is empty. See also firstTime(), duration() and keyFrameTime().

Definition at line 559 of file keyFrameInterpolator.cpp.

Referenced by KeyFrameInterpolator::addKeyFrame(), and KeyFrameInterpolator::duration().

bool loopInterpolation ( ) const

inline

Returns true when the interpolation is played in an infinite loop.

When false (default), the interpolation stops when interpolationTime() reaches firstTime() (with negative interpolationSpeed()) or lastTime().

interpolationTime() is otherwise reset to firstTime() (+ interpolationTime() - lastTime()) (and inversely for negative interpolationSpeed()) and interpolation continues.

In both cases, the endReached() signal is emitted.

Definition at line 237 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::domElement().

int numberOfKeyFrames ( ) const

inline

Returns the number of keyFrames used by the interpolation.

Use addKeyFrame() to add new keyFrames.

Definition at line 197 of file keyFrameInterpolator.h.

void resetInterpolation ( )

slot

Stops the interpolation and resets interpolationTime() to the firstTime().

If desired, call interpolateAtTime() after this method to actually move the frame() to firstTime().

Definition at line 168 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::firstTime(), KeyFrameInterpolator::setInterpolationTime(), and KeyFrameInterpolator::stopInterpolation().

Referenced by KeyFrameInterpolator::addKeyFrame(), QGLViewer::keyPressEvent(), and Camera::operator=().

void setClosedPath ( bool closed = true )

inlineslot

Sets the closedPath() value.

Attention: The closed path feature is not yet implemented.

Definition at line 261 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::initFromDOMElement().

void setFrame ( Frame *const frame )

slot

Sets the frame() associated to the KeyFrameInterpolator.

Definition at line 67 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::frame(), and KeyFrameInterpolator::interpolated().

Referenced by KeyFrameInterpolator::KeyFrameInterpolator(), and Camera::setFrame().

void setInterpolationPeriod ( int period )

inlineslot

Sets the interpolationPeriod().

Definition at line 256 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::initFromDOMElement(), and KeyFrameInterpolator::startInterpolation().

void setInterpolationSpeed ( float speed )

inlineslot

Sets the interpolationSpeed().

Negative or null values are allowed.

Definition at line 254 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::initFromDOMElement().

void setInterpolationTime ( float time )

inlineslot

Sets the interpolationTime().

Attention: The frame() state is not affected by this method. Use this function to define the starting time of a future interpolation (see startInterpolation()). Use interpolateAtTime() to actually interpolate at a given time.

Definition at line 252 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::initFromDOMElement(), KeyFrameInterpolator::interpolateAtTime(), KeyFrameInterpolator::resetInterpolation(), and KeyFrameInterpolator::startInterpolation().

void setLoopInterpolation ( bool loop = true )

inlineslot

Sets the loopInterpolation() value.

Definition at line 258 of file keyFrameInterpolator.h.

Referenced by KeyFrameInterpolator::initFromDOMElement().

void startInterpolation ( int period = -1 )

slot

Starts the interpolation process.

A timer is started with an interpolationPeriod() period that updates the frame()'s position and orientation. interpolationIsStarted() will return true until stopInterpolation() or toggleInterpolation() is called.

If period is positive, it is set as the new interpolationPeriod(). The previous interpolationPeriod() is used otherwise (default).

If interpolationTime() is larger than lastTime(), interpolationTime() is reset to firstTime() before interpolation starts (and inversely for negative interpolationSpeed()).

Use setInterpolationTime() before calling this method to change the starting interpolationTime().

See the keyFrames example for an illustration.

You may also be interested in QGLViewer::animate() and QGLViewer::startAnimation().

Attention: The keyFrames must be defined (see addKeyFrame()) before you startInterpolation(), or else the interpolation will naturally immediately stop.

Definition at line 138 of file keyFrameInterpolator.cpp.

References KeyFrameInterpolator::interpolationPeriod(), KeyFrameInterpolator::interpolationSpeed(), KeyFrameInterpolator::interpolationTime(), KeyFrameInterpolator::setInterpolationPeriod(), and KeyFrameInterpolator::setInterpolationTime().

Referenced by Camera::interpolateTo(), Camera::interpolateToFitScene(), and Camera::interpolateToZoomOnPixel().

void stopInterpolation ( )

slot

Stops an interpolation started with startInterpolation().

See interpolationIsStarted() and toggleInterpolation().

Definition at line 157 of file keyFrameInterpolator.cpp.

Referenced by KeyFrameInterpolator::deletePath(), KeyFrameInterpolator::initFromDOMElement(), Camera::interpolateTo(), Camera::interpolateToFitScene(), Camera::interpolateToZoomOnPixel(), and KeyFrameInterpolator::resetInterpolation().