Keyframe

This is just a draft. Please before edit it, consider that this is an important wiki page and it should be as good as possible.

What is a keyframe?

A keyframe is a basically a "mark" in the timeline. This mark allows the user to make synfig remember the state of the animation at that point (frame). It means that the keyframe is like a label that tell synfig that this frame should be taken account when creating waypoints. Also it is a mark to a special frame where the information of every parameter in the animation is stored there in order to be reused later.

A keyframe is associated to a particular frame and a frame only can have one keyframe.

What does a keyframe looks like?

A keyframe looks like a light brown vertical dashed line in the timetrack dialog placed at the corresponding frame. You can distinguish it from the time cursor by its color (the time cursor is blue).

Also a keyframe looks like an entry in a list in the Keyframes Dialog (fix keyframe dialog to explain better the columns of the dialog)

Keyframes and waypoints

A keyframe doesn't necessarily imply a waypoint, and a waypoint doesn't necessarily imply a keyframe.

A keyframe could live all the time without any waypoint but it stores the information of the values of the parameters on that specific frame. If there is a waypoint there then the waypoint information is stored too. If there is no waypoint in the keyframe then its "stored" value is the result of the surrounding waypoints, its parameter values and the interpolation values the waypoints have. This means that a keyframe remember the values of the paramters at that frame but would not keep them static at that frame. To maintain a parameter value static in a certain frame you must use a waypoint.

Anyway the creation of a waypoint implies possible creation of new waypoints on the neighbour keyframes depending on what's the current value of the Lock Keyframes state. So, maybe , the creation of a waypoint (modifying a parameter or pasting or moving a waypoint or even duplicating a keyframe) can create a waypoint in the the keyframes that are around the inserted waypoint. The waypoint created in the neighbour keyframes are created applying the interpolation method stated by default interpolation value in the toolbox window.

See the examples to understand how it works.

Creating, copying, pasting, deleting or duplicating keyframes

Create a keyframe: Place the cursor at a frame where there isn't currently any keyframe. Then press the Add new keyframe button. If you place the time cursor ar a frame where there is currently an existing keyframe then the Add keyframe button is disabled. Once you press the button then a new entry is added in the list of keyframes and a vertical dahsed line is added in the time line. None waypoint is created.

Duplicate a keyframe: Select a keyframe in the keyframe list of the Keyframes Dialog and place the cursor at a frame where there isn't currently any keyframe. Then press the duplicate button. This would have two separated effects:

1. For each object and for each parameter in that object: If there is a waypoint at the original keyframe then the waypoint is duplicated. Its duplication include the parameter value and its interpolation values.
2. If there is no waypoint in the original keyframe for any particular parameter then it could happen two things:
   1. There is no waypoint for that parameter at ANY frame in the time line: Then NONE waypoint is created.
   2. If there is any waypoint for that parameter in the time line then in the duplicated keyframe is created a new waypoint with a value for the parameter of the result of the current value at the original waypoint and a TBC Smooth interpolation type for both "In" and "Out". (it seems a bug? it should create a waypoint with the current selected default interpolation method?)

Copy/Paste: It does what it supposed to do. With copy you make a copy of the current selected keyframe (from the keyframe list dialog) and stores it on the clipboard. With paste you insert a copy of the last keyframe stored in the clipboard. You paste the keyframe where the time cursor says and it is only enabled if there is not any existing keyframe in the frame where the cursor is.

Editing keyframes: time & description

WIP

Editing keyframes: Properties dialog

WIP

Examples

Duplicate a keyframe with no waypoint on it

For example, imagine that you have following set of keyframes and waypoints and the corresponding parameter of the radius of a circle:

Before duplicate keyframe at 6s

Frame	Keyframe	Waypoint	Radius	Interpolation
0s	yes	yes	20.0	TCB Smooth
2s	yes	no	25.0	n/a
4s	yes	no	30.0	n/a
8s	no	yes	40.0	TCB Smooth

notice that althought the intepolation between 0s and 8s is TCB Smooth the real result 
is linear due that they are the only two waypoints of the animation for that paramter.

If you select the keyframe at 2s, place the time cursor at 6s (where there isn't a keyframe), set the default interpolation to TCB Smooth, and have the lock keyframe status to All keyframes locked and press the duplicate keyframe button, then the result is the following:

After duplicate keyframe at 6s

Frame	Keyframe	Waypoint	Radius	Interpolation
0s	yes	yes	20.0	TCB Smooth
2s	yes	no	25,78125	n/a
4s	yes	yes	30.0	TCB Smooth
6s	yes	yes	25.0	TCB Smooth
8s	no	yes	40.0	TCB Smooth

You can see that:

1. At 0s none has changed. Not affected by the insertion of the keyframe. It is two keyframes away from 6s and also have a waypoint.
2. At 2s there was a keyframe and stills there. But previous to the creation of the keyframe at 6s the current interpolated value of the radius was 25.0. After the creation of the keyframe at 6s the radius is the result of the interpolation between 0s and 4s frames waypoints with its radius values and its interpolation methods. That is 25.78125. This keyframe is one keyframe away the new 6s keyframe so no waypoint is created.
3. At 4s there was a keyframe and still being there. But in this case the 4s keyframe is a neighbour of the new 6s keyframe. As well as the lock keyframe state was set to All keyframes locked then the keyframe at 4s has been locked adding a waypoint on it. The radius value hasn't changed (still being 30.0) becasue it was locked adding a waypoint with its current value). The Interpolation mode of the waypoint was set to TCB Smooth as stated by its default value.
4. At 6s there is a new keyframe with a new waypoint with the old value of the interpolated value of the keyframe at 2s. That is a radius of 25.0.
5. At 8s nothing has changed. There wasn't any keyframe and thre was a waypoint so nothing is expected to change.

Imagine now that you repeat the same operations but you choose the default interpolation set to Constant. Then the result is the following:

Caption

Frame	Keyframe	Waypoint	Radius	Interpolation
0s	yes	yes	20.0	TCB Smooth
2s	yes	no	20.0	n/a
4s	yes	yes	30.0	Constant
6s	yes	yes	25.0	TCB Smooth
8s	no	yes	40.0	TCB Smooth

Now you can see that the keyframe at 2s doesn't hold the value of the parameter by itself. It only remember the value if a waypoint is created on it by the result of the insertion of a neighbour waypoint or keyframe, or if a keyframe is duplicated. In this case the value at 2s has changed drastically due to the different interpolation method for the created waypoint on 4s.

Advanced uses of keyframes

WIP