Microscope OpenCV and NumPy nodes

Grayscale and color-space conversion, blur, thresholding, morphology, connected components, filtering, mask/image arithmetic, statistics, contour conversion, ROI rasterization and boolean operations.

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_opencv. 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-opencv --python /absolute/path/to/microscope-nodes-opencv/.venv/bin/python --trust

This installs NumPy and headless OpenCV from this pack's declared dependencies. 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.

Fixed Threshold now declares a tile-local contract alongside Grayscale. Otsu remains a region-wide histogram operation and is explicitly rejected when input geometry is tiled; use fixed thresholds for whole-slide batches. Numerical fixed-threshold behavior is unchanged.

Build a first mask in the viewer

Open a local slide, connect the Python companion, and install/register this pack as described above. In Workflow, add WSI Region, Grayscale, and Threshold, then connect the matching typed ports:

WSI Region.image → Grayscale.image
Grayscale.gray → Threshold.gray
Threshold.mask → binary mask result

Start with the viewport source scope so the graph reads the current view rather than constructing a full-slide array. Set the source Working MPP to no finer than measured source MPP; choose a larger number for a coarser image. Set Threshold to a starting value in [0,255]; Select darker pixels is on by default, so a pixel becomes foreground when its grayscale intensity is at or below the threshold. Add the completed mask to Layers to inspect it over the source slide.

This threshold is an intensity rule, not a tissue model. Stain, background, scanner, and exposure affect it. A single cutoff can include dark artifacts or omit pale tissue; inspect the overlay and tune it on representative local regions before using it for downstream analysis. It is not validated for diagnosis or quantitative clinical decisions.

For a whole-slide tile run, the graph's processing nodes need compatible tile-local contracts. Grayscale and fixed Threshold declare tile-local execution. Use Otsu threshold must remain off: Otsu computes a region-wide histogram and fails on tiled inputs. The viewer reads bounded overlapping/context tiles and writes sparse mask cores, subject to its execution and storage limits; this is not native-resolution monolithic inference.

Node families

The generated official node reference shows the exact current port types, defaults, constraints, stable IDs, and execution contracts parsed from this package's registry. The main families are:

Family	Nodes	Typical use
Image preparation	Grayscale, Color-space channels, Gaussian blur	Convert RGB to grayscale or HSV/Lab channels; reduce fine intensity variation before thresholding.
Binary masks	Threshold, Adaptive threshold, Morphology, Invert mask	Fixed/Otsu thresholding, local thresholding, opening/closing/dilation/erosion, and inversion. Adaptive window size is odd and bounded.
Components and measures	Connected components, Filter components, Tissue statistics	Label connected foreground components, filter by component criteria, and calculate table/fraction summaries.
Raster operations	Mask arithmetic, Image blend	Combine aligned masks or images with a selected operation/weight. Spatial inputs must share geometry.
Vector conversion	Mask to ROI, ROI to mask, Apply ROI, ROI Boolean	Convert bounded contours to WSI-coordinate polygon ROIs, rasterize ROI geometry, mask images, and combine ROI sets. Vectorization simplifies/bounds contours and is not a substitute for the original raster when precise pixel boundaries matter.
Probability	Probability threshold	Convert an aligned probability raster to a binary mask using a 0–1 cutoff.

All of these are ordinary pack nodes discovered from microscope-node.toml; none requires a special viewer build. Nodes accept only their declared input types. The viewer and companion reject mismatched geometry rather than silently resize or align spatial inputs. See the generated schema instead of guessing parameter labels or limits.

Installation and environment separation

The manifest declares numpy>=2,<3 and opencv-python-headless>=4.12,<5. For an isolated pack environment:

python3 -m venv .venv
.venv/bin/python -m pip install -e .

Then register the checkout with the interpreter that will run it:

microscope nodes register /absolute/path/to/microscope-nodes-opencv \
  --python /absolute/path/to/microscope-nodes-opencv/.venv/bin/python --trust

register does not install dependencies or copy the checkout. Restart the companion and reconnect the viewer after registration. Alternatively use Add Nodes from Git for a public credential-free HTTPS clone and inspect/trust an exact commit. The managed pack environment remains separate from the SDK environment.

Troubleshooting

• Pack missing from the library: check the manifest path and registration, restart the companion, then refresh/reconnect the node catalogue.
• No module named cv2 or numpy: install this pack's dependencies into the exact interpreter named by the registration, not only into the SDK venv.
• Cannot connect ports: check the port label/type and the generated schema; image, grayscale, mask, probability, ROI, table, and scalar values are different types.
• Misaligned raster or ROI error: use sources and layers from the same captured WSI region/grid. Do not mix layers with different shape, bounds, or MPP.
• Otsu rejected during whole-slide execution: turn off Otsu and choose a fixed threshold. Otsu is a region-wide histogram operation.
• Unexpected threshold mask: inspect the grayscale source and tweak the cutoff/foreground direction. A threshold cannot compensate for all stain and scanner variation.

Numerical test

From this repository, install declared dependencies and run the local algorithm/import tests:

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

These tests use local arrays/fixtures. They do not require model weights and do not claim clinical validity.