Viewer controls

The marimol viewer includes rich interactive 3D navigation, atom picking, and measurement capabilities:

Rotate: Left-click and drag anywhere on the canvas to rotate the 3D structure.
Zoom: Scroll with the mouse wheel (or pinch on trackpads) to zoom in and out.
Pan / Move: Right-click and drag to translate the camera view across the screen without moving the center of rotation.
Snap to Axis: Click on the X, Y, or Z label on the bottom-left coordinate triad to instantly align the camera along that principal Cartesian axis.
Atom Selection & Inspection:
- Single Selection: Left-click any atom to select it. The atom is highlighted with a cyan ring, and an info card appears at the bottom right displaying its index, element symbol, and Cartesian coordinates ||([x, y, z]||).
- Multi-Selection: Hold Shift while clicking atoms to select or deselect multiple atoms.
- Deselect: Click anywhere on the empty background (without Shift) to clear the selection.
Reactive Python State:
- The returned widget connects directly to marimo's reactive graph!
- viewer.selected_atoms: A Python list of integers containing the 0-based indices of all currently selected atoms (e.g. [0, 2]). Whenever you click atoms in the viewer, any downstream marimo cells referencing viewer.selected_atoms automatically re-execute.
- viewer.current_frame: An integer indicating the currently active frame index (0-indexed) during trajectory playback.
Measurement Tool:
- Click the Ruler icon in the top-right overlay to toggle measurement mode:
  - Click 2 atoms to measure the interatomic distance (||(\text{Å}||)).
  - Click 3 atoms to measure the bond angle (||(^\circ||)).
  - Click 4 atoms to measure the dihedral / torsion angle (||(^\circ||)).
- Click the ruler button again or click empty canvas space to exit measurement mode.
Extra Data Drawer:
- Click the List icon in the top-right overlay to expand the metadata drawer, showing properties such as unit cell volume, density, lattice parameters (||(a, b, c, \alpha, \beta, \gamma||)), atom counts, or custom calculation results.
Capture & Recording Tools (added in v0.2.0):
- Click the Camera icon (or press S) to save a high-resolution PNG screenshot directly to your downloads.
- Click the Video icon (or press R) to record WebM/MP4 animations of trajectory playback or auto-spin, or to record your manual interactions with the structure.
Help & Controls Overlay (added in v0.2.0):
- Press the H key while hovering over the viewer or click the Question Mark icon in the top-right overlay to display an interactive summary of all navigation, selection, measuring, recording, trajectory, and axis controls.
Trajectory Controls:
- When visualizing a list of frames, a media player overlay appears with buttons for First, Previous, Play/Pause, Next, and Last frame, as well as an optional scrubbable frame slider.

Viewer arguments

All viewer functions (view_structure, view_ase, view_pymatgen, view_cspy) accept the following configuration parameters:

Parameter	Type	Default	Description
`data` / `atoms` / `structure`	`dict` \| `list[dict]`	Required	Structure dictionary or list of dictionaries (or `ase.Atoms`, `pymatgen.core.Structure`, `cspy.Crystal` / `cspy.Molecule`).
`config`	`dict` \| `str` \| `PathLike`	`None`	Reusable configuration dictionary, TOML string, or path to a TOML file. Explicit keyword arguments will override config values. (added in v0.2.0)
`style`	`str` \| `dict`	`"ball-and-stick"`	Visual representation style: `"ball-and-stick"`, `"vdw"`, `"wireframe"`, or a custom style dictionary.
`background_color`	`str`	`"white"`	Viewport background color (e.g. `"white"`, `"black"`, `"transparent"`, `"#1e1e1e"`).
`show_axes`	`bool`	`False`	Whether to display the interactive XYZ coordinate triad in the bottom-left corner.
`projection`	`str`	`"orthographic"`	Camera projection type: `"orthographic"` (parallel projection, ideal for crystallography and measurements) or `"perspective"`.
`width`	`str`	`"100%"`	CSS width of the viewer container (e.g. `"100%"`, `"600px"`).
`height`	`str`	`"400px"`	CSS height of the viewer container (e.g. `"400px"`, `"500px"`).
`viewer_outline`	`bool` \| `str`	`False`	Draws a border around the viewer container. Set `True` for a subtle grey outline or pass a CSS border string (e.g. `"1px solid #ccc"`).
`fog`	`bool`	`False`	Enables distance fog effect for depth cueing in large lattices.
`fog_strength`	`float`	`0.5`	Strength of the fog effect (0.0 to 1.0).
`clip_distance`	`float`	`0.0`	Near camera clipping plane distance in Å. If `0.0` (default), near clipping is disabled. If positive, clips atoms closer to the camera than this distance. (added in v0.3.0)
`draw_outlines`	`bool`	`False`	Draws stylized cartoon / cel-shaded silhouette outlines around atoms and bonds.
`draw_labels`	`bool`	`False`	Displays element/index labels on top of atoms with 3D occlusion testing.
`measuring_tool`	`bool`	`False`	Enables the ruler button in the top-right overlay for distance, angle, and dihedral measurements.
`unwrap_molecules`	`bool`	`False`	Unwraps molecules split across periodic unit cell boundary conditions and centers whole molecules inside the cell. Since v0.3.1, by setting this to `False`, the bond computation is also forced to be done without periodic conditions.
`structure_transparency`	`float`	`0.0`	Transparency level for atoms and bonds between 0.0 (completely opaque) and 1.0 (fully transparent), useful for viewing internal vectors. (added in v0.3.0)
`vector_width`	`float`	`0.08`	Shaft radius / width for 3D vector arrows. (added in v0.3.0)
`vector_outline`	`bool` \| `str`	`False`	Whether to draw outlines around 3D vector arrows (or outline color string). (added in v0.3.0)
`vector_color`	`str`	`"red"`	Default color name or hex code for 3D vector arrows. (added in v0.3.0)
`spin`	`bool`	`False`	Enables continuous automatic 3D rotation of the structure.
`spin_axis`	`tuple[float, float, float]`	`(0.0, 1.0, 0.0)`	Cartesian 3D axis vector around which the structure rotates during auto-spin.
`spin_speed`	`float`	`2.0`	Angular rotation speed for auto-spin (positive for clockwise, negative for counter-clockwise).
`multi_traj`	`bool`	`True`	Displays trajectory media playback controls (play/pause) for multi-frame data.
`traj_fps`	`float`	`10.0`	Playback speed in frames per second for trajectory animations.
`trajectory_slider`	`bool`	`False`	Displays a scrubbable timeline slider in the trajectory control bar.
`compute_extra_data`	`bool`	`False`	Automatically computes physical/crystallographic properties (density, volume, lattice lengths & angles, atom count, molecular weight) for the info drawer.
`extra_data`	`Callable[[T], dict]`	`None`	Custom callable accepting the structure/object and returning a dictionary of metadata for the extra data drawer (only available in `view_ase`, `view_pymatgen`, `view_cspy`). (added in v0.3.0)
`show_help`	`bool`	`True`	Whether to show the help button and enable the 'h' interaction help overlay. (added in v0.2.0)
`recording_tools`	`bool`	`False`	Whether to show screenshot (PNG) and animation video recording (WebM/MP4) buttons in the viewer toolbar. (added in v0.2.0)
`dpi`	`int`	`200`	Resolution in dots per inch (DPI) for exported screenshots and video recordings. (added in v0.2.0)
`record_include_bgd`	`bool`	`False`	Whether to include the viewer's background color in exported screenshots and video recordings (default is `False` for transparent backgrounds). (added in v0.2.0)
`record_include_ui`	`bool`	`False`	Whether to include all viewer UI elements (playback controls, info panels, measurements, labels) in exported screenshots and video recordings. (added in v0.2.0)

