diff --git a/.gitignore b/.gitignore index cc908aeb..5ef7a182 100644 --- a/.gitignore +++ b/.gitignore @@ -151,6 +151,8 @@ waveorder/_version.py *.npz *.tif[f] *.pdf +# the screening tutorial ships its vector figures and whitepaper PDF +!docs/guide/labelfree-screening/**/*.pdf # example data /examples/data_temp/* diff --git a/docs/conf.py b/docs/conf.py index c61cb07e..64962688 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -106,7 +106,8 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +# Developer notes that live next to a page but are not part of the site. +exclude_patterns = ["guide/labelfree-screening/README.md"] # The reST default role (used for this markup `text`) to use for all documents. # default_role = None diff --git a/docs/guide.rst b/docs/guide.rst index 2954c6cc..ddf596d2 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -10,6 +10,7 @@ User Guides guide/QLIPP guide/data-schema + guide/labelfree-screening/labelfree-screening guide/buyers-guide guide/microscope-installation-guide guide/software-installation-guide diff --git a/docs/guide/labelfree-screening/README.md b/docs/guide/labelfree-screening/README.md new file mode 100644 index 00000000..8b2e07df --- /dev/null +++ b/docs/guide/labelfree-screening/README.md @@ -0,0 +1,58 @@ +# Label-free screening tutorial: source files + +This folder is self-contained: the tutorial page, the 2-page whitepaper PDF +source, the figures, the configs the tutorial teaches, and the scripts that +regenerate everything. + +| Path | Contents | +| --- | --- | +| `labelfree-screening.md` | The tutorial page (rendered on the docs site). | +| `whitepaper.tex` | 2-page print layout of the same content (boxed failure modes, Biohub footer). | +| `whitepaper.pdf` | The built whitepaper. | +| `make_pdf.sh` | Builds `whitepaper.pdf` with pdflatex. | +| `figures/` | Tutorial figures: PDF (whitepaper) and PNG (docs site). | +| `figures/make_figures.py` | Draws the data figures from the crops in `figures/data/`. | +| `figures/data/` | 8-bit image crops behind the data figures, each scaled to the contrast its panel shows. | +| `figures/koehler/` | Draws the Koehler alignment figure from a parametric cartoon microscope (`scope_model.py`, `make_figure.py`). | +| `figures/requirements.txt` | Pinned packages for both figure scripts, compiled from `requirements.in`. | +| `configs/phase.yml` | Baseline 2D phase reconstruction config. | +| `configs/phase_autofocus.yml` | Baseline plus `z_focus_offset: auto`. | +| `configs/phase_autofocus_tilt.yml` | Autofocus plus warm-started illumination tilt fitting. | +| `brand/` | CZ Biohub logo for the whitepaper footer. | + +## Rebuilding + +You need [uv](https://docs.astral.sh/uv/), and for the PDF a full TeX Live or +MacTeX install (`make_pdf.sh` lists the LaTeX packages). Nothing outside this +folder is read. + +```sh +cd figures +uv run --no-project --python 3.12 --with-requirements requirements.txt python make_figures.py +uv run --no-project --python 3.12 --with-requirements requirements.txt python koehler/make_figure.py +cd .. && ./make_pdf.sh +``` + +- The first run downloads cadquery and vtk (several hundred MB). The Koehler + figure takes one to two minutes, because it renders a 3D model; on a + headless Linux machine vtk needs an OpenGL context (e.g. `xvfb-run`). +- With the pinned packages the figures come out byte-for-byte identical to + the committed ones on the machine they were made on (macOS, Apple + silicon). Other platforms may differ in rendering details. +- `whitepaper.pdf` is built without timestamps, so rebuilding with the same + TeX install reproduces it exactly. The date in its footer is set by hand in + `whitepaper.tex`. + +## Where the crops come from + +The crops in `figures/data/` are cut from one raw position of the OPS atlas +store (`A/1/029029`, well center) and from `waveorder reconstruct` outputs +for that position and for `A/1/002029` (north edge), using the configs in +`configs/` and variants of them with the one setting each panel names +changed. `python figures/make_figures.py --from-hpc` rebuilds the crops from +those stores; it needs Biohub HPC access and iohub, and its docstring lists +the reconstructions it expects. + +The committed crops were recovered from the figure PDFs of an earlier +revision of this tutorial, at 161 to 248 pixels across. Rebuilding them with +`--from-hpc` gives 256-pixel crops cut from the full-resolution data. diff --git a/docs/guide/labelfree-screening/brand/biohub-logo-black.png b/docs/guide/labelfree-screening/brand/biohub-logo-black.png new file mode 100644 index 00000000..84232814 Binary files /dev/null and b/docs/guide/labelfree-screening/brand/biohub-logo-black.png differ diff --git a/docs/guide/labelfree-screening/configs/phase.yml b/docs/guide/labelfree-screening/configs/phase.yml new file mode 100644 index 00000000..99199e0a --- /dev/null +++ b/docs/guide/labelfree-screening/configs/phase.yml @@ -0,0 +1,13 @@ +input_channel_names: [BF] +reconstruction_dimension: 2 +phase: + transfer_function: + yx_pixel_size: 0.325 + z_pixel_size: 2.0 + wavelength_illumination: 0.450 + index_of_refraction_media: 1.0 + numerical_aperture_detection: 0.55 + numerical_aperture_illumination: 0.4 + invert_phase_contrast: false + apply_inverse: + regularization_strength: 0.001 diff --git a/docs/guide/labelfree-screening/configs/phase_autofocus.yml b/docs/guide/labelfree-screening/configs/phase_autofocus.yml new file mode 100644 index 00000000..553ad88b --- /dev/null +++ b/docs/guide/labelfree-screening/configs/phase_autofocus.yml @@ -0,0 +1,14 @@ +input_channel_names: [BF] +reconstruction_dimension: 2 +phase: + transfer_function: + yx_pixel_size: 0.325 + z_pixel_size: 2.0 + wavelength_illumination: 0.450 + index_of_refraction_media: 1.0 + numerical_aperture_detection: 0.55 + numerical_aperture_illumination: 0.4 + invert_phase_contrast: false + z_focus_offset: auto + apply_inverse: + regularization_strength: 0.001 diff --git a/docs/guide/labelfree-screening/configs/phase_autofocus_tilt.yml b/docs/guide/labelfree-screening/configs/phase_autofocus_tilt.yml new file mode 100644 index 00000000..db8480ee --- /dev/null +++ b/docs/guide/labelfree-screening/configs/phase_autofocus_tilt.yml @@ -0,0 +1,19 @@ +input_channel_names: [BF] +reconstruction_dimension: 2 +phase: + transfer_function: + yx_pixel_size: 0.325 + z_pixel_size: 2.0 + wavelength_illumination: 0.450 + index_of_refraction_media: 1.0 + numerical_aperture_detection: 0.55 + numerical_aperture_illumination: 0.4 + invert_phase_contrast: false + z_focus_offset: auto + tilt_angle_zenith: {init: 0.13, lr: 0.05} + tilt_angle_azimuth: {init: 0.0, lr: 0.05} + apply_inverse: + regularization_strength: 0.001 +optimization: + max_iterations: 50 + method: adam diff --git a/docs/guide/labelfree-screening/figures/data/edge_baseline.png b/docs/guide/labelfree-screening/figures/data/edge_baseline.png new file mode 100644 index 00000000..dff8f550 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/edge_baseline.png differ diff --git a/docs/guide/labelfree-screening/figures/data/edge_tilt.png b/docs/guide/labelfree-screening/figures/data/edge_tilt.png new file mode 100644 index 00000000..d52a2139 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/edge_tilt.png differ diff --git a/docs/guide/labelfree-screening/figures/data/flipped.png b/docs/guide/labelfree-screening/figures/data/flipped.png new file mode 100644 index 00000000..8bba38f8 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/flipped.png differ diff --git a/docs/guide/labelfree-screening/figures/data/focus_+2.png b/docs/guide/labelfree-screening/figures/data/focus_+2.png new file mode 100644 index 00000000..30d90869 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/focus_+2.png differ diff --git a/docs/guide/labelfree-screening/figures/data/focus_-2.png b/docs/guide/labelfree-screening/figures/data/focus_-2.png new file mode 100644 index 00000000..77f2b18f Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/focus_-2.png differ diff --git a/docs/guide/labelfree-screening/figures/data/focus_0.png b/docs/guide/labelfree-screening/figures/data/focus_0.png new file mode 100644 index 00000000..92d2447b Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/focus_0.png differ diff --git a/docs/guide/labelfree-screening/figures/data/nominal.png b/docs/guide/labelfree-screening/figures/data/nominal.png new file mode 100644 index 00000000..23221851 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/nominal.png differ diff --git a/docs/guide/labelfree-screening/figures/data/reg_1e-1.png b/docs/guide/labelfree-screening/figures/data/reg_1e-1.png new file mode 100644 index 00000000..a2b69955 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/reg_1e-1.png differ diff --git a/docs/guide/labelfree-screening/figures/data/reg_1e-5.png b/docs/guide/labelfree-screening/figures/data/reg_1e-5.png new file mode 100644 index 00000000..f19a940f Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/reg_1e-5.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_0.png b/docs/guide/labelfree-screening/figures/data/stack_0.png new file mode 100644 index 00000000..9a416f90 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_0.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_1.png b/docs/guide/labelfree-screening/figures/data/stack_1.png new file mode 100644 index 00000000..7929e6dd Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_1.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_2.png b/docs/guide/labelfree-screening/figures/data/stack_2.png new file mode 100644 index 00000000..62424eae Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_2.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_3.png b/docs/guide/labelfree-screening/figures/data/stack_3.png new file mode 100644 index 00000000..f74efda4 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_3.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_4.png b/docs/guide/labelfree-screening/figures/data/stack_4.png new file mode 100644 index 00000000..1f2623ab Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_4.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_5.png b/docs/guide/labelfree-screening/figures/data/stack_5.png new file mode 100644 index 00000000..818625f0 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_5.png differ diff --git a/docs/guide/labelfree-screening/figures/data/stack_6.png b/docs/guide/labelfree-screening/figures/data/stack_6.png new file mode 100644 index 00000000..79787ea0 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/data/stack_6.png differ diff --git a/docs/guide/labelfree-screening/figures/fig_flip.pdf b/docs/guide/labelfree-screening/figures/fig_flip.pdf new file mode 100644 index 00000000..76cf462e Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_flip.pdf differ diff --git a/docs/guide/labelfree-screening/figures/fig_flip.png b/docs/guide/labelfree-screening/figures/fig_flip.png new file mode 100644 index 00000000..a4a53e2c Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_flip.png differ diff --git a/docs/guide/labelfree-screening/figures/fig_focus.pdf b/docs/guide/labelfree-screening/figures/fig_focus.pdf new file mode 100644 index 00000000..9c1a2053 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_focus.pdf differ diff --git a/docs/guide/labelfree-screening/figures/fig_focus.png b/docs/guide/labelfree-screening/figures/fig_focus.png new file mode 100644 index 00000000..febd9a7f Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_focus.png differ diff --git a/docs/guide/labelfree-screening/figures/fig_koehler.pdf b/docs/guide/labelfree-screening/figures/fig_koehler.pdf new file mode 100644 index 00000000..79f56f08 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_koehler.pdf differ diff --git a/docs/guide/labelfree-screening/figures/fig_koehler.png b/docs/guide/labelfree-screening/figures/fig_koehler.png new file mode 100644 index 00000000..37bcda91 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_koehler.png differ diff --git a/docs/guide/labelfree-screening/figures/fig_overview.pdf b/docs/guide/labelfree-screening/figures/fig_overview.pdf new file mode 100644 index 00000000..88f86d21 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_overview.pdf differ diff --git a/docs/guide/labelfree-screening/figures/fig_overview.png b/docs/guide/labelfree-screening/figures/fig_overview.png new file mode 100644 index 00000000..5160ef27 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_overview.png differ diff --git a/docs/guide/labelfree-screening/figures/fig_reg.pdf b/docs/guide/labelfree-screening/figures/fig_reg.pdf new file mode 100644 index 00000000..fbf2551a Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_reg.pdf differ diff --git a/docs/guide/labelfree-screening/figures/fig_reg.png b/docs/guide/labelfree-screening/figures/fig_reg.png new file mode 100644 index 00000000..bd736c06 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_reg.png differ diff --git a/docs/guide/labelfree-screening/figures/fig_tilt.pdf b/docs/guide/labelfree-screening/figures/fig_tilt.pdf new file mode 100644 index 00000000..ff74f4d4 Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_tilt.pdf differ diff --git a/docs/guide/labelfree-screening/figures/fig_tilt.png b/docs/guide/labelfree-screening/figures/fig_tilt.png new file mode 100644 index 00000000..e205a76a Binary files /dev/null and b/docs/guide/labelfree-screening/figures/fig_tilt.png differ diff --git a/docs/guide/labelfree-screening/figures/koehler/make_figure.py b/docs/guide/labelfree-screening/figures/koehler/make_figure.py new file mode 100644 index 00000000..11034058 --- /dev/null +++ b/docs/guide/labelfree-screening/figures/koehler/make_figure.py @@ -0,0 +1,444 @@ +"""Draw the Koehler alignment figure for the label-free screening tutorial. + +Renders a cartoon inverted microscope (see scope_model.py) from one view: +an overview, then four zoomed panels that step through realigning Koehler +illumination. Each zoomed panel carries an inset of the field stop as seen +on the camera, filled with a raw brightfield crop (../data/stack_3.png). + +Needs cadquery (which brings vtk); see ../../README.md for the exact command +and pinned versions. Writes fig_koehler.pdf/.png into the parent folder (or +into the directory given as the first argument) at final print width, so +its 8 pt labels match the other tutorial figures. +""" + +import math +import sys +import tempfile +from pathlib import Path + +import matplotlib +import numpy as np + +matplotlib.use("Agg") +import matplotlib.pyplot as plt +import scope_model as ts +from matplotlib.patches import ConnectionPatch, FancyBboxPatch, Polygon, Rectangle +from PIL import Image, ImageDraw, ImageFilter + +# Arrow geometry is laid out in pixels of a 960 px wide panel; panels are +# rendered S times larger so the print stays sharp. +S = 2 +SIZE = (960 * S, 1250 * S) # panel size in pixels +AZ, EL = 35, 10 # camera azimuth and elevation in degrees, shared by all panels +OVERVIEW = dict(focus=(-33.6, 236.7, 407), half_height=492) # microscope fills the panel +BLACK = "#1a1a1a" +RED = "#e2574c" +ORANGE = "#f39c34" +BLUE = "#4b83e8" +N_IN = 600 # inset image size in pixels +FULL_W = 7.5 # print width (in) of a full-width figure, as in make_figures.py +LW = 0.42 # line widths below are in points for a 5-panel row 2.4x wider than print; this scales them down +N_BLADES, BLADE_TILT = 10, 11 # field stop blades and their rotation in degrees (also in make_figures.py) +HERE = Path(__file__).resolve().parent +CELL = np.asarray( + Image.open(HERE.parent / "data" / "stack_3.png").convert("L").resize((N_IN, N_IN), Image.LANCZOS), float +) # raw brightfield crop shown through the field stop +OFF = (0.64, 0.38) # off-centre field stop position in the inset + + +def basis(az=AZ, el=EL): + """Screen right and up unit vectors for a view direction.""" + a, e = math.radians(az), math.radians(el) + right = np.array([math.sin(a), math.cos(a), 0.0]) + up = np.array([-math.sin(e) * math.cos(a), math.sin(e) * math.sin(a), math.cos(e)]) + return right, up + + +# zoomed view: shifted off-centre to leave the lower-left corner free +ZOOM = dict(focus=tuple(np.array([0, ts.AX + 8, 623]) - basis()[0] * 3), half_height=171) + + +def project(view, pts): + """Project 3D points to pixel coordinates of a rendered view. + + Parameters + ---------- + view : dict + ``focus`` and ``half_height`` of the orthographic view. + pts : array-like, shape (n, 3) + Points in model coordinates. + + Returns + ------- + ndarray, shape (n, 2) + """ + right, up = basis() + rel = np.atleast_2d(pts) - np.array(view["focus"]) + k = SIZE[1] / 2 / view["half_height"] + return np.stack([SIZE[0] / 2 + rel @ right * k, SIZE[1] / 2 - rel @ up * k], axis=1) + + +def arc3d(center, u, v, radius, a0, a1, n=60): + """Points on a 3D arc spanned by unit vectors u and v.""" + t = np.radians(np.linspace(a0, a1, n))[:, None] + return np.array(center) + radius * (np.cos(t) * np.array(u) + np.sin(t) * np.array(v)) + + +def arrow(ax, xy, color, lw=3.2, heads=(True, True), head=(45, 36), scale=S, halo=1.3, z=5): + """Draw a polyline with solid triangular heads and a thin white halo. + + Parameters + ---------- + ax : matplotlib.axes.Axes + Axes to draw on, in pixel coordinates. + xy : ndarray, shape (n, 2) + Path in pixels. + color : str + Arrow color. + lw : float + Line width in points (before the `LW` print scaling). + heads : tuple of bool + Whether to draw a head at the start and at the end. + head : tuple of float + Head length and width in layout pixels (multiplied by `scale`). + scale : float + Pixel scale of the target axes relative to the 960 px layout. + halo : float + White outline width in points. + z : int + zorder. + """ + xy = np.asarray(xy, float) + lw, halo = lw * LW, halo * LW + hl, hw = head[0] * scale, head[1] * scale + seg = np.linalg.norm(np.diff(xy, axis=0), axis=1) + s = np.concatenate([[0], np.cumsum(seg)]) + fine = np.linspace(0, s[-1], 300) + xy = np.stack([np.interp(fine, s, xy[:, 0]), np.interp(fine, s, xy[:, 1])], axis=1) + s = fine + lo = hl * 0.8 if heads[0] else 0 + hi = s[-1] - (hl * 0.8 if heads[1] else 0) + keep = (s >= lo) & (s <= hi) + tris = [] + for on, tip, back in ((heads[0], xy[0], s <= hl), (heads[1], xy[-1], s >= s[-1] - hl)): + if not on: + continue + d = tip - xy[back].mean(axis=0) + d /= np.linalg.norm(d) + base = tip - d * hl + nrm = np.array([-d[1], d[0]]) * hw / 2 + tris.append([tip, base + nrm, base - nrm]) + passes = [(color, 0, z + 1)] + if halo: + passes.insert(0, ("white", 2 * halo, z)) + for c, extra, zz in passes: + ax.plot(xy[keep, 0], xy[keep, 1], color=c, lw=lw + extra, solid_capstyle="butt", zorder=zz) + for tri in tris: + ax.add_patch( + Polygon(tri, closed=True, fc=c, ec=c, lw=extra if extra else 0.15, joinstyle="miter", zorder=zz) + ) + + +def rotation_arrow(ax, center, axis, radius, a0, a1, color=BLACK, **kw): + """Curved arrow around a 3D axis through `center`.""" + axis = np.array(axis, float) + axis /= np.linalg.norm(axis) + ref = np.array([0, 0, 1.0]) if abs(axis[2]) < 0.9 else np.array([1.0, 0, 0]) + u = np.cross(axis, ref) + u /= np.linalg.norm(u) + v = np.cross(axis, u) + arrow(ax, project(ZOOM, arc3d(center, u, v, radius, a0, a1)), color, **kw) + + +def ring_arrow(ax, heads): + """Black arrow turning the knurled field diaphragm ring.""" + cam = -AZ + below = ts.FIELD_RING_Z[0] - 9 # just under the ring, on the side facing the camera + pts = arc3d((0, ts.AX, below), (1, 0, 0), (0, 1, 0), 55, cam - 48, cam + 48) + arrow(ax, project(ZOOM, pts), BLACK, lw=3.0, heads=heads, head=(36, 29)) + + +# ---------------------------------------------------------------- insets +def blades(center, radius, n=N_BLADES, rot=BLADE_TILT): + """Vertices of a bladed (polygonal) aperture, in inset pixels.""" + t = np.radians(rot + np.arange(n) * 360 / n) + return np.stack([center[0] + radius * np.cos(t), center[1] + radius * np.sin(t)], axis=1) * N_IN + + +def stop_image(center, radius, blur=0, ghost=None): + """Bright bladed field stop on a black field. + + Parameters + ---------- + center : tuple of float + Aperture centre in inset fractions. + radius : float + Aperture radius in inset fractions. + blur : float + Gaussian blur radius in pixels. + ghost : tuple, optional + ``(radius, blur, weight)`` of a fainter defocused copy underneath. + + Returns + ------- + ndarray, shape (N_IN, N_IN) + """ + + def one(r, b): + im = Image.new("L", (N_IN, N_IN), 0) + ImageDraw.Draw(im).polygon([tuple(p) for p in blades(center, r)], fill=255) + if b: + im = im.filter(ImageFilter.GaussianBlur(b)) + return np.asarray(im, float) + + img = one(radius, blur) + if ghost: + img = np.maximum(img, ghost[2] * one(ghost[0], ghost[1])) + return img + + +def edge_dist(radius, ang, n=N_BLADES, rot=BLADE_TILT): + """Distance from the aperture centre to its edge along a direction.""" + half = 180 / n + rel = (ang - rot) % (2 * half) - half + return radius * math.cos(math.radians(half)) / math.cos(math.radians(rel)) + + +INSET_W = 0.25 # inset width as a fraction of the panel width + + +def inset_axes(ax): + """Square inset in the lower-left corner of a panel.""" + w = INSET_W + h = w * SIZE[0] / SIZE[1] + ia = ax.inset_axes([0.035, 0.03, w, h]) + ia.set_xticks([]) + ia.set_yticks([]) + for sp in ia.spines.values(): + sp.set_edgecolor("#555555") + sp.set_linewidth(0.45) + return ia + + +def show(ia, mask): + """Show the brightfield crop through a field stop mask (0-255).""" + ia.imshow(mask / 255 * CELL, cmap="gray", vmin=0, vmax=255, interpolation="bilinear") + ia.set_xlim(0, N_IN) + ia.set_ylim(N_IN, 0) + + +def inset_close(ax): + """Blurred, off-centre stop shrinking as the field stop closes.""" + ia = inset_axes(ax) + show(ia, stop_image(OFF, 0.27, blur=20)) + c = np.array(OFF) * N_IN + for ang in (45, 135, 225, 315): + d = np.array([math.cos(math.radians(ang)), math.sin(math.radians(ang))]) + tip = edge_dist(0.27, ang) + arrow( + ia, + np.array([c + d * (tip + 0.25) * N_IN, c + d * tip * N_IN]), + RED, + lw=3.0, + heads=(False, True), + scale=1.6, + halo=0, + ) + + +def inset_focus(ax): + """Off-centre stop coming into focus.""" + ia = inset_axes(ax) + show(ia, stop_image(OFF, 0.19, ghost=(0.22, 26, 0.45))) + # outline the focused blade edges in the focus-knob color + ia.add_patch(Polygon(blades(OFF, 0.19), closed=True, fc="none", ec=ORANGE, lw=0.6, zorder=4)) + + +def inset_center(ax): + """Centred, focused stop with X/Y motion arrows.""" + ia = inset_axes(ax) + show(ia, stop_image((0.5, 0.5), 0.19)) + c = np.array([0.5, 0.5]) * N_IN + for d in ((1, 1), (1, -1)): + d = np.array(d) / math.sqrt(2) * 0.4 * N_IN + arrow(ia, np.array([c - d, c + d]), BLUE, lw=3.8, scale=2.0, halo=0) + + +def inset_open(ax): + """Field of view fully lit, stop opened just past its edges. + + The square field of view sits where the other insets do. The dashed + stop surrounds it on a white patch that fades into the drawing, and is + cut off by the panel edge at the lower left. + """ + w = INSET_W * SIZE[0] + x0, y1 = 0.035 * SIZE[0], SIZE[1] * (1 - 0.03) + c = np.array([x0 + w / 2, y1 - w / 2]) + a = w / 2 + half = 1.95 * a # radius of the white patch: just past the stop, which reaches 1.55 a + g = np.linspace(-1, 1, 500) + r = np.hypot(*np.meshgrid(g, g)) + t = np.clip((1.0 - r) / 0.17, 0, 1) # opaque inside, fading over the outer 17% + rgba = np.ones((500, 500, 4)) + rgba[..., 3] = t * t * (3 - 2 * t) + ax.imshow(rgba, extent=(c[0] - half, c[0] + half, c[1] + half, c[1] - half), interpolation="bilinear", zorder=2) + ax.imshow(CELL, extent=(x0, x0 + w, y1, y1 - w), cmap="gray", vmin=0, vmax=255, interpolation="bilinear", zorder=3) + ax.add_patch(Rectangle((x0, y1 - w), w, w, fc="none", ec=BLACK, lw=0.45, zorder=3.5)) + # stop just outside the corners of the field of view (corner distance is 1.41 a) + rad = 1.47 * a / math.cos(math.pi / N_BLADES) + ang = np.radians(BLADE_TILT + 360 / N_BLADES * np.arange(N_BLADES)) + ax.add_patch( + Polygon( + c + rad * np.stack([np.cos(ang), np.sin(ang)], 1), + closed=True, + fc="none", + ec="#555555", + lw=0.45, + ls=(0, (4, 2.5)), + zorder=4, + ) + ) + for deg in (45, 135, 225, 315): + d = np.array([math.cos(math.radians(deg)), math.sin(math.radians(deg))]) + tip = edge_dist(rad, deg) + arrow( + ax, np.array([c + d * (tip - 0.56 * a), c + d * tip]), RED, lw=3.0, heads=(False, True), scale=1.43, halo=0 + ) + + +# ---------------------------------------------------------------- panels +def panel_close(ax): + """Close the field stop: turn the ring one way; the stop image shrinks.""" + ring_arrow(ax, (False, True)) + inset_close(ax) + + +def panel_focus(ax): + """Focus the condenser: turn the focus knob; the condenser moves up and down.""" + knob_face = (ts.FOCUS_KNOB_X + 7, *ts.FOCUS_KNOB_YZ) + rotation_arrow(ax, knob_face, (1, 0, 0), 24, -60, 170) + right, _ = basis() + base = np.array([0, ts.TURRET_Y, 0]) - right * 110 # clear of the turret, to its left + line = np.array([base + (0, 0, 560), base + (0, 0, 664)]) + arrow(ax, project(ZOOM, line), ORANGE, lw=4.2) + inset_focus(ax) + + +def panel_center(ax): + """Center the condenser: turn both centering screws; the condenser moves in X and Y.""" + spans = {-30: (-150, 80), -150: (100, 330)} # arc of each arrow, on the side facing the camera + for ang in ts.SCREW_ANGLES: + span = spans[ang] + a = math.radians(ang) + d = np.array([math.cos(a), math.sin(a), 0]) + c = np.array([0, ts.AX, ts.SCREW_Z]) + d * (ts.SCREW_TIP_R + 6) + rotation_arrow(ax, c, d, 16, *span, lw=2.8, head=(32, 27)) + # X and Y in the plane perpendicular to the light path, drawn as if + # that plane were tipped toward the viewer so all four heads read + c = project(ZOOM, [(0, ts.AX, ts.LENS_BOTTOM_Z - 32)])[0] + a, tip = math.radians(AZ), math.sin(math.radians(26)) + k = SIZE[1] / 2 / ZOOM["half_height"] * 44 + for d in ((math.sin(a), math.cos(a) * tip), (math.cos(a), -math.sin(a) * tip)): + d = np.array(d) * k + arrow(ax, np.array([c - d, c + d]), BLUE, lw=4.2) + inset_center(ax) + + +def panel_open(ax): + """Open the field stop: turn the ring back until the stop clears the field of view.""" + ring_arrow(ax, (True, False)) + inset_open(ax) + + +# panel titles take the color of the knob they turn +TITLE_COLORS = {"close": RED, "focus": ORANGE, "center": BLUE, "open": RED} + +PANELS = [ + ("overview", "", {"A", "B", "C"}, OVERVIEW, None), + ("close", "Close field stop", {"A"}, ZOOM, panel_close), + ("focus", "Focus", {"B"}, ZOOM, panel_focus), + ("center", "Center", {"C"}, ZOOM, panel_center), + ("open", "Open field stop", {"A"}, ZOOM, panel_open), +] + + +def main(out=HERE.parent): + """Render the five panels and save fig_koehler.pdf/.png. + + Parameters + ---------- + out : path-like, optional + Output directory; the figures folder by default. + """ + out = Path(out) + plt.rcParams["font.family"] = "monospace" + plt.rcParams["font.size"] = 8 + fig, axes = plt.subplots(1, 5, figsize=(FULL_W, 2.055)) + fig.subplots_adjust(left=0.004, right=0.996, top=0.917, bottom=0.007, wspace=0.05) + cache = {} + for ax, (name, title, hl, view, draw) in zip(axes, PANELS): + key = (frozenset(hl), draw is not None) + if key not in cache: + parts = ts.build(hl) + if draw: # keep the zoomed panels clear of the eyepiece tube + parts = [q for q in parts if not q[0].startswith(("eyepiece", "tube_"))] + with tempfile.TemporaryDirectory() as tmp: + png = Path(tmp) / f"panel_{name}.png" + ts.render( + ts.mesh_scene(parts), png, view["focus"], AZ, EL, view["half_height"], size=SIZE, ss=2, line_px=7 + ) + cache[key] = plt.imread(png) + ax.imshow(cache[key], interpolation="lanczos") + ax.set_xlim(0, SIZE[0]) + ax.set_ylim(SIZE[1], 0) + ax.set_xticks([]) + ax.set_yticks([]) + for sp in ax.spines.values(): + sp.set_edgecolor("#555555") + sp.set_linewidth(0.5) + sp.set_visible(draw is not None) + if draw: + draw(ax) + ax.set_xlim(0, SIZE[0]) + ax.set_ylim(SIZE[1], 0) + ax.set_title(title, fontsize=8, pad=3, color=TITLE_COLORS.get(name, BLACK)) + # zoom box on the overview, connected to the first zoomed panel + k = SIZE[1] / 2 / OVERVIEW["half_height"] + cx, cy = project(OVERVIEW, [ZOOM["focus"]])[0] + hh = ZOOM["half_height"] * k + hw = hh * SIZE[0] / SIZE[1] + axes[0].add_patch( + FancyBboxPatch( + (cx - hw, cy - hh), + 2 * hw, + 2 * hh, + boxstyle=f"round,pad=0,rounding_size={8 * S}", + fc="none", + ec="#555555", + lw=0.5, + ls=(0, (3, 2)), + zorder=6, + ) + ) + fig.add_artist( + ConnectionPatch( + (cx - hw, cy - hh), + (0, 0), + "data", + "data", + axesA=axes[0], + axesB=axes[1], + color="#555555", + lw=0.5, + ls=(0, (3, 2)), + ) + ) + for ext, dpi in (("pdf", 300), ("png", 300)): + # no creation date, so reruns give byte-identical PDFs + meta = {"CreationDate": None} if ext == "pdf" else None + fig.savefig(out / f"fig_koehler.{ext}", dpi=dpi, metadata=meta) + print("wrote fig_koehler.pdf/.png") + + +if __name__ == "__main__": + main(*sys.argv[1:]) diff --git a/docs/guide/labelfree-screening/figures/koehler/scope_model.py b/docs/guide/labelfree-screening/figures/koehler/scope_model.py new file mode 100644 index 00000000..32db47d3 --- /dev/null +++ b/docs/guide/labelfree-screening/figures/koehler/scope_model.py @@ -0,0 +1,552 @@ +"""Cartoon inverted microscope: parametric 3D model and flat-shaded renderer. + +The model is schematic: an original drawing with the proportions of a +generic inverted stand, not to scale and not taken from vendor CAD. Units +are roughly mm. Axes: +x is the user's right, y runs front (0) to back, +z is up from the table. + +`build` returns the parts, `mesh_scene` tessellates them, and `render` +draws a view with flat tones, soft shading on rounded edges and outlines +at silhouettes and sharp edges. Used by make_figure.py. +""" + +import math +import warnings + +import cadquery as cq +import numpy as np +import vtk +from PIL import Image, ImageFilter +from vtk.util import numpy_support as ns + +AX = 260.0 # y position of the optical axis +# Positions of the Koehler controls, shared with the arrows in make_figure.py. +TURRET_Y = AX + 12 # y of the condenser turret axis +FIELD_RING_Z = (652.0, 664.0) # bottom and top of the field diaphragm ring +FOCUS_KNOB_X = 88.0 # outer face of the right condenser focus knob +FOCUS_KNOB_YZ = (328.0, 650.0) # axis of the condenser focus knobs +SCREW_Z = 612.5 # height of the condenser centering screws +SCREW_ANGLES = (-150, -30) # their directions about the optical axis, degrees +SCREW_TIP_R = 86.0 # radius of their outer ends +LENS_BOTTOM_Z = 508.0 # bottom of the condenser lens + + +def _hex(h): + return tuple(int(h[i : i + 2], 16) for i in (1, 3, 5)) + + +# palette: (light, base, shade, outline); a "top" tone is derived from light +PAL = { + "body": ("#f3f3f3", "#d9d9d9", "#c4c4c4", "#8c8c8c"), + "head": ("#f0f0f0", "#cecece", "#bcbcbc", "#8c8c8c"), + "panel": ("#d2d2d2", "#cccccc", "#c0c0c0", "#8c8c8c"), + "white": ("#fcfcfc", "#ebebeb", "#dcdcdc", "#8c8c8c"), + "mid": ("#c4c4c4", "#adadad", "#989898", "#777777"), + "mid2": ("#8a8a8a", "#747474", "#666666", "#555555"), + "dark": ("#5c5c5c", "#484848", "#3b3b3b", "#2a2a2a"), + "blue": ("#7dd3f1", "#3aaee0", "#2e97ca", "#2a7fa8"), + "red": ("#f08a80", "#e2574c", "#c7453b", "#8f2c25"), + "orange": ("#f9c27a", "#f39c34", "#d98424", "#9c5c12"), + "cobalt": ("#8fb4f5", "#4b83e8", "#3a6cc9", "#27498c"), + "green": ("#8fdc9f", "#45b85e", "#379a4d", "#226632"), + "yellow": ("#fbe58a", "#f3cf3f", "#d9b52e", "#8f7412"), + "lime": ("#b5e08a", "#86c94a", "#6fae38", "#47731f"), + "sky": ("#a9d8f5", "#6cb8ea", "#559fd0", "#2f6c96"), +} + + +def _tones(v): + light, base, shade, outline = (_hex(c) for c in v) + top = tuple(min(255, c + 5) for c in light) + return (top, light, base, shade, outline) + + +PAL = {k: _tones(v) for k, v in PAL.items()} + + +def box(x0, x1, y0, y1, z0, z1): + """Axis-aligned box from its extents.""" + return cq.Workplane("XY").box(x1 - x0, y1 - y0, z1 - z0, centered=False).translate((x0, y0, z0)) + + +def cyl_x(d, x0, x1, y, z): + """Cylinder with its axis along x.""" + return cq.Workplane("YZ", origin=(x0, 0, 0)).center(y, z).circle(d / 2).extrude(x1 - x0) + + +def cyl_y(d, y0, y1, x, z): + """Cylinder with its axis along y.""" + return cq.Workplane("ZX", origin=(0, y0, 0)).center(z, x).circle(d / 2).extrude(y1 - y0) + + +def cyl_z(d, z0, z1, x=0.0, y=AX): + """Cylinder with its axis along z.""" + return cq.Workplane("XY", origin=(0, 0, z0)).center(x, y).circle(d / 2).extrude(z1 - z0) + + +def prism_yz(pts, x0, x1): + """Polygon in the (y, z) plane extruded along x.""" + return cq.Workplane("YZ", origin=(x0, 0, 0)).polyline(pts).close().extrude(x1 - x0) + + +ROUND = 0.45 # global scale on edge radii + + +def soft(wp, r, selector=None, scale=True): + """Round the edges of a solid. + + The CAD kernel refuses a fillet that does not fit the local geometry, so + smaller radii are tried in turn. A change of radius is reported, since it + changes the drawing. + + Parameters + ---------- + wp : cq.Workplane + Solid to round. + r : float + Edge radius. + selector : str, optional + CadQuery edge selector; all edges by default. + scale : bool, optional + Multiply `r` by the global `ROUND` factor. + + Returns + ------- + cq.Workplane + """ + if scale: + r *= ROUND + for rr in (r, r * 0.6, r * 0.3): + try: + e = wp.edges(selector) if selector else wp.edges() + rounded = e.fillet(rr) + except Exception: # the kernel raises its own error types + continue + if rr != r: + warnings.warn(f"edge radius reduced from {r:g} to {rr:g}", stacklevel=2) + return rounded + raise RuntimeError(f"could not round edges at radius {r:g} or smaller") + + +def knurled_z(d, z0, z1, n=15, depth=1.8): + """Disc on the optical axis with a smooth, wavy knurled rim.""" + t = np.linspace(0, 2 * math.pi, n * 12, endpoint=False) + r = d / 2 + depth * np.cos(n * t) + pts = [(float(a * math.cos(b)), float(a * math.sin(b))) for a, b in zip(r, t)] + return cq.Workplane("XY", origin=(0, AX, z0)).spline(pts, periodic=True).close().extrude(z1 - z0) + + +def objective(band_h=5): + """One objective along +z from the origin: (barrel, band) solids.""" + barrel = ( + cq.Workplane("XY") + .circle(15) + .extrude(36) + .faces(">Z") + .workplane() + .circle(15) + .workplane(offset=11) + .circle(8) + .loft(combine=True) + ) + band = cq.Workplane("XY", origin=(0, 0, 22)).circle(15.8).extrude(band_h) + return barrel, band + + +def nosepiece_parts(): + """Tilted nosepiece with five objectives; the active one is vertical. + + Returns + ------- + list of tuple + ``(name, cq.Workplane, palette_name)`` triples in model coordinates. + """ + alpha, r = 15, 40 + out = [] + disc = cq.Workplane("XY", origin=(0, 0, -16)).circle(64).extrude(16) + disc = soft(disc, 5) + cone = cq.Workplane("XY", origin=(0, 0, -34)).circle(40).workplane(offset=18).circle(64).loft(combine=True) + local = [("nosepiece", disc.union(cone), "mid2")] + bands = ["yellow", "lime", "sky", "white", "red"] + for k in range(5): + barrel, band = objective() + for nm, wp, pal in (("barrel", barrel, "white"), ("band", band, bands[k])): + wp = wp.rotate((0, 0, 0), (0, 1, 0), alpha).translate((r, 0, 0)).rotate((0, 0, 0), (0, 0, 1), 72 * k) + local.append((f"objective_{nm}_{k}", wp, pal)) + ca, sa = math.cos(math.radians(alpha)), math.sin(math.radians(alpha)) + for nm, wp, pal in local: + wp = ( + wp.rotate((0, 0, 0), (0, 1, 0), -alpha) + .translate((-r * ca, 0, -r * sa)) + .rotate((0, 0, 0), (0, 0, 1), -90) + .translate((0, AX, 322)) + ) + out.append((nm, wp, pal)) + return out + + +def build(highlight=False): + """Build the microscope. + + Parameters + ---------- + highlight : bool or set of str + Colour the Koehler controls (field diaphragm red, condenser focus + orange, centering screws blue, aperture lever green). Pass True for + all, or a subset of ``{"A", "B", "C", "lever"}``. + + Returns + ------- + list of tuple + ``(name, cq.Workplane, palette_name)`` triples. A trailing ``~`` on + the palette name shades every curved face smoothly from its normals. + """ + P = [] + + def add(name, wp, pal): + P.append((name, wp, pal)) + + def hl(color, normal, key=""): + on = highlight is True or (highlight and key in highlight) + return color if on else normal + + def mirror_x(fn, side): + wp = fn() + return wp if side > 0 else wp.mirror("YZ") + + # ---------------- base ---------------- + body = prism_yz([(0, 0), (570, 0), (548, 430), (400, 430), (400, 375), (30, 375), (30, 267)], -100, 100) + body = soft(body, 14) + body = body.cut(box(-20, 101, 165, 360, 200, 366)) + add("base", body, "body") + liner = box(-20, 98, 165, 360, 200, 366).cut(box(-17, 99, 168, 357, 203, 363)) + add("recess_liner", liner, "mid") + add("fluor_turret", soft(box(5, 90, 172, 330, 205, 262), 7), "mid2") + add("fluor_dial", soft(cyl_x(52, 88, 96, 230, 234), 2), "dark") + add("fluor_lever", soft(box(84, 97, 290, 318, 208, 222), 3), "white") + P.extend(nosepiece_parts()) + for side, sx in (("R", 1), ("L", -1)): + add(f"focus_flange_{side}", mirror_x(lambda: cyl_x(115, 100, 106, 225, 88), sx), "white") + add( + f"focus_knob_{side}", + mirror_x(lambda: soft(cyl_x(92, 106, 140, 225, 88), 6).union(soft(cyl_x(56, 138, 178, 225, 88), 6)), sx), + "dark", + ) + add("side_button", cyl_x(44, 100, 102, 300, 150), "body") + add("side_slot", soft(box(100, 102, 235, 300, 178, 190), 4, "|X"), "mid2") + add("front_slot", box(-45, -10, 0, 7, 30, 48), "mid2") + add("tool_panel", soft(box(100, 102.5, 425, 530, 215, 330), 8, "|X"), "mid2") + + # ---------------- eyepiece tube ---------------- + add("tube_shelf", soft(box(-115, 102, -15, 115, 267, 400), 12), "body") + add("tube_panel", prism_yz([(34, 384), (98, 384), (98, 292), (72, 292)], 102, 103.5), "panel") + add("tube_knob", soft(cyl_y(28, -35, -15, 5, 340), 4), "dark") + add("tube_body", soft(box(-100, 100, 0, 110, 395, 580), 26), "body") + for i, sx in enumerate((-45, 45)): + dark = ( + soft(cq.Workplane("XY").circle(30).extrude(75), 8) + .union(cq.Workplane("XY", origin=(0, 0, 100)).circle(23).extrude(40)) + .union(soft(cq.Workplane("XY", origin=(0, 0, 139)).circle(29).extrude(24), 6)) + ) + band = cq.Workplane("XY", origin=(0, 0, 74)).circle(25).extrude(27) + for nm, wp, pal in (("tube", dark, "dark"), ("band", band, "white")): + wp = wp.rotate((0, 0, 0), (1, 0, 0), 58).translate((sx, 12, 528)) + add(f"eyepiece_{nm}_{i}", wp, pal) + + # ---------------- stage and sample ---------------- + add("stage", soft(box(-130, 130, 120, 440, 383, 395), 1.2, scale=False), "dark") + add("stage_drum", soft(cyl_y(62, 95, 150, 92, 392), 8), "dark") + add("stage_tab", soft(box(100, 138, 392, 500, 371, 383), 4), "dark") + add("sample", soft(box(-65, 65, AX - 55, AX + 55, 395, 417), 4), "blue") + add("stage_rod", cyl_z(20, 135, 383, 128, 372).union(soft(cyl_z(16, 70, 86, 128, 372), 3)), "dark") + add("stage_rod_collar", soft(cyl_z(28, 85, 136, 128, 372), 4), "white") + + # ---------------- pillar and lamp head ---------------- + add("pillar", soft(prism_yz([(400, 425), (540, 425), (390, 745), (310, 745)], -55, 55), 12), "body") + add("head", soft(box(-95, 95, 211, 309, 712, 850), 26), "head") + add("head_window", soft(box(-62, 22, 208, 211.5, 760, 795), 5, "|Y"), "mid2") + add("head_slot", soft(box(-50, 5, 208, 211.5, 728, 737), 3, "|Y"), "mid") + add("lamphouse", soft(cyl_y(84, 305, 350, 30, 800), 10), "dark") + add("neck", cyl_z(52, 664, 714), "mid") + + # ---------------- Koehler controls ---------------- + add("A_field_diaphragm_ring", knurled_z(84, *FIELD_RING_Z), hl("red~", "dark~", "A")) + add("focus_block", soft(box(-42, 42, 310, 345, 600, 712), 8), "body") + for side, sx in (("R", 1), ("L", -1)): + add(f"focus_stem_{side}", mirror_x(lambda: cyl_x(14, 40, 62, *FOCUS_KNOB_YZ), sx), "white") + add( + f"B_condenser_focus_knob_{side}", + mirror_x( + lambda: soft(cyl_x(38, 62, FOCUS_KNOB_X, *FOCUS_KNOB_YZ), 5).union( + cyl_x(20, FOCUS_KNOB_X - 1, FOCUS_KNOB_X + 1.5, *FOCUS_KNOB_YZ) + ), + sx, + ), + hl("orange", "dark", "B"), + ) + holder = cyl_z(140, 607, 618).union(box(-35, 35, AX, 330, 607, 618)) + holder = holder.cut(cyl_z(70, 600, 625)) + add("condenser_holder", soft(holder, 3), "white") + for i, ang in enumerate(SCREW_ANGLES): + s = soft(cyl_x(10, 66, SCREW_TIP_R, AX, SCREW_Z), 2).rotate((0, AX, 0), (0, AX, 1), ang) + add(f"C_centering_screw_{i}", s, hl("cobalt", "dark", "C")) + tc = TURRET_Y + add("condenser_turret", soft(cyl_z(185, 575, 607, 0, tc), 4), "white") + band = cyl_z(188, 584, 598, 0, tc).cut(cyl_z(175, 580, 600, 0, tc)) + add("condenser_turret_band", band, "dark") + lever = soft(cyl_x(7, 90, 112, tc, 591), 2).rotate((0, tc, 0), (0, tc, 1), -105) + add("aperture_lever", lever, hl("green", "white", "lever")) + add("condenser_lens", cyl_z(80, 516, 575), "white") + add("condenser_lens_rim", soft(cyl_z(82, LENS_BOTTOM_Z, LENS_BOTTOM_Z + 8), 2), "dark") + return P + + +def _smooth_groups(faces): + """Group faces that meet tangentially, so no outline is drawn there.""" + parent = list(range(len(faces))) + + def find(i): + while parent[i] != i: + parent[i] = parent[parent[i]] + i = parent[i] + return i + + edges = {} + for i, f in enumerate(faces): + for e in f.Edges(): + edges.setdefault(e.hashCode(), []).append((i, e)) + for lst in edges.values(): + for a in range(len(lst)): + for b in range(a + 1, len(lst)): + (i, e), (j, e2) = lst[a], lst[b] + if i == j or not e.isSame(e2): + continue + try: + p = e.positionAt(0.5) + if faces[i].normalAt(p).dot(faces[j].normalAt(p)) > 0.97: + parent[find(i)] = find(j) + except Exception: # no normal at a degenerate edge: leave the faces apart + pass + return [find(i) for i in range(len(faces))] + + +def _axis_tone(n): + """Tone index per normal: 0 top, 1 front, 2 side, 3 back or underside. + + Parameters + ---------- + n : ndarray, shape (m, 3) + Outward normals. + + Returns + ------- + ndarray, shape (m,) + """ + ax = np.abs(n).argmax(axis=1) + sign = np.take_along_axis(n, ax[:, None], axis=1)[:, 0] > 0 + tone = np.full(len(n), 2) + tone[(ax == 2) & sign] = 0 + tone[(ax == 2) & ~sign] = 3 + tone[(ax == 1) & ~sign] = 1 + tone[(ax == 1) & sign] = 3 + return tone + + +def _face_shading(face, verts, tris, force=False): + """Fixed tone for a face, or per-vertex normals for a blend. + + Returns + ------- + tone : int + Tone index, or -1 when the face is a blend (fillet or corner patch) + that should be toned per pixel from its normals. + normals : ndarray, shape (len(verts), 3) + Outward vertex normals (zeros unless the face is a blend). + """ + v = np.array([(q.x, q.y, q.z) for q in verts]) + t = np.array(tris) + zeros = np.zeros_like(v) + if face.geomType() == "PLANE": + nv = face.normalAt() + return int(_axis_tone(np.array([[nv.x, nv.y, nv.z]]))[0]), zeros + n = np.cross(v[t[:, 1]] - v[t[:, 0]], v[t[:, 2]] - v[t[:, 0]]) + total = np.linalg.norm(n, axis=1).sum() + mean = n.sum(axis=0) + wraps = total == 0 or np.linalg.norm(mean) / total < 0.8 + if wraps and not force: + return 2, zeros + try: + k = int(np.linalg.norm(n, axis=1).argmax()) + nv = face.normalAt(cq.Vector(*v[t[k]].mean(axis=0))) + if np.dot((nv.x, nv.y, nv.z), n[k]) < 0: + n = -n + except Exception: # no normal at this point: keep the triangle winding as is + pass + vn = np.zeros_like(v) + for k in range(3): + np.add.at(vn, t[:, k], n) + vn /= np.maximum(np.linalg.norm(vn, axis=1), 1e-12)[:, None] + return -1, vn + + +def mesh_scene(parts): + """Tessellate parts into one triangle soup with per-face attributes. + + Returns + ------- + dict + ``pts`` (n, 3), ``normals`` (n, 3), ``tris`` (m, 3), ``tri_id`` (m,), + and per-face-id tables ``fill`` (k, 4, 3), ``line`` (k, 3), + ``group`` (k,), ``tone`` (k,). Face id 0 is the background. + """ + pts, nrm, tris, tri_id = [], [], [], [] + white = [(255, 255, 255)] * 4 + fill, line, group, tone = [white], [(255, 255, 255)], [0], [0] + n, gbase = 0, 1 + for _, wp, pal in parts: + smooth = pal.endswith("~") + tones = PAL[pal.rstrip("~")] + shape = wp.val() + shape.mesh(0.2, 0.06) + faces = shape.Faces() + groups = _smooth_groups(faces) + for f, g in zip(faces, groups): + verts, t = f.tessellate(0.2, 0.06) + if not t: + continue + ft, vn = _face_shading(f, verts, t, smooth) + fid = len(fill) + fill.append(tones[:4]) + line.append(tones[4]) + group.append(gbase + g) + tone.append(ft) + pts.extend((v.x, v.y, v.z) for v in verts) + nrm.extend(vn) + tris.extend((a + n, b + n, c + n) for a, b, c in t) + tri_id.extend([fid] * len(t)) + n += len(verts) + gbase += len(faces) + return dict( + pts=np.array(pts), + normals=np.array(nrm), + tris=np.array(tris), + tri_id=np.array(tri_id), + fill=np.array(fill, np.uint8), + line=np.array(line, np.uint8), + group=np.array(group, np.int64), + tone=np.array(tone), + ) + + +def render(scene, path, focus, azim, elev, half_height, size=(960, 1060), ss=3, line_px=5): + """Render a flat-shaded cartoon with outlines. + + Parameters + ---------- + scene : dict + Output of `mesh_scene`. + path : path-like + Output PNG. + focus : tuple of float + Point at the image centre. + azim : float + Camera azimuth in degrees, measured from +x toward the front (-y). + elev : float + Camera elevation in degrees. + half_height : float + Half the image height in model units (orthographic). + size : tuple of int + Output size in pixels. + ss : int + Supersampling factor. + line_px : int + Outline width in supersampled pixels (odd). + """ + tris, tri_id = scene["tris"], scene["tri_id"] + pd = vtk.vtkPolyData() + vp = vtk.vtkPoints() + vp.SetData(ns.numpy_to_vtk(scene["pts"], deep=True)) + pd.SetPoints(vp) + cells = np.hstack([np.full((len(tris), 1), 3), tris]).astype(np.int64) + ca = vtk.vtkCellArray() + ca.SetCells(len(tris), ns.numpy_to_vtkIdTypeArray(cells.ravel(), deep=True)) + pd.SetPolys(ca) + idc = np.stack([tri_id & 255, (tri_id >> 8) & 255, (tri_id >> 16) & 255], axis=1).astype(np.uint8) + ncol = np.clip(np.rint((scene["normals"] + 1) * 127.5), 0, 255) + carr = ns.numpy_to_vtk(idc, deep=True) + carr.SetName("id") + parr = ns.numpy_to_vtk(ncol.astype(np.uint8), deep=True) + parr.SetName("normal") + pd.GetCellData().SetScalars(carr) + pd.GetPointData().SetScalars(parr) + mapper = vtk.vtkPolyDataMapper() + mapper.SetInputData(pd) + mapper.SetColorModeToDirectScalars() + actor = vtk.vtkActor() + actor.SetMapper(mapper) + actor.GetProperty().LightingOff() + ren = vtk.vtkRenderer() + ren.SetBackground(0, 0, 0) + ren.AddActor(actor) + win = vtk.vtkRenderWindow() + win.SetOffScreenRendering(1) + win.SetMultiSamples(0) + win.SetSize(size[0] * ss, size[1] * ss) + win.AddRenderer(ren) + a, e = math.radians(azim), math.radians(elev) + d = np.array([math.cos(e) * math.cos(a), -math.cos(e) * math.sin(a), math.sin(e)]) + cam = ren.GetActiveCamera() + cam.ParallelProjectionOn() + cam.SetFocalPoint(*focus) + cam.SetPosition(*(np.array(focus) + 4000 * d)) + cam.SetViewUp(0, 0, 1) + cam.SetParallelScale(half_height) + ren.ResetCameraClippingRange() + + def grab(): + win.Render() + w2i = vtk.vtkWindowToImageFilter() + w2i.SetInput(win) + w2i.ReadFrontBufferOff() + w2i.Update() + img = w2i.GetOutput() + w, h, _ = img.GetDimensions() + buf = ns.vtk_to_numpy(img.GetPointData().GetScalars()) + return buf.reshape(h, w, -1)[::-1, :, :3].astype(np.int64) + + mapper.SetScalarModeToUseCellData() + rgb = grab() + mapper.SetScalarModeToUsePointData() + normal = grab() / 127.5 - 1.0 + ids = rgb[..., 0] | (rgb[..., 1] << 8) | (rgb[..., 2] << 16) + ids = np.clip(ids, 0, len(scene["fill"]) - 1) + tone = scene["tone"][ids] + blend = tone < 0 + tone[blend] = 2 + color = scene["fill"][ids, tone] + # blends fade between the tones of the faces they join + nb = normal[blend] + nb /= np.maximum(np.linalg.norm(nb, axis=1), 1e-9)[:, None] + fb = scene["fill"][ids[blend]].astype(float) + rows = np.arange(len(nb)) + mix = ( + nb[:, 0:1] ** 2 * fb[:, 2] + + nb[:, 1:2] ** 2 * fb[rows, np.where(nb[:, 1] < 0, 1, 3)] + + nb[:, 2:3] ** 2 * fb[rows, np.where(nb[:, 2] > 0, 0, 3)] + ) + color[blend] = np.clip(np.rint(mix), 0, 255).astype(np.uint8) + kid = scene["group"][ids] + oc = scene["line"][ids] + lines = np.full_like(color, 255) + eh = kid[:, :-1] != kid[:, 1:] + m = np.minimum(oc[:, :-1], oc[:, 1:]) + lines[:, :-1][eh] = np.minimum(lines[:, :-1][eh], m[eh]) + ev = kid[:-1, :] != kid[1:, :] + m = np.minimum(oc[:-1, :], oc[1:, :]) + lines[:-1, :][ev] = np.minimum(lines[:-1, :][ev], m[ev]) + lim = Image.fromarray(lines).filter(ImageFilter.MinFilter(line_px)) + la = np.asarray(lim) + mask = (la < 255).any(axis=2) + out = color.copy() + out[mask] = la[mask] + Image.fromarray(out).resize(size, Image.LANCZOS).save(path) diff --git a/docs/guide/labelfree-screening/figures/make_figures.py b/docs/guide/labelfree-screening/figures/make_figures.py new file mode 100644 index 00000000..6290e7ea --- /dev/null +++ b/docs/guide/labelfree-screening/figures/make_figures.py @@ -0,0 +1,457 @@ +"""Generate the data figures for the label-free screening tutorial. + +Draws every figure from the 8-bit image crops in ./data/, so it needs no +data outside this folder. See ../README.md for the exact command and the +pinned package versions. + +Writes vector PDF (for the whitepaper) and PNG (for the docs site) figure +pairs into this folder. Figures are drawn at their print size with 8 pt +labels: the overview at the full text width, the failure-mode figures at +the size they take inside their boxes, so the whitepaper includes them +unscaled. + +The crops in ./data/ are cut from one raw OPS position and from +reconstructions of it on the Biohub HPC. ``--from-hpc`` rebuilds them there +(needs iohub); the paths are options because they are specific to that +system. + +The Koehler alignment figure has its own script, koehler/make_figure.py. +""" + +import argparse +from pathlib import Path + +import matplotlib +import matplotlib.patheffects as pe +import matplotlib.pyplot as plt +import numpy as np +from PIL import Image, ImageDraw + +matplotlib.use("Agg") +plt.rcParams["font.family"] = "monospace" +plt.rcParams["font.size"] = 8 + +FIGURES = Path(__file__).resolve().parent +DATA = FIGURES / "data" + +# Defaults for --from-hpc: the raw OPS position, and the folder of +# reconstructions of it (one .zarr per variant, see refresh_from_hpc). +RAW_PATH = "/hpc/projects/icd.fast.ops/ops0105_20260106/0-convert/live_imaging/phenotyping_transform.zarr/A/1/029029" +RECONS = "/hpc/mydata/talon.chandler/2026-11-04-wo-hcs-whitepaper/recons" + +FULL_W = 7.5 # print width (in) of a full-width figure: letter paper, 1.25 cm margins +BOX_W = 2.9 # print width (in) of a figure inside a failure-mode box +N_SLICES = 7 # slices in the defocus stack +CROP_PX = 256 # stored crop size; more than any panel needs at print resolution + +# Zoom regions chosen from full-FOV overviews: clean monolayer, no debris. +YS = slice(384, 896) +XS = slice(1152, 1664) +T_YS, T_XS = slice(256, 768), slice(1280, 1792) # edge-tile crop +F_YS, F_XS = slice(384, 704), slice(1344, 1664) # focus-sweep crop +S_YS, S_XS = slice(640, 1152), slice(1280, 1792) # defocus-stack crop +PX_UM = 0.325 # yx pixel size in micrometers +N_WIDE, N_FOCUS = 512, 320 # source pixels across the wide and focus crops + + +def refresh_from_hpc(raw_path=RAW_PATH, recons=RECONS): + """Rebuild the crops in ./data/ from the raw data and reconstructions. + + Each crop is scaled to the contrast limits its panel is shown with, + resampled to ``CROP_PX`` pixels and stored as an 8-bit grayscale PNG. + + Parameters + ---------- + raw_path : str + Raw OME-Zarr position with a ``BF`` channel of ``N_SLICES`` slices. + recons : str + Folder holding one ``.zarr`` phase reconstruction per panel: + ``nominal`` (the "correct", "reg 1e-3" and "0 slices" panels), + ``flipped``, ``reg_1e-5``, ``reg_1e-1``, ``offset_-2.0`` ("-2 + slices"), ``defocused`` ("+2 slices"), and, for edge position + 002029, ``edge_baseline`` ("tilt not modeled") and ``edge_apply`` + ("tilt fitted"). + """ + from iohub import open_ome_zarr + + def load_phase(name, position="029029"): + with open_ome_zarr(Path(recons) / f"{name}.zarr" / f"A/1/{position}") as ds: + return np.asarray(ds.data[0, 0, 0]).astype(np.float32) + + def write(name, img, lo, hi): + scaled = np.rint(np.clip((img - lo) / (hi - lo), 0, 1) * 255).astype(np.uint8) + Image.fromarray(scaled).resize((CROP_PX, CROP_PX), Image.LANCZOS).save(DATA / f"{name}.png") + print(f"wrote data/{name}.png") + + DATA.mkdir(exist_ok=True) + with open_ome_zarr(raw_path) as raw_ds: + bf_idx = raw_ds.channel_names.index("BF") + bf = np.asarray(raw_ds.data[0, bf_idx]).astype(np.float32) # (N_SLICES, 2048, 2048) + # shared grayscale so the background stays consistent across slices + stack = bf[:, S_YS, S_XS] + stack_lo, stack_hi = np.percentile(stack, [0.5, 99.5]) + for z in range(N_SLICES): + write(f"stack_{z}", stack[z], stack_lo, stack_hi) + + nominal = load_phase("nominal") + lo, hi = np.percentile(nominal[YS, XS], [1, 99.5]) + write("nominal", nominal[YS, XS], lo, hi) + write("flipped", load_phase("flipped")[YS, XS], lo, hi) + for reg in ("1e-5", "1e-1"): + crop = load_phase(f"reg_{reg}")[YS, XS] + write(f"reg_{reg}", crop, *np.percentile(crop, [1, 99.5])) + for off, name in (("-2", "offset_-2.0"), ("0", "nominal"), ("+2", "defocused")): + write(f"focus_{off}", load_phase(name)[F_YS, F_XS], lo, hi) + for key, name in (("edge_baseline", "edge_baseline"), ("edge_tilt", "edge_apply")): + crop = load_phase(name, position="002029")[T_YS, T_XS] + write(key, crop, *np.percentile(crop, [1, 99.5])) + + +def load(name): + """Load one display-scaled crop from ./data/. + + Parameters + ---------- + name : str + Basename of the PNG in ./data/ (without extension). + + Returns + ------- + numpy.ndarray + 2D uint8 image. + """ + return np.asarray(Image.open(DATA / f"{name}.png").convert("L")) + + +def show(ax, img): + """Show a display-scaled crop in grayscale without ticks.""" + ax.imshow(img, cmap="gray", vmin=0, vmax=255) + ax.set_xticks([]) + ax.set_yticks([]) + + +def field_stop_view(img, radius=0.19, n_blades=10, tilt_deg=11): + """Show an image through a centered, focused field stop. + + Matches the "Center" inset of the Koehler figure: a bright bladed + aperture on a dark field. + + Parameters + ---------- + img : numpy.ndarray + 2D uint8 image filling the camera field of view. + radius : float, optional + Aperture radius as a fraction of the image width. + n_blades : int, optional + Number of aperture blades. + tilt_deg : float, optional + Rotation of the blades in degrees. + + Returns + ------- + numpy.ndarray + 2D uint8 image, black outside the aperture. + """ + n = 600 + t = np.radians(tilt_deg + np.arange(n_blades) * 360 / n_blades) + mask = Image.new("L", (n, n), 0) + ImageDraw.Draw(mask).polygon(list(zip(n * (0.5 + radius * np.cos(t)), n * (0.5 + radius * np.sin(t)))), fill=255) + big = np.asarray(Image.fromarray(img).resize((n, n), Image.LANCZOS), float) + return np.rint(big * np.asarray(mask) / 255).astype(np.uint8) + + +def add_scalebar(ax, n_px, n_src, length_um=25): + """Draw a scale bar in the lower-right corner of an image axis. + + The bar and label carry a thin black outline so they stay legible + over bright cells, and the label right-aligns with the bar end so + a label wider than the bar overhangs inward, never off the panel. + + Parameters + ---------- + ax : matplotlib.axes.Axes + Image axis. + n_px : int + Width of the displayed image in pixels. + n_src : int + Width of the same field in source pixels of size ``PX_UM``. + length_um : float, optional + Scale bar length in micrometers. + """ + k = n_px / n_src # displayed pixels per source pixel + bar_px = length_um / PX_UM * k + # inset from the right and bottom edges by 45 and 55 source pixels + x0, y0 = n_px - bar_px - 45 * k, n_px - 55 * k + ax.plot( + [x0, x0 + bar_px], + [y0, y0], + color="white", + lw=1.5, + path_effects=[pe.withStroke(linewidth=3, foreground="black")], + ) + ax.text( + x0 + bar_px, + y0 - 10 * k, # label 10 source pixels above the bar + f"{length_um} µm", + color="white", + ha="right", + va="bottom", + fontsize=7, + path_effects=[pe.withStroke(linewidth=1.5, foreground="black")], + ) + + +def panel(ax, name, title, n_src=N_WIDE, scalebar=False): + """Render one grayscale image panel from a crop in ./data/.""" + img = load(name) + show(ax, img) + ax.set_title(title, fontsize=8) + if scalebar: + add_scalebar(ax, img.shape[-1], n_src) + + +def save(fig, stem, tight=True): + """Save a figure as vector PDF (whitepaper) and PNG (docs site). + + Parameters + ---------- + fig : matplotlib.figure.Figure + Figure to save and close. + stem : str + Output basename, without extension. + tight : bool, optional + Crop to the drawn content. Turn off to keep the exact figure size. + """ + bbox = "tight" if tight else None + # 220 dpi shows every stored pixel of the crops at print size and keeps the PDFs small + for ext, dpi in (("pdf", 220), ("png", 220)): + # no creation date, so reruns give byte-identical PDFs + meta = {"CreationDate": None} if ext == "pdf" else None + fig.savefig(FIGURES / f"{stem}.{ext}", dpi=dpi, bbox_inches=bbox, transparent=True, metadata=meta) + plt.close(fig) + print(f"wrote {stem}.pdf/.png") + + +def draw_mda_zstack_panel(ax, z_start, z_end, z_step): + """Draw the Micro-Manager MDA "Z-stacks (slices)" group box. + + Mimics the Multi-Dimensional Acquisition dialog, laid out compactly so + the text stays legible at print size. + + Parameters + ---------- + ax : matplotlib.axes.Axes + Target axes; its aspect ratio should be 440:330. + z_start, z_end, z_step : str + Values shown in the three text fields. + """ + w, h = 440, 330 + ax.set_xlim(0, w) + ax.set_ylim(h, 0) + ax.axis("off") + pt = ax.get_position().width * ax.figure.get_figwidth() * 72 / w + gui = dict(family="DejaVu Sans", va="center") # bundled with matplotlib, so it renders the same anywhere + box = matplotlib.patches.FancyBboxPatch + + def rounded(x, y, bw, bh, fc, ec, r=4, lw=0.5, z=2): + ax.add_patch(box((x, y), bw, bh, boxstyle=f"round,pad=0,rounding_size={r}", fc=fc, ec=ec, lw=lw, zorder=z)) + + def checkbox(x, y, size=30): + rounded(x, y - size / 2, size, size, "white", "#8e8e8e", r=4) + ax.plot( + [x + 0.22 * size, x + 0.43 * size, x + 0.80 * size], + [y, y + 0.24 * size, y - 0.27 * size], + color="#1f3f99", + lw=0.11 * size * pt, + solid_capstyle="round", + solid_joinstyle="round", + zorder=3, + ) + + ax.add_patch(plt.Rectangle((0, 0), w, h, fc="#efefef", ec="none", zorder=0)) + rounded(8, 26, w - 16, h - 34, "none", "#c4c4c4", r=5, lw=0.6, z=1) + ax.add_patch(plt.Rectangle((22, 10), 300, 32, fc="#efefef", ec="none", zorder=1.5)) + checkbox(30, 26) + ax.text(70, 26, "Z-stacks (slices)", fontsize=27 * pt, weight="bold", color="#1e1e1e", **gui) + rows = (("Z-start [um]", z_start, True), ("Z-end [um]", z_end, True), ("Z-step [um]", z_step, False)) + for i, (label, value, has_set) in enumerate(rows): + y = 82 + 50 * i + ax.text(34, y, label, fontsize=24 * pt, color="#111111", **gui) + rounded(192, y - 21, 112, 42, "white", "#b4b4b4", r=2) + ax.text(202, y, value, fontsize=24 * pt, color="#111111", **gui) + if has_set: + rounded(312, y - 20, 102, 40, "#f5f5f5", "#c6c6c6", r=5) + ax.text(363, y, "Set", fontsize=24 * pt, color="#9a9a9a", ha="center", **gui) + rounded(34, 212, 236, 40, "#e2e2e2", "#a6a6a6", r=4) + ax.text(46, 232, "relative Z", fontsize=24 * pt, color="#111111", **gui) + ax.add_patch(plt.Polygon([[236, 226], [256, 226], [246, 239]], fc="#111111", ec="none", zorder=3)) + checkbox(96, 290, size=28) + ax.text(136, 290, "Keep shutter open", fontsize=24 * pt, color="#111111", **gui) + + +def make_overview(): + """Figure 1: acquisition settings, defocus stack, WaveOrder, phase.""" + fig = plt.figure(figsize=(FULL_W, 2.1)) + + def icon_axes(rect, aspect_equal=False): + ax = fig.add_axes(rect) + ax.set_xlim(0, 1) + ax.set_ylim(0, 1) + if aspect_equal: + ax.set_aspect("equal", anchor="W") + ax.axis("off") + return ax + + # Three icons of equal width in one column, labels left-aligned beside them. + ICON_X, ICON_W = 0.015, 0.085 + ICON_TEXT_X = ICON_X + ICON_W + 0.012 + square = ICON_W * FULL_W / 2.1 # height of a square icon, in figure units + + # Koehler alignment on top: the centered, focused field stop of Figure 2. + ax = fig.add_axes([ICON_X, 0.655, ICON_W, square]) + show(ax, field_stop_view(load("stack_3"))) + for spine in ax.spines.values(): + spine.set_color("0.3") + spine.set_linewidth(0.5) + fig.text(ICON_TEXT_X, 0.655 + square / 2, "Koehler\nalignment", fontsize=7, va="center", ha="left") + + # Transmission optics: cone angles drawn to scale for each NA. + # half-angle = asin(NA): 23.6 deg for 0.4 (illumination, top), + # 33.4 deg for 0.55 (detection, bottom). + ax = icon_axes([ICON_X, 0.30, ICON_W, square], aspect_equal=True) + tan_ill = np.tan(np.arcsin(0.4)) + tan_det = np.tan(np.arcsin(0.55)) + # trapezoids: cone sides truncated near the sample plane (y = 0.5) + ill_near, ill_far = 0.70, 0.95 # condenser above the sample + det_near, det_far = 0.30, 0.05 # objective below the sample + ax.add_patch( + plt.Polygon( + [ + [0.5 - (ill_near - 0.5) * tan_ill, ill_near], + [0.5 + (ill_near - 0.5) * tan_ill, ill_near], + [0.5 + (ill_far - 0.5) * tan_ill, ill_far], + [0.5 - (ill_far - 0.5) * tan_ill, ill_far], + ], + color="0.45", + ) + ) + ax.add_patch( + plt.Polygon( + [ + [0.5 - (0.5 - det_near) * tan_det, det_near], + [0.5 + (0.5 - det_near) * tan_det, det_near], + [0.5 + (0.5 - det_far) * tan_det, det_far], + [0.5 - (0.5 - det_far) * tan_det, det_far], + ], + color="0.25", + ) + ) + ax.plot([0.08, 0.92], [0.5, 0.5], color="black", lw=1.0) + fig.text(ICON_TEXT_X, 0.58, "0.4 NA condenser", fontsize=7, va="center", ha="left") + fig.text(ICON_TEXT_X, 0.36, "0.55 NA, 20$\\times$\ndetection", fontsize=7, va="center", ha="left") + + # z stack: the Micro-Manager MDA settings that give 7 slices at 2 um. + mda_h = square * 330 / 440 + ax = fig.add_axes([ICON_X, 0.03, ICON_W, mda_h]) + draw_mda_zstack_panel(ax, "-6", "6", "2") + fig.text(ICON_TEXT_X, 0.03 + mda_h / 2, "7-slice z stack\n2 µm spacing", fontsize=7, va="center", ha="left") + + # Defocus stack: all 7 planes fanned bottom-to-top in acquisition order. + step_x, step_y, size_x, size_y = 0.006, 0.053, 0.135, 0.47 # fan offsets and slice size, figure units + for k in range(N_SLICES): + ax = fig.add_axes([0.29 + step_x * k, 0.085 + step_y * k, size_x, size_y]) + img = load(f"stack_{k}").copy() + if k < N_SLICES - 1: + # blank the part hidden behind the next slice; it is never seen and only bloats the files + h, w = img.shape + img[: int(h * (1 - step_y / size_y)) - 2, int(w * step_x / size_x) + 2 :] = 128 + show(ax, img) + for spine in ax.spines.values(): + spine.set_color("0.3") + fig.text(0.3755, 0.025, "7-slice defocus stack", fontsize=8, ha="center") + + # WaveOrder box: config + CLI. + ax = icon_axes([0.497, 0.05, 0.3, 0.9]) + ax.add_patch(plt.Rectangle((0.02, 0.02), 0.96, 0.96, fill=False, color="0.3", lw=1.0)) + ax.text(0.5, 0.885, "WaveOrder", fontsize=9, ha="center", weight="bold") + config = [ + "$ cat config.yml", + "...", + "yx_pixel_size: 0.325", + "z_pixel_size: 2.0", + "numerical_aperture_detection: 0.55", + "numerical_aperture_illumination: 0.4", + "z_focus_offset: auto", + "...", + ] + command = [ + "$ waveorder reconstruct \\", + " -i data.zarr/A/1/029029 \\", + " -c config.yml \\", + " -o phase.zarr", + ] + ax.text(0.045, 0.56, "\n".join(config), fontsize=6.5, va="center") + ax.text(0.045, 0.19, "\n".join(command), fontsize=6.5, va="center") + + # Reconstruction. + show(fig.add_axes([0.83, 0.13, 0.16, 0.72]), load("nominal")) + fig.text(0.91, 0.025, "quantitative phase", fontsize=8, ha="center") + + # Arrows in the clear gaps between columns. + for x0, x1 in ((0.253, 0.283), (0.466, 0.494), (0.801, 0.825)): + fig.add_artist( + matplotlib.patches.FancyArrowPatch( + (x0, 0.5), + (x1, 0.5), + transform=fig.transFigure, + arrowstyle="-|>", + mutation_scale=10, + color="0.15", + lw=1.2, + ) + ) + + save(fig, "fig_overview", tight=False) # exact width, included at the full text width + + +def make_failure_modes(): + """Figures for the four failure-mode boxes, at their print size.""" + two, three = (BOX_W, 1.15), (BOX_W, 1.0) # sizes of the 2- and 3-panel figures (in) + + # contrast flip + fig, axs = plt.subplots(1, 2, figsize=two) + panel(axs[0], "nominal", "correct\n(nucleoli bright)", scalebar=True) + panel(axs[1], "flipped", "flipped z axis\n(nucleoli dark)") + save(fig, "fig_flip") + + # regularization sweep + fig, axs = plt.subplots(1, 3, figsize=three) + for ax, reg, note in zip(axs, ["1e-5", "1e-3", "1e-1"], ["too noisy", "chosen", "too smooth"]): + name = "nominal" if reg == "1e-3" else f"reg_{reg}" + panel(ax, name, f"reg {reg}\n({note})", scalebar=(reg == "1e-5")) + save(fig, "fig_reg") + + # focus offset + fig, axs = plt.subplots(1, 3, figsize=three) + for ax, off in zip(axs, ["-2", "0", "+2"]): + note = "(chosen)" if off == "0" else "" + panel(ax, f"focus_{off}", f"{off} slices\n{note}", n_src=N_FOCUS, scalebar=(off == "-2")) + save(fig, "fig_focus") + + # illumination tilt on an edge FOV + fig, axs = plt.subplots(1, 2, figsize=two) + panel(axs[0], "edge_baseline", "tilt not modeled\n", scalebar=True) + panel(axs[1], "edge_tilt", "tilt fitted\n(0.49 rad zenith)") + save(fig, "fig_tilt") + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--from-hpc", action="store_true", help="rebuild ./data/ from the Biohub HPC stores first") + parser.add_argument("--raw", default=RAW_PATH, help="raw OME-Zarr position used by --from-hpc") + parser.add_argument("--recons", default=RECONS, help="folder of reconstructions used by --from-hpc") + args = parser.parse_args() + if args.from_hpc: + refresh_from_hpc(args.raw, args.recons) + make_overview() + make_failure_modes() diff --git a/docs/guide/labelfree-screening/figures/requirements.in b/docs/guide/labelfree-screening/figures/requirements.in new file mode 100644 index 00000000..36f8b19b --- /dev/null +++ b/docs/guide/labelfree-screening/figures/requirements.in @@ -0,0 +1,4 @@ +cadquery==2.8.0 +matplotlib==3.10.8 +numpy==2.4.2 +pillow==13.0.0 diff --git a/docs/guide/labelfree-screening/figures/requirements.txt b/docs/guide/labelfree-screening/figures/requirements.txt new file mode 100644 index 00000000..481c6934 --- /dev/null +++ b/docs/guide/labelfree-screening/figures/requirements.txt @@ -0,0 +1,125 @@ +# This file was autogenerated by uv via the following command: +# uv pip compile requirements.in --python-version 3.12 --universal -o requirements.txt +aiohappyeyeballs==2.7.1 + # via aiohttp +aiohttp==3.14.5 + # via wslink +aiosignal==1.4.0 + # via aiohttp +attrs==26.1.0 + # via aiohttp +cadquery==2.8.0 + # via -r requirements.in +cadquery-ocp==7.9.3.1.1 + # via cadquery +cadquery-ocp-proxy==7.9.3.1.1 + # via cadquery-ocp +casadi==3.8.2 + # via cadquery +contourpy==1.4.0 + # via matplotlib +cycler==0.12.1 + # via matplotlib +ezdxf==1.4.5 + # via cadquery +fonttools==4.68.0 + # via + # ezdxf + # matplotlib +frozenlist==1.8.0 + # via + # aiohttp + # aiosignal +idna==3.20 + # via yarl +kiwisolver==1.5.1 + # via matplotlib +llvmlite==0.50.0 + # via numba +matplotlib==3.10.8 + # via + # -r requirements.in + # vtk +more-itertools==11.2.1 + # via trame-server +msgpack==1.2.4 + # via wslink +multidict==7.2.1 + # via + # aiohttp + # yarl +multimethod==1.12 + # via cadquery +nlopt==2.11.0 + # via cadquery +numba==0.68.1 + # via cadquery +numpy==2.4.2 + # via + # -r requirements.in + # casadi + # contourpy + # ezdxf + # matplotlib + # nlopt + # numba + # scipy +packaging==26.3 + # via matplotlib +pillow==13.0.0 + # via + # -r requirements.in + # matplotlib +propcache==0.5.4 + # via + # aiohttp + # yarl +pyparsing==3.3.3 + # via + # cadquery + # ezdxf + # matplotlib +python-dateutil==4.0.0 + # via matplotlib +pyyaml==6.0.3 + # via trame +runtype==0.5.3 + # via cadquery +scipy==1.18.1 + # via cadquery +trame==4.0.0 + # via cadquery +trame-client==4.1.4 + # via + # trame + # trame-components + # trame-vtk + # trame-vuetify +trame-common==1.3.0 + # via + # trame + # trame-client + # trame-server +trame-components==2.5.0 + # via cadquery +trame-server==4.1.2 + # via trame +trame-vtk==2.11.17 + # via cadquery +trame-vuetify==3.3.0 + # via cadquery +typing-extensions==4.16.0 + # via + # aiohttp + # aiosignal + # ezdxf +tzdata==2026.6 + # via python-dateutil +vtk==9.6.2 + # via cadquery-ocp +wslink==2.6.0 + # via + # trame + # trame-server +yarl==1.25.1 + # via aiohttp diff --git a/docs/guide/labelfree-screening/labelfree-screening.md b/docs/guide/labelfree-screening/labelfree-screening.md new file mode 100644 index 00000000..592a0ca2 --- /dev/null +++ b/docs/guide/labelfree-screening/labelfree-screening.md @@ -0,0 +1,190 @@ +# WaveOrder for label-free high-throughput screening + +![Key acquisition settings produce a defocus stack that WaveOrder converts into quantitative phase](./figures/fig_overview.png) + +**Figure 1.** Key acquisition settings (left) produce a defocus stack with +defocus-dependent contrast that WaveOrder converts into quantitative phase. + +This guide demonstrates WaveOrder for label-free high-throughput screening +using optical pooled screening (OPS) data from the +[Biohub's multimodal perturbation atlas](https://www.biorxiv.org/content/10.64898/2026.06.01.728087v1) +[1], where phase from defocus enabled label-free tracking and phenotyping of +CRISPR-perturbed A549 cells. Brightfield defocus stacks from a standard +motorized widefield microscope, together with a +[WaveOrder](https://github.com/biohub/waveorder) config [2], yield +quantitative phase at screening scale (**Figure 1**). + +After reading this guide and acquiring data, use the +[first-reconstruction guide](../first-reconstruction.md) and connect your +agent to the [Biohub MCP](https://biohub.ai/mcp) to run the +`waveorder-tutorial` skill. Methods are described in the +[WaveOrder preprint](https://arxiv.org/abs/2412.09775) [3]. This guide is +also available as a [two-page PDF](./whitepaper.pdf). + +## Acquisition + +The three settings that matter most are: + +- **Koehler illumination.** Align the condenser before every session + (**Figure 2**). Misalignment is the most common source of artifacts. Ron + Vale's five-minute + [iBiology tutorial](https://www.ibiology.org/talks/set-up-koehler-illumination/) + [4] is a good refresher. +- **Condenser NA ≈ 2/3 of detection NA.** We used a 0.4 NA + condenser and a 0.55 NA objective. A larger condenser aperture reduces + contrast, while a smaller condenser aperture reduces contrast and + resolution. +- **Z spacing and range.** At 20×, start at 2 µm spacing and cover the full + cell height with visibly blurred features on either end of the stack + (here, 7 slices = 12 µm). Center the stack on the focus; otherwise set + `z_focus_offset` to the offset in slices or to `auto`. For different + objectives, scale inversely with magnification: e.g. 4 µm at 10×, 1 µm at + 40×. + +| Parameter | Perturbation atlas value | Notes | +| --- | --- | --- | +| Objective | 20×, 0.55 NA, air (n = 1) | any objective works; match the config | +| Condenser | 0.4 NA | ≈2/3 of detection NA, Koehler aligned | +| Z stack | 7 slices, 2 µm | confirm defocused features on top and bottom slices; use more slices for thicker samples | +| Camera | 6.5 µm pixels | 6.5 µm / 20× = 0.325 µm at the sample | +| Wavelength | 450 nm | any wavelength is fine; ideally use a 10 nm bandpass filter | +| Exposure | a few ms | fill 1/2–2/3 of the dynamic range | + +**Table 1.** Acquisition parameters for the +[Biohub's multimodal perturbation atlas dataset](https://www.biorxiv.org/content/10.64898/2026.06.01.728087v1). + +![Realign the condenser after changing the objective or the sample](./figures/fig_koehler.png) + +**Figure 2.** Realign the condenser after changing the objective or the +sample. After focusing on the sample, +**close** the field stop, +**focus** and +**center** the field stop edges, then +**open** the field stop. + +## Reconstruction + +Convert to OME-Zarr with [iohub](https://github.com/czbiohub-sf/iohub) +(`iohub convert -i -o data.zarr`), then record the acquisition +parameters in a file named `config.yml` +([download](./configs/phase_autofocus.yml)): + +```yaml +input_channel_names: [BF] +reconstruction_dimension: 2 +phase: + transfer_function: + yx_pixel_size: 0.325 # 6.5 um / 20x + z_pixel_size: 2.0 + wavelength_illumination: 0.450 + index_of_refraction_media: 1.0 + numerical_aperture_detection: 0.55 + numerical_aperture_illumination: 0.4 + invert_phase_contrast: false + z_focus_offset: auto + apply_inverse: + regularization_strength: 0.001 +``` + +Reconstruct one position and compare it to the raw data in napari: + +```bash +waveorder reconstruct -i data.zarr/A/1/029029 -c config.yml -o phase.zarr +waveorder view data.zarr/A/1/029029 phase.zarr/A/1/029029 +``` + +Dense structures (nucleoli, nuclear envelopes, cell margins) should appear +brighter than background, as in **Figure 1**. +`reconstruction_dimension: 2` returns one phase image per defocus stack, the +best choice for samples that are thin compared to the depth of field of the +microscope. If the sample appears to blur all at once as you defocus, use 2. +If different regions of the sample blur at different defocus positions, +consider trialing 3. + +## Failure modes and their fixes + +**Failure mode 1 | Flipped z axis.** Stages disagree on the z sign +convention (is the first slice above or below focus?). If the convention is +flipped, contrast will be inverted and downstream comparison will be +challenging. Dense organelles should be bright. Fix: +`invert_phase_contrast: true`. Check once per microscope by reconstructing +one stack both ways. + +![Correct versus inverted phase contrast](./figures/fig_flip.png) + +**Failure mode 2 | Incorrect regularization.** `regularization_strength` +balances noise and resolution and varies by orders of magnitude across +samples and exposures. Sweep decades on one position and choose manually. +Too small amplifies blotchy low-frequency noise; too large leaves a +washed-out image. The optimum is usually within a decade of `1e-3`. + +```bash +for reg in 1e-5 1e-4 1e-3 1e-2 1e-1; do + sed "s/regularization_strength: .*/regularization_strength: $reg/" config.yml > config_$reg.yml + waveorder reconstruct -i data.zarr/A/1/029029 -c config_$reg.yml -o phase_$reg.zarr +done +waveorder view phase_*.zarr/A/1/029029 +``` + +![Regularization sweep](./figures/fig_reg.png) + +**Failure mode 3 | Focus drift.** When the stack center (e.g. the 4th +slice in a 7-slice stack) is not in focus, the reconstruction will be +blurry. Setting `z_focus_offset: auto` runs the search that can recover the +defocus offset: + +```text +$ waveorder reconstruct -i data.zarr/A/1/029029 -c config.yml -o phase.zarr +Resolving z_focus_offset with a per-slice focus search... +Resolved z_focus_offset = 0 (slice units) from the data; per-crop focus slices [3, 3, 3, 3, 3] +``` + +![z_focus_offset sweep](./figures/fig_focus.png) + +**Failure mode 4 | Tilted illumination at the well edge.** Misaligned +Koehler and imaging near a well-edge meniscus tilt the illumination, making +cells look shadow-cast with reduced contrast. Fit the tilt by gradient +descent in the same config: + +```yaml +# inside phase.transfer_function: + z_focus_offset: auto + tilt_angle_zenith: {init: 0.13, lr: 0.05} + tilt_angle_azimuth: {init: 0.0, lr: 0.05} +# and at the top level: +optimization: + max_iterations: 50 + method: adam +``` + +![Edge-of-well field with and without the fitted illumination tilt](./figures/fig_tilt.png) + +## Scaling up + +A single config file should generate good reconstructions across a screen. +We suggest parallelizing `waveorder reconstruct` over positions (one process +or cluster job per position) with `device: cuda:0` to reconstruct on a GPU. +We recommend `z_focus_offset: auto` to find the focus of each position. +Give each job its own config copy and output store (e.g. +`config_.yml`, `phase_.zarr`); jobs that share them +overwrite each other's transfer function. + +We recommend manual supervision to set up the optimized +`tilt_angle_{zenith,azimuth}` parameters across entire wells. We find that +initializing these tilt parameters at good initial tilts gives the +most stable reconstructions, so we recommend inspecting reconstructions at the +well edges, then refining the initial values until you reach stable +reconstructions that pass QC. + +## References + +1. C. Liu, A. V. Hillsley, M. Sekhar, et al., "A Multimodal Perturbation + Atlas Defines the Phenotypic Resolution of Cellular Morphology," + [bioRxiv 2026.06.01.728087](https://www.biorxiv.org/content/10.64898/2026.06.01.728087v1). +2. WaveOrder repository: + [github.com/biohub/waveorder](https://github.com/biohub/waveorder). +3. T. Chandler, I. E. Ivanov, G. Sturm, et al., "WaveOrder: A differentiable + wave-optical framework for scalable biological microscopy with diverse + modalities," [arXiv:2412.09775](https://arxiv.org/abs/2412.09775). +4. R. Vale, "Microscopy: Setting Up Koehler Illumination," + [iBiology Microscopy Series](https://www.ibiology.org/talks/set-up-koehler-illumination/). diff --git a/docs/guide/labelfree-screening/make_pdf.sh b/docs/guide/labelfree-screening/make_pdf.sh new file mode 100755 index 00000000..454c40c2 --- /dev/null +++ b/docs/guide/labelfree-screening/make_pdf.sh @@ -0,0 +1,21 @@ +#!/bin/bash +# Build the 2-page whitepaper PDF from whitepaper.tex. +# +# Needs pdflatex with the LaTeX packages extsizes, geometry, helvet, textcomp, +# graphicx, xcolor, fancyvrb, booktabs, caption, enumitem, fancyhdr and +# hyperref (all in a full TeX Live or MacTeX install). +set -euo pipefail +cd "$(dirname "$0")" +trap 'rm -f whitepaper.aux whitepaper.out' EXIT +for pass in 1 2; do + if ! pdflatex -interaction=nonstopmode -halt-on-error whitepaper.tex >/dev/null; then + echo "pdflatex failed; last lines of whitepaper.log:" >&2 + tail -n 25 whitepaper.log >&2 + exit 1 + fi +done +rm -f whitepaper.log +# The layout is designed for exactly two pages; report the count if poppler is installed. +if command -v pdfinfo >/dev/null; then + pdfinfo whitepaper.pdf | grep Pages +fi diff --git a/docs/guide/labelfree-screening/whitepaper.pdf b/docs/guide/labelfree-screening/whitepaper.pdf new file mode 100644 index 00000000..22baca28 Binary files /dev/null and b/docs/guide/labelfree-screening/whitepaper.pdf differ diff --git a/docs/guide/labelfree-screening/whitepaper.tex b/docs/guide/labelfree-screening/whitepaper.tex new file mode 100644 index 00000000..7d665d4b --- /dev/null +++ b/docs/guide/labelfree-screening/whitepaper.tex @@ -0,0 +1,276 @@ +% WaveOrder label-free screening whitepaper: 2-page print layout. +% The docs-site version of this tutorial is labelfree-screening.md; this +% file re-lays the same content and figures for a compact PDF. +% Uses only base texlive packages (no tcolorbox/titlesec on the build host). +\documentclass[9pt]{extarticle} +\usepackage[letterpaper,margin=1.25cm,bottom=1.8cm]{geometry} +\usepackage[T1]{fontenc} +\usepackage{textcomp} +\usepackage{helvet} +\renewcommand{\familydefault}{\sfdefault} +\usepackage{graphicx} +\usepackage{xcolor} +\usepackage{fancyvrb} +\usepackage{booktabs} +\usepackage[labelfont=bf,labelsep=period,font=small,skip=3pt]{caption} +\usepackage{enumitem} +\setlist{nosep,leftmargin=1.2em} +\usepackage{fancyhdr} +\usepackage[colorlinks=true,linkcolor=black,urlcolor=blue!60!black]{hyperref} +% Reproducible build: no timestamps or random IDs in the PDF. +\pdfinfoomitdate=1 \pdftrailerid{} \pdfsuppressptexinfo=-1 +\frenchspacing +\setlength{\parindent}{0pt} +\setlength{\parskip}{4pt} +\pagestyle{fancy} +\fancyhf{} +\renewcommand{\headrulewidth}{0pt} +\fancyfoot[L]{\raisebox{-3pt}{\includegraphics[height=13pt]{brand/biohub-logo-black.png}}} +\fancyfoot[R]{\small Computational Imaging Team \textbar{} \texttt{\{talon.chandler,shalin.mehta\}@biohub.org} \textbar{} 2026-11-17} + +\definecolor{boxgray}{gray}{0.96} +\definecolor{boxframe}{gray}{0.75} +% Knob colors in the Koehler figure, reused for the verbs in its caption. +\definecolor{kclose}{HTML}{E2574C} +\definecolor{kfocus}{HTML}{F39C34} +\definecolor{kcenter}{HTML}{4B83E8} +% Section heading under a thin rule; \mysectiontop omits the rule at a page top. +\newcommand{\mysectiontop}[1]{{\Large\bfseries #1}\par\vspace{2pt}} +% Blocks (figures, tables, rules) are separated by equal stretch, so each page +% shares its spare space evenly and gaps match above and below every block. +% A rule is not a paragraph, so the gap above it carries the \parskip that +% the paragraph below it gets for free. +\newcommand{\blockgap}{\par\vspace{2pt plus 1fill}} +\newcommand{\sectionrule}{\par\vspace{\dimexpr2pt+\parskip\relax plus 1fill}% +{\color{boxframe}\hrule height 0.4pt}\vspace{2pt plus 1fill}} +\newcommand{\mysection}[1]{\sectionrule\mysectiontop{#1}} + +% Failure-mode grid, read down each column: two equal columns with equal horizontal and vertical +% gaps, figures at their natural (print) size; the shorter column +% is padded inside its last box so both columns end on the same line. +% (The zero-height rule keeps the padding from being stripped at the box end.) +\newlength{\fmgap}\setlength{\fmgap}{8pt} +\newlength{\fmwL}\newlength{\fmwR} +\newdimen\fmpadL \newdimen\fmpadR +\newdimen\fmhL \newdimen\fmhR +\newsavebox{\fmcolL}\newsavebox{\fmcolR} +\newcommand{\fmbox}[1]{\fcolorbox{boxframe}{boxgray}{% +\begin{minipage}{\dimexpr\linewidth-2\fboxsep-2\fboxrule}#1\end{minipage}}} +\newcommand{\fmcolumn}[3]{% width, upper box, lower box +\begin{minipage}[t]{#1}\vspace{0pt}% +\fmbox{#2}\par\nointerlineskip\vspace{\fmgap}% +\fmbox{#3}% +\end{minipage}} +\setlength{\fboxsep}{6pt} +\setlength{\fboxrule}{0.4pt} + +% Verbatim blocks saved up front so they can live inside boxes. +\begin{SaveVerbatim}{cfgyml} +input_channel_names: [BF] +reconstruction_dimension: 2 +phase: + transfer_function: + yx_pixel_size: 0.325 # 6.5 um / 20x + z_pixel_size: 2.0 + wavelength_illumination: 0.450 + index_of_refraction_media: 1.0 + numerical_aperture_detection: 0.55 + numerical_aperture_illumination: 0.4 + invert_phase_contrast: false + z_focus_offset: auto + apply_inverse: + regularization_strength: 0.001 +\end{SaveVerbatim} + +\begin{SaveVerbatim}{tiltcfg} + z_focus_offset: auto + tilt_angle_zenith: {init: 0.13, lr: 0.05} + tilt_angle_azimuth: {init: 0.0, lr: 0.05} +optimization: {max_iterations: 50, method: adam} +\end{SaveVerbatim} + +\begin{document} + +{\huge\bfseries WaveOrder for label-free high-throughput screening} + +\vspace{5pt} +This guide demonstrates WaveOrder for label-free high-throughput +screening using optical pooled screening (OPS) data from the +\href{https://www.biorxiv.org/content/10.64898/2026.06.01.728087v1}{Biohub's multimodal +perturbation atlas} [1], where phase from defocus enabled label-free tracking and +phenotyping of CRISPR-perturbed A549 cells. Brightfield +defocus stacks from a standard motorized widefield microscope, together with a +\href{https://github.com/biohub/waveorder}{WaveOrder} config [2], yield +quantitative phase at screening scale (\textbf{Figure~1}). + +After reading this guide and acquiring data, use the +\href{https://github.com/biohub/waveorder/blob/main/docs/guide/first-reconstruction.md}{first-reconstruction +guide} and connect your agent to the +\href{https://biohub.ai/mcp}{Biohub MCP} to run the +\texttt{waveorder-tutorial} skill. Methods are described in the +\href{https://arxiv.org/abs/2412.09775}{WaveOrder preprint} [3]. + +\blockgap +\noindent\begin{minipage}{\linewidth} +\includegraphics[width=\linewidth]{figures/fig_overview.pdf} +\captionof{figure}{Key acquisition settings (left) produce a defocus stack with +defocus-dependent contrast that WaveOrder converts into quantitative phase.} +\end{minipage} + +\mysection{Acquisition} + +The three settings that matter most are: +\begin{itemize} +\item \textbf{Koehler illumination.} Align the condenser before every + session (\textbf{Figure~2}). Misalignment is the most common source of artifacts. Ron Vale's + five-minute + \href{https://www.ibiology.org/talks/set-up-koehler-illumination/}{iBiology + tutorial} [4] is a good refresher. +\item \textbf{Condenser NA $\approx$ 2/3 of detection NA.} We used a 0.4 NA condenser and + a 0.55 NA objective. A larger condenser aperture reduces contrast, while a + smaller condenser aperture reduces contrast and resolution. +\item \textbf{Z spacing and range.} At 20$\times$, start at 2 \textmu m + spacing and cover the full cell height with visibly blurred features on either end of the stack (here, 7 slices = 12 \textmu m). + Center the stack on the focus; otherwise set \texttt{z\_focus\_offset} to the offset in slices or to \texttt{auto}. + For different objectives, scale inversely with magnification: e.g.\ 4 \textmu m at 10$\times$, 1 \textmu m + at 40$\times$. +\end{itemize} + +\blockgap +\noindent\begin{minipage}{\linewidth} +\small +\centering +\begin{tabular}{lll} +\toprule +Parameter & Perturbation atlas value & Notes \\ +\midrule +Objective & 20$\times$, 0.55 NA, air ($n = 1$) & any objective works; match the config \\ +Condenser & 0.4 NA & $\approx$2/3 of detection NA, Koehler aligned \\ +Z stack & 7 slices, 2 \textmu m & confirm defocused features on top and bottom slices; use more slices for thicker samples \\ +Camera & 6.5 \textmu m pixels & 6.5 \textmu m / 20$\times$ = 0.325 \textmu m at the sample \\ +Wavelength & 450 nm & any wavelength is fine; ideally use a 10 nm bandpass filter \\ +Exposure & a few ms & fill 1/2--2/3 of the dynamic range \\ +\bottomrule +\end{tabular} +\captionof{table}{Acquisition parameters for the \href{https://www.biorxiv.org/content/10.64898/2026.06.01.728087v1}{Biohub's multimodal perturbation atlas dataset.}} +\end{minipage} + +\blockgap +\noindent\begin{minipage}{\linewidth} +\includegraphics[width=\linewidth]{figures/fig_koehler.pdf} +\captionof{figure}{Realign the condenser after changing the objective or the sample. +After focusing on the sample, \textcolor{kclose}{\textbf{close}} the field +stop, \textcolor{kfocus}{\textbf{focus}} and +\textcolor{kcenter}{\textbf{center}} the field stop edges, then +\textcolor{kclose}{\textbf{open}} the field stop.} +\end{minipage} + +\newpage +\mysectiontop{Reconstruction} + +\begin{minipage}[t]{0.55\linewidth}\raggedright +Convert to OME-Zarr with +\href{https://github.com/czbiohub-sf/iohub}{iohub} +(\texttt{iohub convert -i -o data.zarr}), record the acquisition +parameters in a config, reconstruct one position, and compare against the +raw data in napari: + +\vspace{3pt} +\begin{Verbatim}[fontsize=\small] +waveorder reconstruct \ + -i data.zarr/A/1/029029 \ + -c config.yml -o phase.zarr +waveorder view data.zarr/A/1/029029 \ + phase.zarr/A/1/029029 +\end{Verbatim} +\vspace{3pt} + +Dense structures (nucleoli, nuclear envelopes, cell margins) should appear +brighter than background, as in \textbf{Figure~1}. \texttt{reconstruction\_dimension:~2} returns one +phase image per defocus stack, the best choice for samples that are thin compared to the depth of field of the microscope. If the sample appears to blur all at once as you defocus, use 2. If different regions of the sample blur at different defocus positions, consider trialing 3. +\end{minipage}\hfill +\begin{minipage}[t]{0.42\linewidth} +\vspace{0pt} +\fcolorbox{boxframe}{boxgray}{% +\begin{minipage}{\dimexpr\linewidth-2\fboxsep-2\fboxrule} +{\small\texttt{\$ cat config.yml}}\par\vspace{1pt} +{\small\UseVerbatim{cfgyml}} +\end{minipage}} +\end{minipage} + +\sectionrule +\setlength{\fmwL}{\dimexpr0.5\linewidth-0.5\fmgap\relax} +\setlength{\fmwR}{\fmwL} +\newcommand{\fmleft}{\fmcolumn{\fmwL}{% +{\small\textbf{Failure mode 1 \textbar{} Flipped z axis}}\par\vspace{2pt} +\centering +\includegraphics{figures/fig_flip.pdf} +\par\vspace{2pt}\raggedright\small +Stages disagree on the z sign convention---is the first slice above or below focus? If the convention is flipped, contrast +will be inverted and downstream comparison will be challenging. Dense organelles should be +bright. Fix: \texttt{invert\_phase\_contrast: true}. Check once per +microscope by reconstructing one stack both ways.}{% +{\small\textbf{Failure mode 2 \textbar{} Incorrect regularization}}\par\vspace{2pt} +\centering +\includegraphics{figures/fig_reg.pdf} +\par\vspace{2pt}\raggedright\small +\texttt{regularization\_strength} balances noise and resolution and varies by +orders of magnitude across samples and exposures. Sweep decades on one +position and choose manually. Too small +amplifies blotchy low-frequency noise; too large leaves a washed-out image. The optimum is usually within a decade of +\texttt{1e-3}. +\par\vskip\fmpadL\hrule height 0pt}} +\newcommand{\fmright}{\fmcolumn{\fmwR}{% +{\small\textbf{Failure mode 3 \textbar{} Focus drift}}\par\vspace{2pt} +\centering +\includegraphics{figures/fig_focus.pdf} +\par\vspace{2pt}\raggedright\small +When the stack center (e.g.\ the 4th slice in a 7-slice stack) is not in focus, the reconstruction will be blurry. +Setting \texttt{z\_focus\_offset:~auto} runs +the search that can recover the defocus offset.}{% +{\small\textbf{Failure mode 4 \textbar{} Tilted illumination at the well edge}}\par\vspace{2pt} +\centering +\includegraphics{figures/fig_tilt.pdf} +\par\vspace{2pt}\raggedright\small +Misaligned Koehler and imaging near a well-edge meniscus tilt the illumination, making cells look shadow-cast +with reduced contrast. Fit the tilt by gradient descent in the same config (tilt keys go under \texttt{transfer\_function}): +{\footnotesize\UseVerbatim{tiltcfg}} +\par\vskip\fmpadR\hrule height 0pt}} +\sbox{\fmcolL}{\fmleft}\sbox{\fmcolR}{\fmright} +\fmhL=\dimexpr\ht\fmcolL+\dp\fmcolL\relax +\fmhR=\dimexpr\ht\fmcolR+\dp\fmcolR\relax +\ifdim\fmhL<\fmhR \fmpadL=\dimexpr\fmhR-\fmhL\relax \else \fmpadR=\dimexpr\fmhL-\fmhR\relax \fi +\noindent\fmleft\hspace{\fmgap}\fmright + +\mysection{Scaling up} + +A single config file should generate good reconstructions across a screen. We suggest parallelizing +\texttt{waveorder reconstruct} over positions (one process or cluster job +per position) with \texttt{device:~cuda:0} to reconstruct on a GPU. We recommend +\texttt{z\_focus\_offset:~auto} to find the focus of each position. Give each job its own copy of the config and +its own output store; jobs that share them overwrite each other's transfer function. + +We recommend manual supervision +to set up the optimized \texttt{tilt\_angle\_\{zenith,azimuth\}} parameters across entire wells. We find that initializing these tilt parameters at good initial tilts gives the most stable reconstructions, so we recommend inspecting +reconstructions at the well edges, then refining the initial values until you reach stable reconstructions that pass QC. + +\mysection{References} + +\sloppy\footnotesize +\begin{enumerate}[leftmargin=*,labelindent=0pt,align=left] +\item C.~Liu, A.~V.~Hillsley, M.~Sekhar, et al., ``A Multimodal Perturbation + Atlas Defines the Phenotypic Resolution of Cellular Morphology,'' + \href{https://www.biorxiv.org/content/10.64898/2026.06.01.728087v1}{bioRxiv + 2026.06.01.728087}. +\item WaveOrder repository: + \href{https://github.com/biohub/waveorder}{github.com/biohub/waveorder}. +\item T.~Chandler, I.~E.~Ivanov, G.~Sturm, et al., + ``WaveOrder: A differentiable wave-optical framework for scalable + biological microscopy with diverse modalities,'' + \href{https://arxiv.org/abs/2412.09775}{arXiv:2412.09775}. +\item R.~Vale, ``Microscopy: Setting Up Koehler Illumination,'' + \href{https://www.ibiology.org/talks/set-up-koehler-illumination/}{iBiology + Microscopy Series}. +\end{enumerate} + +\end{document} diff --git a/tests/api_tests/test_auto_focus_offset.py b/tests/api_tests/test_auto_focus_offset.py new file mode 100644 index 00000000..f92ef4c8 --- /dev/null +++ b/tests/api_tests/test_auto_focus_offset.py @@ -0,0 +1,86 @@ +"""Tests for z_focus_offset: 'auto' resolution.""" + +import pytest + +from waveorder.api import phase +from waveorder.optim._types import OptimizableFloat + +SIM_SETTINGS = phase.Settings( + transfer_function=dict( + yx_pixel_size=0.325, + z_pixel_size=2.0, + wavelength_illumination=0.45, + index_of_refraction_media=1.0, + numerical_aperture_detection=0.55, + numerical_aperture_illumination=0.4, + z_focus_offset=2.0, + ), + apply_inverse=dict(regularization_strength=1e-3), +) + + +def _settings_with_offset(offset): + dumped = SIM_SETTINGS.model_dump() + dumped["transfer_function"]["z_focus_offset"] = offset + return phase.Settings.model_validate(dumped) + + +@pytest.fixture(scope="module") +def defocused_data(): + """Simulated 7-slice stack whose focus sits 2 slices from center.""" + _, data = phase.simulate(settings=SIM_SETTINGS, recon_dim=2, zyx_shape=(7, 128, 128)) + return data + + +def test_auto_accepted_in_settings(): + settings = _settings_with_offset("auto") + assert settings.transfer_function.z_focus_offset == "auto" + + settings = _settings_with_offset({"init": "auto", "lr": 0.05}) + offset = settings.transfer_function.z_focus_offset + assert isinstance(offset, OptimizableFloat) + assert offset.initial_value == "auto" + + +def test_unresolved_auto_value_raises(): + with pytest.raises(ValueError, match="resolved from the data"): + OptimizableFloat(init="auto", lr=0.05).value + + +def test_simulate_rejects_auto(): + with pytest.raises(ValueError, match="measured data"): + phase.simulate(settings=_settings_with_offset("auto"), recon_dim=2, zyx_shape=(5, 32, 32)) + + +def test_resolve_recovers_integer_offset(defocused_data): + resolved = phase.resolve_z_focus_offset(defocused_data, _settings_with_offset("auto")) + offset = resolved.transfer_function.z_focus_offset + assert isinstance(offset, float) + assert offset == 2.0 + + +def test_resolve_keeps_learning_rate(defocused_data): + settings = _settings_with_offset(OptimizableFloat(init="auto", lr=0.05)) + resolved = phase.resolve_z_focus_offset(defocused_data, settings) + offset = resolved.transfer_function.z_focus_offset + assert isinstance(offset, OptimizableFloat) + assert offset.initial_value == 2.0 + assert offset.learning_rate == 0.05 + + +def test_resolve_passes_through_numeric(defocused_data): + settings = _settings_with_offset(1.5) + resolved = phase.resolve_z_focus_offset(defocused_data, settings) + assert resolved is settings + + +def test_compute_transfer_function_drops_auto_in_3d(defocused_data): + with pytest.warns(UserWarning, match="3D reconstructions do not use a focus offset"): + phase.compute_transfer_function(defocused_data, recon_dim=3, settings=_settings_with_offset("auto")) + + +def test_reconstruct_resolves_auto(defocused_data): + resolved = phase.resolve_z_focus_offset(defocused_data, _settings_with_offset("auto")) + fixed = phase.reconstruct(defocused_data, recon_dim=2, settings=resolved) + auto = phase.reconstruct(defocused_data, recon_dim=2, settings=_settings_with_offset("auto")) + assert abs(auto - fixed).max() == 0.0 diff --git a/tests/cli_tests/test_reconstruct.py b/tests/cli_tests/test_reconstruct.py index 66baac03..1d2f2453 100644 --- a/tests/cli_tests/test_reconstruct.py +++ b/tests/cli_tests/test_reconstruct.py @@ -314,6 +314,45 @@ def test_optimization_cli(tmp_path): assert optimized.phase.transfer_function.z_focus_offset != 0.0 +def test_auto_focus_offset_cli_writes_no_config(tmp_path): + """`z_focus_offset: auto` is resolved for the run without saving a new config.""" + from waveorder.api.phase import TransferFunctionSettings as PhaseTFSettings + + input_path = tmp_path / "input.zarr" + output_path = tmp_path / "output.zarr" + + channel_names = ["Brightfield"] + dataset = open_ome_zarr(input_path, layout="hcs", mode="w", channel_names=channel_names) + position = dataset.create_position("0", "0", "0") + data = np.random.rand(1, 1, 7, 64, 64).astype(np.float32) + 10.0 + position.create_image("0", data, transform=[TransformationMeta(type="scale", scale=(1, 1, 2.0, 0.325, 0.325))]) + dataset.close() + + recon_settings = settings.ReconstructionSettings( + input_channel_names=channel_names, + time_indices=0, + reconstruction_dimension=2, + phase=settings.PhaseSettings(transfer_function=PhaseTFSettings(z_focus_offset="auto")), + ) + config_path = tmp_path / "focus.yml" + utils.model_to_yaml(recon_settings, config_path) + + result = CliRunner().invoke( + app, + ["reconstruct", "-i", str(input_path / "0" / "0" / "0"), "-c", str(config_path), "-o", str(output_path)], + catch_exceptions=False, + ) + assert result.exit_code == 0 + assert "z_focus_offset =" in result.output + assert (output_path / "0" / "0" / "0").exists() + + # The user's config is untouched, no sibling config appears, and the + # transfer function is named after the config the user passed. + assert sorted(path.name for path in tmp_path.glob("*.yml")) == ["focus.yml"] + assert utils.yaml_to_model(config_path, settings.ReconstructionSettings) == recon_settings + assert (tmp_path / "transfer_function_focus.zarr").exists() + + def test_cli_apply_inv_tf_mock(tmp_input_path_zarr): tmp_input_zarr, tmp_config_yml = tmp_input_path_zarr tmp_config_yml = tmp_config_yml.with_name("0.yml").resolve() diff --git a/tests/models/test_isotropic_thin_3d.py b/tests/models/test_isotropic_thin_3d.py index 75039001..cba8fba0 100644 --- a/tests/models/test_isotropic_thin_3d.py +++ b/tests/models/test_isotropic_thin_3d.py @@ -123,3 +123,45 @@ def test_reconstruct_apodization_rolloff_smoke(): nyquist_row_apod = np.abs(np.fft.fft2(phase_apod.numpy())[16, :]) nyquist_row_hard = np.abs(np.fft.fft2(phase_hard.numpy())[16, :]) assert nyquist_row_apod.max() < 1e-3 * nyquist_row_hard.max() + + +def test_gram_singular_system_matches_svd(): + """The gradient-mode decomposition reconstructs identically to the SVD.""" + torch.manual_seed(0) + zyx_data = torch.rand(4, 32, 32) + 10.0 + absorption_tf, phase_tf = isotropic_thin_3d.calculate_transfer_function( + yx_shape=(32, 32), + yx_pixel_size=6.5 / 20, + z_position_list=[-2, -1, 0, 1], + wavelength_illumination=0.5, + index_of_refraction_media=1.0, + numerical_aperture_illumination=0.4, + numerical_aperture_detection=0.55, + ) + + results = [] + for use_svd in (True, False): + singular_system = isotropic_thin_3d.calculate_singular_system(absorption_tf, phase_tf, use_svd=use_svd) + results.append( + isotropic_thin_3d.apply_inverse_transfer_function(zyx_data, singular_system, regularization_strength=1e-3) + ) + for svd_result, gram_result in zip(*results): + assert torch.allclose(svd_result, gram_result, atol=1e-4) + + +def test_gram_singular_system_finite_gradients(): + """Gradients stay finite where singular values are degenerate or zero.""" + z_focus_offset = torch.tensor(0.0, requires_grad=True) + z_positions = (-torch.arange(4) + 2 + z_focus_offset) * 0.25 + _, phase_yx = isotropic_thin_3d.reconstruct( + torch.rand(4, 32, 32) + 10.0, + yx_pixel_size=0.1, + z_position_list=z_positions, + wavelength_illumination=0.532, + index_of_refraction_media=1.3, + numerical_aperture_illumination=0.9, + numerical_aperture_detection=1.2, + ) + loss = (phase_yx**2).mean() + loss.backward() + assert torch.isfinite(z_focus_offset.grad) diff --git a/waveorder/api/phase.py b/waveorder/api/phase.py index 24ee9341..2eb7aee3 100644 --- a/waveorder/api/phase.py +++ b/waveorder/api/phase.py @@ -2,6 +2,7 @@ from __future__ import annotations +import warnings from collections.abc import Mapping from typing import Literal, Union @@ -28,6 +29,7 @@ _wrap_output_tensor, ) from waveorder.device import resolve_device +from waveorder.focus import compute_midband_power from waveorder.models import isotropic_thin_3d, phase_thick_3d from waveorder.optim import ( NullLogger, @@ -36,6 +38,7 @@ optimize_reconstruction, ) from waveorder.optim._types import OptimizableFloat +from waveorder.optim.autoreg import select_crop from waveorder.optim.losses import MidbandPowerLossSettings, build_loss_fn # --- Settings --- @@ -45,6 +48,15 @@ class TransferFunctionSettings( OptimizableFourierTransferFunctionSettings, WavelengthIllumination, ): + z_focus_offset: Union[Literal["auto"], float, OptimizableFloat] = Field( + default=0, + description=( + "(optimizable) offset from center slice in slice units; 'auto' finds the " + "in-focus slice from the data with a per-slice search over a 3D " + "reconstruction; '{init: auto, lr: 0.05}' refines the searched slice to " + "sub-slice precision with the gradient optimizer" + ), + ) numerical_aperture_illumination: Union[NonNegativeFloat, OptimizableFloat] = Field( default=0.9, description="(optimizable) condenser numerical aperture" ) @@ -74,6 +86,141 @@ class Settings(MyBaseModel): # --- Functions --- +def _z_focus_offset_is_auto(transfer_function: TransferFunctionSettings) -> bool: + """Whether ``z_focus_offset`` asks to be estimated from the data.""" + v = transfer_function.z_focus_offset + return v == "auto" or (isinstance(v, OptimizableFloat) and v.initial_value == "auto") + + +def _drop_auto_z_focus_offset(settings: Settings, reason: str) -> Settings: + """Warn and replace an unused ``z_focus_offset: "auto"`` with 0.""" + warnings.warn(f"ignoring z_focus_offset: 'auto': {reason}", UserWarning) + return Settings( + transfer_function=settings.transfer_function.model_copy(update={"z_focus_offset": 0.0}), + apply_inverse=settings.apply_inverse, + ) + + +def _select_scoring_crops(zyx: torch.Tensor, crop_size: int = 512) -> list[tuple[int, int, int]]: + """Spatially spread crops for focus scoring: one per quadrant plus center. + + A single most-structured crop is fragile: bright floating debris + dominates a variance score while sitting in a different focal plane + than the sample. Several spread-out crops, each the most structured + within its region, let the median focus index reject local outliers. + """ + _, Y, X = zyx.shape + regions = [ + (0, Y // 2, 0, X // 2), + (0, Y // 2, X // 2, X), + (Y // 2, Y, 0, X // 2), + (Y // 2, Y, X // 2, X), + (Y // 4, Y // 4 + Y // 2, X // 4, X // 4 + X // 2), + ] + crops = set() + for y_lo, y_hi, x_lo, x_hi in regions: + if y_hi - y_lo < 1 or x_hi - x_lo < 1: + continue + y0, x0, size = select_crop(zyx[:, y_lo:y_hi, x_lo:x_hi], crop_size=crop_size) + crops.add((y_lo + y0, x_lo + x0, size)) + return sorted(crops) + + +def resolve_z_focus_offset( + czyx_data: xr.DataArray, + settings: Settings = None, + device: str | torch.device | None = None, +) -> Settings: + """Resolve ``z_focus_offset: "auto"`` from the data. + + Reconstructs 3D phase volumes on a handful of structured crops of + the data, scores each slice's midband spectral power, and takes the + median sharpest slice across crops as the focus: + ``z_focus_offset = focus_idx - Z // 2``. + + This discrete integer search is robust to multi-slice focus errors, + which gradient optimization cannot fix: shifting the model focus by + a whole number of slices relabels which acquired plane is "in + focus" and still reconstructs a locally sharp image, so the + sharpness landscape has a local optimum at every integer offset. + For sub-slice precision, write + ``z_focus_offset: {init: auto, lr: 0.05}``: the integer search runs + first and seeds the gradient optimizer, which refines within the + correct basin and co-optimizes any other optimizable parameters + (e.g. tilt angles). + + Parameters + ---------- + czyx_data : xr.DataArray + CZYX brightfield data (single channel). + settings : Settings, optional + Phase settings. Returned unchanged unless ``z_focus_offset`` is + ``"auto"``, either bare or as an ``OptimizableFloat`` init. + device : str, torch.device, or None + Compute device. None = CPU, "auto" = best available. + + Returns + ------- + Settings + Copy of ``settings`` with ``z_focus_offset`` resolved to a float + (or to an ``OptimizableFloat`` with a float init). + """ + if settings is None: + settings = Settings() + if not _z_focus_offset_is_auto(settings.transfer_function): + return settings + + Z = czyx_data.shape[1] + if Z == 1: + offset = 0.0 + focus_indices = [] + else: + # The focus reconstruction needs a numeric offset (its value does not + # enter the 3D model) and enough z padding to keep wrap-around from + # biasing the per-slice score. + tf_3d = settings.transfer_function.model_copy( + update={ + "z_focus_offset": 0.0, + "z_padding": max(settings.transfer_function.z_padding, Z // 2), + } + ) + settings_3d = Settings(transfer_function=tf_3d, apply_inverse=settings.apply_inverse) + s = tf_3d.resolve_floats() + yx = YXPixelSize.from_value(s.yx_pixel_size) + + zyx = torch.as_tensor(np.asarray(czyx_data.values[0], dtype=np.float32)) + focus_indices = [] + for y0, x0, size in _select_scoring_crops(zyx): + czyx_crop = czyx_data.isel(y=slice(y0, y0 + size), x=slice(x0, x0 + size)) + phase_zyx = reconstruct(czyx_crop, recon_dim=3, settings=settings_3d, device=device).values[0] + midband_per_slice = ( + compute_midband_power( + torch.as_tensor(phase_zyx), + NA_det=s.numerical_aperture_detection, + lambda_ill=s.wavelength_illumination, + pixel_size=(yx.y + yx.x) / 2, + ) + .cpu() + .numpy() + ) + focus_indices.append(int(np.argmax(midband_per_slice))) + offset = float(int(np.median(focus_indices)) - (Z // 2)) + + current = settings.transfer_function.z_focus_offset + if isinstance(current, OptimizableFloat): + resolved = OptimizableFloat(initial_value=offset, learning_rate=current.learning_rate) + else: + resolved = offset + print( + f"Resolved z_focus_offset = {offset:g} (slice units) from the data" + + (f"; per-crop focus slices {focus_indices}" if focus_indices else "") + ) + return Settings( + transfer_function=settings.transfer_function.model_copy(update={"z_focus_offset": resolved}), + apply_inverse=settings.apply_inverse, + ) + + def simulate( settings: Settings = None, recon_dim: Literal[2, 3] = 3, @@ -108,6 +255,8 @@ def simulate( """ if settings is None: settings = Settings() + if _z_focus_offset_is_auto(settings.transfer_function): + raise ValueError("z_focus_offset: 'auto' is estimated from measured data; set a numeric value for simulate()") s = settings.transfer_function.resolve_floats() yx_pixel_size = YXPixelSize.from_value(s.yx_pixel_size) @@ -220,6 +369,12 @@ def compute_transfer_function( settings = Settings() device = resolve_device(device) + if _z_focus_offset_is_auto(settings.transfer_function): + if recon_dim == 3: + settings = _drop_auto_z_focus_offset(settings, "3D reconstructions do not use a focus offset") + else: + settings = resolve_z_focus_offset(czyx_data, settings, device=device) + zyx_shape = czyx_data.shape[1:] # CZYX -> ZYX s = settings.transfer_function.resolve_floats() @@ -386,6 +541,11 @@ def reconstruct( """ if settings is None: settings = Settings() + if _z_focus_offset_is_auto(settings.transfer_function): + if recon_dim == 3: + settings = _drop_auto_z_focus_offset(settings, "3D reconstructions do not use a focus offset") + else: + settings = resolve_z_focus_offset(czyx_data, settings, device=device) tf = compute_transfer_function(czyx_data, recon_dim, settings, device=device) return apply_inverse_transfer_function(czyx_data, tf, recon_dim, settings, device=device) @@ -446,6 +606,12 @@ def optimize( settings = Settings() device = resolve_device(device) + if _z_focus_offset_is_auto(settings.transfer_function): + if recon_dim == 3: + settings = _drop_auto_z_focus_offset(settings, "3D reconstructions do not use a focus offset") + else: + settings = resolve_z_focus_offset(czyx_data, settings, device=device) + opt_params, _ = extract_optimizable_params(settings.transfer_function) if not opt_params: diff --git a/waveorder/cli/reconstruct.py b/waveorder/cli/reconstruct.py index 3b49972e..a273f460 100644 --- a/waveorder/cli/reconstruct.py +++ b/waveorder/cli/reconstruct.py @@ -1,3 +1,4 @@ +import tempfile from pathlib import Path import typer @@ -35,6 +36,13 @@ def _reconstruct_cli( If any parameter has an `lr` key (OptimizableFloat), an optimization loop runs before the standard reconstruction pipeline. + If `z_focus_offset` is 'auto' (bare, or as an `init`), the in-focus slice is + found with a per-slice search over a 3D reconstruction of the first + position. The resolved offset is used for this run and printed; it depends + on the data, so no new config is written for it. As + `{init: auto, lr: 0.05}`, the searched slice seeds the optimization loop, + which refines it to sub-slice precision. + If `apply_inverse` has an `auto_regularization` block, `regularization_strength` is chosen from the data after the transfer function is computed, and the resolved settings are written alongside the config. @@ -58,59 +66,115 @@ def _reconstruct_cli( settings = utils.yaml_to_model(config_filepath, ReconstructionSettings) - # Check for optimizable parameters and run optimization if needed - if has_optimizable_params(settings): - config_filepath = _run_optimization(settings, input_position_dirpaths[0], config_filepath) - - # Positions that share a ZYX shape can share a transfer function, so compute - # one per distinct shape, using the first position that has that shape. - position_zyx_shapes = read_zyx_shapes(input_position_dirpaths) - first_position_by_zyx_shape: dict[tuple[int, ...], Path] = {} - for zyx_shape, input_position_dirpath in zip(position_zyx_shapes, input_position_dirpaths, strict=True): - first_position_by_zyx_shape.setdefault(zyx_shape, input_position_dirpath) - - if len(first_position_by_zyx_shape) > 1: - typer.echo( - typer.style( - f"Found {len(first_position_by_zyx_shape)} distinct ZYX shapes across " - f"{len(input_position_dirpaths)} positions: computing one transfer " - "function per shape.", - fg="yellow", + # `config_filepath` names what this run writes (the transfer function and + # any resolved configs); `run_config` is the config the steps below read. + run_config = config_filepath + + with tempfile.TemporaryDirectory() as scratch_dir: + # Resolve z_focus_offset: 'auto' before anything consumes the offset (the + # optimizer needs a numeric init and the transfer function a numeric + # offset). The offset depends on the data, so it is not saved next to the + # user's config: the steps below read it from a copy that lasts for this + # run only. + if _has_auto_z_focus_offset(settings): + _run_auto_z_focus_offset(settings, input_position_dirpaths[0]) + run_config = Path(scratch_dir) / config_filepath.name + utils.model_to_yaml(settings, run_config) + + # Check for optimizable parameters and run optimization if needed + if has_optimizable_params(settings): + config_filepath = _run_optimization(settings, input_position_dirpaths[0], config_filepath) + run_config = config_filepath + + # Positions that share a ZYX shape can share a transfer function, so compute + # one per distinct shape, using the first position that has that shape. + position_zyx_shapes = read_zyx_shapes(input_position_dirpaths) + first_position_by_zyx_shape: dict[tuple[int, ...], Path] = {} + for zyx_shape, input_position_dirpath in zip(position_zyx_shapes, input_position_dirpaths, strict=True): + first_position_by_zyx_shape.setdefault(zyx_shape, input_position_dirpath) + + if len(first_position_by_zyx_shape) > 1: + typer.echo( + typer.style( + f"Found {len(first_position_by_zyx_shape)} distinct ZYX shapes across " + f"{len(input_position_dirpaths)} positions: computing one transfer " + "function per shape.", + fg="yellow", + ) ) - ) - transfer_function_paths = {} - for zyx_shape, input_position_dirpath in first_position_by_zyx_shape.items(): - # Only disambiguate the filename when there is more than one shape, so - # single-shape runs keep writing the path users already expect. - suffix = "" if len(first_position_by_zyx_shape) == 1 else "_" + "x".join(str(size) for size in zyx_shape) - transfer_function_path = output_dirpath.parent / f"transfer_function_{config_filepath.stem}{suffix}.zarr" - compute_transfer_function_cli(input_position_dirpath, config_filepath, transfer_function_path) - transfer_function_paths[zyx_shape] = transfer_function_path - - # Choose regularization_strength from the data, if asked to. This runs after - # the transfer function (which it needs, and which does not depend on - # `apply_inverse`) and before the reconstruction, so the sweep happens once - # rather than per timepoint inside the process pool. - if _has_auto_regularization(settings): - config_filepath = _run_auto_regularization( - settings, - input_position_dirpaths[0], - config_filepath, + transfer_function_paths = {} + for zyx_shape, input_position_dirpath in first_position_by_zyx_shape.items(): + # Only disambiguate the filename when there is more than one shape, so + # single-shape runs keep writing the path users already expect. + suffix = "" if len(first_position_by_zyx_shape) == 1 else "_" + "x".join(str(size) for size in zyx_shape) + transfer_function_path = output_dirpath.parent / f"transfer_function_{config_filepath.stem}{suffix}.zarr" + compute_transfer_function_cli(input_position_dirpath, run_config, transfer_function_path) + transfer_function_paths[zyx_shape] = transfer_function_path + + # Choose regularization_strength from the data, if asked to. This runs after + # the transfer function (which it needs, and which does not depend on + # `apply_inverse`) and before the reconstruction, so the sweep happens once + # rather than per timepoint inside the process pool. + if _has_auto_regularization(settings): + config_filepath = _run_auto_regularization( + settings, + input_position_dirpaths[0], + config_filepath, + ) + run_config = config_filepath + + # Apply each position's matching inverse transfer function + apply_inverse_transfer_function_cli( + input_position_dirpaths, + transfer_function_paths, + run_config, + output_dirpath, + num_processes, + write_config_scale_to_output, + resume, ) - # Apply each position's matching inverse transfer function - apply_inverse_transfer_function_cli( - input_position_dirpaths, - transfer_function_paths, - config_filepath, - output_dirpath, - num_processes, - write_config_scale_to_output, - resume, + +def _has_auto_z_focus_offset(settings) -> bool: + """Whether the phase block asks for an automatic focus-offset search. + + 3D reconstructions do not use a focus offset, so 'auto' is left for the + API to warn about and drop. + """ + from waveorder.api import phase + + return ( + settings.phase is not None + and settings.reconstruction_dimension == 2 + and phase._z_focus_offset_is_auto(settings.phase.transfer_function) ) +def _run_auto_z_focus_offset(settings, input_position_dirpath): + """Resolve z_focus_offset from the data and store it in `settings`, in place.""" + # Deferred imports for the same reason as above + from iohub.ngff import open_ome_zarr + + from waveorder.api import phase + from waveorder.cli.printing import echo_headline + from waveorder.cli.utils import resolve_time_indices + + echo_headline("\nResolving z_focus_offset with a per-slice focus search...") + + input_dataset = open_ome_zarr(input_position_dirpath, layout="fov", mode="r") + try: + t_idx = resolve_time_indices(settings.time_indices, input_dataset.data.shape[0])[0] + czyx = input_dataset.to_xarray().isel(t=t_idx).sel(c=settings.input_channel_names) + finally: + input_dataset.close() + + settings.phase = phase.resolve_z_focus_offset(czyx, settings.phase, device=settings.device) + + offset = settings.phase.transfer_function.z_focus_offset + typer.echo(typer.style(f" z_focus_offset = {float(offset):g} (slice units), t={t_idx}", fg="green")) + + def _run_optimization(settings, input_position_dirpath, config_filepath): """Run parameter optimization before standard reconstruction.""" # Deferred imports for the same reason as above diff --git a/waveorder/models/isotropic_thin_3d.py b/waveorder/models/isotropic_thin_3d.py index 0f958413..3db61d2a 100644 --- a/waveorder/models/isotropic_thin_3d.py +++ b/waveorder/models/isotropic_thin_3d.py @@ -229,9 +229,10 @@ def calculate_singular_system( phase_2d_to_3d_transfer_function : Tensor Transfer function for phase, same shape as absorption TF use_svd : bool - If True (default), use torch.linalg.svd for best reconstruction - accuracy. Set to False for a norm-based decomposition that - supports gradient backpropagation on all devices + If True (default), use torch.linalg.svd. Set to False for an + equivalent closed-form decomposition of the 2x2 Gram matrix with + epsilon-smoothed branch points, which supports gradient + backpropagation on all devices Returns ------- @@ -257,11 +258,10 @@ def calculate_singular_system( if use_svd: # Full SVD over the (s=2, Z) matrix at each spatial frequency. - # Captures cross-channel coupling between absorption and phase, - # giving the best reconstruction accuracy. - # Note: torch.linalg.svd backward fails with complex tensors on - # some GPU types due to singular vector phase ambiguity - # (svd_backward: e^{i phi} error). Use use_svd=False when + # Note: torch.linalg.svd backward produces non-finite gradients + # where singular values are degenerate (e.g. both zero beyond the + # band limit) and fails outright with complex tensors on some GPU + # types (svd_backward: e^{i phi} error). Use use_svd=False when # gradients are needed. BVyVxsZ = sfYX.permute(0, 3, 4, 1, 2) Up, Sp, Vhp = torch.linalg.svd(BVyVxsZ, full_matrices=False) @@ -269,17 +269,67 @@ def calculate_singular_system( S = Sp.permute(0, 3, 1, 2) # (B, s, Vy, Vx) Vh = Vhp.permute(0, 3, 4, 1, 2) # (B, s, Z, Vy, Vx) else: - # Norm-based decomposition: assumes absorption and phase channels - # are independent (U=identity). Less accurate than full SVD but - # supports gradient backpropagation on all devices. - # Per-channel norms: S[b, k] = norm(H[b, k, :]) - S = torch.sqrt(torch.clamp(torch.sum(torch.abs(sfYX) ** 2, dim=2), min=1e-12)) # (B, s=2, Vy, Vx) - # Normalized rows: Vh[b, k, z] = H[b, k, z] / S[b, k] - Vh = sfYX / (S[:, :, None] + 1e-12) # (B, s=2, Z, Vy, Vx) - # U = identity (each channel reconstructs independently) - U = torch.zeros(B, s, s, Vy, Vx, dtype=sfYX.dtype, device=sfYX.device) - for i in range(s): - U[:, i, i] = 1.0 + # Closed-form singular system from the 2x2 Gram matrix G = H H^†. + # This is the same decomposition the SVD branch computes (up to + # the phase gauge, which the reconstruction is invariant to), but + # with epsilon-smoothed branch points so gradients stay finite + # where the singular values are degenerate or zero, where + # torch.linalg.svd backward does not. Works on all devices. + absorption_row = sfYX[:, 0] # (B, Z, Vy, Vx) + phase_row = sfYX[:, 1] + # G = [[a, b], [conj(b), c]] at each spatial frequency. The Gram + # entries square the transfer function, so accumulate and solve the + # (Z-free) eigenproblem in double precision to keep the + # decomposition tight in float32 overall. + a = (absorption_row.abs() ** 2).sum(dim=1, dtype=torch.float64) # (B, Vy, Vx) + c = (phase_row.abs() ** 2).sum(dim=1, dtype=torch.float64) + b = (absorption_row * phase_row.conj()).sum(dim=1, dtype=torch.complex128) + + mean = (a + c) / 2 + # Smooth the eigenvalue gap with a relative epsilon (so healthy + # frequencies are perturbed by <1e-9 relative) plus a tiny absolute + # floor that keeps sqrt backward finite where H is exactly zero. + tiny = 1e-30 + half_gap = torch.sqrt(((a - c) / 2) ** 2 + b.abs() ** 2 + (1e-9 * mean) ** 2 + tiny) + lam1 = mean + half_gap + lam2 = torch.clamp(mean - half_gap, min=0.0) + S = torch.stack((torch.sqrt(lam1 + tiny), torch.sqrt(lam2 + tiny)), dim=1).to( + absorption_row.real.dtype + ) # (B, 2, Vy, Vx) + + # Leading eigenvector of G, taking whichever closed form is better + # conditioned at each frequency: [b, lam1 - a] or [lam1 - c, conj(b)]. + # Where H is ~zero both forms vanish and the normalized vector decays + # to zero along with S, so no explicit degenerate branch is needed. + u_x, u_y = b, (lam1 - a).to(b.dtype) + w_x, w_y = (lam1 - c).to(b.dtype), b.conj() + use_u = (u_x.abs() ** 2 + u_y.abs() ** 2) >= (w_x.abs() ** 2 + w_y.abs() ** 2) + v1_x = torch.where(use_u, u_x, w_x) + v1_y = torch.where(use_u, u_y, w_y) + norm1 = torch.sqrt(v1_x.abs() ** 2 + v1_y.abs() ** 2 + tiny) + v1_x = v1_x / norm1 + v1_y = v1_y / norm1 + + v1_x = v1_x.to(sfYX.dtype) + v1_y = v1_y.to(sfYX.dtype) + + # Columns of U: v1 and its orthonormal complement [-conj(v1_y), conj(v1_x)] + U = torch.stack( + ( + torch.stack((v1_x, -v1_y.conj()), dim=1), + torch.stack((v1_y, v1_x.conj()), dim=1), + ), + dim=1, + ) # (B, s, s, Vy, Vx) + + # Vh = S^-1 U^† H; rows have unit norm where S > 0 and vanish with S. + Vh = torch.stack( + ( + (v1_x.conj()[:, None] * absorption_row + v1_y.conj()[:, None] * phase_row) / S[:, 0, None], + (-v1_y[:, None] * absorption_row + v1_x[:, None] * phase_row) / S[:, 1, None], + ), + dim=1, + ) # (B, s, Z, Vy, Vx) if not batched: U = U.squeeze(0) @@ -547,8 +597,10 @@ def reconstruct( tilt_angle_azimuth=tilt_angle_azimuth, pupil_steepness=pupil_steepness, ) - # Use norm-based decomposition when gradients are needed (optimization), - # full SVD otherwise (better accuracy for final reconstruction) + # Both decompositions produce the same reconstruction, but + # torch.linalg.svd backward is non-finite at degenerate singular values + # (ubiquitous beyond the band limit) and unsupported for complex inputs + # on some GPUs, so gradient mode uses the closed-form Gram decomposition. needs_grad = absorption_tf.requires_grad or phase_tf.requires_grad singular_system = calculate_singular_system(absorption_tf, phase_tf, use_svd=not needs_grad) return apply_inverse_transfer_function( diff --git a/waveorder/optim/_types.py b/waveorder/optim/_types.py index 7d4e9111..7331653c 100644 --- a/waveorder/optim/_types.py +++ b/waveorder/optim/_types.py @@ -2,7 +2,7 @@ from __future__ import annotations -from typing import Any, Union +from typing import Any, Literal, Union from pydantic import BaseModel, model_validator @@ -13,6 +13,10 @@ class OptimizableFloat(BaseModel): Accepts a bare float/int (backwards compatible, not optimizable) or a mapping with `init`/`initial_value` and `lr`/`learning_rate`. + ``initial_value: "auto"`` marks the value to be estimated from the data + before any numeric use; only fields whose resolution is implemented + (currently phase ``z_focus_offset``) accept it. + Examples -------- >>> OptimizableFloat(init=0.0, lr=0.01) @@ -21,7 +25,7 @@ class OptimizableFloat(BaseModel): OptimizableFloat(initial_value=3.0, learning_rate=0.5) """ - initial_value: float = 0.0 + initial_value: Union[float, Literal["auto"]] = 0.0 learning_rate: float = 0.01 @model_validator(mode="before") @@ -40,6 +44,11 @@ def _normalize_aliases(cls, data: Any) -> Any: @property def value(self) -> float: + if self.initial_value == "auto": + raise ValueError( + "initial_value: 'auto' must be resolved from the data before use; " + "'auto' is currently supported only for phase z_focus_offset" + ) return self.initial_value @property @@ -51,7 +60,7 @@ def is_optimizable(self) -> bool: return self.learning_rate > 0 def __float__(self) -> float: - return self.initial_value + return self.value def __repr__(self) -> str: return f"OptimizableFloat(initial_value={self.initial_value}, learning_rate={self.learning_rate})" @@ -85,9 +94,9 @@ def extract_optimizable_params(obj: Any, prefix: str = "") -> tuple[dict[str, tu if isinstance(obj, OptimizableFloat): key = prefix if obj.is_optimizable: - optimizable[key] = (obj.initial_value, obj.learning_rate) + optimizable[key] = (obj.value, obj.learning_rate) else: - fixed[key] = obj.initial_value + fixed[key] = obj.value return optimizable, fixed if isinstance(obj, BaseModel): diff --git a/waveorder/optim/optimize.py b/waveorder/optim/optimize.py index 588902be..88fe2472 100644 --- a/waveorder/optim/optimize.py +++ b/waveorder/optim/optimize.py @@ -287,9 +287,18 @@ def closure(): if torch.isnan(loss) or torch.isnan(recon).any(): raise ValueError("NaN in reconstruction or loss") + # These parameters produced a finite reconstruction, so they + # are safe to roll back to. Checkpointing after the step + # would save unvalidated values: a degenerate SVD gradient + # can step parameters to non-finite values, and rolling back + # to those crashes the final reconstruction. + last_good = {name: t.detach().clone() for name, t in param_tensors.items()} + if use_gradients: loss.backward() optimizer.step() + if any(not torch.isfinite(t).all() for t in param_tensors.values()): + raise ValueError("non-finite parameters after optimizer step") except (RuntimeError, ValueError): # SVD convergence failure or NaN — revert to last good params @@ -298,8 +307,10 @@ def closure(): t.copy_(last_good[name]) break - # Checkpoint good params - last_good = {name: t.detach().clone() for name, t in param_tensors.items()} + # Checkpoint post-step parameters (the lbfgs closure validates them + # during the step) only when they are finite. + if method == "lbfgs" and all(torch.isfinite(t).all() for t in param_tensors.values()): + last_good = {name: t.detach().clone() for name, t in param_tensors.items()} wall_times.append(time.monotonic() - t_start) loss_val = loss.item()