ProteinMotion
Reference navigation
On this page

Animate

Build a fluent protein or camera animation through the .animate property.

View sourceGuide and examplesInherits Animation
python
from proteinmotion.animation import Animate

Constructor

python
Animate(target)

Parameters

ParameterDefaultDescription
targetRequiredObject to animate or use as a destination. The supported object type depends on the operation.

Notes

Protein operations include shift(), rotate(), scale(), and set_opacity(). Camera operations include orbit() and zoom(). set_color() returns a separate Colorize animation; focus() returns a Focus animation. Place color and transforms in separate arguments to play().

Example and output

This excerpt runs inside a scene’s construct() method. The full example file includes imports, structure loading, and camera setup. Run it from a repository checkout.

Code Scene excerpt
python
p = ubiquitin()
frame(self, p)
self.play(FadeIn(p), run_time=1)
self.play(Rotate(p, np.pi), run_time=3)
self.play(Representation(p, "ribbon"), run_time=1)
self.play(
    p.animate.shift((5, 0, 0)),
    self.camera.animate.orbit(theta=0.6),
    run_time=2,
)
self.wait(0.5)
Output Preview · 7.5 s · 60 fps
Rotation and movement

Ubiquitin, PDB 1UBQ.

Full source: Motion Download MP4

Methods and properties

NameDescription
requires_linear_timelinepropertyWhether the animation preserves a linear clip clock for staggered item timing.
shift()methodTranslate the object by an offset.
rotate()methodRotate around the molecular centroid.
scale()methodScale around the molecular centroid.
set_opacity()methodSet or animate opacity in [0, 1].
orbit()methodChange horizontal and vertical camera angles.
zoom()methodDivide camera distance by factor. Values greater than 1 zoom in.
depth_cue()methodEase the camera's distance fog to ``strength`` (0 disables it).
set_color()methodApply a tint across all representations. None restores the base palette.
show_atoms()methodShow ball-and-stick detail over the active representation. Chained animations may also change color, opacity, or transforms.
hide_atoms()methodHide ball-and-stick detail while retaining the active representation.
representation()methodAdd a representation transition to this animation chain.
focus()methodFrame a protein or region and optionally track its moving center.
frame()methodAnimate the camera to frame a protein or region over the clip; use lens_focus for depth of field.
set_focus()methodCreate a FocusPull animation for this camera.
lens_focus()methodSet lens focus without changing framing.
bind()methodCapture starting values when the scene schedules the animation.
apply()methodEvaluate the animation at eased progress alpha. Called by the timeline.
during()method · inherited from AnimationSet this animation duration and start delay in seconds.
targetsproperty · inherited from AnimationObjects whose state this animation changes.

requires_linear_timeline

View source
python
Animate.requires_linear_timeline

Whether the animation preserves a linear clip clock for staggered item timing.

shift()

View source
python
Animate.shift(vector)

Translate the object by an offset.

ParameterDefaultDescription
vectorRequiredFinite 3D translation vector in ångströms.

Returns: The object or animation builder.

rotate()

View source
python
Animate.rotate(angle, axis=(0, 1, 0))

Rotate around the molecular centroid.

ParameterDefaultDescription
angleRequiredRotation angle in radians.
axis(0, 1, 0)Nonzero 3D rotation axis; it is normalized internally.

Returns: The protein or animation builder.

scale()

View source
python
Animate.scale(factor)

Scale around the molecular centroid.

ParameterDefaultDescription
factorRequiredPositive scale or zoom factor.

Returns: The protein or animation builder.

set_opacity()

View source
python
Animate.set_opacity(opacity, **kwargs)

Set or animate opacity in [0, 1].

ParameterDefaultDescription
opacityRequiredOpacity in [0, 1], from transparent to opaque.
**kwargs—Additional keyword options described below or in the linked constructor.

Returns: The object or animation builder.

orbit()

View source
python
Animate.orbit(theta=0, phi=0)

Change horizontal and vertical camera angles.

ParameterDefaultDescription
theta0Change in horizontal camera angle, in radians.
phi0Change in vertical camera angle, in radians.

Returns: The camera or animation builder.

zoom()

View source
python
Animate.zoom(factor)

Divide camera distance by factor. Values greater than 1 zoom in.

ParameterDefaultDescription
factorRequiredPositive scale or zoom factor.

Returns: The camera or animation builder.

depth_cue()

View source
python
Animate.depth_cue(strength)

Ease the camera's distance fog to ``strength`` (0 disables it).

ParameterDefaultDescription
strengthRequiredTarget fog strength; 0 disables distance fog.

set_color()

View source
python
Animate.set_color(color, **kwargs)

Apply a tint across all representations. None restores the base palette.

ParameterDefaultDescription
colorRequiredHex color or RGB values. For tint setters, None restores the representation’s base palette.
**kwargs—Additional keyword options described below or in the linked constructor.

Returns: The object or a Colorize animation.

show_atoms()

View source
python
Animate.show_atoms(**kwargs)

Show ball-and-stick detail over the active representation. Chained animations may also change color, opacity, or transforms.

ParameterDefaultDescription
**kwargs—Additional keyword options described below or in the linked constructor.

hide_atoms()

View source
python
Animate.hide_atoms(**kwargs)

Hide ball-and-stick detail while retaining the active representation.

ParameterDefaultDescription
**kwargs—Additional keyword options described below or in the linked constructor.

representation()

View source
python
Animate.representation(style, **options)

Add a representation transition to this animation chain.

ParameterDefaultDescription
styleRequiredHighlight shape or line style; allowed values are specified by the constructor.
**options—Keyword options forwarded to the requested representation or plot.

focus()

View source
python
Animate.focus(
    region,
    *,
    margin=1.25,
    aspect=None,
    follow=True,
    screen_position=(0.5, 0.5),
)

Frame a protein or region and optionally track its moving center.

ParameterDefaultDescription
regionRequiredRegion selection attached to a protein.
marginkeyword only1.25Positive framing margin; larger values leave more space around the target.
aspectkeyword onlyNoneImage width divided by height.
followkeyword onlyTrueTrack the selection’s center after the focus completes.
screen_positionkeyword only(0.5, 0.5)Normalized subject position; (0, 0) is top-left and (1, 1) bottom-right.

Returns: The camera, scene, or Focus animation.

frame()

View source
python
Animate.frame(region, **kwargs)

Animate the camera to frame a protein or region over the clip; use lens_focus for depth of field.

ParameterDefaultDescription
regionRequiredRegion selection attached to a protein.
**kwargs—Additional keyword options described below or in the linked constructor.

set_focus()

View source
python
Animate.set_focus(target, **kwargs)

Create a FocusPull animation for this camera.

ParameterDefaultDescription
targetRequiredProtein, Region, or world point.
**kwargs—FocusPull options, including chain, residues, atoms, fstop and follow.

Returns: FocusPull

lens_focus()

View source
python
Animate.lens_focus(target, **kwargs)

Set lens focus without changing framing.

ParameterDefaultDescription
targetRequiredObject to animate or use as a destination. The supported object type depends on the operation.
**kwargs—Additional keyword options described below or in the linked constructor.

bind()

View source
python
Animate.bind()

Capture starting values when the scene schedules the animation.

Returns: None

Called by ProteinScene.play(). An animation instance can be bound once.

apply()

View source
python
Animate.apply(alpha)

Evaluate the animation at eased progress alpha. Called by the timeline.

ParameterDefaultDescription
alphaRequiredEased animation progress in [0, 1].

Returns: None

during()

View source

Inherited from animation.Animation.

python
Animate.during(seconds, *, delay=0)

Set this animation duration and start delay in seconds.

ParameterDefaultDescription
secondsRequiredPositive animation duration in seconds.
delaykeyword only0Nonnegative animation start delay in seconds.

targets

View source

Inherited from animation.Animation.

python
Animate.targets

Objects whose state this animation changes.