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.
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`).
`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).
`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.
`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.

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 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",
    },
}

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.