Easy3D 2.5.3
KeyFrameInterpolator Class Reference

A keyframe interpolator for animation generation. More...

#include <easy3d/renderer/key_frame_interpolator.h>

Public Member Functions

 KeyFrameInterpolator (Frame *frame=nullptr)
 Creates a KeyFrameInterpolator, with frame as associated frame(). More...
 
virtual ~KeyFrameInterpolator ()
 
Path creation and modification
bool add_keyframe (const Frame &frame)
 Appends a new keyframe to the path. More...
 
bool add_keyframe (const Frame &frame, float time)
 Appends a new keyframe to the path, with its associated time (in seconds). More...
 
void delete_last_keyframe ()
 Removes the lastly added keyframe from the path. More...
 
void set_keyframe_time (std::size_t index, float t)
 Sets the time corresponding to the index-th keyframe. More...
 
void set_keyframe_position (std::size_t index, const vec3 &pos)
 Sets the position of the index-th keyframe. More...
 
void set_keyframe_orientation (std::size_t index, const quat &q)
 Sets the orientation of the index-th keyframe. More...
 
void delete_path ()
 Removes all keyframes from the path. More...
 
Associated Frame
Frameframe () const
 Returns the associated Frame and that is interpolated by the KeyFrameInterpolator. More...
 
void set_frame (Frame *const frame)
 
Access keyframe and path parameters
std::size_t number_of_keyframes () const
 Returns the number of keyframes used by the interpolation. More...
 
Frame keyframe (std::size_t index) const
 Returns the Frame associated with the keyframe at index. More...
 
float keyframe_time (std::size_t index) const
 Returns the time corresponding to the index-th keyframe. More...
 
const vec3keyframe_position (std::size_t index) const
 Returns the position of the index-th keyframe. More...
 
const quatkeyframe_orientation (std::size_t index) const
 Returns the orientation of the index-th keyframe. More...
 
float duration () const
 Returns the duration of the KeyFrameInterpolator path, expressed in seconds. More...
 
float firstTime () const
 Returns the time corresponding to the first keyframe, expressed in seconds. More...
 
float lastTime () const
 Returns the time corresponding to the last keyframe, expressed in seconds. More...
 
Interpolation
bool is_interpolation_started () const
 Returns whether the interpolation is being performed. More...
 
void start_interpolation ()
 Starts the interpolation process. More...
 
void stop_interpolation ()
 Stops an interpolation started with start_interpolation(). More...
 
void toggle_interpolation ()
 Calls start_interpolation() or stop_interpolation(), depending on is_interpolation_started().
 
const std::vector< Frame > & interpolate ()
 Computes and returns all the interpolated frames.
 
Path drawing
void draw_cameras (const Camera *camera, float camera_width, const vec4 &color=vec4(0.5f, 0.8f, 0.5f, 1.0f))
 Draws the virtual 3D cameras for the keyframes. More...
 
void draw_path (const Camera *camera, float thickness=2.0f, const vec4 &color=vec4(1.0f, 1.0f, 0.5f, 1.0f))
 Draws the interpolated camera path. More...
 

Interpolation parameters

enum  Method { FITTING , INTERPOLATION }
 
Method interpolation_method () const
 Returns the interpolation method. More...
 
float interpolation_speed () const
 Returns the current interpolation speed. More...
 
int interpolation_period () const
 Returns the current interpolation period, expressed in milliseconds. More...
 
int frame_rate () const
 Returns the desired frame rate. Default value is 30. More...
 
void set_interpolation_method (Method m)
 Sets the interpolation_method().
 
void set_interpolation_speed (float speed)
 Sets the interpolation_speed().
 
void set_frame_rate (int fps)
 Sets the desired frame rate.
 

File io

Signal frame_interpolated
 
Signal interpolation_stopped
 
bool save_keyframes (const std::string &file_name) const
 saves the camera path to a file
 
bool read_keyframes (const std::string &file_name)
 reads camera path from a file
 

Detailed Description

A keyframe interpolator for animation generation.

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

A keyframes is defined by a Frame and a time, expressed in seconds. The time has to be monotonously increasing over keyframes. When interpolation_speed() 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 keyframe_time().

