read_image

read_image(path, *, channels=3, size=None, nearest=False, dicom_window='auto')

Read one image or volume as a channels-last array.

The reader every other part of this package uses, which is the reason it is public: a picture drawn from a differently resized copy is a picture of something the model never saw, and the disagreements it shows may be the resizing rather than the model. Boxes come back from predict in the source image’s own pixels, so drawing them needs the image at size=None.

Scaled to 0-1 for anything read in real units (DICOM, NIfTI) and left at 0-255 for ordinary pictures, which to_float divides later. Both are drawable: the plotting functions decide by the range rather than by the dtype.

DICOM is detected by content rather than by extension, because exports out of an archive frequently carry no extension or one the archive invented. A directory of slices is read as one volume, so a CSV may name a series directory in the column that names a file.

Parameters

Name	Type	Description	Default
path	str | Path	a file, or a directory holding one DICOM series.	required
channels	int	how many channels to return - 1, 3 or 4 for ordinary pictures.	3
size	tuple[int, …] | None	resize to this shape, or None for the file’s own. Give it in the order every shape in this package uses, (height, width) and (height, width, depth).	None
nearest	bool	nearest-neighbour rather than interpolation. Required for masks: interpolating a mask invents colours that match no class, which then become background without a word.	False
dicom_window		the window to apply to data in real units, "auto" to take the one the file records, or (centre, width). Ignored for ordinary pictures.	'auto'

Returns

Name	Type	Description
	np.ndarray	A channels-last array: (height, width, channels) for an image and
	np.ndarray	(height, width, depth, channels) for a volume.

Raises

Name	Type	Description
	ImageError	for a channel count an ordinary picture cannot have.

No example: it reads a file, so there is nothing to show without one on disk. The data science bowl article draws what it returns.