Skip to content

Python Viewer

These functions are the top-level entry points for launching or preparing viewer sessions from ASE Atoms objects or trajectories.

viewer

High-level Python viewer helpers and controller facades.

QualityPreset(name: str, ico_subdiv: int) dataclass

Python-side viewer fidelity preset.

The preset resolves to the currently supported render-fidelity knobs before the config is passed to Rust. Additional fidelity controls can be added here later without changing the Rust interface.

bevy_viewer(atoms: Atoms | list[Atoms], config: Optional[ViewerConfig] = None) -> None

Open the interactive Bevy viewer and block until it closes.

Parameters:

  • atoms (Atoms or list[Atoms]) –

    Single structure or trajectory to display.

  • config (ViewerConfig, default: None ) –

    Viewer configuration passed to the Rust backend.

launch_viewer(atoms: Atoms | list[Atoms], config: Optional[ViewerConfig] = None) -> ViewerSession

Launch a low-level live viewer session.

Parameters:

  • atoms (Atoms or list[Atoms]) –

    Single structure or trajectory to display.

  • config (ViewerConfig, default: None ) –

    Viewer configuration passed to the Rust backend.

Returns:

  • ViewerSession –

    Low-level Rust-backed session object.

run_viewer_session(atoms: Atoms | list[Atoms], callback, config: Optional[ViewerConfig] = None) -> None

Run a viewer session on the main thread and invoke a callback.

Parameters:

  • atoms (Atoms or list[Atoms]) –

    Single structure or trajectory to display.

  • callback (callable) –

    Callback that receives the low-level session handle while the viewer is running.

  • config (ViewerConfig, default: None ) –

    Viewer configuration passed to the Rust backend.

prepare_viewer_session(atoms: Atoms | list[Atoms], config: Optional[ViewerConfig] = None) -> PreparedViewerSession

Prepare a low-level session that can be started later.

Parameters:

  • atoms (Atoms or list[Atoms]) –

    Single structure or trajectory to display.

  • config (ViewerConfig, default: None ) –

    Viewer configuration passed to the Rust backend.

Returns:

  • PreparedViewerSession –

    Prepared session object that can be launched later.

viewer_session(atoms: Atoms | list[Atoms], config: Optional[ViewerConfig] = None) -> ViewerSessionFacade

Launch a high-level live viewer session.

Parameters:

  • atoms (Atoms or list[Atoms]) –

    Single structure or trajectory to display.

  • config (ViewerConfig, default: None ) –

    Viewer configuration passed to the Rust backend.

Returns:

  • ViewerSessionFacade –

    Python facade exposing camera, appearance, render, and frame controls.

headless_viewer_session(atoms: Atoms | list[Atoms], path: str, width: int = 800, height: int = 600, config: Optional[ViewerConfig] = None) -> PreparedHeadlessRenderFacade

Prepare a headless render session that can be scripted before saving.

Parameters:

  • atoms (Atoms or list[Atoms]) –

    Single structure or trajectory to render.

  • path (str) –

    Output PNG path.

  • width (int, default: 800 ) –

    Output image width in pixels.

  • height (int, default: 600 ) –

    Output image height in pixels.

  • config (ViewerConfig, default: None ) –

    Viewer configuration passed to the Rust backend.

Returns: