Export and run ShowPtycho

Export and run ShowPtycho#

This tutorial exports a ShowPtycho reconstruction as a browser folder and opens it with no Python kernel and no Jupyter. You can run it by granting the folder to Chrome, or by using the generated local launcher. The exported viewer opens from exact bright-field detector columns by default, then runs SSB live as you tune aberrations.

If you just want the interactive widget inside a notebook, see ShowPtycho in Jupyter instead. This page assumes you already have a fitted ssb (solved with ssb.fit(trials=200, refinement="nelder-mead"); an unfitted export uses only the supplied starting aberrations).

Export#

from quantem.widget import ShowPtycho

# ssb is already fitted: result = ssb.fit(trials=200, refinement="nelder-mead")
w = ShowPtycho(ssb, source_file="scan_master.h5", save_dir="out/")
w.export("out/", title="my sample SSB")

This writes a folder:

  • index.html — the viewer

  • ShowPtycho.command — double-click launcher for Chrome on macOS

  • source/ — the exact BF-column browser source plus linked HDF5 evidence

  • snapshots/ — calibration, manifest, viewer snapshots, and review metadata

The export persists no expanded float32 images and no complex64 BF reducers. By default, the browser range-reads source/bf_columns.u8 or source/bf_columns.u16 and does not decode the compressed HDF5 stack on open. Saved aberration states live in snapshots/snapshots.json; reopening the folder through a folder grant or quantem showptycho out/ reads them back into the snapshot strip automatically.

Export at native detector size#

The WebGPU browser export cannot bin the detector. If the ssb was built with det_bin=2 (a 96x96 calibration) but the embedded HDF5 is native 192x192, the browser decodes 192x192, mismatches the calibration, and shows

detector shape mismatch; HDF5 has 192x192, calibration has 96x96

with blank panels. Always build and export at native detector size (det_bin=1, the default).

Run it#

The exported folder needs source/ and snapshots/ present next to index.html. There are three ways to open it.

A. Double-click ShowPtycho.command (macOS, zero setup)#

  1. Double-click ShowPtycho.command at the folder root.

  2. A Terminal window starts the bundled range server (stdlib-only, uses the Mac’s built-in Python) and Chrome opens the viewer already wired to it.

  3. Close the Terminal window when done; that stops the server.

The launcher serves only this folder, from wherever it sits — copy the folder to another Mac and the same double-click works, nothing to install.

B. Double-click index.html (File System Access)#

  1. Double-click index.html.

  2. Click Open data folder and grant the folder the HTML lives in (browsers without the folder picker fall back to a plain file chooser).

  3. It renders, starting at the embedded calibration snapshot.

One grant per session. This works fully offline.

C. CLI (serves and opens, no grant click)#

quantem showptycho out/

The command serves the folder over range-capable HTTP and opens it, so the viewer loads without the manual folder-grant. Use this when double-click + grant is inconvenient (for example over a remote connection).

What you can do in the viewer#

  • Drag C10 / C12 / phi12 / rotation — the browser rebuilds the BF-indexed G(k) reducers and re-runs SSB live; the phase and FFT update in tens of milliseconds on a real GPU.

  • Toggle the FFT panel to watch Bragg spots sharpen as aberrations improve.

  • Change colormap, contrast, and the amplitude/complex view.

  • Save writes the current aberrations and preview JPEG into snapshots/ without prompting for a separate download in the normal local folder workflow.

Verify WebGPU is on real hardware#

Interactive speed requires a real GPU. If a browser falls back to a software renderer (SwiftShader), the reconstruction still runs but slowly, and any timing you read is meaningless. On a real adapter the stats bar names the hardware (for example nvidia ... or apple ...); a software fallback will not. New GPUs can be missing from a browser’s allow-list — if WebGPU is unexpectedly absent, launch the browser with GPU blocklisting ignored.

Checklist#

  1. The ssb was fitted with fit(trials=200, refinement="nelder-mead") before export.

  2. Native detector (det_bin=1) — the browser cannot bin.

  3. Export writes a clean root: index.html, ShowPtycho.command, source/, and snapshots/.

  4. Open by double-click + Open data folder, or quantem showptycho out/.

  5. On open, the stats bar shows a non-null loss and the phase renders.

Privacy#

Exports embed source HDF5 file basenames in the metadata under snapshots/ and in the viewer state. The direct w.export(...) example above is therefore for local or otherwise trusted use.

For a community-facing folder, build it through the canonical CLI and request redaction explicitly:

quantem showptycho scan_master.h5 \
  --out shared-review \
  --anonymize \
  --trials 200 \
  --refinement nelder-mead

--anonymize replaces the local acquisition name and source paths in saved calibration and optimization provenance while retaining the scientific fit and software-version record. Inspect the resulting folder before publishing it; the detector evidence itself is still experimental data and must be yours to share.