Scene¶

Qualified name: algan.scene.Scene

class Scene(video_settings=None, background=None, memory=None, scene_initializer=None, *, premultiplied_over=False)[source]¶

Bases: RenderLoopMixin

The container that turns recorded animations into rendered video.

A Scene owns its actor registry, camera, lights, timeline, animation contexts, audio state, and render loop. Creating one pushes it onto the process-global SceneManager stack, making it the destination for mobs constructed without an explicit scene.

Rendering (get_frames(), from RenderLoopMixin) proceeds in batches of frames sized to the memory budget: for each batch this scene’s timeline materializes every actor’s animated state at the batch’s frame times, actors produce render primitives, and the ray tracer renders and post-processes the frames, which are streamed to the video writer. Batch preparation for the next batch runs concurrently on a worker thread (ALGAN_PREFETCH_BATCHES=0 disables).

Parameters:

video_settings (VideoSettings | None) – Resolution / fps / quality settings (see algan.settings.video_settings).
background (Color | str | torch.Tensor | Callable | None) – What the Scene is drawn on: a color, an image tensor, or a procedural callable. A Taichi @ti.func uses the scalar (x, y, time) -> color contract and is evaluated at render time. Python callables passed through the render APIs receive broadcastable Torch tensors; the direct constructor calls a Python callable once, with a coordinate grid. Defaults to None, meaning SETTINGS.style.background. It is the same background set_background() sets and save_video(background=...) overrides for one render.
memory – Optional ManualMemory render arena.
scene_initializer – Callable run on (re)creation; the default spawns the camera and a point light.
premultiplied_over (bool) – Export transparent frames for linear-light over compositing, keeping glow additive. Defaults to False. See set_premultiplied_over() for the required color settings and consumer interpretation.

Methods

`add_actor`	Register a Mob with this Scene so it takes part in rendering.
`add_effect`	Register an audio effect with this Scene.
`add_light`	Add a light to this Scene.
`background_is_transparent`	Whether the Scene's background has any transparency.
`clear_lights`	Remove every light from this Scene.
`current`	Get the Scene currently being authored.
`despawn_mobs`	Despawn every spawned Mob in the Scene.
`get_background`	Get the Scene's current background.
`get_camera`	Get this Scene's camera.
`get_light_sources`	Get this Scene's lights.
`length_to_pixels`	Convert a world-space length to a length in rendered pixels.
`pixels_to_length`	Convert a length in rendered pixels to a world-space length.
`remove_light`	Remove a light from this Scene.
`render_all_funcs`	Render discovered scene functions in isolated Scene contexts.
`reset`	Empty the Scene completely and start over.
`save_audio`	Mix this Scene's audio effects down to an audio file.
`save_frame`	Render one or more still frames from this Scene.
`save_video`	Render everything recorded on this Scene to a video file.
`set_background`	Set what the Scene is drawn against.
`set_environment_map`	Light the Scene with an environment map, and show it as a backdrop.
`set_premultiplied_over`	Export coverage and additive glow together for linear compositing.
`set_video_settings`	Set this Scene's resolution, frame rate and anti-aliasing.
`show_frame`	Render one frame and display it, for interactive work.
`use_manim_defaults`	Set this Scene up the way Manim sets its scenes up.
`view`	Open this Scene in the interactive viewer.
`wait`	Hold the scene still for a while.

Attributes

premultiplied_over

Whether frames are exported for linear-light over compositing; see set_premultiplied_over(), which owns the setting.

add_actor(actor)[source]¶

Mob constructors call this for you; you only need it for a Mob built with add_to_scene=False that you later decide to render.

Parameters:: actor – The Mob to register. Ignored if the Scene is no longer accepting actors (during a render).
Returns:: This Scene, so calls can be chained.
Return type:: Scene

add_effect(effect)[source]¶

The Audio and Speech contexts use this; the effect’s own start time decides where it lands in the finished video.

Parameters:: effect – The AudioEffect to add.
Returns:: This Scene, so calls can be chained.
Return type:: Scene

add_light()[source]¶

Add a light to this Scene.

