Microscope InstanSeg nuclei

InstanSeg brightfield_nuclei v0.1.1 TorchScript inference, normalization, cancellation, and compact instance-label output.

This is an ordinary microscope-node.toml extension. The companion loads it through the public node-pack discovery and package-isolated execution path; no official-only runtime is used. Node IDs are namespaced under microscope_instanseg. Historical microscope.* IDs remain supported by schema-declared legacy_ids when this pack is installed.

Install locally

Review the source, install the scientific dependencies into a package-specific interpreter, then register the local checkout explicitly:

python3 -m venv .venv
.venv/bin/python -m pip install -e .
microscope nodes register /absolute/path/to/microscope-nodes-instanseg --python /absolute/path/to/microscope-nodes-instanseg/.venv/bin/python --trust

This installs NumPy and PyTorch from this pack's declared dependencies. PyTorch CPU/CUDA builds and hardware support depend on the local platform; choose a user-managed environment for a CUDA-specific build. Registration is explicit local trust. The SDK injects the framework into the isolated node process; installed package environments do not share Python site-packages.

Development and tests

python -m pip install -e .
python -m unittest discover -s tests -v

No environment or model weights are committed. Model weights must be obtained by the user from the official source, stored locally, and pass the pinned SHA-256 check.

Attribution

This package's implementation is Microscope.io source code. It depends on NumPy (BSD-3-Clause) and OpenCV (Apache-2.0 Python distribution; OpenCV project components retain their upstream BSD notices). See NumPy licenses and OpenCV licenses. Model-specific attribution and source licenses are documented in the respective model README.

Model: InstanSeg, Apache-2.0, official brightfield_nuclei v0.1.1 TorchScript; SHA-256 0c724da169d507d8dd2e206ad3675a0b1566824eee6e20ad9a0ba916311d9dd0. Model weights are not included.

Whole-slide execution uses 1024×1024 padded inputs at actual 0.5 MPP on both axes. Bounded native region/reference inference remains supported up to 1024 pixels/axis. An optional aligned binary ROI keeps whole local instances with at least min_roi_fraction (default 0.5) of pixels inside the gate; labels are not fragmented by a pixelwise mask. Browser core ownership can still split instances at seams. Deterministic global IDs do not imply biological seam reconciliation.

Use the node

The stable type ID is microscope_instanseg.brightfield_nuclei. Its required image input is RGB; an optional aligned binary roi input gates retained instances. It returns labels, a uint32 instance-label raster on the source geometry. Label 0 is background; positive values identify the local predicted instances.

The model is Apache-2.0 InstanSeg brightfield_nuclei v0.1.1 and requires 0.5 µm/px on both axes. For a bounded region graph, use a source region at 0.5 MPP whose width and height do not exceed 1024 source pixels after resampling. Whole-slide mode uses the viewer's 1024×1024 tile contract with 64-pixel context padding/overlap. Use the supported viewer tile run and be aware that current core ownership can split one biological instance at a tile seam; it does not guarantee perfect biological stitching.

Parameters are weights (local instanseg.pt path, not portable), device (cpu or cuda), and min_roi_fraction (default 0.5, range 0–1). The optional ROI retains a complete local instance if at least the chosen fraction of its labeled pixels overlap the ROI; it does not cut the instance's pixels to the polygon. The output remains instance labels.

Install the pack into its isolated Python environment and register it with the companion as in the installation section. Download the official weights separately from the model source, verify they match the package-pinned SHA-256, and set that path in the node inspector. The package installs NumPy and PyTorch; CPU/CUDA wheels and hardware compatibility depend on the local platform. For CUDA, use a compatible PyTorch/CUDA installation; the device choice does not install drivers. No weights are bundled. This optional model pack is not needed to view or annotate slides.

To execute it, open a slide, pair the companion, add WSI Region and InstanSeg nuclei, select either a bounded region or supported whole-slide mode at the required MPP, set the weights path/device and optional ROI connection, then choose Run. Add labels to Layers and inspect it over the source slide. In whole-slide runs, output/storage bounds can stop a run before a partial result is installed.

Common failures include missing/mismatched weights (checksum error), absent MPP or the wrong 0.5 spacing, region dimensions over the bound, and a CUDA device without a matching runtime. Choose CPU or make the expected local environment available; do not modify the source spacing to bypass validation.

The model output is research inference, not a clinically validated segmentation. Instance labels do not represent a validated cell count, and seam splitting can affect object continuity. Use the generated node schema for exact types and parameter constraints. Import tests do not download weights or execute inference:

python -m pip install -e .
python -m unittest discover -s tests -v