Timeline Python API

Concepts & Classes

Keyframe

Represents a state of an entity at a given time. Here, state does not necessarily pertain to the PyMOL concept of state but any property (transform, PyMOL state, setting, etc…) for a given entity (PyMOL Object or Camera).

Clip

Represents a collection of keyframes that describes an animation over time.

Program

Represents an animation of an object as a function of t. Where t is the interpolation factor from [0, 1] (0 represents the beginning of the animation and 1 represents the end). Visually, they are represented as clips with a keyframe count of two. PyMOL supplies several builtin programs including: nutate, rock, roll, state loop, etc… See Creating Custom Programs below to add complex, custom animations in the timeline.

Track

Represents a set of related keyframes and clips. These keyframes and clips are interpolated to and through each other within the same track and not outside. For each animated property, there shall be one Timeline track.

Composition

Represents a set of tracks. Allows for multiple objects and/or properties to be animated simultaneously.

Sequence Composition

A special composition that only stores clips of “normal” compositions. This is useful to combine multiple compositions into a single animation and blend between them seamlessly. Currently, the blending effect is not yet implemented.

Timeline Python API

General comments of the API

All timeline functions force named-arguments for all parameters of each function. Thus, you must specify the name of the parameter followed by the argument value you want to pass. Examples are shown below. Also, uncommon from the rest of most of the other PyMOL API, builtin types are not commonly passed nor returned. Parameter and return types are specified for each function and a full description of their meaning is explained above. Examples of movies using the Python API can be found at: www.pymol.org.

Explanation of terms

• Arguments: a sequence of named parameters. For the timeline API, all arguments are named; positional arguments are disallowed. No arguments needed are shown by an empty sequence []. Defaulted arguments are shown by a proceeding assignment with value (ex: myParam = “myValue”). All non-defaulted parameters in this sequence must be provided. Sequence representation is for the purpose of documentation only. A sequence is not expected as input for the API.
• Return: a sequence of returned value(s). No returned values are depicted by empty sequence []. Sequence representation is for the purpose of documentation only. A sequence is not expected as input for the API.
• Description: explanation of the use of the API function call.
• Example: brief example of how to use the API.
• Query: As these functions mutate the timeline state, developers may often need to retrieve the current state of a timeline composition or element. These properties can be fetched from a variable that is synchronized with the Timeline backend and doesn’t require a call via `cmd`.
• See Also: Related timeline API calls. Many of these examples could be paired with the presented function.

API

timeline_add_composition

Signature

def timeline_add_composition() -> None

Description

Appends a new composition to the timeline.

Example

myComp = cmd.timeline_add_composition()

See Also

timeline_delete_composition

---

timeline_delete_composition

Signature

def timeline_delete_composition(comp: Composition) -> None

Description

Deletes the composition from the timeline. The composition and all track, clip, and keyframe instances managed under the deleted composition are thus invalidated and should not be used in the API again.

Example

myComp = cmd.timeline_add_composition()
cmd.timeline_delete_composition(comp=myComp)
# myComp now invalidated

See Also

timeline_add_composition

---

timeline_set_composition_duration

Signature

def timeline_set_composition_duration(comp: Composition, duration: int) -> None:

Description

Sets the duration of comp to duration number of frames.

Example

myComp = cmd.timeline_add_composition()
cmd.timeline_set_composition_duration(comp=myComp, duration=120)
# myComp is now 2 seconds (assuming myComp is set to at 60 fps (default))

Query

Duration can be queried by duration.

Example

cmd.timeline_set_composition_duration(comp=myComp, duration=240)
print(myComp.duration) # prints “240”

See Also

timeline_add_composition

---

timeline_scrub_to

Signature

def timeline_scrub_to(comp: Composition, frame_num: int)

Description

Sets the current frame number of the composition to the given frame number. The argument frame_num may be outside the bounds of the composition’s duration but will not be reached during the animation.

Example

myComp = cmd.timeline_add_composition()
cmd.timeline_scrub_to(comp=myComp, frame_num=50)

See Also

timeline_set_composition_duration

---

timeline_add_object_track

Signature

def timeline_add_object_track(comp: Composition, obj_name: str, track_type: TrackType=TrackType.TRANSFORM, track_type_detail: str="") -> Track

Description

Appends a new object track onto comp. obj_name must be a valid name of an object currently managed in PyMOL.

Example

myComp = cmd.timeline_add_composition()
foo_track = cmd.timeline_add_object_track(comp=myComp, obj_name="foo")

See Also

timeline_delete_track

---

timeline_delete_track

Signature

def timeline_delete_track(track: Track) -> None:

Description

Deletes track from its composition. The track and all clip and keyframe instances managed under the deleted track are thus invalidated and should not be used in the API again.

Example

myComp = cmd.timeline_add_composition()
foo_track = cmd.timeline_add_object_track(comp=myComp, obj_name="foo")

See Also

timeline_add_object_track

---

timeline_store_scene_at

Signature

def timeline_store_scene_at(comp: Composition, frame_num: int, scene_name: str) -> Keyframe

Description

Appends a new scene keyframe onto comp at frame frame_num with the scene of name scene_name.

Example

