Local Python workflow builder

Workflow replaces the user-facing browser Algorithms inspector. Its React Flow (@xyflow/react) canvas provides a typed, draggable graph, a searchable node library, a schema-based parameter inspector, execution status, local save, and portable JSON import/export. You can build and save graphs without Python; execution uses the local Python companion described below.

Use the workflow editor

Open the Workflow tab in the viewer inspector, then choose Open workflow. The editor has a top toolbar, a node library, the graph canvas, an inspector, and an optional console. Drag the dividers to resize the library, inspector, or console; use Full screen to expand the editor. The layout is saved in this browser. At a narrow viewport, Nodes and Settings open their panels, and each panel has its own Close action. Escape closes the dock without canceling a running job.

The node library groups available nodes by category. Search matches node names, descriptions, categories, and package identities. When Python is paired, the library reports the number of installed packs; while offline, it identifies the catalogue as offline and explains that Python is needed to check installed packs. If search has no matches, choose Clear search or try an operation or package name. Add a node with its library button or drag it onto the canvas. An empty graph offers Add WSI source and Browse nodes actions.

Each node card names the operation and its role/category. Its ports show the value type; input ports also identify optional inputs. Drag from an output handle to an input handle to connect them. Only compatible port types connect. Nodes can be moved, selected, deleted, and grouped into a composite; select a node to open its parameters. Clicking a connection selects it for inspection, but that selection is presentation state and is not saved in workflow JSON. Use the canvas controls to zoom or fit the graph. If a required node definition is unavailable, choose Review node packages to inspect the missing package requirement.

The inspector uses the selected node's schema to show its description, default values, help, and parameter limits. Boolean fields use checkboxes; enumerated fields use a list; numeric fields enforce the schema's range and step. While a numeric value is incomplete or invalid, the draft remains visible and marked invalid, while the last valid value remains in the graph. Correct it before running. Nodes without editable parameters say so; if Python is offline, the inspector explains that the local connection is needed to check a node package's schema.

The status line explains whether the graph can run. It identifies a missing slide, an unpaired Python companion, unavailable node definitions, or required inputs that still need connections. Run starts local execution and Cancel stops the active job; node cards show state and numeric progress when the runtime provides it. Open Console to read node events, errors, and the bounded tail of local Python output. On failure, the status offers Open Console and reminds you to review the error and node parameters. After a completed run, View outputs opens the result list. Spatial masks, probability maps, instance labels, and ROIs expose the existing Add to Layers or Add ROIs to Annotations action when supported. Other JSON or array outputs can be inspected or exported. A result without spatial layers is described explicitly; it is not installed as a layer.

Use Save for a draft stored in this browser, Export workflow JSON for a portable graph file, and Load workflow JSON to import one. Loading validates the graph but does not execute it or install a node pack. Save and export shortcuts are Ctrl/⌘ S and Ctrl/⌘ Shift S; Ctrl/⌘ Enter runs the graph. The optional Python setup and workflow guide link opens in a new tab. The viewer's introduction can be replayed from Settings; replay does not change the existing consent choice. First-visit consent remains required before the viewer opens.

The native viewer remains available without installing Python. Opening, navigating, annotating, and saving slides do not require a Python connection.

Connection and trust

From a Python repository clone: pip install -e '.[workflows]', microscope serve --origin <exact-viewer-origin>. After publication: pip install "microscope-io[workflows]". Pair using the short-lived terminal code. Accept browser local-network permission if requested. The companion binds only loopback, validates Host/Origin, uses restrictive preflight/CORS and origin-bound session bearer authorization. Viewing does not request localhost access until the workflow editor is opened.

A paired viewer can execute Python with the user's filesystem permissions. Add Nodes from Git reviews a static manifest/exact commit/dependencies before explicit trust; installs get separate venvs, not security sandboxes. A pack may expose static JSON composites; the reviewed graph is embedded in the workflow, stays read-only while installed, and can be forked locally for editing. Workflow required_packs records each pack's HTTPS repository URL and, after approval, its version and exact installed commit. Older official workflows are upgraded with the canonical official URLs when loaded; custom URLs are saved with the local draft and portable JSON. URLs containing credentials, query strings, or fragments are rejected and omitted from export.

The offline viewer catalogue includes the approved 26 official node schemas. Official pack repositories and technical references are not yet publicly distributed; their GitLab links do not grant access. Until those repositories are made publicly readable, users can install only reachable repositories they provide themselves. Workflow creation, JSON import/export, and local execution remain available for compatible installed packs.

The Add Nodes from Git panel lists each required pack that is not installed, with a per-pack review button and a Review all action for up to four packs. Reviewing downloads repository metadata only; the user sees every reviewed commit and dependency before choosing Trust and install all. Installation remains a separate explicit approval step. The companion permits at most four pending reviews. Private repositories that require credentials cannot be cloned by the UI installer; clone them with normal Git tools and register a trusted local checkout instead. Opening or importing a workflow never installs code automatically.

Spatial contracts and scientific boundaries

Spatial values carry WSI level-0 pixel bounds, explicit X/Y micrometres per pixel, array shape, pixel-to-level-0 affine sampling transform, resolution kind, and valid-data bounds. Pixel indices, level-0 slide pixels, and physical micrometres are distinct. ROI GeoJSON coordinates are WSI level-0 pixels (not longitude/latitude). A vector layer preserves polygon rings/holes; raster sources retain their raster grid and do not get expanded into polygon features. Deleted/unavailable layers fail before a job starts; each source is copied into an immutable local job input before the first asynchronous upload.

Built-in conversion operations include mask-to-ROI (disconnected components and holes), ROI-to-mask, probability thresholding, ROI intersection/union/difference, and applying an ROI to a raster. Mask-to-ROI bounds feature count and simplifies contours; use the original mask when that approximation is not suitable for downstream measurements.

Actual X/Y slide MPP calibrates browser resampling; output bounds preserve the precise physical grid, cropping less than one working pixel at right/bottom. Models enforce their expected working MPP. No objective-power guesses. ROI scope uses its bounding rectangle. Invalid MPP/oversized inputs fail actionably.

Presets: threshold/clean tissue, Double-Pass overview (10 MPP), Conflux overview (40 MPP), InstanSeg nuclei region (.5 MPP), connected components. Model weights are explicit local paths and checksum-pinned; export/local draft persistence excludes them, runtime input IDs, obvious absolute paths and secret fields. Arbitrary user-authored parameters should not contain private patient metadata. Native model details/licensing/setup live in Python's developer docs.

Conflux/Double-Pass user-facing browser implementations were removed. InstanSeg had been a feasibility harness, not an exposed working browser node; its full native TorchScript now executes through Python. Historical model-evaluation harnesses remain developer-only. Internal shared sampler Double-Pass, censusRecipeV1, pinned artifacts/fixtures and contribution scheduling were not changed.