Custom Style Dictionaries

When specifying a custom dict for the style argument, you can configure:

custom_style = {
    "bond_radius": 0.12,              # Cylinder radius for bonds in Angstroms (0.0 hides bonds)
    "atomic_radius_scaler": 0.8,       # Scale factor multiplied by atomic/VdW radii
    "hydrogen_atom_radius": 0.2,       # Fixed radius override for hydrogen atoms
    "fixed_atomic_radius": None,       # If set, gives all non-H atoms a fixed radius in Angstroms
    "use_vdw_radii": False,            # True uses Van der Waals radii; False uses covalent radii
}

Data structure

marimol operates natively on a clean dictionary format. If you are not using ASE, Pymatgen, or mol-cspy, you can pass structures directly using standard Python dictionaries:

structure_dict = {
    # [Required] Cartesian coordinates in Angstroms (Nx3 list)
    "positions": [
        [0.0, 0.0, 0.0],
        [0.0, 0.0, 1.089],
        [1.026, 0.0, -0.363],
        [-0.513, -0.889, -0.363],
        [-0.513, 0.889, -0.363],
    ],

    # [Required] Chemical element symbols or atomic numbers
    "species": ["C", "H", "H", "H", "H"],

    # [Optional] Explicit covalent bonds (auto-computed if omitted and bond_radius > 0)
    "bonds": [
        {"source": 0, "target": 1},
        {"source": 0, "target": 2},
        {"source": 0, "target": 3},
        {"source": 0, "target": 4},
    ],

    # [Optional] 3x3 lattice vectors in Angstroms for periodic crystal structures
    "unit_cell": [
        [10.0, 0.0, 0.0],
        [0.0, 10.0, 0.0],
        [0.0, 0.0, 10.0],
    ],

    # [Optional] Custom atom text labels when draw_labels=True
    "labels": ["C_center", "H1", "H2", "H3", "H4"],

    # [Optional] List of atom indices to highlight with an outline
    "highlight": [0],

    # [Optional] Arbitrary key-value metadata shown in the extra data drawer
    "extra_data": {
        "energy": -40.512,
        "point_group": "Td",
    },

    # [Optional] 3D vector arrows (e.g. dipole moments, forces, spins) *(added in v0.3.0)*
    "vectors": [
        # Arrow starting at atom 0 pointing in a given direction with explicit length
        {"origin": 0, "direction": [0.0, 0.0, 1.0], "length": 1.5, "color": "yellow", "width": 0.10, "outline": True},
        # Arrow between two Cartesian coordinate positions or atom indices
        {"origin": [0.0, 0.0, 0.0], "end": [1.0, 1.0, 0.0], "color": "cyan"},
    ],

    # [Optional] Frame-level vector defaults *(added in v0.3.0)*
    "vector_width": 0.08,
    "vector_outline": False,
    "vector_color": "red",
}

Trajectories

A trajectory is simply a Python list[dict] containing multiple structure dictionaries in sequence:

trajectory_data = [frame_0, frame_1, frame_2, ...]

Examples

Below are examples showcasing different data formats, visual styles, and viewer capabilities. Click View Code on any example to expand its implementation. You can also run and explore dedicated interactive example notebooks in the examples/ folder by running:

uv run just examples