ShowBragg widget for interactive Bragg-vector analysis

[henryhng]

What problem does this solve?

quantem.diffraction.BraggVectors is a Bragg disk analysis pipeline, but tuning each of those 6 stages requires a manual notebook loop in choosing and adjusting parameters.

ShowBragg changes that workflow and makes it an interactive widget. Lightweight operations like template generation and basis selection update immediately as controls change, while more expensive operations such as disk detection and lattice fitting are triggered by buttons.

A live demo of the ShowBragg widget can be found here.

This makes a 4D-STEM dataset and a fitted BraggVectors object interactive in that they can be used to construct a StrainMap, while keeping the scientific workflow in the Python analysis layer.

What should reviewer(s) do?

1. Confirm that a Dataset4dstem can be tuned, detected, fitted through the widget.

   widget = ShowBragg(dataset)
   widget.detect()
   widget.fit()

2. Confirm no scientific state duplicatation (see src/quantem/widget/showbragg.py)

   peaks, bvm, and basis proxy directly to widget.bragg instead of keeping their own widget side copies.

3. Check automatic candidate selection

   num_candidates=0 derives the candidate count from the data rather than falling back to a fixed value such as 100, which is a change from what was implemented inside quantem.

4. Check mouse dragging

   Dragging a basis marker should update local React preview state while the pointer is moving, and commit the new basis to the kernel once on pointer release, as to avoid rerunning choose_basis_vectors and index_peaks for every pointer event.

Verification

Automated tests

• PYTHONPATH=src pytest -q tests/showbragg tests/test_choose_lattice.py — 20 passed
• npm run build — pass
• npx tsc --noEmit — pass
• npx vitest run — 169 passed

Real-data validation

Tested on a twinned Ag nanowire 4D-STEM dataset:

• Shape: (100, 30, 144, 144); Dtype: uint8; Scan dimensions: approximately 12.5 × 10 nm
• Backend: CPU / PyTorch; Scan positions: 3,000
• Full disk detection: approximately 25 s; Lattice fitting: approximately 0.4 s
• Fitted scan positions: 97%

Selected basis:

• g1 = (-2, -11)
• g2 = (14, -5)
• Included angle: 80.7°

Interactive validation

• All six panels render. Pan and zoom work. Basis candidates can be selected.
• Basis markers can be dragged. Marker dragging remains local to the browser until pointer release.

Not yet verified:

• Button-triggered detection and fitting end to end

Additional changes

While checking the widget against the project UI and performance conventions, this PR also:

• Replaces the subtract mean: on control with a Subtract Mean switch.
• Standardizes command-button labels to Title Case.

Scope

This PR adds the interactive ShowBragg workflow together with its supporting tests, documentation, and frontend implementation.

It does not add a tutorial notebook or corresponding experimental data, or a standalone HTML export. It also does not include new Bragg-detection or lattice-fititng algorithms. The tutorial notebook is planned as a follow-up once the nanowire dataset is available through HuggingFace repository

---

This PR follows the scikit-package workflow for reproducible scientific software.

[github-actions]

This PR is 1 commit behind electronmicroscopy/quantem.widget:main.

Fetch that remote and update local main before you branch, or rebase this branch onto it before review.
A warning is enough. The PR can stay open while main moves.

[github-actions]

• Keep henryhng/quantem.widget:showbragg until this PR is merged.
• After merge, delete henryhng/quantem.widget:showbragg if you own it and no other PR uses it.
• Then remove its dedicated worktree and local showbragg branch and update local main.

[bobleesj]

Thanks Henry. I think this widget is in the direction. Unlike other widgets like Show2D or Show4DSTEM, this is primarily based on algorithm. Do you have strong tests on those and real-data? We probably also need float precision and algo speed matters too.

[bobleesj]

Also let's make sure we work with our colleague who would need this widget first. We always want to discuss first either vis github issue or slsck to align in usage so that time for PR effort can be saved