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

virtual	~KeyFrameInterpolator ()

Path creation and modification
bool	add_keyframe (const Frame &frame)
	Appends a new keyframe to the path.

bool	add_keyframe (const Frame &frame, float time)
	Appends a new keyframe to the path, with its associated `time` (in seconds).

void	delete_last_keyframe ()
	Removes the lastly added keyframe from the path.

void	set_keyframe_time (std::size_t index, float t)
	Sets the time corresponding to the `index-th` keyframe.

void	set_keyframe_position (std::size_t index, const vec3 &pos)
	Sets the position of the `index-th` keyframe.

void	set_keyframe_orientation (std::size_t index, const quat &q)
	Sets the orientation of the `index-th` keyframe.

void	delete_path ()
	Removes all keyframes from the path.

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

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

Access keyframe and path parameters
std::size_t	number_of_keyframes () const
	Returns the number of keyframes used by the interpolation.

Frame	keyframe (std::size_t index) const
	Returns the Frame associated with the keyframe at `index`.

float	keyframe_time (std::size_t index) const
	Returns the time corresponding to the `index-th` keyframe.

const vec3 &	keyframe_position (std::size_t index) const
	Returns the position of the `index-th` keyframe.

const quat &	keyframe_orientation (std::size_t index) const
	Returns the orientation of the `index-th` keyframe.

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

float	first_time () const
	Returns the time corresponding to the first keyframe, expressed in seconds.

float	last_time () const
	Returns the time corresponding to the last keyframe, expressed in seconds.

Interpolation
bool	is_interpolation_started () const
	Returns whether the interpolation is being performed.

void	start_interpolation ()
	Starts the interpolation process.

void	stop_interpolation ()
	Stops an interpolation started with start_interpolation().

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.

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.

Interpolation parameters
enum	Method { FITTING , INTERPOLATION }

Method	interpolation_method () const
	Returns the interpolation method.

float	interpolation_speed () const
	Returns the current interpolation speed.

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

int	frame_rate () const
	Returns the desired frame rate. Default value is 30.

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
	Emitted when a frame is interpolated.

Signal	interpolation_stopped
	Emitted when the interpolation is 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 the 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 keyframe 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 a 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 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 sample the viewpoints (as equally as possible).

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();

Todo: Allow edit the duration for each keyframe? (not sure due to many keyframes and can be annoying).

Examples: Tutorial_206_CameraInterpolation/main.cpp.

Member Enumeration Documentation

◆ Method

enum Method

Interpolation method

Enumerator
FITTING	Fit a curve to the keyframes.
INTERPOLATION	Interpolate between keyframes.

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.

Parameters

frame The frame to be associated with the KeyFrameInterpolator.

◆ ~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).

Parameters

frame The frame to be added as a keyframe.

Returns: true if the keyframe has been successfully added.

Examples: Tutorial_204_Viewer_Qt/main.cpp.

◆ 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.

Parameters

frame	The frame to be added as a keyframe.
time	The time associated with the keyframe.

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/main.cpp.

◆ 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

camera	The current camera used by the viewer.
camera_width	Controls 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.
color	The color of the cameras.

◆ 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

camera	The current camera used by the viewer.
thickness	The thickness of the path.
color	The color of the path.

◆ duration()

float duration ( ) const

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

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

Returns: The duration of the path.

See also: keyframe_time().

◆ first_time()

float first_time ( ) const

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

Returns 0.0 if the path is empty.

Returns: The time of the first keyframe.

See also: last_time(), 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.

Returns: The associated Frame.

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.

Returns: The frame rate.

◆ interpolate()

const std::vector< Frame > & interpolate ( )

Computes and returns all the interpolated frames.

Returns: A vector of interpolated frames.

◆ interpolation_method()

Method interpolation_method ( ) const

inline

Returns the interpolation method.

Default value is Interpolation (cubic spline interpolation).

Returns: The interpolation method.

◆ 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.

Returns: The interpolation period in milliseconds.

◆ 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).

Returns: The interpolation speed.

◆ 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.

Returns: true if the interpolation is started, false otherwise.

◆ 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].

Parameters

index The index of the keyframe.

Returns: The Frame associated with the keyframe.

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].

Parameters

index The index of the keyframe.

Returns: The orientation of the keyframe.

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].

Parameters

index The index of the keyframe.

Returns: The position of the keyframe.

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].

Parameters

index The index of the keyframe.

Returns: The time corresponding to the keyframe.

See also: set_keyframe_time().

◆ last_time()

float last_time ( ) const

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

Returns 0.0 if the path is empty.

Returns: The time of the last keyframe.

See also: first_time(), 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.

Returns: The number of keyframes.

◆ read_keyframes()

bool read_keyframes ( const std::string & file_name )

Reads the camera path from a file.

Parameters

file_name The name of the file.

Returns: true if the keyframes were successfully read.

◆ save_keyframes()

bool save_keyframes ( const std::string & file_name ) const

Saves the camera path to a file.

Parameters

file_name The name of the file.

Returns: true if the keyframes were successfully saved.

◆ set_frame()

void set_frame ( Frame *const frame )

inline

Sets the frame() associated to the KeyFrameInterpolator.

Parameters

frame The frame to be associated with the KeyFrameInterpolator.

◆ set_frame_rate()

void set_frame_rate ( int fps )

Sets the desired frame rate.

Parameters

fps	The frame rate.

◆ set_interpolation_method()

void set_interpolation_method ( Method m )

Sets the interpolation_method().

Parameters

m	The interpolation method.

◆ set_interpolation_speed()

void set_interpolation_speed ( float speed )

Sets the interpolation_speed().

Parameters

speed The interpolation speed.

◆ 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].

Parameters

index	The index of the keyframe.
q	The orientation to be set for the keyframe.

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].

Parameters

index	The index of the keyframe.
pos	The position to be set for the keyframe.

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].

Parameters

index	The index of the keyframe.
t	The time to be set for the keyframe.

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/main.cpp.

◆ 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/main.cpp.

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

G:/3_code/Easy3D/easy3d/renderer/key_frame_interpolator.h
G:/3_code/Easy3D/easy3d/renderer/key_frame_interpolator.cpp

Public Member Functions

Interpolation parameters

File io

Detailed Description

Member Enumeration Documentation

◆ Method

Constructor & Destructor Documentation

◆ KeyFrameInterpolator()

◆ ~KeyFrameInterpolator()

Member Function Documentation

◆ add_keyframe() [1/2]

◆ add_keyframe() [2/2]

◆ delete_last_keyframe()

◆ delete_path()

◆ draw_cameras()

◆ draw_path()

◆ duration()

◆ first_time()

◆ frame()

◆ frame_rate()

◆ interpolate()

◆ interpolation_method()

◆ interpolation_period()

◆ interpolation_speed()

◆ is_interpolation_started()

◆ keyframe()

◆ keyframe_orientation()

◆ keyframe_position()

◆ keyframe_time()

◆ last_time()

◆ number_of_keyframes()

◆ read_keyframes()

◆ save_keyframes()

◆ set_frame()

◆ set_frame_rate()

◆ set_interpolation_method()

◆ set_interpolation_speed()

◆ set_keyframe_orientation()

◆ set_keyframe_position()

◆ set_keyframe_time()

◆ start_interpolation()

◆ stop_interpolation()