plexora 0.0.1__py3-none-any.whl

plexora/plugins/figure_builder/static/figureSceneSnapshot.js

@@ -0,0 +1,361 @@
+/**
+ * FigureScene - reading the viewer's state, and putting it back.
+ *
+ * This is the file the whole product claim rests on. A captured panel looks
+ * like a screenshot; what makes it something else is that everything affecting
+ * what is on screen is written down here in a form that survives the screen.
+ *
+ * Two rules govern what goes in:
+ *
+ * **Only what changes the science.** Channels, their colours, their display
+ * windows, the overlays, the region of the image. Not the sidebar's scroll
+ * position, not the cursor, not which panel was expanded -- storing those would
+ * make two identical captures compare unequal and would restore a UI the user
+ * has since rearranged.
+ *
+ * **Nothing in screen units.** The viewport is full-resolution image pixels and
+ * the windows are raw 16-bit, whatever the slider happened to be showing. Both
+ * are stable under zoom, under HD mode and under a different monitor; the
+ * alternatives are indistinguishable from them once written down, and only
+ * these two can be re-rendered at an arbitrary DPI years later.
+ *
+ * A channel is identified by the last segment of its tile URL rather than by
+ * its name. A name is something the user renames; the key is generated at
+ * import from the file and the channel's position and does not move. A figure
+ * that identified channels by name would lose them the first time somebody
+ * relabelled "LSP20209_2" as "CD8a" -- which is a thing people do on the way to
+ * making a figure.
+ */
+const FigureScene = {
+
+    /**
+     * The stable id of one image channel, from the config entry the viewer was
+     * built with.
+     */
+    channelKey(config, fullname) {
+        const entry = (config?.imageData || []).find((channel) => channel.fullname === fullname);
+        if (!entry || !entry.src) return "";
+        return String(entry.src).replace(/\/+$/, "").split("/").pop();
+    },
+
+    /**
+     * Every channel currently contributing to the image, as the scene records
+     * them.
+     *
+     * Read from the sidebar's slots rather than from the saved channel list,
+     * because the saved list is what was last PERSISTED and the slots are what
+     * is on screen -- and the gap between them is exactly the unsaved
+     * adjustment the user is capturing.
+     */
+    channels(ctx) {
+        const sidebar = window.__plexora?.viewerSidebar;
+        const config = ctx.config;
+        if (!sidebar || !Array.isArray(sidebar.channelSlots)) return [];
+
+        const out = [];
+        for (const slot of sidebar.channelSlots) {
+            if (!slot.name || !slot.enabled) continue;
+            const fullname = ctx.dataLayer?.getFullChannelName
+                ? ctx.dataLayer.getFullChannelName(slot.name)
+                : slot.name;
+            const key = this.channelKey(config, fullname);
+            if (!key) continue;
+            // Raw 16-bit, always. slot.range is byte-domain outside HD mode, so
+            // storing it directly would produce a window that means nothing the
+            // next time the viewer is in the other mode.
+            const window_ = sidebar.toRawRangeForSlot
+                ? sidebar.toRawRangeForSlot(slot)
+                : slot.range;
+            out.push({
+                key: key,
+                fullname_at_capture: fullname,
+                color: { r: slot.color.r, g: slot.color.g, b: slot.color.b },
+                window: [Number(window_[0]), Number(window_[1])],
+                visible: true,
+            });
+        }
+        return out;
+    },
+
+    /**
+     * Core's own overlays: the cell layers, HD tiles, the scale bar.
+     *
+     * The layers are recorded in stacking order with their modes and
+     * opacities, but WITHOUT the colours -- those belong to whichever plugin
+     * computed them, and that plugin records its own state and its own legend
+     * through the capture bridge. Copying a lookup table of half a million
+     * cells into every panel would put megabytes of derived data into a
+     * document whose whole point is that it holds none.
+     */
+    coreOverlays(ctx) {
+        const viewer = ctx.viewer;
+        const layers = (viewer?.cellLayers?.() || []).map((layer, index) => ({
+            name: layer.name,
+            mode: layer.mode,
+            opacity: layer.opacity,
+            visible: Boolean(layer.visible),
+            z: index,
+        }));
+        return {
+            cell_layers: layers,
+            hd_tiles: Boolean(document.getElementById("viewer_controls_hd")?.checked),
+            scalebar_visible: Boolean(viewer?.show_scalebar),
+        };
+    },
+
+    /**
+     * Ask every open plugin what it is drawing.
+     *
+     * A DOM CustomEvent rather than a call, because Figure Builder must not
+     * know any plugin's internals -- the same reason ROI and Cell Explorer talk
+     * through `plexora:roi-hover` rather than through each other's classes. A
+     * plugin that is not loaded contributes nothing and the capture proceeds;
+     * that is the honest outcome, and it is what makes a figure built today
+     * still openable in a build where that plugin was uninstalled.
+     *
+     * Each contribution carries a `legend` the plugin computed NOW, which is
+     * what lets export draw a legend with no plugin JavaScript running at all.
+     */
+    pluginStates() {
+        const contributions = {};
+        try {
+            window.dispatchEvent(new CustomEvent("plexora:figure-capture-state", {
+                detail: {
+                    contribute(name, payload) {
+                        if (!name || !payload) return;
+                        contributions[String(name)] = {
+                            version: String(payload.version || ""),
+                            state: payload.state || {},
+                            legend: Array.isArray(payload.legend) ? payload.legend : [],
+                        };
+                    },
+                },
+            }));
+        } catch (error) {
+            // A plugin that throws while describing itself must not cost the
+            // user their capture. The panel is still worth having without that
+            // plugin's overlay recorded, and the omission is visible.
+            console.error("figure_builder: a plugin failed to describe its state", error);
+        }
+        return contributions;
+    },
+
+    /**
+     * The whole snapshot for a captured region.
+     *
+     * `viewport` is already in full-resolution image pixels -- converted by the
+     * capture tool, which is the only place that touches screen coordinates.
+     */
+    capture(ctx, sourceId, viewport) {
+        return {
+            snapshot_version: FigureSchema.SNAPSHOT_VERSION,
+            source_id: sourceId,
+            viewport: {
+                x: viewport.x, y: viewport.y, w: viewport.w, h: viewport.h,
+            },
+            channels: this.channels(ctx),
+            core_overlays: this.coreOverlays(ctx),
+            plugins: this.pluginStates(),
+            captured_at: new Date().toISOString(),
+        };
+    },
+
+    /**
+     * What the viewer is looking at right now, in full-resolution image pixels.
+     *
+     * Used to stash the state a panel edit is about to displace, so Cancel puts
+     * the user back where they were rather than leaving them somewhere they
+     * never chose.
+     */
+    currentViewport(ctx) {
+        const viewer = ctx.viewer?.viewer;
+        const item = viewer?.world?.getItemAt(0);
+        if (!item) return { x: 0, y: 0, w: 1, h: 1 };
+        const bounds = item.viewportToImageRectangle(viewer.viewport.getBounds(true));
+        const scale = 2 ** (ctx.config?.extraZoomLevels || 0);
+        return {
+            x: bounds.x / scale, y: bounds.y / scale,
+            w: Math.max(1, bounds.width / scale), h: Math.max(1, bounds.height / scale),
+        };
+    },
+
+    // -- putting it back -------------------------------------------------
+
+    /**
+     * The scene's channels as the rows the sidebar's own restore path takes.
+     *
+     * Deliberately reuses `applySavedChannels` rather than driving the viewer
+     * directly. That function already handles the things a second
+     * implementation would get wrong on a project nobody tested it on: it
+     * prefetches each channel's statistics in parallel, converts the raw window
+     * into whichever domain the slider is currently in, and stands down the
+     * auto-level that a marker change would otherwise schedule on top of the
+     * range being restored. A parallel path would be a second answer to all
+     * three.
+     *
+     * Returns the rows plus the channels that could not be resolved, which are
+     * reported and never guessed at: a figure that silently substituted a
+     * different channel would look right and be wrong.
+     */
+    restoreRows(ctx, scene) {
+        const byKey = new Map();
+        for (const channel of ctx.config?.imageData || []) {
+            const key = String(channel.src || "").replace(/\/+$/, "").split("/").pop();
+            if (key) byKey.set(key, channel);
+        }
+
+        const rows = [];
+        const missing = [];
+        for (const channel of scene.channels || []) {
+            const entry = byKey.get(channel.key);
+            if (!entry) {
+                missing.push(channel.fullname_at_capture || channel.key);
+                continue;
+            }
+            rows.push({
+                // The SHORT name, which is what the slots are keyed by -- the
+                // same field `persistChannelList` writes.
+                channel: entry.name || entry.fullname,
+                channel_active: true,
+                r: channel.color.r, g: channel.color.g, b: channel.color.b,
+                opacity: 1,
+                // Raw 16-bit both ways: this is the form the saved channel list
+                // uses, so the conversion into the live domain is the sidebar's
+                // and there is one of it.
+                start: channel.window[0],
+                end: channel.window[1],
+            });
+        }
+        return { rows: rows, missing: missing };
+    },
+
+    /**
+     * Put a captured scene back into the live viewer.
+     *
+     * Returns a report -- what was restored, what could not be, which plugins
+     * answered. Nothing here throws on a missing piece: a panel captured with a
+     * plugin that is no longer installed still shows its image and its
+     * channels, and saying which part is absent is more useful than refusing
+     * the whole restore.
+     *
+     * The project's own saved channel list is NOT touched. That is what
+     * `suspendPersistence` is for, and it is the difference between looking at
+     * a figure panel and permanently overwriting the settings the user had.
+     */
+    async restore(ctx, scene) {
+        const sidebar = window.__plexora?.viewerSidebar;
+        const report = { channels: 0, missing_channels: [], plugins: {}, viewport: false };
+        if (!scene) return report;
+
+        const resolved = this.restoreRows(ctx, scene);
+        report.missing_channels = resolved.missing;
+
+        sidebar?.suspendPersistence?.();
+        try {
+            if (sidebar && resolved.rows.length) {
+                await sidebar.applySavedChannels(resolved.rows);
+                report.channels = resolved.rows.length;
+            }
+            this.restoreOverlays(ctx, scene.core_overlays);
+            report.viewport = this.restoreViewport(ctx, scene.viewport);
+            report.plugins = this.restorePlugins(scene.plugins);
+        } finally {
+            // In a `finally`, because a restore that throws halfway must not
+            // leave the project's channel list permanently unsaveable -- the
+            // symptom would be a viewer that quietly stops remembering
+            // anything, hours later, with no way to connect it to this.
+            sidebar?.resumePersistence?.();
+        }
+        return report;
+    },
+
+    /**
+     * Move the viewer to the captured region.
+     *
+     * The inverse of the capture conversion, and new code: nothing in the
+     * viewer restored a viewport before this, because nothing had a viewport
+     * worth restoring.
+     */
+    restoreViewport(ctx, viewport) {
+        const viewer = ctx.viewer?.viewer;
+        const item = viewer?.world?.getItemAt(0);
+        if (!item || !viewport) return false;
+        const scale = 2 ** (ctx.config?.extraZoomLevels || 0);
+        const bounds = item.imageToViewportRectangle(new OpenSeadragon.Rect(
+            viewport.x * scale, viewport.y * scale,
+            viewport.w * scale, viewport.h * scale));
+        // Immediately rather than animated: this is a jump to a recorded place,
+        // and a two-second pan across a slide to get there is a two-second wait
+        // that tells the user nothing.
+        viewer.viewport.fitBounds(bounds, true);
+        return true;
+    },
+
+    /**
+     * Core's overlays, as far as they still exist.
+     *
+     * A layer belongs to whichever plugin registered it, so a scene captured
+     * with Cell Explorer open restores nothing here when it is closed -- and
+     * says so, rather than conjuring a layer with no colours in it.
+     */
+    restoreOverlays(ctx, overlays) {
+        if (!overlays) return;
+        const viewer = ctx.viewer;
+        const controls = window.__plexora?.viewerControls;
+
+        let restored = null;
+        for (const layer of overlays.cell_layers || []) {
+            if (!viewer?.cellLayer?.(layer.name)) continue;
+            // Per layer, because each has its own mode: a phenotype map drawn
+            // filled and a gate drawn as outlines are a legitimate pair, and
+            // restoring one mode for all of them would flatten that.
+            viewer.setCellLayerMode?.(layer.name, layer.mode);
+            viewer.setLayerOpacity?.(layer.name, layer.opacity);
+            viewer.setCellLayerVisible?.(layer.name, layer.visible);
+            if (layer.visible && layer.mode && layer.mode !== "none") restored = layer;
+        }
+        // setCellLayerMode changes how the mask is DRAWN; it does not fetch a
+        // mask that is not loaded. viewerControls.selectMode is the path that
+        // does, so it is called once for whichever layer is actually showing --
+        // otherwise a panel captured with outlines on reopens with the layer
+        // switched on and nothing in it.
+        if (restored && controls?.selectMode) controls.selectMode(restored.mode);
+
+        const hd = document.getElementById("viewer_controls_hd");
+        if (hd && hd.checked !== overlays.hd_tiles) {
+            hd.checked = overlays.hd_tiles;
+            // Through the element's own change event, so the reload work stays
+            // in viewerControls rather than being reimplemented here.
+            hd.dispatchEvent(new Event("change", { bubbles: true }));
+        }
+        viewer?.setScalebarVisible?.(Boolean(overlays.scalebar_visible));
+    },
+
+    /**
+     * Hand each plugin its own state back.
+     *
+     * The mirror of the capture bridge, and equally ignorant: Figure Builder
+     * passes the blob to whoever answers to that name and records what they
+     * said. A plugin that is not open reports nothing, which becomes a notice
+     * on the panel rather than an error -- the image and the channels are
+     * restored either way, and that is most of the view.
+     */
+    restorePlugins(plugins) {
+        const report = {};
+        if (!plugins || !Object.keys(plugins).length) return report;
+        try {
+            window.dispatchEvent(new CustomEvent("plexora:figure-restore-state", {
+                detail: {
+                    plugins: plugins,
+                    report(name, outcome) { report[String(name)] = String(outcome); },
+                },
+            }));
+        } catch (error) {
+            console.error("figure_builder: a plugin failed to restore its state", error);
+        }
+        for (const name of Object.keys(plugins)) {
+            if (!(name in report)) report[name] = "skipped";
+        }
+        return report;
+    },
+};