When the user start_interpolation(), a timer is started which will update the frame()'s position and orientation every interpolation_period() milliseconds. This update increases the time by interpolation_period() * interpolation_speed() milliseconds. This mechanism ensures that the number of interpolation steps is constant and equal to the total path duration() divided by the interpolation_period() * interpolation_speed(). This is especially useful for benchmarking or movie creation (constant number of snapshots).

During the interpolation, the KeyFrameInterpolator emits an frame_interpolated Signal which will usually be connected to the viewer's update() method. The interpolation is stopped when duration has reached. Another Signal interpolation_stopped will be emitted when the interpolation reaches its end or the when the stop_interpolation() method was triggered.

Note that a Camera has a keyframe_interpolator() method, that can be used to drive the Camera along a path, or to restore a saved position (a path made of a single keyframe).

Note
The default duration of any two consecutive keyframes is the same. So for a smoother animation, it is suggested to regularly (as equally as possible) sample the viewpoints.
Attention
If a Constraint is attached to the frame() (see Frame::constraint()), it should be deactivated before is_interpolation_started(), otherwise the interpolated motion (computed as if there was no constraint) will probably be erroneous.

Animation example:

// the KeyFrameInterpolator kfi is given the camera's frame that it will be driven over time.
kfi = new KeyFrameInterpolator( camera()->frame() );
kfi->add_keyframe(...);
kfi->add_keyframe(...);
// ...and so on for all the keyframes.
// starts animation
kfi->start_interpolation();
KeyFrameInterpolator(Frame *frame=nullptr)
Creates a KeyFrameInterpolator, with frame as associated frame().
Definition: key_frame_interpolator.cpp:55
Frame * frame() const
Returns the associated Frame and that is interpolated by the KeyFrameInterpolator.
Definition: key_frame_interpolator.h:180
Todo:
Allow edit the duration for each keyframe? (not sure due to many keyframes and can be annoying).
Examples
Tutorial_206_CameraInterpolation.

Constructor & Destructor Documentation

◆ KeyFrameInterpolator()

KeyFrameInterpolator ( Frame frame = nullptr)
explicit

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

The frame() can be set or changed using set_frame(). The interpolation_speed() and interpolation_period() are set to their default values.

◆ ~KeyFrameInterpolator()

~KeyFrameInterpolator ( )
virtual

Virtual destructor. Clears the keyframe path.

Member Function Documentation

◆ add_keyframe() [1/2]

bool add_keyframe ( const Frame frame)

Appends a new keyframe to the path.

Same as add_keyframe(const Frame&, float), except that the keyframe_time() is automatically set to previous keyframe_time() plus one second (or 0.0 if there is no previous keyframe).

Returns
true if the keyframe has been successfully added.
Examples
Tutorial_204_Viewer_Qt.

◆ add_keyframe() [2/2]

bool add_keyframe ( const Frame frame,
float  time 
)

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

The path will use the current frame state.

Returns
true if the keyframe has been successfully added.
Attention
The keyframe_time() have to be monotonously increasing over keyframes.

◆ delete_last_keyframe()

void delete_last_keyframe ( )

Removes the lastly added keyframe from the path.

This is the reverse operation of add_keyframe(const Frame&) and add_keyframe(const Frame&, float).

◆ delete_path()

void delete_path ( )

Removes all keyframes from the path.

Upon return, the number_of_keyframes() will return 0.

Examples
Tutorial_204_Viewer_Qt.

◆ draw_cameras()

void draw_cameras ( const Camera camera,
float  camera_width,
const vec4 color = vec4(0.5f, 0.8f, 0.5f, 1.0f) 
)

Draws the virtual 3D cameras for the keyframes.

Parameters
cameraThe current camera used by the viewer.
camera_widthControls the size of the cameras. A good value can be 5% of the scene radius, or 10% of the character height (in walking mode), for instance.

◆ draw_path()

void draw_path ( const Camera camera,
float  thickness = 2.0f,
const vec4 color = vec4(1.0f, 1.0f, 0.5f, 1.0f) 
)

