overlay_instances

overlay_instances(
    image,
    labels,
    alpha=OVERLAY_ALPHA,
    outline=False,
    colours=None,
)

An instance label map over its image, coloured so no two touching objects match.

The rule is adjacency rather than identity, and it is stated here rather than left to luck: a colour repeats across the picture and never between neighbours. See the comment above _adjacent_pairs for the measurement that made the exact colouring the cheap option rather than the expensive one.

A picture that needs more colours than the palette has gets a UserWarning, naming how many it needs and how many objects lost the guarantee. The slot wraps onto a colour a neighbour already holds - provably, since a slot is only past the end of the palette once every colour before it was taken by a neighbour - so two touching objects are drawn as one and this figure answers its own question wrongly. That is the one failure it is for, so it is said rather than hidden. Unreachable on anything measured here: the hardest of 670 Data Science Bowl cases needs 3 of the 8 colours in the default palette.

Parameters

Name	Type	Description	Default
image	np.ndarray	one image, as overlay_mask takes it.	required
labels	np.ndarray	an instance label map, one integer per object and 0 for background.	required
alpha	float	how much of the tint shows. Ignored when outline is true, where a stroke is drawn at full strength - a translucent outline is a smudge.	OVERLAY_ALPHA
outline	bool	draw one stroke per object instead of filling it, which is what a pathologist is used to and what leaves the tissue entirely visible.	False
colours	list[str] | None	the palette to take slots from. Defaults to the engine’s CLASS_COLOURS, which the R package reads too.	None

Returns

Name	Type	Description
	np.ndarray	A height x width x 3 array of 0-255 integers.

Raises

Name	Type	Description
	PlatypusError	if the shapes do not correspond, or the palette is empty.

import numpy as np image = np.full((5, 9, 3), 0.5) labels = np.zeros((5, 9), dtype=int) labels[1:4, 1:4] = 1 labels[1:4, 4:7] = 2 # touching object 1 along a seam shown = overlay_instances(image, labels) shown.shape (5, 9, 3) bool((shown[2, 2] != shown[2, 5]).any()) # two touching objects, two colours True