plexora/plugins/figure_builder/static/figureSchema.js

@@ -0,0 +1,218 @@
+/**
+ * FigureSchema - the parts of the figure format the client has to agree with.
+ *
+ * Ids are generated HERE rather than by the server so a captured panel appears
+ * the instant the pointer is released, not after a round trip. That is the same
+ * bargain ROI makes, and it carries the same obligation: the server validates
+ * every id it is sent (server/schema.py ID_PATTERN), because these end up in
+ * DOM attributes and selectors.
+ *
+ * The two coordinate systems are kept apart on this side too. `mm` is page
+ * geometry -- placements, annotations, page size. Full-resolution image pixels
+ * are scene geometry, and nothing here converts between them: they only meet at
+ * export, where mm x DPI decides how many source pixels to read. A helper that
+ * turned one into the other would be a helper somebody eventually used to store
+ * a panel's crop in screen units, which is exactly the mistake that makes a
+ * figure un-re-renderable.
+ */
+const FigureSchema = {
+
+    SCHEMA_VERSION: 1,
+    SNAPSHOT_VERSION: 1,
+
+    /** Millimetres per inch, and per CSS pixel at the nominal 96 dpi. */
+    MM_PER_INCH: 25.4,
+
+    PAGE_PRESETS: {
+        a4: { w: 210.0, h: 297.0, label: "A4" },
+        letter: { w: 215.9, h: 279.4, label: "US Letter" },
+        square: { w: 200.0, h: 200.0, label: "Square" },
+    },
+
+    /**
+     * A short random id with a readable prefix.
+     *
+     * crypto.randomUUID where it exists; the fallback matters because Plexora
+     * is served over plain http on 127.0.0.1 in some deployments, and
+     * `crypto.randomUUID` is a secure-context API. Without a fallback, capture
+     * would simply stop working there with a TypeError nobody could interpret.
+     */
+    newId(prefix) {
+        const random = (window.crypto && window.crypto.randomUUID)
+            ? window.crypto.randomUUID().replace(/-/g, "")
+            : (Date.now().toString(36) + Math.random().toString(36).slice(2, 10));
+        return prefix + "_" + random.slice(0, 12);
+    },
+
+    newPanelId() { return this.newId("pnl"); },
+    newPageId() { return this.newId("pg"); },
+    newSourceId() { return this.newId("src"); },
+    newAnnotationId() { return this.newId("ann"); },
+    newGroupId() { return this.newId("grp"); },
+
+    /**
+     * The panel label for a zero-based position: A..Z, then AA, AB, ...
+     *
+     * Base-26 with no zero digit, which is the spreadsheet-column sequence
+     * rather than plain base conversion -- position 26 is "AA", not "BA".
+     */
+    labelFor(index, style) {
+        if (style === "A1") return "A" + String(index + 1);
+        let n = Math.max(0, Math.floor(index));
+        let out = "";
+        do {
+            out = String.fromCharCode(65 + (n % 26)) + out;
+            n = Math.floor(n / 26) - 1;
+        } while (n >= 0);
+        return style === "a" ? out.toLowerCase() : out;
+    },
+
+    /** Panels on one page, in the order their labels should run. */
+    panelsOnPage(document_, pageId) {
+        return Object.values(document_.panels || {})
+            .filter((panel) => panel.placement && panel.placement.page_id === pageId)
+            // Reading order, then z as the tiebreak. A user who lays out a 3x2
+            // grid expects A B C / D E F, which is rows before columns; sorting
+            // by z alone would number them by the order they happened to be
+            // captured in.
+            .sort((a, b) => (a.placement.y_mm - b.placement.y_mm)
+                || (a.placement.x_mm - b.placement.x_mm)
+                || (a.placement.z - b.placement.z));
+    },
+
+    /** Panels not on any page: captured, kept, not laid out. */
+    panelsInTray(document_) {
+        return Object.values(document_.panels || {}).filter((panel) => !panel.placement);
+    },
+
+    pageById(document_, pageId) {
+        return (document_.pages || []).find((page) => page.page_id === pageId) || null;
+    },
+
+    /**
+     * A scene snapshot with nothing captured yet.
+     *
+     * Exists so that a panel built by any path -- capture, split, an imported
+     * asset -- has the same shape, and so a field added to the format has one
+     * place to be defaulted rather than N call sites to be remembered in.
+     */
+    emptyScene(sourceId) {
+        return {
+            snapshot_version: this.SNAPSHOT_VERSION,
+            source_id: sourceId || "",
+            viewport: { x: 0, y: 0, w: 1, h: 1 },
+            channels: [],
+            core_overlays: { cell_layers: [], hd_tiles: false, scalebar_visible: false },
+            plugins: {},
+            captured_at: new Date().toISOString(),
+        };
+    },
+
+    /**
+     * How many microns across a captured region is, or null.
+     *
+     * Null propagates rather than defaulting: a scale bar drawn from an assumed
+     * pixel size is wrong and looks exactly like one that is right, which is the
+     * single worst failure mode a figure tool has.
+     */
+    physicalWidthUm(source, viewport) {
+        const pixelSize = source && source.pixel_size;
+        if (!pixelSize || !(pixelSize.value > 0) || !viewport) return null;
+        return viewport.w * pixelSize.value;
+    },
+
+    /**
+     * The source region a panel of THIS shape should show.
+     *
+     * A panel is captured at one proportion and then dragged into another --
+     * a square field cropped into a wide strip is the commonest thing anybody
+     * does to a figure. Reopening it for editing has to frame the shape the
+     * panel is NOW, not the shape it was captured at, or the edit would quietly
+     * put back a proportion the user deliberately changed.
+     *
+     * Centre and WIDTH are preserved and the height follows the panel's aspect.
+     * Width rather than height because the user framed the field by what is
+     * across it: re-deriving the width would move the left and right edges they
+     * chose, which is the part of the framing they can see.
+     *
+     * Used by both routes into editing -- Quick Edit's mini viewer and the main
+     * viewer's outline -- so the two cannot disagree about what a panel is
+     * looking at.
+     *
+     * Pure, and `image` is optional: with it the result is nudged back inside
+     * the slide rather than hanging over the edge.
+     */
+    aspectViewport(viewport, aspect, image) {
+        const width = viewport.w;
+        const height = aspect > 0 ? width / aspect : viewport.h;
+        let x = viewport.x;
+        let y = viewport.y + viewport.h / 2 - height / 2;
+
+        if (image && image.width > 0 && image.height > 0) {
+            // Slid back inside where it fits, and left alone where it does not:
+            // a region wider than the slide is a legitimate thing to have
+            // captured at the edge of a small image, and shrinking it here
+            // would change the field rather than move it.
+            if (width <= image.width) x = Math.max(0, Math.min(x, image.width - width));
+            if (height <= image.height) y = Math.max(0, Math.min(y, image.height - height));
+        }
+        return { x: x, y: y, w: width, h: height };
+    },
+
+    /** A round number of microns that fits comfortably inside `spanUm`. */
+    scaleBarLength(spanUm) {
+        if (!(spanUm > 0)) return null;
+        const target = spanUm / 4;
+        const candidates = [1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500,
+            1000, 2000, 5000, 10000];
+        let best = candidates[0];
+        for (const value of candidates) {
+            if (value <= target) best = value;
+        }
+        return best;
+    },
+
+    formatMicrons(value) {
+        if (!(value > 0)) return "";
+        if (value >= 1000) return (value / 1000).toFixed(value % 1000 ? 1 : 0) + " mm";
+        if (value >= 10) return Math.round(value) + " µm";
+        return value.toFixed(1) + " µm";
+    },
+
+    /**
+     * Text that is about to be put in the DOM as markup.
+     *
+     * Every user-supplied string on this side goes through here or through
+     * textContent. The server strips control characters and caps length but
+     * deliberately does not HTML-escape -- escaping at the store double-escapes
+     * on every round trip -- so escaping is this side's job, at the point of
+     * use.
+     */
+    escapeHtml(value) {
+        return String(value === undefined || value === null ? "" : value)
+            .replace(/[&<>"']/g, (c) => ({
+                "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
+            }[c]));
+    },
+
+    /** "3 minutes ago" for a timestamp, "" for anything unparseable. */
+    timeAgo(iso) {
+        if (!iso) return "";
+        const then = new Date(iso).getTime();
+        if (Number.isNaN(then)) return "";
+        const seconds = Math.round((Date.now() - then) / 1000);
+        if (seconds < 60) return "just now";
+        const minutes = Math.round(seconds / 60);
+        if (minutes < 60) return minutes + (minutes === 1 ? " minute ago" : " minutes ago");
+        const hours = Math.round(minutes / 60);
+        if (hours < 24) return hours + (hours === 1 ? " hour ago" : " hours ago");
+        const days = Math.round(hours / 24);
+        if (days < 30) return days + (days === 1 ? " day ago" : " days ago");
+        return new Date(iso).toLocaleDateString(undefined,
+            { year: "numeric", month: "short", day: "numeric" });
+    },
+
+    countPhrase(count, singular, plural) {
+        return count + " " + (count === 1 ? singular : (plural || singular + "s"));
+    },
+};