plexora 0.0.1__py3-none-any.whl

plexora/plugins/figure_builder/server/pixels.py

@@ -0,0 +1,142 @@
+"""Raw channel pixels for Quick Edit, read straight off the pyramid.
+
+Quick Edit shows a small live view of the image behind a figure panel so the
+user can reframe it and adjust its channels without leaving the canvas. It
+needs actual pixels, and there were two ways to get them.
+
+**Not the main viewer's routes.** Those go through `data_model`, which holds ONE
+loaded datasource behind a lock and loads the whole cell table, the segmentation
+mask and the channel metadata with it ("this can take some time" is in its own
+docstring). Quick Edit would pay that per panel, evict whatever the user had
+open, and pay it again when they went back to the viewer -- and a figure
+legitimately spans several images, so a four-panel figure would do it four
+times. Export already refuses to touch that module for exactly this reason, and
+`test_the_export_never_loads_a_datasource` pins it.
+
+**So: the same reader export uses.** `render.SourceImage` opens the TIFF
+directly, per request, and this hands back one channel of one region as a plain
+array of numbers.
+
+## One channel at a time, and no compositing
+
+The response is a single channel's greyscale, uint16 little-endian, and the
+browser composites. That is the whole performance argument for the feature:
+changing a channel's colour or dragging its contrast slider is then arithmetic
+over bytes already in memory and costs NO network at all. A route that returned
+a composited RGB would make every contrast tweak a round trip, which is exactly
+the interaction Quick Edit exists to make cheap. MiniMap already works this way.
+
+Sixteen bits rather than eight because the windows are chosen in raw units: an
+8-bit response would have to be pre-windowed, and then the slider could only
+move within whatever window the server happened to pick.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from plexora.plugins.figure_builder.server.render import (
+    MAX_SOURCE_PIXELS, RenderError, SourceImage, choose_level)
+
+#: Biggest region a single request may hand back, per side. The mini viewer is
+#: a few hundred pixels across; this is well past what it asks for and well
+#: short of what would make a response worth megabytes.
+MAX_OUT_PIXELS = 1024
+
+#: How many pixels the coarsest level is sampled down to when computing the
+#: intensity summary. Enough for a stable percentile, small enough to be
+#: instant on a whole slide.
+STATS_SAMPLE = 512
+
+
+def read_region(datasource, channel_key, box, out_size):
+    """One channel of one region, resampled to `out_size`.
+
+    `box` is (x, y, w, h) in FULL-RESOLUTION image pixels -- the same
+    coordinate system a panel's `scene.viewport` is in, so a caller never has
+    to know which pyramid level was actually read.
+
+    Returns `(array, clipped_box)`: a 2-D uint16 array of exactly `out_size`,
+    and the part of `box` that was inside the image. The clipped box is
+    returned rather than silently applied, because a region that ran off the
+    edge of the slide has to be drawn in the right PLACE, and a caller given
+    only the pixels would centre the wrong thing.
+    """
+    out_w, out_h = int(out_size[0]), int(out_size[1])
+    if out_w < 1 or out_h < 1:
+        raise RenderError("a region must be at least one pixel")
+    if out_w > MAX_OUT_PIXELS or out_h > MAX_OUT_PIXELS:
+        raise RenderError(
+            f"a region of {out_w}x{out_h} is past what one read returns "
+            f"(max {MAX_OUT_PIXELS} a side)")
+
+    with SourceImage(datasource) as source:
+        index = source.channel_index(channel_key)
+        if index is None:
+            raise RenderError(f"{channel_key!r} is not a channel of this image")
+
+        level = choose_level(source, box[2], out_w)
+        divisor = 2 ** level
+        plane, clipped = source.read(index, level, (
+            box[0] / divisor, box[1] / divisor,
+            (box[0] + box[2]) / divisor, (box[1] + box[3]) / divisor))
+
+    return _resample(plane, out_w, out_h), tuple(value * divisor for value in clipped)
+
+
+def _resample(plane, out_w, out_h):
+    """To exactly the requested size, in uint16.
+
+    Pillow rather than a stride trick: LANCZOS is what the exporter uses, and a
+    mini viewer that resampled differently from the export would show the user
+    a slightly different picture from the one they are composing.
+    """
+    from PIL import Image
+
+    array = np.asarray(plane)
+    if array.size == 0:
+        return np.zeros((out_h, out_w), dtype=np.uint16)
+    # Pillow's "I;16" mode cannot resize, so the arithmetic is done in float32
+    # and put back afterwards -- which is also what keeps a 16-bit source from
+    # being quantised to 8 bits on the way through.
+    image = Image.fromarray(array.astype(np.float32), mode="F")
+    if image.size != (out_w, out_h):
+        image = image.resize((out_w, out_h), Image.LANCZOS)
+    return np.clip(np.asarray(image), 0, 65535).astype(np.uint16)
+
+
+def channel_stats(datasource, channel_key):
+    """What a contrast slider needs to know about a channel.
+
+    Read from the COARSEST pyramid level: the percentiles of a whole slide are
+    the same to within noise at any level, and reading level 0 to draw a slider
+    would be a gigabyte for a number the user is about to drag past anyway.
+    """
+    with SourceImage(datasource) as source:
+        index = source.channel_index(channel_key)
+        if index is None:
+            raise RenderError(f"{channel_key!r} is not a channel of this image")
+
+        level = max(0, source.levels - 1)
+        array = source.level(level)
+        plane = array[index] if array.ndim == 3 else array
+        height, width = plane.shape[-2], plane.shape[-1]
+        if height * width > MAX_SOURCE_PIXELS:
+            raise RenderError("this image has no level small enough to summarise")
+        sample = np.asarray(plane)
+
+    step = max(1, int(max(sample.shape) / STATS_SAMPLE))
+    sample = sample[::step, ::step].astype(np.float32)
+    if sample.size == 0:
+        return {"min": 0, "max": 1, "p01": 0, "p999": 1, "dtype": "uint16"}
+
+    low, high = np.percentile(sample, [1.0, 99.9])
+    return {
+        "min": float(sample.min()),
+        "max": float(sample.max()),
+        # The default window the viewer's auto-level lands on, so a channel
+        # switched on in Quick Edit arrives looking the way it would there.
+        "p01": float(low),
+        "p999": float(high),
+        "dtype": str(np.asarray(sample).dtype),
+    }

plexora/plugins/figure_builder/server/provenance.py

@@ -0,0 +1,174 @@
+"""How a figure explains itself.
+
+Two outputs from one function, because they are the same facts for two readers:
+`manifest()` is the machine-readable record that ships beside the export, and
+`lines()` is the page appended to a PDF for the human holding the printout.
+
+The thing worth getting right is what counts as provenance. Not "this figure was
+made in Plexora" -- that explains nothing. What a reader needs in order to
+believe, or to reproduce, a panel:
+
+* which image, and which REGION of it, in the image's own coordinates;
+* how big that region is in microns, or an explicit statement that the scale is
+  unknown;
+* which channels, with the display window and colour each was drawn with;
+* which plugin drew which overlay, and at what version;
+* what the export could NOT reproduce, named rather than omitted.
+
+That last one is the point of this file existing rather than the export just
+writing a title page. An export that silently leaves out the phenotype colouring
+a figure was made to show is an export that misrepresents the figure, and the
+only defence against that is to say so in writing, on the artefact itself.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from plexora.plugins.figure_builder.server import compose
+
+
+def manifest(document, results, options):
+    """The machine-readable record: `figure-provenance.json`.
+
+    Deliberately holds the scene snapshots verbatim. A manifest that summarised
+    them would be a second description of the same thing, and the summary is the
+    one that goes stale.
+    """
+    return {
+        "manifest_version": 1,
+        "generated_at": _now(),
+        "figure": {
+            "figure_id": document["figure_id"],
+            "title": document["title"],
+            "revision": document["revision"],
+            "created_at": document["created_at"],
+            "updated_at": document["updated_at"],
+        },
+        "export": {
+            "format": options.get("format"),
+            "dpi": options.get("dpi"),
+            "pages": [page["page_id"] for page in document["pages"]],
+        },
+        "sources": [
+            {
+                "source_id": source["source_id"],
+                "kind": source["kind"],
+                "datasource": source["datasource"],
+                "image": source["image"],
+                "pixel_size": source["pixel_size"],
+                "fingerprint": source["fingerprint"],
+            }
+            for source in document["sources"].values()
+        ],
+        "panels": [
+            {
+                "panel_id": panel["panel_id"],
+                "label": result.get("label"),
+                "source_id": panel["source_id"],
+                "placement": panel["placement"],
+                "scene": panel["scene"],
+                "derived_from": panel["derived_from"],
+                "render": result,
+            }
+            for panel, result in results
+        ],
+    }
+
+
+def lines(document, results, options):
+    """The provenance page, as lines of text.
+
+    Text rather than a layout because it is appended as a plain page: a table
+    that has to fit is a table that eventually does not, and a figure's
+    provenance must never be the thing that fails to export.
+    """
+    out = [
+        document["title"],
+        "",
+        f"Exported {_now()} · revision {document['revision']} · "
+        f"{options.get('format', 'pdf').upper()} at {options.get('dpi')} DPI",
+        "",
+        "SOURCES",
+    ]
+    for source in document["sources"].values():
+        name = source["display_name"] or source["datasource"] or source["source_id"]
+        size = source["image"]
+        scale = (f"{source['pixel_size']['value']:g} {source['pixel_size']['unit']}/px "
+                 f"({source['pixel_size']['source']})"
+                 if source["pixel_size"] else "scale information unavailable")
+        out.append(f"  {name} — {size['width']} × {size['height']} px — {scale}")
+    if not document["sources"]:
+        out.append("  (none)")
+
+    out += ["", "PANELS"]
+    for panel, result in results:
+        out.extend(_panel_lines(document, panel, result))
+
+    limitations = _limitations(results)
+    if limitations:
+        out += ["", "NOT REPRODUCED IN THIS EXPORT"]
+        out += [f"  {line}" for line in limitations]
+        out += [
+            "",
+            "  These are stated rather than omitted. The panels above were",
+            "  re-rendered from the source image at the resolution requested;",
+            "  anything listed here was drawn by a tool whose data a figure does",
+            "  not store, and appears only in the on-screen preview.",
+        ]
+    return out
+
+
+def _panel_lines(document, panel, result):
+    source = document["sources"].get(panel["source_id"], {})
+    viewport = panel["scene"]["viewport"]
+    label = result.get("label") or panel["panel_id"]
+    name = source.get("display_name") or source.get("datasource") or "unknown source"
+
+    out = [f"  {label} — {name}",
+           f"      region  x {viewport['x']:.1f}  y {viewport['y']:.1f}  "
+           f"w {viewport['w']:.1f}  h {viewport['h']:.1f}  (full-resolution image pixels)"]
+
+    pixel_size = source.get("pixel_size")
+    if pixel_size:
+        across = viewport["w"] * pixel_size["value"]
+        down = viewport["h"] * pixel_size["value"]
+        out.append(f"      field   {compose.format_microns(across)} × "
+                   f"{compose.format_microns(down)}")
+    else:
+        out.append("      field   scale information unavailable")
+
+    if result.get("effective_dpi"):
+        out.append(f"      source detail {result['effective_dpi']:g} DPI at this size"
+                   + (f" (requested {result['requested_dpi']})"
+                      if result.get("requested_dpi") else ""))
+
+    for channel in panel["scene"]["channels"]:
+        colour = channel["color"]
+        out.append(
+            f"      channel {channel['fullname_at_capture'] or channel['key']}"
+            f"  window {channel['window'][0]:g}–{channel['window'][1]:g}"
+            f"  rgb({colour['r']},{colour['g']},{colour['b']})")
+
+    for name, contribution in panel["scene"]["plugins"].items():
+        out.append(f"      overlay {name} {contribution['version']}")
+    return out
+
+
+def _limitations(results):
+    channels = set()
+    overlays = set()
+    for _, result in results:
+        channels.update(result.get("missing_channels") or [])
+        overlays.update(result.get("missing_overlays") or [])
+    out = []
+    if channels:
+        out.append("channels no longer present in the source: " + ", ".join(sorted(channels)))
+    if overlays:
+        out.append("overlays drawn by a tool rather than by the image: "
+                   + ", ".join(sorted(overlays)))
+    return out
+
+
+def _now():
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")

