Imaging

The imaging module contains types for working with medical imaging data.

CropSettings

Bases: BaseModel

Configuration settings for cropping medical images.

Attributes:

Name	Type	Description
crop_to	CropTarget	The target area to crop. Defaults to CropTarget.ANATOMY.
padding	int	The amount of padding to apply around the cropped area. Defaults to 1.
visit_index	Optional[int]	Specifies which visit's ROI to use when crop_to is ROI_ENHANCE or ROI_NONENHANCE. If None, the union of all available ROIs is used. If an integer is provided, only the ROI from that specific visit is used.

CropTarget

Bases: Enum

Enum representing different cropping targets for medical imaging.

Attributes:

Name	Type	Description
ANATOMY	int	Crop to the anatomical structure (e.g., brain or breast)
ROI_ENHANCE	int	Crop to the region of interest (ROI) for the enhancing region.
ROI_NONENHANCE	int	Crop to the region of interest (ROI) for the non-enhancing region.

ITKNifti

Bases: Image3D

Placeholder class for ITK-based NIfTI handling.

Image3D

Bases: BaseModel

Abstract base class for 3D medical images.

Attributes:

Name	Type	Description
image	Any	The underlying image data (e.g., NIfTI image object).

Methods:

Name	Description
array	Abstract property to get the image data as a NumPy array or PyTorch tensor.
from_file	Abstract method to load an image from a file.
to_file	Abstract method to save the image to a file.
shape	Abstract property to get the shape of the image.
centroid	Abstract property to get the centroid of the image.
spacing	Abstract property to get the voxel spacing of the image.
voxvol	Abstract property to calculate the volume of a voxel.
from_array	Abstract method to create an image from a NumPy array or PyTorch tensor.

array property

Returns the image data as a NumPy array or PyTorch tensor.

Returns:

Type	Description
ndarray | Tensor	np.ndarray | torch.Tensor: The image data.

centroid property

Returns the centroid of the image.

Returns:

Type	Description
ndarray	np.ndarray: The centroid coordinates.

shape property

Returns the shape of the image.

Returns:

Name	Type	Description
Shape3D	Shape3D	The 3D shape of the image.

spacing property

Returns the voxel spacing of the image.

Returns:

Name	Type	Description
Spacing3D	Spacing3D	The spacing along each axis and the unit of measurement.

voxvol property

Calculates the volume of a voxel.

Returns:

Name	Type	Description
float	float	The voxel volume.

from_array(array, referenceImage) staticmethod

Creates a 3D image from a NumPy array or PyTorch tensor.

Parameters:

Name	Type	Description	Default
array	ndarray | Tensor	The array representing the image.	required
referenceImage	Image3D	An reference image for copying metadata.	required

Returns:

Name	Type	Description
Image3D	Image3D	The created 3D image.

from_file(path) staticmethod

Loads a 3D image from a file.

Parameters:

Name	Type	Description	Default
path	FilePath	The path to the image file.	required

Returns:

Name	Type	Description
Image3D	Image3D	The loaded image.

to_file(path)

Saves the image to a file.

Parameters:

Name	Type	Description	Default
path	FilePath	The destination file path.	required

NibabelNifti

Bases: Image3D

Implementation of Image3D for NIfTI images using NiBabel.

Attributes:

Name	Type	Description
image	Nifti1Image	The NIfTI image object.

array property

Returns the image data as a NumPy array.

Returns:

Type	Description
ndarray | Tensor	np.ndarray | torch.Tensor: The image data.

centroid property

Returns the centroid of the image.

Returns:

Type	Description
ndarray	np.ndarray: The centroid coordinates.

shape property

Returns the shape of the image.

Returns:

Name	Type	Description
Shape3D	Shape3D	The 3D shape of the image.

spacing property

Returns the voxel spacing of the image.

Returns:

Name	Type	Description
Spacing3D	Spacing3D	The spacing along each axis and the unit of measurement.

from_array(array, referenceImage=None) staticmethod

Creates a NIfTI image from a NumPy array or PyTorch tensor.

Parameters:

Name	Type	Description	Default
array	ndarray | Tensor	The array representing the image.	required
referenceImage	Optional[NibabelNifti]	An reference NIfTI image for copying metadata.	None

Returns:

Name	Type	Description
NibabelNifti	NibabelNifti	The created NIfTI image.

from_file(path) staticmethod

Loads a NIfTI image from a file.

Parameters:

Name	Type	Description	Default
path	FilePath	The path to the NIfTI file.	required

Returns:

Name	Type	Description
NibabelNifti	NibabelNifti	The loaded NIfTI image.

to_file(path)

Saves the NIfTI image to a file.

Parameters:

Name	Type	Description	Default
path	FilePath	The destination file path.	required

Shape3D

Bases: NamedTuple

Represents the 3D size/shape of an image or volume.

Attributes:

Name	Type	Description
x	int	The size (i.e. number of points) along the x-axis.
y	int	The size (i.e. number of points) along the y-axis.
z	int	The size (i.e. number of points) along the z-axis.

Spacing3D

Bases: NamedTuple

Represents the spacing between voxels in a 3D image or volume.

Attributes:

Name	Type	Description
x	float	Spacing along the x-axis.
y	float	Spacing along the y-axis.
z	float	Spacing along the z-axis.
unit	Unit	The unit of measurement for the spacing values.

Unit

Bases: Enum

Enum representing units of measurement commonly used in medical imaging.

Attributes:

Name	Type	Description
UNKNOWN	int	Unknown unit.
METER	int	Unit of length in meters.
MILLIMETER	int	Unit of length in millimeters.
MICRON	int	Unit of length in microns.
SECONDS	int	Unit of time in seconds.
MILLISECONDS	int	Unit of time in milliseconds.
MICROSECONDS	int	Unit of time in microseconds.
HERTZ	int	Unit of frequency in hertz.
PARTSPERMILLION	int	Unit for parts per million.
RADIANSPERSECOND	int	Unit for angular velocity in radians per second.