Viewer UI Controls

Viewer UI Controls#

QuantEM viewers use the same names for common display chrome. Use explicit keyword arguments for durable APIs, and use ui_mode as a convenience preset for common sharing contexts. Maintainer-only frontend wording and review rules live in Widget UI protocol.

Show2D and Show3D open at size="medium": 450 CSS pixels per image panel.

`size`	Width per image panel	Scale relative to medium
`"small"`	300 px	⅔×
`"medium"` (default)	450 px	1×
`"large"`	600 px	1⅓×
`"xlarge"`	900 px	2×

An ordinary grayscale or RGB image is one panel; a stack uses one panel per stack. Image aspect ratios are preserved. Fonts and controls keep the shared UI scale, and narrow notebook columns reflow panels or constrain their width. Insets scale with their parent image. These sizes never bin the source data or change reconstruction sampling, image zoom, or the FFT frequency range.

Show2D(image)                       # medium, 450 px per panel
Show3D(stacks, size="large")         # 600 px per panel
Show2D(images, size="xlarge")        # 900 px per panel
Show2D(images, panel_width_px=380)   # explicit width overrides size

panel_width_px=None or 0 uses the named preset. Saved manual widths remain intact when restoring viewer state. Static SSB figures use the same relative scale; their export resolution is controlled independently by figure DPI.

Presets#

Preset	Why it exists	Behavior
`ui_mode="interactive"`	Normal notebook analysis.	Full widget UI, controls open, default annotations visible.
`ui_mode="presentation"`	Shared HTML that should open cleanly but remain adjustable.	Controls start collapsed behind `Controls`; stats, resize handles, and zoom badges are hidden where supported. Titles, panel labels, and scale bars stay visible.
`ui_mode="report"`	Clean figure in a report or manuscript-style notebook.	Controls are removed with no GUI recovery button; stats, resize handles, and zoom badges are hidden. Titles, panel labels, and scale bars stay visible.
`ui_mode="minimal"`	Bare visual/GIF-like output.	Title, controls, stats, panel titles, scale bars, resize handles, zoom badges, and equivalent optional chrome are hidden where supported.

Explicit keyword arguments override the preset:

Show2D(
    images,
    ui_mode="presentation",
    show_panel_titles=True,
    show_scale_bar=True,
)

Common Names#

Each name below is a constructor keyword of the widgets listed. A widget that only syncs the name as a trait takes it as an attribute after construction (widget.show_resize_handles = False); those are listed in the last column.

Name	Constructor keyword of	Attribute only	Meaning
`ui_mode`	Show1D, Show2D, Show3D, Show4DSTEM		Preset for the rows below; explicit keywords override it.
`show_title`	Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowDiffraction		Show or hide the top title row.
`show_controls`	Show1D, Show2D, Show4DSTEM, ShowDiffraction	Show3D, Show3DSlices	Expose controls at all. Set `False` for a permanently clean display with no GUI recovery button.
`controls_collapsed`	Show1D, Show2D, Show4DSTEM, ShowDiffraction	Show3D, Show3DSlices	Start with controls hidden behind a top `Controls` button.
`show_stats`	Show1D, Show2D, Show3D, Show4DSTEM, ShowDiffraction		Show or hide mean/min/max/std readouts where the widget renders or computes them.
`show_panel_titles`	Show2D	Show3D	Show labels on individual image/volume panels.
`panel_title_font_size`, `panel_title_style`	Show2D		Font size and JSON-safe title chrome (background, text color, border color/width, padding, radius, max width) for per-panel labels.
`panel_title_spans`	Show2D		Structured colored text spans for panel-title status words; Show3D takes the same spans as `panel_titles` entries.
`panel_annotations`	Show2D, Show3D		Per-panel in-image labels: local callouts, ROI labels, dose/status badges, or region notes that are not the panel title.
`marker_colors`, `marker_style`	Show2D		Per-panel identity colors. `marker_style="around"` draws a color frame with a black inner edge.
`row_markers`, `col_markers`	Show2D		Row/column group frames keyed by zero-based visible row or column slot. Each group draws one rectangle with no internal dividers.
`show_scale_bar`	Show2D, Show3D, Show3DSlices, Show4DSTEM		Show or hide scale bars.
`show_zoom_indicator`	Show2D	Show3D	Opt into the zoom readout; hidden by default so a publication export does not imply a calibrated scale beyond the scale bar.
`show_resize_handles`		Show3D	Show or hide resize handles. Show2D hides them automatically when controls are collapsed.
`show_legend`, `show_grid`	Show1D		Show or hide trace legends and plot grid lines.

Recommended Report Defaults#

Use this for shared HTML reports where collaborators should see clean figures first but can still reopen controls:

widget = Show3D(data, ui_mode="presentation")

Use this for static-looking report embeds where controls should not be recoverable but scientific context should remain:

widget = Show3D(data, ui_mode="report")

Use this for the cleanest visual output:

widget = Show3D(data, ui_mode="minimal")

Prefer explicit overrides instead of new one-off names. For example, use show_scale_bar=False rather than widget-specific spellings like hide_scalebar=True.

Colored status words in panel titles#

Use colored title spans when borders identify a group but the title itself needs a status word, such as low / mid / high dose, under / cal / over regularization, raw vs denoised, or a χ² value. Spans are structured dictionaries, not HTML, so exported offline HTML remains theme-safe and XSS-safe.

from quantem.widget import Show2D, Show3D

status_titles = [
    [
        {"text": "BF denoise  "},
        {"text": "low", "color": "#60a5fa"},
        {"text": "  χ²="},
        {"text": "0.5", "color": "#f59e0b"},
    ],
    [
        {"text": "BF denoise  "},
        {"text": "mid", "color": "#34d399"},
        {"text": "  χ²="},
        {"text": "1.0", "color": "#34d399"},
    ],
    [
        {"text": "BF denoise  "},
        {"text": "high", "color": "#f87171"},
        {"text": "  χ²="},
        {"text": "1.8", "color": "#f87171"},
    ],
]

Show2D(images, labels=status_titles, marker_colors=["#60a5fa", "#34d399", "#f87171"])
Show3D(stack_a, stack_b, stack_c, panel_titles=status_titles)

The plain fallback text is still synced as the normal panel label/title, so panel menus, title-based API lookups, notebook state, and export_html(...) continue to behave like ordinary strings.

Panel frames and title chrome#

Use per-panel markers for individual identity and row/column markers when a whole visual group should share one frame. Row and column keys are zero-based visible grid slots, so hidden panels do not leave ghost group borders.

Show2D(
    images,
    labels=status_titles,
    ncols=3,
    marker_colors=["#60a5fa", "#34d399", "#f87171"],
    marker_style="around",
    row_markers={0: "#60a5fa"},
    col_markers={2: "#f59e0b"},
    panel_title_style={
        "bg": "rgba(0,0,0,0.72)",
        "fg": "#ffffff",
        "border_color": "#60a5fa",
        "border_width": 1,
        "pad_x": 6,
        "pad_y": 2,
        "radius": 2,
        "max_width": "hug",
    },
)

For local region labels inside a panel, use panel_annotations. Longer examples live in the advanced tutorial.