Reference navigation

On this page

CLASS · v0.9.1

ProteinScene

Define a protein animation as a sequence of play() and wait() calls.

from proteinmotion import ProteinScene

Constructor

ProteinScene(*, width=1920, height=1080, fps=30, background='#0b1220', msaa=4)

Parameters

Parameter	Default	Description
`width`keyword only	`1920`	Image width in pixels.
`height`keyword only	`1080`	Image height in pixels.
`fps`keyword only	`30`	Video frames per second; must be positive.
`background`keyword only	`'#0b1220'`	Background color as a hex string or RGB values.
`msaa`keyword only	`4`	Multisample count: 1 or 4.

Notes

Subclass ProteinScene and implement construct(). Configure initial geometry, styles, and camera pose before the first play() or wait(). Concurrent animations can change separate properties.

Attributes

Name	Description
`camera`	Camera used by the scene.
`duration`	Total timeline duration in seconds.
`width, height`	Output dimensions in pixels.
`fps`	Frames per second.

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

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

Name	Description
construct()method	Override this method to define the scene with add(), play(), wait(), and camera setup.
add()method	Add proteins, density objects, or annotations at the current timeline time.
play()method	Run animations together, then advance the timeline by run_time seconds.
focus()method	Animate camera focus using the scene’s output aspect ratio.
wait()method	Extend the timeline while holding the current state.
build()method	Call construct() once and prepare the timeline.
seek()method	Evaluate the scene at a time clamped to its duration. Supports forward and backward seeks.
render_frame()method	Render one point on the timeline to an image.
render()method	Export the timeline to a video file.
preview()method	Open an interactive preview window. Requires the preview extra.

construct()

View source

ProteinScene.construct()

Override this method to define the scene with add(), play(), wait(), and camera setup.

Returns: None

add()

View source

ProteinScene.add(*proteins)

Add proteins, density objects, or annotations at the current timeline time.

Parameter	Default	Description
`*proteins`	—	Protein or annotation objects to add or render.

play()

View source

ProteinScene.play(*animations, run_time=1.0, rate_func=None)

Run animations together, then advance the timeline by run_time seconds.

Parameter	Default	Description
`*animations`	—	Animation objects to run together.
`run_time`keyword only	`1.0`	Clip duration in seconds; must be positive.
`rate_func`keyword only	`None`	Callable that maps progress in [0, 1] to a finite value in [0, 1].

Returns: The scene.

Animations that write the same object property concurrently raise ValueError. Create a new animation object for each play() call.

focus()

View source

ProteinScene.focus(target, *, run_time=1.5, margin=1.25, follow=True, rate_func=None)

Animate camera focus using the scene’s output aspect ratio.

Parameter	Default	Description
`target`	Required	Object to animate or use as a destination. The supported object type depends on the operation.
`run_time`keyword only	`1.5`	Clip duration in seconds; must be positive.
`margin`keyword only	`1.25`	Positive framing margin; larger values leave more space around the target.
`follow`keyword only	`True`	Track the selection’s center after the focus completes.
`rate_func`keyword only	`None`	Callable that maps progress in [0, 1] to a finite value in [0, 1].

Returns: The scene.

wait()

View source

ProteinScene.wait(duration=1.0)

Extend the timeline while holding the current state.

Parameter	Default	Description
`duration`	`1.0`	Hold duration in seconds; must be nonnegative.

Returns: The scene.

build()

View source

ProteinScene.build()

Call construct() once and prepare the timeline.

Returns: The scene.

seek()

View source

ProteinScene.seek(time)

Evaluate the scene at a time clamped to its duration. Supports forward and backward seeks.

Parameter	Default	Description
`time`	Required	Timeline position in seconds.

Returns: List of visible objects.

render_frame()

View source

ProteinScene.render_frame(time=0.0, *, output=None, renderer=None, eevee=None)

Render one point on the timeline to an image.

Parameter	Default	Description
`time`	`0.0`	Timeline position in seconds.
`output`keyword only	`None`	Output file path.
`renderer`keyword only	`None`	"native", "eevee", an existing renderer instance, or None for native.
`eevee`keyword only	`None`	Optional EEVEEOptions instance; requires renderer="eevee".

Returns: RGBA uint8 image array.

render()

View source

ProteinScene.render(
    output,
    *,
    codec='auto',
    bitrate='20M',
    progress=True,
    renderer='native',
    eevee=None,
)

Export the timeline to a video file.

Parameter	Default	Description
`output`	Required	Output file path.
`codec`keyword only	`'auto'`	FFmpeg encoder name; auto selects hardware H.264 on macOS when available.
`bitrate`keyword only	`'20M'`	Target video bitrate, such as "20M".
`progress`keyword only	`True`	Print frame progress and render timing.
`renderer`keyword only	`'native'`	"native" (default) or "eevee".
`eevee`keyword only	`None`	Optional EEVEEOptions instance; requires renderer="eevee".

Returns: Dictionary containing frames, seconds, fps, adapter, codec, and output. Here fps is render throughput.

preview()

View source

ProteinScene.preview()

Open an interactive preview window. Requires the preview extra.

Returns: None