plexora/plugins/figure_builder/server/render.py

@@ -0,0 +1,278 @@
+"""Re-rendering a captured panel from the source pixels.
+
+This is the half of the product claim that the preview raster is not. A panel
+captured at 300 screen pixels exports at whatever the page size and the DPI ask
+for -- two thousand, four thousand -- because the scene records the region in
+full-resolution image coordinates and the windows in raw units, and both survive
+the screen they were chosen on.
+
+**Nothing here goes through `data_model`.** That module holds ONE loaded
+datasource behind a lock, and it is the one the user is looking at; a render
+that called `load_datasource` would evict their session to draw a figure, and a
+figure spanning four images would evict it four times. Reading the file directly
+is what makes exporting a multi-image figure possible at all.
+
+## The compositing, and why it looks like this
+
+It is the numpy transcription of `client/src/shaders/frag.glsl` plus the
+`lighter` blend `viewerManager.js` composites channels with. Per channel:
+
+    t   = clip((raw - lo) / (hi - lo), 0, 1)      # the shader's range_clamp
+    rgb = colour * t * ALPHA                      # u_tile_color * pixel_val
+    accumulate, then clip                         # canvas "lighter"
+
+Written out rather than approximated because an export that does not match what
+the user was looking at is worse than no export: they chose those windows by
+eye, against that arithmetic.
+
+## What this does NOT re-render
+
+Overlays -- coloured cells, ROI outlines -- are not reproduced. They cannot be,
+from what a figure stores: a cell layer's colours are a lookup table over every
+cell in the image, and a figure deliberately holds no derived data of that size.
+Reproducing them would mean re-running the plugin that computed them, server
+side, which is a different feature.
+
+So an export reports them, per panel, instead of quietly dropping them. See
+`missing_overlays`. The microscopy image itself is fully re-rendered, which is
+the part that could not be recovered any other way.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from plexora import api
+
+#: The alpha every channel is drawn with, from frag.glsl's `u8_r_range(0.9)` /
+#: `u16_rg_range(0.9)`. Not a style choice here -- it is what the user was
+#: looking at when they chose their windows.
+CHANNEL_ALPHA = 0.9
+
+#: Ceiling on one rendered panel, in pixels per side. A 300 mm page at 1200 DPI
+#: is ~14,000 px; past this a single panel is gigabytes of float32 and the
+#: request is a mistake rather than a figure.
+MAX_PANEL_PIXELS = 16_000
+
+#: Most source pixels one panel may read before it is refused. A whole-slide
+#: overview at level 0 is 10^10 pixels; the level chooser normally avoids that,
+#: and this catches the cases where it cannot.
+MAX_SOURCE_PIXELS = 120_000_000
+
+
+class RenderError(Exception):
+    """This panel cannot be rendered, with a reason worth showing the user."""
+
+
+class SourceImage:
+    """One image file, opened once and read from many times.
+
+    Held open across a whole export rather than reopened per panel: a figure is
+    routinely eight panels from one slide, and reopening a pyramidal TIFF eight
+    times is eight directory walks for the same answer.
+    """
+
+    def __init__(self, datasource):
+        import tifffile
+        import zarr
+
+        dataset = api.dataset(datasource)
+        source = dataset.image.source
+        if source is None or not source.path:
+            raise RenderError(f"{datasource} has no image file on disk")
+
+        self.datasource = datasource
+        self.channels = list(dataset.image.channels)
+        self._file = tifffile.TiffFile(source.path, is_ome=False)
+        self._zarr = zarr.open(self._file.series[0].aszarr(), mode="r")
+        self._is_array = hasattr(self._zarr, "shape")
+        self.levels = 1 if self._is_array else len(list(self._zarr))
+        width, height = dataset.image.size
+        self.width = int(width or 0)
+        self.height = int(height or 0)
+
+    def close(self):
+        try:
+            self._file.close()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def level(self, index):
+        """One pyramid level as an array-like, level 0 being full resolution."""
+        if self._is_array:
+            return self._zarr
+        return self._zarr[str(index)]
+
+    def channel_index(self, key):
+        """Where a channel sits in the pyramid, from its stable URL key.
+
+        The pyramid holds only real image channels -- 'Area' is a Plexora-side
+        placeholder for a segmentation mask and was never part of the file -- so
+        the index is the position among those, which is exactly what
+        `ImageHandle.channels` gives.
+        """
+        for index, channel in enumerate(self.channels):
+            src = str(channel.get("src") or "").rstrip("/")
+            if src.rsplit("/", 1)[-1] == key:
+                return index
+        return None
+
+    def read(self, channel_index, level, box):
+        """A rectangle of one channel, at one level, as a 2-D array.
+
+        `box` is in THAT LEVEL's pixels. Clipped to the array rather than
+        refused: a capture that runs a few pixels off the edge of the slide is
+        an ordinary thing to have drawn, and the result is the region that
+        exists with black where the image does not.
+        """
+        array = self.level(level)
+        plane = array[channel_index] if array.ndim == 3 else array
+        height, width = plane.shape[-2], plane.shape[-1]
+
+        x0 = max(0, min(int(math.floor(box[0])), width))
+        y0 = max(0, min(int(math.floor(box[1])), height))
+        x1 = max(x0, min(int(math.ceil(box[2])), width))
+        y1 = max(y0, min(int(math.ceil(box[3])), height))
+        if x1 <= x0 or y1 <= y0:
+            return np.zeros((1, 1), dtype=np.float32), (x0, y0, x1, y1)
+        if (x1 - x0) * (y1 - y0) > MAX_SOURCE_PIXELS:
+            raise RenderError(
+                "this panel covers more of the image than one render can read; "
+                "export it at a lower DPI"
+            )
+        return np.asarray(plane[y0:y1, x0:x1]), (x0, y0, x1, y1)
+
+
+def choose_level(source, viewport_width, target_pixels):
+    """The cheapest pyramid level that still has the detail being asked for.
+
+    The largest level index whose pixels across the region still meet or exceed
+    the target, so a 400-pixel-wide panel of a whole slide reads a few hundred
+    kilobytes instead of the level-0 gigabyte that would be downsampled away.
+    Level 0 when nothing else is big enough, which is also when the warning
+    below applies.
+    """
+    best = 0
+    for level in range(max(1, source.levels)):
+        if viewport_width / (2 ** level) >= target_pixels:
+            best = level
+        else:
+            break
+    return best
+
+
+def effective_dpi(viewport_width_px, width_mm):
+    """How many dots per inch this panel's SOURCE can actually supply.
+
+    Reported rather than enforced: a panel below the threshold still exports,
+    because a reviewer's deadline is a real thing and a slightly soft inset is
+    usually the right trade. Silently upscaling and saying nothing is not.
+    """
+    if width_mm <= 0:
+        return 0.0
+    return viewport_width_px / (width_mm / 25.4)
+
+
+def render_panel(source, scene, target_width, target_height):
+    """One panel's image, as an (H, W, 3) uint8 array.
+
+    `target_width`/`target_height` are the pixels the page asks for at the
+    chosen DPI. The level is picked from the width; the result is resampled to
+    exactly the requested size, so the page composition never has to reason
+    about what the pyramid happened to hold.
+    """
+    from PIL import Image
+
+    if max(target_width, target_height) > MAX_PANEL_PIXELS:
+        raise RenderError(
+            f"a panel of {target_width}x{target_height} pixels is past what one "
+            f"render can produce (max {MAX_PANEL_PIXELS} a side)")
+
+    viewport = scene["viewport"]
+    level = choose_level(source, viewport["w"], target_width)
+    divisor = 2 ** level
+    box = (viewport["x"] / divisor, viewport["y"] / divisor,
+           (viewport["x"] + viewport["w"]) / divisor,
+           (viewport["y"] + viewport["h"]) / divisor)
+
+    accumulator = None
+    rendered = 0
+    for channel in scene.get("channels") or []:
+        if not channel.get("visible", True):
+            continue
+        index = source.channel_index(channel["key"])
+        if index is None:
+            # Reported by the caller through `missing_channels`; nothing is
+            # substituted, because a substituted channel produces a panel that
+            # looks right and is wrong.
+            continue
+        plane, _ = source.read(index, level, box)
+        if accumulator is None:
+            accumulator = np.zeros((plane.shape[0], plane.shape[1], 3), dtype=np.float32)
+        elif plane.shape != accumulator.shape[:2]:
+            # Levels of a pyramid can be off by a pixel against each other.
+            plane = plane[:accumulator.shape[0], :accumulator.shape[1]]
+
+        low, high = float(channel["window"][0]), float(channel["window"][1])
+        span = high - low
+        if span <= 0:
+            continue
+        # The shader's range_clamp, in raw units -- identical arithmetic to
+        # dividing both sides by 65535 first, and without the rounding.
+        scaled = np.clip((plane.astype(np.float32) - low) / span, 0.0, 1.0)
+        colour = channel["color"]
+        weight = CHANNEL_ALPHA / 255.0
+        for offset, key in enumerate(("r", "g", "b")):
+            value = float(colour[key])
+            if value:
+                accumulator[:scaled.shape[0], :scaled.shape[1], offset] += scaled * (value * weight)
+        rendered += 1
+
+    if accumulator is None:
+        # Every channel was gone, or the panel had none. Black, which is what
+        # the viewer shows for the same state, rather than an error: the panel's
+        # labels and scale bar are still worth exporting.
+        accumulator = np.zeros((max(1, target_height), max(1, target_width), 3),
+                               dtype=np.float32)
+
+    image = Image.fromarray((np.clip(accumulator, 0.0, 1.0) * 255.0).astype(np.uint8), "RGB")
+    if image.size != (target_width, target_height):
+        # LANCZOS both ways. Downsampling a bright-on-black fluorescence image
+        # with a box filter loses thin structures; upsampling with nearest
+        # produces the blocky look that gives "exported from a screenshot" away.
+        image = image.resize((max(1, target_width), max(1, target_height)), Image.LANCZOS)
+    return image, {"level": level, "channels_rendered": rendered}
+
+
+def panel_report(source, scene, width_mm, dpi):
+    """What is worth telling the user about this panel before they export it.
+
+    Computed separately from the render so the export dialog can show it without
+    reading a single pixel.
+    """
+    viewport = scene["viewport"]
+    missing = [channel.get("fullname_at_capture") or channel["key"]
+               for channel in scene.get("channels") or []
+               if source.channel_index(channel["key"]) is None]
+    overlays = []
+    for layer in (scene.get("core_overlays") or {}).get("cell_layers") or []:
+        if layer.get("visible") and layer.get("mode") not in (None, "", "none"):
+            overlays.append(layer["name"])
+    overlays.extend(name for name in (scene.get("plugins") or {}) if name not in overlays)
+
+    return {
+        "effective_dpi": round(effective_dpi(viewport["w"], width_mm), 1),
+        "requested_dpi": dpi,
+        "missing_channels": missing,
+        # Named, not silently dropped: an export that omits the phenotype
+        # colouring a figure was made to show has to say so.
+        "missing_overlays": sorted(set(overlays)),
+    }