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() -> Composition
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_add_sequence_composition
Signature
def timeline_add_sequence_composition() -> Composition
Description
- Appends a new sequence composition to the Timeline.
Example
mySeqComp = cmd.timeline_add_sequence_composition()
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)