ChooseLattice

Pick an ordered origin and two lattice-vector points on a 2D image. Displays a single image, lets you wheel-zoom and drag-pan to inspect a region, and lets you click 3 ordered points whose pixel coordinates (in the ORIGINAL, un-zoomed image) are exposed for downstream lattice-vector calculations.

import numpy as np
from quantem.widget import ChooseLattice

widget = ChooseLattice(image, cmap="gray")

After clicking the origin, then a1, then a2 on the image:

widget.origin   # (row, col) or None
widget.a1       # (row, col) or None
widget.a2       # (row, col) or None
widget.u        # a1 - origin, or None until both are placed
widget.v        # a2 - origin, or None until both are placed
widget.points_array  # (n, 2) array of the picked (row, col) pairs so far

Use set_points(...) / clear_points() to set or reset the picks programmatically.

Reference

class quantem.widget.choose_lattice.ChooseLattice(*args: Any, **kwargs: Any)

Bases: StaticFallbackMixin, AnyWidget

Interactive picker for an ordered origin + two lattice-vector points.

Parameters:

• data (array_like or quantem Dataset2d) – A single 2D image. NumPy, PyTorch, CuPy arrays, or a quantem Dataset2d (its .array/.name are auto-extracted).

• cmap (str, default "gray") – Matplotlib colormap name used to render the image.

• vmin (float, optional) – Explicit display range. Defaults to a robust 1st/99th percentile auto-contrast when not given.

• vmax (float, optional) – Explicit display range. Defaults to a robust 1st/99th percentile auto-contrast when not given.

• log_scale (bool, default False) – Apply a log1p display stretch before contrast scaling.

• title (str, default "") – Title shown above the image. Defaults to a quantem Dataset2d’s .name when not given explicitly.

• point_labels (sequence of str, default ("Origin", "u", "v")) – Labels for the 3 points, in placement order. The first label is shown next to the raw origin point; the second and third are shown next to the derived lattice vectors (see u and v below), not the raw pixel positions of the 2nd/3rd clicks.

• save_state (bool, default False) – Embed full interactive state in the notebook so a cold reopen restores the picked points. See StaticFallbackMixin for the image-only fallback used otherwise.

• notebook_preview_format ({"jpeg", "webp", "png"} or None, default None) – Static preview format used when save_state=False. Defaults to None (no fallback image): unlike Show2D/Show3D, ChooseLattice’s live widget does not reliably hide the saved-notebook fallback sibling while interactive, so enabling it shows a redundant image alongside the live widget. Opt in explicitly if a cold-reopen preview is worth that tradeoff.

• notebook_preview_quality (int, default 88) – Lossy preview quality for JPEG/WebP, from 1 to 100. Ignored for PNG.

• notebook_preview_max_px (int, default 512) – Longest image side for the saved-notebook preview.

Notes

Click on the image to place points in order; once 3 are placed, click near an existing point and drag to adjust it. Use clear_points() (or the “Clear Points” button) to start over. Pixel coordinates are always reported in the ORIGINAL image’s (row, col) space, regardless of the current zoom/pan. The u and v properties expose the lattice vectors a1 - origin and a2 - origin for downstream use.

set_points(points: Sequence[Sequence[float]]) → None

Programmatically set the picked points (up to 3, in order).

clear_points() → None

Remove all picked points.

property points_array: ndarray

Picked points as an (n, 2) array of (row, col) pixel coordinates.

property origin: tuple[float, float] | None

First picked point (row, col), or None if not yet placed.

property a1: tuple[float, float] | None

Second picked point (row, col), or None if not yet placed.

property a2: tuple[float, float] | None

Third picked point (row, col), or None if not yet placed.

property u: tuple[float, float] | None

Lattice vector a1 - origin, or None until both are placed.

property v: tuple[float, float] | None

Lattice vector a2 - origin, or None until both are placed.

Interactive controls

Control	Trait	Expected effect
Click on the image (fewer than 3 points placed)	points	Appends the next ordered point
Drag an existing point	points	Adjusts that point’s pixel coordinates in place
Clear Points button	points	Resets to no points
Pan (drag) / zoom (wheel)	view transform	Image translates / zooms about the cursor
Double-click	view transform	Resets zoom/pan