---

name: scene-and-rendering description: "Configure MolecularNodes Blender scenes, cameras, engines, materials, compositor/world settings, and still or animation renders with host-aware recovery." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Scene and rendering

Use this sub-skill when the scene already contains MolecularNodes entities and the next task is to make a reproducible Blender view, render, snapshot, animation, or annotation overlay. The runtime is a Blender 5.2-compatible bpy host; ordinary Python is useful for planning and validation but is not a substitute for Blender.

Route before editing

• For installation, add-on registration, or package/backend diagnosis, use setup-and-import.
• For loading molecules, styles, selections, or direct style-node edits, use molecules-and-styles; this skill only shows the material and render settings needed after a style exists.
• For trajectory playback or annotation creation, use trajectories-and-annotations.
• For density, CellPack, or ensemble-specific scene contents, use density-and-ensembles.

The detailed contracts are in Canvas API, engines and compositor, and rendering recovery.

Operating contract

Inputs

• A live Blender scene and active camera, plus a bpy.types.Object, MolecularEntity, or entity view/bounding box to frame.
• Optional render choices: engine ("EEVEE", "CYCLES", mn.scene.EEVEE, or mn.scene.Cycles), (width, height), transparency, frame/range, output path, image format, world/compositor edits, and an existing style material socket.
• An explicit host mode: interactive UI, Blender background mode, or the headless bpy module. Do not assume a viewport or a GPU from package facts.

Outputs

• A configured mn.Canvas and camera whose settings can be read back from canvas.scene, canvas.camera, and the engine object.
• A still copied to the exact requested snapshot() path, or an MP4 copied to the exact requested animation() path; callers create parent directories and validate non-zero output. With no path, display is notebook-dependent.
• A validated compositor/world graph and, when enabled, a composited mn_annotations overlay.

Safe default workflow

1. Make the host mode explicit and create canvas = mn.Canvas(engine="EEVEE", resolution=(320, 240), transparent=False, template="Molecular Nodes"). The default/template constructor path is destructive. template=None on the constructor preserves the current scene; call canvas.scene_reset(None) only for an intentional Blender factory-startup reset. Canvas registers the add-on, installs assets, selects the engine, creates a camera helper, and installs the annotation compositor.
2. Obtain the already-created entity from the molecule/style workflow. Do not import structure or trajectory data here.
3. Set reproducible settings before framing: canvas.fps, canvas.frame_range, canvas.frame, canvas.render_scale, canvas.samples, color management, canvas.world.background, canvas.transparent, and the required canvas.passes.
4. In an interactive context with a valid 3D View, frame with canvas.frame_object(entity, viewpoint="front") or canvas.frame_view(entity.get_view(...), viewpoint="front"). In background or headless mode, prepare the camera with the data API or a saved scene; these helpers depend on Blender's view3d operator. Re-frame after changing the lens if a new camera distance is desired.
5. Create the output parent, render with canvas.snapshot(path, frame=..., file_format="PNG"), and validate a non-zero file plus the scene/camera/frame read-back. Use canvas.animation(path, frame_start=..., frame_end=..., render_scale=...) for MP4 output and apply the same file validation.

Camera and engine decisions

• Named viewpoints are default, front, back, top, bottom, left, and right (case-insensitive). canvas.camera.rotation is an XYZ degree tuple; canvas.camera.set_viewpoint() accepts a named view or a custom Euler sequence in radians. Prefer the degree property when writing human-readable angles.
• Use EEVEE for a fast preview with explicitly set samples/ray-tracing and color settings. Use Cycles when path-traced lighting or a Cycles-only style is required; request mn.scene.Cycles(device="CPU") and read back the device for a CPU device selection. This does not claim GPU availability, speed, or universal material compatibility.
• Materials are independent node graphs. Choose a preset or custom material only after the style socket exists. See engines and compositor.

Validation and recovery gates

• Read back canvas.resolution, canvas.render_scale, canvas.frame_range, canvas.frame, canvas.engine.name, canvas.samples, camera rotation/lens, and canvas.passes before rendering.
• canvas.passes = [...] is a replacement set, not an additive update; unknown pass names must be corrected after the resulting ValueError.
• canvas.compositor.reset() is a context manager; enter it with with .... Its reset removes annotations until canvas.compositor.add_annotations() is called. After canvas.world.reset(), the background and hdri_strength convenience sockets are unavailable until the template world node is rebuilt or reloaded.
• In background/headless mode, do not use viewport OpenGL rendering or UI redraw operators, and do not assume camera framing helpers have a 3D View. Prefer a prepared data-API camera plus snapshot()/animation(). In an interactive area, use context overrides only for operators that truly require a window/area/region; UI/viewport behavior remains host-specific.
• If an engine, material, or annotation is invisible, verify the active camera, engine compatibility, frame, material socket, compositor output, and render mode before changing molecule data. See rendering recovery.

Non-goals

This skill does not define structure/trajectory/density import, selection semantics, or the depth of add_style(). It owns only the scene, camera, render, material-selection, compositor/world, snapshot/animation, and Blender context boundary after those upstream objects exist.