save_class_masks

save_class_masks(
    prediction,
    directory,
    *,
    classes,
    cases=None,
    threshold=0.5,
    suffix='',
)

One binary picture per class, which is how an overlapping prediction reaches disk.

onehot_to_colours refuses a prediction where a voxel is in two classes at once, and its refusal says overlapping classes are written one file per class. This is that file per class. regions gives a channel per named region and a sigmoid per channel, so the channels neither compete nor sum to one, and the only lossless thing a picture can hold is one channel.

Each file is <case><suffix>_<region>.png, mode L, 0 or 255 - a mask anything opens and anything thresholds back, rather than a colour that has to be looked up. The class name goes through class_filename, so whole tumour is whole_tumour on disk.

The argument is classes rather than names because the R package’s save_masks and save_volumes already use names for the files they write, and a sibling writer where the same word means the classes instead is the quiet kind of mistake: a call copied from one to the other would pass filenames as class names, the counts would match whenever they happened to, and nothing would refuse it.

What this does not do is decide for you. A channel where nothing reaches threshold is written as an empty picture rather than skipped: a missing file reads as “this run did not produce that class”, and an empty one reads as “it did and the answer was nothing”, which are different findings and only one of them is true.

Parameters

Name	Type	Description	Default
prediction	np.ndarray	Channels-last probabilities or a one-hot array, either (h, w, c) for one image or (n, h, w, c) for a stack. A volume cannot come here: a PNG carries no voxel spacing and no orientation, so a volume mask written as pictures cannot be laid back over the scan it was computed from. Only rank 5 is refused, because a single volume (d, h, w, c) and a stack of images have the same rank and nothing in the array can tell them apart.	required
directory	str | Path	Where to write. Created, with parents, if it does not exist.	required
classes	Sequence[str]	One name per channel, in channel order - [region.name for region in spec.data.regions]. Channel order is the order the regions were written in, which is also the order every per-class score is reported in.	required
cases	Sequence[str] | None	One name per image, usually the source filenames’ stems. Defaults to mask_0001 and so on.	None
threshold	float	A channel is hot where it reaches this. 0.5 is what every metric in the package thresholds a multilabel channel at, so a different number here writes a picture that disagrees with the score printed beside it.	0.5
suffix	str	Added before the class, so two models can write into one directory.	''

Returns

Name	Type	Description
	list[Path]	The paths written, image by image and within an image channel by channel.