Lights only affect Mobs whose material responds to light – a MeshBasicMaterial looks the same however the scene is lit. Adding the same light twice does nothing.

Animation

Not animated: the light exists from this point in the timeline onwards.

Parameters:: light – The light to add.
Returns:: The light that was added, so it can be kept and animated.
Return type:: Light

background_is_transparent()[source]¶

Whether the Scene’s background has any transparency.

This decides the output format: a transparent background makes save_video() write .mov with an alpha channel instead of .mp4. A procedural background is always treated as opaque.

Returns:: Whether any background pixel is less than fully opaque.
Return type:: bool

clear_lights()[source]¶

Remove every light from this Scene.

Lit materials go black afterwards unless a new light or an environment map is added.

Animation

Not animated: the lights stop contributing from this point in the timeline onwards.

Returns:: This Scene, so calls can be chained.
Return type:: Scene

static current()[source]¶

Get the Scene currently being authored.

Creates the default Scene on first use, so this never returns None.

Returns:: The active Scene.
Return type:: Scene

despawn_mobs(retain_history=False, runtime=None, **kwargs)[source]¶

Despawn every spawned Mob in the Scene.

Parents are despawned before their children, so composite Mobs disappear as a unit rather than in pieces.

Animation

Recorded as an animation: all the despawns run together inside a Sync, over the current context’s runtime (1 second by default) unless runtime overrides it.

Parameters:

retain_history (bool) – Whether to keep the fully despawned actors whose earlier lifespan still has to render, and discard the rest. Defaults to False, which leaves Scene.actors alone. True is what a scene-ending fade wants: actors that never acquired a complete lifespan are dropped.
runtime (float | None) – Seconds the despawn takes, overriding the current context. Defaults to None, meaning use the context’s runtime.
**kwargs – Passed to each despawn() – notably animate=False to remove everything without fading.

Returns:

This Scene, so calls can be chained.

Return type:

Scene

get_background()[source]¶

Get the Scene’s current background.

Returns:: Whatever the background was set to: a color, an image tensor, or a procedural callable.
Return type:: Color or torch.Tensor or Callable

get_camera()[source]¶

Get this Scene’s camera.

Returns:: The camera, or None if the Scene has not been initialized with one.
Return type:: Camera

get_light_sources()[source]¶

Get this Scene’s lights.

Returns:: The live list of registered lights; mutating it changes the Scene.
Return type:: list[Light]

length_to_pixels(length)[source]¶

Convert a world-space length to a length in rendered pixels.

Parameters:: length (float) – Length in world units.
Returns:: The equivalent number of pixels at the Scene’s current resolution.
Return type:: float

pixels_to_length(length)[source]¶

Convert a length in rendered pixels to a world-space length.

Parameters:: length (float) – Length in pixels.
Returns:: The equivalent length in world units at the Scene’s current resolution.
Return type:: float

remove_light()[source]¶

Remove a light from this Scene.

Removing a light that is not registered does nothing.

Animation

Not animated: the light stops contributing from this point in the timeline onwards.

Parameters:: light – The light to remove.
Returns:: The light that was passed in.
Return type:: Light

static render_all_funcs(*args, **kwargs)[source]¶: Render discovered scene functions in isolated Scene contexts.

reset(rebuild_timeline=True)[source]¶

Empty the Scene completely and start over.

Drops all actors, audio effects, the camera and the lights, then re-runs the Scene initializer, which puts the default camera and lighting back. With the default rebuild_timeline=True time also returns to zero and the timeline, animation and audio managers are rebuilt, so nothing recorded so far survives, and Mob references from before the reset are invalid and must not be reused. Other Scenes on the SceneManager stack are untouched.

Animation

Not animated, and destructive: this discards the recording rather than animating anything out.

Parameters:: rebuild_timeline (bool) – Whether to reset time and rebuild the timeline, animation and audio managers as well as the contents. Defaults to True; False rebuilds the contents only and leaves the recording in place.
Returns:: This Scene, so calls can be chained.
Return type:: Scene

save_audio(file_path, sample_rate=44100, codec='pcm_s32le', nbytes=4)[source]¶