Draws the interpolated camera path.

Parameters
cameraThe current camera used by the viewer.

◆ duration()

float duration ( ) const

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

The duration simply corresponds to lastTime() - firstTime(). It returns 0.0 if the path has less than 2 keyframes.

See also
keyframe_time().

◆ firstTime()

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 keyframe_time().

◆ frame()

Frame * frame ( ) const
inline

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

The returned Frame was set using set_frame() or with the KeyFrameInterpolator constructor. When is_interpolation_started(), this Frame's position and orientation will regularly be updated by a timer, so that they follow the KeyFrameInterpolator path.

See also
set_frame()

◆ frame_rate()

int frame_rate ( ) const
inline

Returns the desired frame rate. Default value is 30.

The frame_rate() multiplied by interpolation_period() is always equal to 1.0.

◆ interpolation_method()

Method interpolation_method ( ) const
inline

Returns the interpolation method.

Default value is Interpolation (cubic spline interpolation).

◆ interpolation_period()

int interpolation_period ( ) 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 is_interpolation_started(). This period (multiplied by interpolation_speed()) will be added to be the next frame's time. The interpolation_period() multiplied by frame_rate() is always equal to 1.0.

◆ interpolation_speed()

float interpolation_speed ( ) const
inline

Returns the current interpolation speed.

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

◆ is_interpolation_started()

bool is_interpolation_started ( ) const
inline

Returns whether the interpolation is being performed.

Use start_interpolation(), stop_interpolation() or toggleInterpolation() to modify this state.

◆ keyframe()

Frame keyframe ( std::size_t  index) const

Returns the Frame associated with the keyframe at index.

The index has to be in the range [0, number_of_keyframes()-1].

See also
keyframe_time()

◆ keyframe_orientation()

const quat & keyframe_orientation ( std::size_t  index) const

Returns the orientation of the index-th keyframe.

The index has to be in the range [0, number_of_keyframes()-1].

See also
set_keyframe_orientation()

◆ keyframe_position()

const vec3 & keyframe_position ( std::size_t  index) const

Returns the position of the index-th keyframe.

The index has to be in the range [0, number_of_keyframes()-1].

See also
set_keyframe_position()

◆ keyframe_time()

float keyframe_time ( std::size_t  index) const

Returns the time corresponding to the index-th keyframe.

The index has to be in the range [0, number_of_keyframes()-1].

See also
set_keyframe_time().

◆ lastTime()

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 keyframe_time().

◆ number_of_keyframes()

std::size_t number_of_keyframes ( ) const
inline

Returns the number of keyframes used by the interpolation.

Use add_keyframe() to add new keyframes.

◆ set_frame()

void set_frame ( Frame *const  frame)
inline

Sets the frame() associated to the KeyFrameInterpolator.

◆ set_keyframe_orientation()

void set_keyframe_orientation ( std::size_t  index,
const quat q 
)

Sets the orientation of the index-th keyframe.

The index has to be in the range [0, number_of_keyframes()-1].

See also
keyframe_time()

◆ set_keyframe_position()

void set_keyframe_position ( std::size_t  index,
const vec3 pos 
)

Sets the position of the index-th keyframe.

The index has to be in the range [0, number_of_keyframes()-1].

See also
keyframe_time()

◆ set_keyframe_time()

void set_keyframe_time ( std::size_t  index,
float  t 
)

Sets the time corresponding to the index-th keyframe.

The index has to be in the range [0, number_of_keyframes()-1].

Note
The time t have to be monotonously increasing over keyframes.
See also
keyframe_time()

◆ start_interpolation()

void start_interpolation ( )

Starts the interpolation process.

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

Note
The keyframes must be defined (see add_keyframe()) before you start_interpolation(), or else the interpolation will naturally immediately stop.
Examples
Tutorial_204_Viewer_Qt.

◆ stop_interpolation()

void stop_interpolation ( )

Stops an interpolation started with start_interpolation().

See also
start_interpolation(), is_interpolation_started(), and toggleInterpolation().
Examples
Tutorial_204_Viewer_Qt.

The documentation for this class was generated from the following files: