Reference navigation

On this page

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,
    supersampling=None,
    renderer=None,
    look=None,
    eevee=None,
)

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.
`supersampling`keyword only	`None`	Native and Studio renderers draw each frame at this multiple of the width and height (1, 2, 3, or 4) and average down in linear light. None uses 2 for outputs up to 1920 × 1080 and 1 for larger ones; EEVEE uses EEVEEOptions.supersampling instead.
`renderer`keyword only	`None`	native, studio, or eevee; None inherits the scene setting. render_frame also accepts a renderer instance.
`look`keyword only	`None`	StudioLook for the Studio renderer. None inherits the scene look.
`eevee`keyword only	`None`	EEVEEOptions for the EEVEE renderer. None inherits scene options.

Notes

Subclass and implement construct(). Direct setters are recorded at the current authoring time. Use play() to interpolate. Define renderer and look on the scene class or constructor so CLI, preview, stills and movies agree.

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=None, rate_func=None, easing=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	`None`	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].
`easing`keyword only	`None`	Named easing (smooth, linear, ease_in_out_sine, there_and_back) or callable mapping [0, 1] to [0, 1]. Per-item easing preserves stagger timing.

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,
    screen_position=(0.5, 0.5),
)

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].
`screen_position`keyword only	`(0.5, 0.5)`	Normalized subject position; (0, 0) is top-left and (1, 1) bottom-right.

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, look=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, studio, or eevee; None inherits the scene setting. render_frame also accepts a renderer instance.
`eevee`keyword only	`None`	EEVEEOptions for the EEVEE renderer. None inherits scene options.
`look`keyword only	`None`	StudioLook for the Studio renderer. None inherits the scene look.

Returns: RGBA uint8 image array.

render()

View source

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

Export the timeline to a video file.

Parameter	Default	Description
`output`	Required	Output file path.
`codec`keyword only	`'auto'`	FFmpeg encoder name. auto tries H.264 VideoToolbox on macOS or NVENC elsewhere, then falls back to libx264 with a warning if hardware initialization fails.
`bitrate`keyword only	`'20M'`	Target video bitrate, such as "20M".
`progress`keyword only	`True`	Print frame progress and render timing.
`renderer`keyword only	`None`	native, studio, or eevee; None inherits the scene setting. render_frame also accepts a renderer instance.
`eevee`keyword only	`None`	EEVEEOptions for the EEVEE renderer. None inherits scene options.
`look`keyword only	`None`	StudioLook for the Studio renderer. None inherits the scene look.

Returns: Dictionary containing frames, seconds, fps, platform, adapter, codec, and output. Here fps is render throughput; platform, adapter and codec describe the runtime selection.

preview()

View source

ProteinScene.preview(*, renderer=None, look=None, close_after=None)

Open an interactive preview window. Requires the preview extra.

Parameter	Default	Description
`renderer`keyword only	`None`	native, studio, or eevee; None inherits the scene setting. render_frame also accepts a renderer instance.
`look`keyword only	`None`	StudioLook for the Studio renderer. None inherits the scene look.
`close_after`keyword only	`None`	Optional preview timeout in seconds, for smoke testing.

Returns: None