Mix this Scene’s audio effects down to an audio file.

Every registered effect is placed at its recorded start time and the result is written out. save_video() does this for you; call it directly only when you want the audio on its own.

Parameters:

file_path (str | Path) – Where to write the audio.
sample_rate (int) – Sample rate in Hz. Defaults to 44100.
codec (str) – FFmpeg audio codec. Defaults to 'pcm_s32le' (uncompressed).
nbytes (int) – Bytes per sample. Defaults to 4.

Returns:

The path written, or None if the Scene has no audio effects.

Return type:

str or pathlib.Path or None

save_frame(video_settings=None, at=None, *, overwrite=True, background=None, post_processes=None)[source]¶

Render one or more still frames from this Scene.

Unlike save_video() this never modifies the Scene: nothing is despawned, the timeline is left as authored, and any temporary video settings or background are restored before returning. Call it as often as you like while building a scene.

Parameters:

file_path (str | Path | None) – Where to write the image. A bare filename is placed in Algan’s output directory; a path with a parent directory is used as given; a path naming a directory (one that exists, or that ends with a separator) has SETTINGS.paths.output_filename placed inside it. A missing extension defaults to .png. Defaults to None, meaning SETTINGS.paths.output_filename. The path actually written is reported, absolute, as result.output_path.
video_settings (VideoSettings | None) – Resolution and anti-aliasing for this still only, normally a preset such as HD. Defaults to None, meaning the Scene’s current settings.
at (float | Sequence[float] | None) – Timestamp in seconds to capture, or a sequence of timestamps to capture several stills in one call. A negative timestamp is an offset backwards from the current authoring time, so -0.5 captures half a second before the current context’s cursor. Resolved timestamps must be finite and non-negative. Defaults to None, capturing just after the current authoring time – i.e. the scene as it stands.
overwrite (bool) – Whether an existing file at the destination is replaced. Defaults to True; False leaves it alone and reports "skipped".
background (Color | str | torch.Tensor | Callable | None) – A color, image, or procedural callable, applied to this still only. Defaults to None, meaning keep the Scene’s background. See set_background() for the callable’s contract – it runs on the render device and is handed broadcastable grids, not scalars.
post_processes – Post-processing passes to apply to the frame, as in save_video(). Defaults to None, meaning bloom. Pass () for no post-processing, or a tuned pass such as partial(bloom_filter, glow_spread=0.015) to narrow the glow.

Returns:

One result per still, with status ("rendered" or "skipped"), output_path and walltime_seconds. A list is returned only when at is a sequence, matching the shape of the input.

Return type:

RenderResult or list of RenderResult

Examples

Scene.save_frame("thumbnail", HD)
Scene.save_frame("shot.png", at=2.5)
Scene.save_frame("previous.png", at=-0.5)
Scene.save_frame("contact_sheet", at=[0, 1, 2])

save_video(video_settings=None, *, overwrite=True, reset=False, background=None, animate_fade_out=None, post_processes=None, codec=None, audio_codec=None, ffmpeg_params=None)[source]¶

Render everything recorded on this Scene to a video file.

Parameters:

file_path (str | Path | None) – Where to write the video. A bare filename such as "my_video" is placed in Algan’s output directory; a path with a parent directory, relative or absolute, is used exactly as given; a path naming a directory (one that exists, or that ends with a separator) has SETTINGS.paths.output_filename placed inside it. If the name has no extension Algan appends .mp4, or .mov when the background is transparent. Defaults to None, meaning SETTINGS.paths.output_filename. The path actually written is reported, absolute, as result.output_path.
video_settings (VideoSettings | None) – Resolution, frame rate and anti-aliasing for this render, normally one of the presets (PREVIEW, LD, MD, HD, PRODUCTION, UHD). Applies to this render only; the Scene’s own settings are restored afterwards. Defaults to None, meaning SETTINGS.video.
overwrite (bool) – Whether an existing file at the destination is replaced. Defaults to True; False skips rendering and returns a "skipped" result.
reset (bool) – Whether to tear the Scene down after rendering: discard its recorded animation, despawn its mobs and rebuild its timeline, animation and audio managers. Mobs created before the render become unusable. Defaults to False, which leaves the Scene exactly as authored, so you can keep animating and render again – including from inside a with block that has not finished yet. A mid-block render covers everything recorded so far and changes nothing, so the final render is the same as if the preview had never happened.
background (Color | str | torch.Tensor | Callable | None) – A color, image, or procedural callable (x, y, time) -> color. Python callables run on the render device and receive broadcastable Torch tensors, not scalars – see set_background() for the exact shapes and the two traps (build constants with x.new_tensor; keep the leading frame axis). A Taichi @ti.func receives scalar normalized coordinates and time and must return a color vector; it is evaluated for the whole render batch by one Taichi kernel writing directly into the output buffer. Defaults to None, meaning keep the Scene’s background.
animate_fade_out (bool | None) – Whether to fade every spawned mob out at the end of the video. Recorded on the timeline, so it persists even when reset is False. Defaults to None, meaning SETTINGS.style.fade_out_on_scene_end (False).
post_processes – Post-processing passes to apply to each frame. Defaults to None, meaning bloom.
codec (str | None) – Encoder overrides passed through to FFmpeg. Each defaults to None, letting Algan pick from the background’s transparency. With no explicit codec, Algan encodes with libx264 or – when the machine’s NVIDIA driver exposes NVENC – the hardware h264_nvenc encoder; set the ALGAN_VIDEO_ENCODER environment variable to software or nvenc to pin that choice (see Saving Videos and Images). A transparent background picks from the container instead: lossless png for .mov (also .mkv, .avi), and libvpx-vp9 for .webm, whose alpha rides in a 4:2:0 chroma plane and so is lossy at object edges. .mp4 cannot carry alpha at all and is refused before the render.
audio_codec (str | None) – Encoder overrides passed through to FFmpeg. Each defaults to None, letting Algan pick from the background’s transparency. With no explicit codec, Algan encodes with libx264 or – when the machine’s NVIDIA driver exposes NVENC – the hardware h264_nvenc encoder; set the ALGAN_VIDEO_ENCODER environment variable to software or nvenc to pin that choice (see Saving Videos and Images). A transparent background picks from the container instead: lossless png for .mov (also .mkv, .avi), and libvpx-vp9 for .webm, whose alpha rides in a 4:2:0 chroma plane and so is lossy at object edges. .mp4 cannot carry alpha at all and is refused before the render.
ffmpeg_params (list[str] | None) – Encoder overrides passed through to FFmpeg. Each defaults to None, letting Algan pick from the background’s transparency. With no explicit codec, Algan encodes with libx264 or – when the machine’s NVIDIA driver exposes NVENC – the hardware h264_nvenc encoder; set the ALGAN_VIDEO_ENCODER environment variable to software or nvenc to pin that choice (see Saving Videos and Images). A transparent background picks from the container instead: lossless png for .mov (also .mkv, .avi), and libvpx-vp9 for .webm, whose alpha rides in a 4:2:0 chroma plane and so is lossy at object edges. .mp4 cannot carry alpha at all and is refused before the render.

Returns:

Metadata with status ("rendered" or "skipped"), output_path, walltime_seconds and the resolved render_plan.

Return type:

RenderResult

Examples

Scene.save_video("my_video")  # LD into algan_outputs/
Scene.save_video("my_video", HD)  # one-off quality override
Scene.save_video("renders/final.mov")  # explicit directory

set_background(overwrite=True)[source]¶

Set what the Scene is drawn against.

Animation

Not animated: the background changes for the whole video, not from this point onwards, since it is Scene state rather than timeline state. For a one-off render, pass background to save_video() instead.

Parameters:

background (Color | str | Tensor | Callable | None) –
A color, a path to an image (scaled to the frame), or a procedural callable (x, y, time) -> color. A color with alpha below 1 makes the output transparent. None leaves the background unchanged.

The callable is evaluated on the render device and receives broadcastable grids, not scalars: x is [1, width, 1] and y is [height, 1, 1], both in [0, 1) with y = 0 at the bottom of the frame, and time is [frames, 1, 1, 1] in seconds. It must return either a resolution-free color or a tensor broadcasting to [frames, height, width, channels] – so build constants with x.new_tensor(...) (not torch.tensor, which lands on the CPU) and keep the leading frame axis, e.g. by multiplying a per-pixel term by torch.ones_like(time). Both are easy to miss; the failure modes are a device-mismatch RuntimeError and “callable background must produce one value per supersampled pixel”.
overwrite (bool) – Whether to replace a background that has already been set. Defaults to True; False makes the call a no-op once a background exists, which is how defaults are applied without stomping a user’s choice.

Returns:

This Scene, so calls can be chained.

Return type:

Scene

Examples

def vignette(x, y, t):
    r2 = (x - 0.5) ** 2 + (y - 0.5) ** 2
    fade = torch.exp(-r2 * 4) * torch.ones_like(t)
    return x.new_tensor((0.02, 0.03, 0.08)) * fade

Scene.save_frame("shot", background=vignette)

set_environment_map(intensity=1.0, ambient=True)[source]¶

Light the Scene with an environment map, and show it as a backdrop.

An equirectangular image surrounds the scene, so reflective and metallic materials pick up their surroundings instead of reflecting a void – the cheapest way to make metal look like metal.

The map is also the backdrop: rays that hit no geometry sample it, so it replaces background rather than sitting behind it. Only the camera’s share of the map is visible (the frustum’s solid angle), and the map is downsampled above 2048 texels wide, so bake the backdrop into it at a resolution that accounts for that if the backdrop carries detail.

Animation

Not animated: the map applies from this point in the timeline onwards.

Parameters:

source –
Path to an image file, or an image tensor of shape [height, width, >=3]. None removes the current map.

Byte-ranged sources – an image file, or an integer-dtype tensor – are divided by 255. A float tensor is taken as authored, so values above 1 are kept: that is what makes a light source in the map brighter than white, which is the whole point of an HDR environment. Author in whatever units you like and use intensity to set the overall level.
intensity (float) – Brightness multiplier for the map’s contribution. Defaults to 1.0.
ambient (bool) – Whether the map also provides ambient light to non-reflective surfaces, rather than only appearing in reflections. Defaults to True.

Returns:

This Scene, so calls can be chained.

Return type:

Scene

Raises:

FileNotFoundError – If source is a path that cannot be read.
ValueError – If the image is not shaped [height, width, >=3].

set_premultiplied_over()[source]¶

Export coverage and additive glow together for linear compositing.

Transparent output keeps bloom out of coverage alpha and stores the sRGB encoding of linear premultiplied light, including color at zero alpha. Decode RGB directly to linear light before applying src + dst * (1 - alpha); do not divide by alpha during that decode. MOV defaults to ProRes 4444, with 8-bit source precision. Ordinary viewers generally do not interpret these samples correctly.

Requires linear color, post-process tonemapping, and no nonlinear tone curve. Incompatible settings raise an error when rendering transparent output. The setting is ignored for opaque backgrounds. Bloom comes from the exported layer only; it does not reproduce backdrop-dependent bloom from every opaque render.

Animation

Takes effect immediately for the whole Scene and is not animated. Can be changed before or after spawning mobs, and survives reset().

Parameters:: enabled (bool) – Whether to enable this export interpretation. Defaults to True; new Scenes default to False.
Returns:: This Scene, so calls can be chained.
Return type:: Scene
Raises:: .AlganConfigurationError – If enabled is not a boolean.

Examples

Export one clip for a linear-light compositor:

from algan import *

Scene.set_background(TRANSPARENT)
Scene.set_premultiplied_over()
Circle(color=YELLOW, glow=1.0).spawn()
Scene.save_video("glow.mov")

set_video_settings(_explicit=True)[source]¶

Set this Scene’s resolution, frame rate and anti-aliasing.

video_settings is a VideoSettings instance, usually one of the built-in presets (PREVIEW, LD, MD, HD, PRODUCTION, UHD).

They apply to every render of this Scene that does not name settings of its own – save_video() and save_frame() alike – and are outranked only by a video_settings argument to one of those calls.

Most scripts do not need this: pass video_settings to save_video() / save_frame() for a one-off render, or set SETTINGS.video for a process-wide default.

Parameters:: _explicit (bool)

show_frame(at=None)[source]¶

Render one frame and display it, for interactive work.

Meant for a notebook or REPL: it plots the frame rather than writing a file. Use save_frame() to save one instead.

Animation

Not animated and non-destructive: rendering a frame leaves the Scene as authored.

Parameters:: at (float | None) – Time to render, in seconds. Defaults to None, meaning just after the current authoring time – i.e. the scene as it stands.
Returns:: The frame(s) that were plotted, as (channels, height, width) tensors with values in [0, 1].
Return type:: list[torch.Tensor]

use_manim_defaults(*, shading=True, background=True, video_settings=False, shape_defaults=False, stroke_geometry=True)[source]¶

Set this Scene up the way Manim sets its scenes up.

Call it once, before building the Scene, and geometry authored against Manim’s conventions – most obviously anything arriving through ManimMob – lands on the pixels Manim would have put it on: same 8-unit frame height, same perspective, same light position, same black background.

Manim’s frame is 8 world units tall and its ThreeDCamera sits 20 units from the frame plane, which is a vertical field of view of 22.62 degrees. Manim’s plain 2-D camera is a flat orthographic projection, but the two agree exactly at z = 0, so this one perspective camera reproduces 2-D scenes exactly and 3-D scenes with Manim’s own perspective.

Manim’s OUT and Algan’s OUTWARD are both +z, so imported geometry needs no coordinate conversion and none is applied.

Animation

Not animated: the Scene is reconfigured immediately, at the point in the timeline where the call happens. Call it before spawning anything.

Parameters:

camera (bool) – Whether to move the camera to Manim’s viewpoint and set its field of view. Defaults to True.
shading (bool) –
Whether to reproduce Manim’s color pipeline: its single light in its own position, ManimMaterial as the default material for 3-D Mobs with none of their own – reproducing the shading Manim’s get_shaded_rgb applies to anything flagged shade_in_3d, which ManimMob carries across so even a flat Cube face is lit – no tonemapping, so a flat fill comes out byte-identical to Manim’s, and Manim’s display-referred working color space, since Manim composites alpha and antialiases in sRGB rather than in linear light. Defaults to True.

The color space is process-wide and changes every render, not only Manim-derived content, and it compiles a separate set of GPU kernels, so the first render after switching pays a cold compile. It is also effectively a process-start decision: the renderer folds it into its kernels at compile time, so switching it after something has already rendered in this process leaves those kernels in the old space while the rest of the pipeline moves to the new one – a measured ~24/255 disagreement. Calling this method once at the top of a script, as intended, is before any render and is safe. To be certain in a process that renders more than once, set ALGAN_LINEAR_COLOR=0 in the environment instead, or pass shading=False here and leave the space alone.
background (bool) – Whether to set the background to black, Manim’s default. Defaults to True.
video_settings (bool) – Whether to also switch the output to Manim’s default 1920x1080 at 60 fps. Defaults to False, so an explicitly chosen quality preset survives the call. Only the aspect ratio affects framing.
shape_defaults (bool) – Whether Algan’s own shapes (Square, Circle, …) also adopt Manim’s default colors and stroke styling. Defaults to False, since it changes shapes that have nothing to do with Manim.
stroke_geometry (bool) – Whether strokes are laid out Manim’s way rather than Algan’s, in the two respects the engines disagree on. Placement (SETTINGS.style.border_placement): a filled shape’s stroke straddles its outline as Manim’s does instead of running inward as Algan’s does, which otherwise puts a Manim shape’s silhouette half a stroke width inside where Manim draws it. Width (SETTINGS.style.manim_stroke_width_ratio): the compatibility layer converts stroke widths by the exact 2.0202 rather than Algan’s round 2, which is otherwise 1.01% too wide. Defaults to True. Neither changes a stroke’s authored color or width, so both are safe for shapes that never came from Manim – but they are process-wide, so pass False to leave other Scenes alone.

Returns:

This Scene, so calls can be chained.

Return type:

Scene