Skip to content

Python Sessions

These facades wrap the lower-level Rust-backed session objects and provide the main scripting surface for live and headless workflows.

_session

ViewerSessionFacade(backend, atoms: list[Atoms])

High-level handle for a running viewer session.

This facade keeps a Python-side copy of the loaded frames and exposes controller objects for camera, color, render, and selection operations.

add_image_selection(selection: list[tuple[int, tuple[int, int, int]]], frame_index: int | None = None) -> None

Add image-aware atoms to the selection for a frame.

add_selection(selection, frame_index: int | None = None) -> None

Add atoms to the shared live selection for a frame.

append_frame(frame: Atoms) -> None

Append a new frame to the live trajectory.

Parameters:

  • frame (Atoms) –

    Structure appended to the currently loaded trajectory.

camera() -> CameraController

Return the camera controller for this session.

Returns:

clear_image_selection(frame_index: int | None = None) -> None

Clear the image-aware selection for a frame.

clear_selection(frame_index: int | None = None) -> None

Clear the shared live selection for a frame.

close() -> None

Close the running viewer session.

colors() -> ColorController

Return the color controller for this session.

Returns:

decrement_supercell_axis(axis: int) -> None

Decrease the symmetric repeat extent for one lattice axis.

follow_tail(enabled: bool = True) -> None

Keep the viewer pinned to the newest frame as frames are appended.

Parameters:

  • enabled (bool, default: True ) –

    Whether follow-tail behavior should be enabled.

increment_supercell_axis(axis: int) -> None

Increase the symmetric repeat extent for one lattice axis.

remove_image_selection(selection: list[tuple[int, tuple[int, int, int]]], frame_index: int | None = None) -> None

Remove image-aware atoms from the selection for a frame.

remove_selection(selection, frame_index: int | None = None) -> None

Remove atoms from the shared live selection for a frame.

render() -> RenderController

Return the rendering controller for this session.

Returns:

reset_supercell() -> None

Reset the viewer to the base cell without repeated images.

select(selection, frame_index: int | None = None) -> ViewerSelection

Create a selection object for subset-aware operations.

Parameters:

  • selection –

    Selection expression understood by :func:selection_mask.

  • frame_index (int or None, default: None ) –

    Frame index used when resolving the selection. None uses the current frame.

Returns:

  • ViewerSelection –

    Selection helper that scopes color and render changes to a subset of atoms.

selected_atoms(frame_index: int | None = None) -> list[int]

Return the currently selected atom indices for a frame.

selected_images(frame_index: int | None = None) -> list[dict]

Return the currently selected image-aware atoms for a frame.

set_frame(index: int) -> None

Switch the viewer to a specific frame index.

Parameters:

  • index (int) –

    Zero-based frame index to display.

set_ghost_repeated_images(enabled: bool = True) -> None

Set whether repeated-only images should be ghosted.

set_image_selection(selection: list[tuple[int, tuple[int, int, int]]], frame_index: int | None = None) -> None

Replace the image-aware selection for a frame.

set_selection(selection, frame_index: int | None = None) -> None

Replace the shared live selection for a frame.

set_supercell(repeats: tuple[int, int, int]) -> None

Set symmetric per-axis repeat extents for displayed periodic images.

supercell() -> dict

Return the current supercell display settings.

toggle_supercell_distinction() -> None

Toggle ghosting of repeated-only images.

wait_until_ready(timeout: float | None = None) -> bool

Wait until the viewer reports readiness or the timeout elapses.

Parameters:

  • timeout (float or None, default: None ) –

    Timeout in seconds. None waits indefinitely.

Returns:

  • bool –

    True if the viewer became ready before the timeout expired.

PreparedHeadlessRenderFacade(prepared_backend, atoms: list[Atoms])

Bases: ViewerSessionFacade

High-level facade for a prepared headless render session.

add_image_selection(selection: list[tuple[int, tuple[int, int, int]]], frame_index: int | None = None) -> None

Add image-aware atoms to the selection for a frame.

add_selection(selection, frame_index: int | None = None) -> None

Add atoms to the shared live selection for a frame.

append_frame(frame: Atoms) -> None

Append a new frame to the live trajectory.

Parameters:

  • frame (Atoms) –

    Structure appended to the currently loaded trajectory.

camera() -> CameraController

Return the camera controller for this session.

Returns:

clear_image_selection(frame_index: int | None = None) -> None

Clear the image-aware selection for a frame.

clear_selection(frame_index: int | None = None) -> None

Clear the shared live selection for a frame.

close() -> None

Close the running viewer session.

colors() -> ColorController

Return the color controller for this session.

Returns:

decrement_supercell_axis(axis: int) -> None

Decrease the symmetric repeat extent for one lattice axis.

follow_tail(enabled: bool = True) -> None

Keep the viewer pinned to the newest frame as frames are appended.

Parameters:

  • enabled (bool, default: True ) –

    Whether follow-tail behavior should be enabled.

increment_supercell_axis(axis: int) -> None

Increase the symmetric repeat extent for one lattice axis.

remove_image_selection(selection: list[tuple[int, tuple[int, int, int]]], frame_index: int | None = None) -> None

Remove image-aware atoms from the selection for a frame.

remove_selection(selection, frame_index: int | None = None) -> None

Remove atoms from the shared live selection for a frame.

render() -> RenderController

Return the rendering controller for this session.

Returns:

reset_supercell() -> None

Reset the viewer to the base cell without repeated images.

save() -> None

Render the scripted scene offscreen and write the PNG.

select(selection, frame_index: int | None = None) -> ViewerSelection

Create a selection object for subset-aware operations.

Parameters:

  • selection –

    Selection expression understood by :func:selection_mask.

  • frame_index (int or None, default: None ) –

    Frame index used when resolving the selection. None uses the current frame.

Returns:

  • ViewerSelection –

    Selection helper that scopes color and render changes to a subset of atoms.

selected_atoms(frame_index: int | None = None) -> list[int]

Return the currently selected atom indices for a frame.

selected_images(frame_index: int | None = None) -> list[dict]

Return the currently selected image-aware atoms for a frame.

set_frame(index: int) -> None

Switch the viewer to a specific frame index.

Parameters:

  • index (int) –

    Zero-based frame index to display.

set_ghost_repeated_images(enabled: bool = True) -> None

Set whether repeated-only images should be ghosted.

set_image_selection(selection: list[tuple[int, tuple[int, int, int]]], frame_index: int | None = None) -> None

Replace the image-aware selection for a frame.

set_selection(selection, frame_index: int | None = None) -> None

Replace the shared live selection for a frame.

set_supercell(repeats: tuple[int, int, int]) -> None

Set symmetric per-axis repeat extents for displayed periodic images.

supercell() -> dict

Return the current supercell display settings.

toggle_supercell_distinction() -> None

Toggle ghosting of repeated-only images.

wait_until_ready(timeout: float | None = None) -> bool

Wait until the viewer reports readiness or the timeout elapses.

Parameters:

  • timeout (float or None, default: None ) –

    Timeout in seconds. None waits indefinitely.

Returns:

  • bool –

    True if the viewer became ready before the timeout expired.