scene_kf = cmd.timeline_store_scene_at(comp=myComp, frame_num=42, scene_name="foo")
cmd.timeline_delete_keyframe(keyframe=scene_kf)

See Also

timeline_add_keyframe

---

timeline_add_keyframe

Signature

def timeline_add_keyframe(track: Track, frame_num: int, obj_state: int = -1) -> Keyframe

Description

Appends a new object keyframe onto track at frame frame_num.

Example

bar_kf = cmd.timeline_add_keyframe(track=foo_track, frame_num=42)

See Also

timeline_add_keyframe

---

timeline_delete_keyframe

Signature

def timeline_delete_keyframe(keyframe: Keyframe) -> None

Description

Deletes a keyframe

Example

bar_kf = cmd.timeline_add_keyframe(track=foo_track, frame_num=42)
cmd.timeline_delete_keyframe(keyframe=bar_kf)

---

timeline_set_keyframe_interpolation

Signature

def timeline_set_keyframe_interpolation(keyframe: Keyframe, interp_mode, KeyframeInterpolationMode) -> None

Description

Describes how the properties between keyframe and the following keyframe are interpolated. By default, virtually all keyframes interpolate linearly (each time step between two keyframe changes in property by the same amount). Values of KeyframeInterpolationMode include:

CONSTANT,

LINEAR,

EASEIN,

EASEOUT,

EASEINOUT

Example

bar_kf = cmd.timeline_add_keyframe(track=foo_track, frame_num=42)
cmd.timeline_set_keyframe_interpolation(keyframe=bar_kf, interp_mode=KeyframeInterpolationMode.LINEAR)

---

timeline_move_keyframe_to

Signature

def timeline_move_keyframe_to(keyframe: Track, frame_num: int) -> None

Description

Moves keyframe to frame frame_num.

Example

bar_kf = cmd.timeline_add_keyframe(track=foo_track, frame_num=42)
cmd.timeline_move_keyframe_to(keyframe=bar_kf, frame_num=24)

See Also

timeline_move_clip_to

---

timeline_move_clip_to

Signature

def timeline_move_clip_to(clip: Clip, frame_num: int)

Description

Moves clip to frame frame_num.

Example

bar_kf = cmd.timeline_add_keyframe(track=foo_track, frame_num=42)
cmd.timeline_delete_keyframe(keyframe=bar_kf)

See Also

timeline_move_keyframe_to

---

timeline_set_clip_duration

Signature

def timeline_set_clip_duration(clip: Clip, duration: int) -> None

Description

Sets the duration of clip to duration frames.

Example

bar_kf = cmd.timeline_add_keyframe(track=foo_track, frame_num=42)
cmd.timeline_delete_keyframe(keyframe=bar_kf)

See Also

timeline_set_clip_speed, timeline_move_clip_to

---

timeline_set_clip_speed

Signature

def timeline_set_clip_speed(clip: Clip, duration: int) -> None

Description

Sets the duration of clip to duration frames.

Example

bar_kf = cmd.timeline_set_clip_speed(track=foo_track, frame_num=42)

See Also

timeline_set_clip_duration, timeline_move_clip_to

---

timeline_register_program

Signature

def timeline_register_program(program_name: str, program_type: object) -> None

Description

Registers the program with program_type type and program_name name to an internal program database. The types are registered so that instances of it can be generated and represented as animation clips on the timeline. After a program is registered, you can store a program using timeline_store_program_at using program_name (case-sensitive) to identify the program.

Example

class Drift:
    def animate(t: float) -> None:
        # ...

cmd.timeline_register_program(program_name="drift", program_type=Drift)

See Also

timeline_store_program_at

---

timeline_store_program_at

Signature

def timeline_store_program_at(track: Track, frame_num: int, duration: int, program: Union[object, str]) -> Clip

Description

Adds an animation clip described by program onto track at frame frame_num for duration frames.

Example

cmd.timeline_register_program(program_name="drift", program_type=Drift)
cam_track = myComp.get_main_camera_track()
cmd.timeline_store_program_at(track=cam_track, frame_num=60, duration=360, program="drift")

See Also

timeline_register_program

Notes

To customize the properties of a program, instantiate a program, edit its properties, and provide it to the function. Example:

roll_prg= pymol.timeline_programs.Roll(cam_track)
roll_prg.num_loops = 2
clip = cmd.timeline_store_program_at(track=cam_track, frame_num=60, duration=360, program=roll_prg)

Since the program itself is agnostic to the duration of the clip that it’s stored in, in order to change the duration of the program, change the clip’s duration instead via timeline_set_clip_duration.

---

timeline_produce (NOT YET SUPPORTED)

Signature

def timeline_produce(comp: Composition, render_mode: str = "draw", first_frame: int = None, last_frame: int = None, encoder: str = None, width: int = None, height: int = None, quality: int=100, quiet: bool=False)

[comp: Composition, render_mode: str = "draw", first_frame: int = None, last_frame: int = None, encoder: str = None, width: int = None, height: int = None, quality: int=100, quiet=False]

Description

Exports a comp to a playable movie (file format determined by encoder).

Example

cmd.movie.timeline_produce(comp=comp)