Image Module#

Module: pyradise.data.image

General#

The image module provides the abstract Image base class and the implementations for the IntensityImage and SegmentationImage classes.

difference between intensity and segmentation image — Fig. 6 Examples of an intensity image and a segmentation image.#

Class Overview#

The following classes are provided by the image module:

Class	Description
`Image`	Base class for all `Image` subclasses.
`IntensityImage`	`Image` class for intensity images (e.g. MR, CT, US images).
`SegmentationImage`	`Image` class for segmentation images (i.e. manual or automatically generated label maps).

Details#

class Image(image, data=None)[source]#

Bases: ABC

An abstract class to store images with additional attributes compared to SimpleITK.Image and itk.Image.

In addition to standard image types, the Image contains a TransformTape which is used to track and playback transformations applied to the image, such that the original physical properties (i.e. origin, direction, spacing) of the image can be retrieved.

Parameters:: image (Union[sitk.Image, itk.Image]) – The image data to be stored.

add_data(data)[source]#

Add additional data to the image.

Parameters:: data (Dict[str, Any]) – The additional data.
Return type:: None
Returns:: None

add_data_by_key(key, data)[source]#

Add additional data by key to the image.

Parameters:

key (str) – The key of the additional data.
data (Any) – The additional data.

Return type:

None

Returns:

None

get_data()[source]#

Get the additional data associated with the image.

Returns:: The additional data associated with the subject.
Return type:: Dict[str, Any]

get_data_by_key(key)[source]#

Get additional data by key or None if the key is not existing.

Parameters:: key (str) – The key of the specific additional data.
Returns:: The data or None.
Return type:: Any

replace_data(key, new_data, add_if_missing=False)[source]#

Replace data by a new value.

Parameters:

key (str) – The key of the additional data.
new_data (Any) – The new additional data.
add_if_missing (bool) – If True, the additional data will be added if the key is not existing (default: False).

Returns:

True if the additional data is replaced successfully, False otherwise.

Return type:

bool

remove_additional_data()[source]#

Remove all additional data from the image.

Return type:: None
Returns:: None

remove_additional_data_by_key(key)[source]#

Remove additional data by a key from the image.

Parameters:: key (str) – The key of the additional data.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

static cast(image, pixel_type, as_sitk=True)[source]#

Cast an image to a certain pixel type and return it as either a itk.Image or SimpleITK.Image.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image to be casted.
pixel_type (Union[itk.support.types.itkCType, int]) – The output pixel type.
as_sitk (bool) – If True the image gets returned as a SimpleITK image otherwise as an ITK image (default: True).

Returns:

The casted image as itk.Image or SimpleITK.Image.

Return type:

Union[sitk.Image, itk.Image]

get_image_data(as_sitk=True)[source]#

Get the image data as an itk.Image (with as_sitk=False) or SimpleITK.Image (with as_sitk=True).

Parameters:: as_sitk (bool) – If True returns the image as a SimpleITK image else as an ITK image (default: True).
Returns:: The image as the either a itk.Image or a SimpleITK.Image.
Return type:: Union[itk.Image, sitk.Image]

set_image_data(image)[source]#

Set the image data.

Parameters:: image (Union[sitk.Image, itk.Image]) – The image to be set.
Return type:: None
Returns:: None

get_image_data_as_np(adjust_axes=True)[source]#

Get the image data as a numpy array.

Parameters:: adjust_axes (bool) – If True, the axes of the image are adjusted to the numpy convention (default: True).
Returns:: The image data as a numpy array.
Return type:: np.ndarray

get_image_itk_type()[source]#

Get the image type of this image.

Returns:: The image type of this image.
Return type:: itk.Image

get_origin()[source]#

Get the origin of the image.

Returns:: The origin of the image.
Return type:: Tuple[float, …]

get_direction()[source]#

Get the direction of the image.

Returns:: The direction of the image.
Return type:: np.ndarray

get_spacing()[source]#

Get the spacing of the image.

Returns:: The spacing of the image
Return type:: Tuple[float, …]

get_size()[source]#

Get the size of the image.

Returns:: The size of the image.
Return type:: Tuple[int, …]

get_dimensions()[source]#

Get the number of image dimensions.

Returns:: The number of image dimensions.
Return type:: int

get_orientation()[source]#

Get the orientation of the image.

Returns:: The orientation of the image.
Return type:: str

get_transform_tape()[source]#

Get the TransformTape.

Returns:: The TransformTape.
Return type:: TransformTape

set_transform_tape(tape)[source]#

Set the TransformTape.

Parameters:: tape (TransformTape) – The TransformTape.
Return type:: None
Returns:: None

add_transform_info(info)[source]#

Add a TransformInfo instance to the TransformTape instance of the image.

Parameters:: info (TransformInfo) – The TransformInfo instance to be added.
Return type:: None
Returns:: None

abstract copy_info(source, include_transforms=False)[source]#

Copy the image information from another image.

Parameters:

source (Image) – The image to copy the information from.
include_transforms (bool) – If True the TransformTape is copied, otherwise not.

Return type:

None

Returns:

None

abstract is_intensity_image()[source]#

Return True if the image is an intensity image otherwise False.

Returns:: n/a
Return type:: bool

class IntensityImage(image, modality)[source]#

Bases: Image

An intensity image class including a TransformTape and Modality to identify the imaging modality of the image.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image data as itk.Image or SimpleITK.Image.
modality (Union[Modality, str]) – The image Modality or the modality’s name.

get_modality(as_str=False)[source]#

Get the Modality.

Parameters:: as_str (bool) – If True returns the Modality as a string, otherwise as type Modality.
Returns:: The Modality.
Return type:: Union[Modality, str]

set_modality(modality)[source]#

Set the Modality.

Parameters:: modality (Modality) – The Modality.
Return type:: None
Returns:: None

copy_info(source, include_transforms=False)[source]#

Copy the image information from another IntensityImage.

The copied information includes the following attributes:

Modality

TransformTape (optional)

Raises:

ValueError – If the source image is not an instance of IntensityImage.

Parameters:

source (IntensityImage) – The source image.
include_transforms (bool) – If True the TransformTape is copied, otherwise not.

Return type:

None

Returns:

None

is_intensity_image()[source]#

If the image is an instance of IntensityImage this function returns True otherwise False.

Returns:: True
Return type:: bool

add_data(data)#

Add additional data to the image.

Parameters:: data (Dict[str, Any]) – The additional data.
Return type:: None
Returns:: None

add_data_by_key(key, data)#

Add additional data by key to the image.

Parameters:

key (str) – The key of the additional data.
data (Any) – The additional data.

Return type:

None

Returns:

None

add_transform_info(info)#

Add a TransformInfo instance to the TransformTape instance of the image.

Parameters:: info (TransformInfo) – The TransformInfo instance to be added.
Return type:: None
Returns:: None

static cast(image, pixel_type, as_sitk=True)#

Cast an image to a certain pixel type and return it as either a itk.Image or SimpleITK.Image.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image to be casted.
pixel_type (Union[itk.support.types.itkCType, int]) – The output pixel type.
as_sitk (bool) – If True the image gets returned as a SimpleITK image otherwise as an ITK image (default: True).

Returns:

The casted image as itk.Image or SimpleITK.Image.

Return type:

Union[sitk.Image, itk.Image]

get_data()#

Get the additional data associated with the image.

Returns:: The additional data associated with the subject.
Return type:: Dict[str, Any]

get_data_by_key(key)#

Get additional data by key or None if the key is not existing.

Parameters:: key (str) – The key of the specific additional data.
Returns:: The data or None.
Return type:: Any

get_dimensions()#

Get the number of image dimensions.

Returns:: The number of image dimensions.
Return type:: int

get_direction()#

Get the direction of the image.

Returns:: The direction of the image.
Return type:: np.ndarray

get_image_data(as_sitk=True)#

Get the image data as an itk.Image (with as_sitk=False) or SimpleITK.Image (with as_sitk=True).

Parameters:: as_sitk (bool) – If True returns the image as a SimpleITK image else as an ITK image (default: True).
Returns:: The image as the either a itk.Image or a SimpleITK.Image.
Return type:: Union[itk.Image, sitk.Image]

get_image_data_as_np(adjust_axes=True)#

Get the image data as a numpy array.

Parameters:: adjust_axes (bool) – If True, the axes of the image are adjusted to the numpy convention (default: True).
Returns:: The image data as a numpy array.
Return type:: np.ndarray

get_image_itk_type()#

Get the image type of this image.

Returns:: The image type of this image.
Return type:: itk.Image

get_orientation()#

Get the orientation of the image.

Returns:: The orientation of the image.
Return type:: str

get_origin()#

Get the origin of the image.

Returns:: The origin of the image.
Return type:: Tuple[float, …]

get_size()#

Get the size of the image.

Returns:: The size of the image.
Return type:: Tuple[int, …]

get_spacing()#

Get the spacing of the image.

Returns:: The spacing of the image
Return type:: Tuple[float, …]

get_transform_tape()#

Get the TransformTape.

Returns:: The TransformTape.
Return type:: TransformTape

remove_additional_data()#

Remove all additional data from the image.

Return type:: None
Returns:: None

remove_additional_data_by_key(key)#

Remove additional data by a key from the image.

Parameters:: key (str) – The key of the additional data.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

replace_data(key, new_data, add_if_missing=False)#

Replace data by a new value.

Parameters:

key (str) – The key of the additional data.
new_data (Any) – The new additional data.
add_if_missing (bool) – If True, the additional data will be added if the key is not existing (default: False).

Returns:

True if the additional data is replaced successfully, False otherwise.

Return type:

bool

set_image_data(image)#

Set the image data.

Parameters:: image (Union[sitk.Image, itk.Image]) – The image to be set.
Return type:: None
Returns:: None

set_transform_tape(tape)#

Set the TransformTape.

Parameters:: tape (TransformTape) – The TransformTape.
Return type:: None
Returns:: None

class SegmentationImage(image, organ, annotator=<pyradise.data.annotator.Annotator object>)[source]#

Bases: Image

A segmentation image class including a TransformTape and additional attributes to identify the Organ segmented and the Annotator who created the segmentation.

The specification of Annotator is optional and can be omitted if not explicitly used.

Parameters:

image (Union[sitk.Image, itk.Image]) – The segmentation image data.
organ (Union[Organ, str]) – The Organ represented by the segmentation image or its name.
annotator (Optional[Union[Annotator, str]]) – The Annotator of the segmentation image or a string with the name of the annotator (default: Annotator.get_default()).

get_organ(as_str=False)[source]#

Get the Organ.

Parameters:: as_str (bool) – It True the Organ gets returned as a str, otherwise as an Organ.
Returns:: The Organ or its name as a string.
Return type:: Union[Organ, str]

set_organ(organ)[source]#

Set the Organ.

Parameters:: organ (Organ) – The Organ.
Return type:: None
Returns:: None

get_annotator(as_str=False)[source]#

Get the Annotator.

Parameters:: as_str (bool) – If True the name of the Annotator gets returned as a str, otherwise as an Annotator (default: False).
Returns:: The Annotator or its name as string.
Return type:: Union[Annotator, str]

set_annotator(annotator)[source]#

Set the Annotator.

Parameters:: annotator (Annotator) – The Annotator.
Return type:: None
Returns:: None

get_organ_annotator_combination()[source]#

Get the OrganAnnotatorCombination.

Returns:: The combination of the Organ and the Annotator.
Return type:: OrganAnnotatorCombination

set_organ_annotator_combination(organ_annotator_combination)[source]#

Set the OrganAnnotatorCombination.

Parameters:: organ_annotator_combination (OrganAnnotatorCombination) – The OrganAnnotatorCombination.
Return type:: None
Returns:: None

copy_info(source, include_transforms=False)[source]#

Copy the image information from another SegmentationImage.

The copied information includes the following attributes:

Organ

Annotator

TransformTape (optional)

Raises:

ValueError – If the source image is not an instance of SegmentationImage.

Parameters:

source (IntensityImage) – The source image.
include_transforms (bool) – If True the TransformTape is copied, otherwise not.

Return type:

None

Returns:

None

is_intensity_image()[source]#

If the image is an IntensityImage this function returns True, otherwise False.

Returns:: False
Return type:: bool

is_binary()[source]#

Check if the image is binary.

Returns:: True if the image is binary, otherwise False.
Return type:: bool

add_data(data)#

Add additional data to the image.

Parameters:: data (Dict[str, Any]) – The additional data.
Return type:: None
Returns:: None

add_data_by_key(key, data)#

Add additional data by key to the image.

Parameters:

key (str) – The key of the additional data.
data (Any) – The additional data.

Return type:

None

Returns:

None

add_transform_info(info)#

Add a TransformInfo instance to the TransformTape instance of the image.

Parameters:: info (TransformInfo) – The TransformInfo instance to be added.
Return type:: None
Returns:: None

static cast(image, pixel_type, as_sitk=True)#

Cast an image to a certain pixel type and return it as either a itk.Image or SimpleITK.Image.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image to be casted.
pixel_type (Union[itk.support.types.itkCType, int]) – The output pixel type.
as_sitk (bool) – If True the image gets returned as a SimpleITK image otherwise as an ITK image (default: True).

Returns:

The casted image as itk.Image or SimpleITK.Image.

Return type:

Union[sitk.Image, itk.Image]

get_data()#

Get the additional data associated with the image.

Returns:: The additional data associated with the subject.
Return type:: Dict[str, Any]

get_data_by_key(key)#

Get additional data by key or None if the key is not existing.

Parameters:: key (str) – The key of the specific additional data.
Returns:: The data or None.
Return type:: Any

get_dimensions()#

Get the number of image dimensions.

Returns:: The number of image dimensions.
Return type:: int

get_direction()#

Get the direction of the image.

Returns:: The direction of the image.
Return type:: np.ndarray

get_image_data(as_sitk=True)#

Get the image data as an itk.Image (with as_sitk=False) or SimpleITK.Image (with as_sitk=True).

Parameters:: as_sitk (bool) – If True returns the image as a SimpleITK image else as an ITK image (default: True).
Returns:: The image as the either a itk.Image or a SimpleITK.Image.
Return type:: Union[itk.Image, sitk.Image]

get_image_data_as_np(adjust_axes=True)#

Get the image data as a numpy array.

Parameters:: adjust_axes (bool) – If True, the axes of the image are adjusted to the numpy convention (default: True).
Returns:: The image data as a numpy array.
Return type:: np.ndarray

get_image_itk_type()#

Get the image type of this image.

Returns:: The image type of this image.
Return type:: itk.Image

get_orientation()#

Get the orientation of the image.

Returns:: The orientation of the image.
Return type:: str

get_origin()#

Get the origin of the image.

Returns:: The origin of the image.
Return type:: Tuple[float, …]

get_size()#

Get the size of the image.

Returns:: The size of the image.
Return type:: Tuple[int, …]

get_spacing()#

Get the spacing of the image.

Returns:: The spacing of the image
Return type:: Tuple[float, …]

get_transform_tape()#

Get the TransformTape.

Returns:: The TransformTape.
Return type:: TransformTape

remove_additional_data()#

Remove all additional data from the image.

Return type:: None
Returns:: None

remove_additional_data_by_key(key)#

Remove additional data by a key from the image.

Parameters:: key (str) – The key of the additional data.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

replace_data(key, new_data, add_if_missing=False)#

Replace data by a new value.

Parameters:

key (str) – The key of the additional data.
new_data (Any) – The new additional data.
add_if_missing (bool) – If True, the additional data will be added if the key is not existing (default: False).

Returns:

True if the additional data is replaced successfully, False otherwise.

Return type:

bool

set_image_data(image)#

Set the image data.

Parameters:: image (Union[sitk.Image, itk.Image]) – The image to be set.
Return type:: None
Returns:: None

set_transform_tape(tape)#

Set the TransformTape.

Parameters:: tape (TransformTape) – The TransformTape.
Return type:: None
Returns:: None

class DoseImage(image, modality, scaling_value)[source]#

Bases: IntensityImage

A dose image class to specialize for properties of RTDose volumes.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image data as itk.Image or SimpleITK.Image.
modality (Union[Modality, str]) – The image Modality or the modality’s name.

add_data(data)#

Add additional data to the image.

Parameters:: data (Dict[str, Any]) – The additional data.
Return type:: None
Returns:: None

add_data_by_key(key, data)#

Add additional data by key to the image.

Parameters:

key (str) – The key of the additional data.
data (Any) – The additional data.

Return type:

None

Returns:

None

add_transform_info(info)#

Add a TransformInfo instance to the TransformTape instance of the image.

Parameters:: info (TransformInfo) – The TransformInfo instance to be added.
Return type:: None
Returns:: None

static cast(image, pixel_type, as_sitk=True)#

Cast an image to a certain pixel type and return it as either a itk.Image or SimpleITK.Image.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image to be casted.
pixel_type (Union[itk.support.types.itkCType, int]) – The output pixel type.
as_sitk (bool) – If True the image gets returned as a SimpleITK image otherwise as an ITK image (default: True).

Returns:

The casted image as itk.Image or SimpleITK.Image.

Return type:

Union[sitk.Image, itk.Image]

copy_info(source, include_transforms=False)#

Copy the image information from another IntensityImage.

The copied information includes the following attributes:

Modality

TransformTape (optional)

Raises:

ValueError – If the source image is not an instance of IntensityImage.

Parameters:

source (IntensityImage) – The source image.
include_transforms (bool) – If True the TransformTape is copied, otherwise not.

Return type:

None

Returns:

None

get_data()#

Get the additional data associated with the image.

Returns:: The additional data associated with the subject.
Return type:: Dict[str, Any]

get_data_by_key(key)#

Get additional data by key or None if the key is not existing.

Parameters:: key (str) – The key of the specific additional data.
Returns:: The data or None.
Return type:: Any

get_dimensions()#

Get the number of image dimensions.

Returns:: The number of image dimensions.
Return type:: int

get_direction()#

Get the direction of the image.

Returns:: The direction of the image.
Return type:: np.ndarray

get_image_data(as_sitk=True)#

Get the image data as an itk.Image (with as_sitk=False) or SimpleITK.Image (with as_sitk=True).

Parameters:: as_sitk (bool) – If True returns the image as a SimpleITK image else as an ITK image (default: True).
Returns:: The image as the either a itk.Image or a SimpleITK.Image.
Return type:: Union[itk.Image, sitk.Image]

get_image_data_as_np(adjust_axes=True)#

Get the image data as a numpy array.

Parameters:: adjust_axes (bool) – If True, the axes of the image are adjusted to the numpy convention (default: True).
Returns:: The image data as a numpy array.
Return type:: np.ndarray

get_image_itk_type()#

Get the image type of this image.

Returns:: The image type of this image.
Return type:: itk.Image

get_modality(as_str=False)#

Get the Modality.

Parameters:: as_str (bool) – If True returns the Modality as a string, otherwise as type Modality.
Returns:: The Modality.
Return type:: Union[Modality, str]

get_orientation()#

Get the orientation of the image.

Returns:: The orientation of the image.
Return type:: str

get_origin()#

Get the origin of the image.

Returns:: The origin of the image.
Return type:: Tuple[float, …]

get_size()#

Get the size of the image.

Returns:: The size of the image.
Return type:: Tuple[int, …]

get_spacing()#

Get the spacing of the image.

Returns:: The spacing of the image
Return type:: Tuple[float, …]

get_transform_tape()#

Get the TransformTape.

Returns:: The TransformTape.
Return type:: TransformTape

is_intensity_image()#

If the image is an instance of IntensityImage this function returns True otherwise False.

Returns:: True
Return type:: bool

remove_additional_data()#

Remove all additional data from the image.

Return type:: None
Returns:: None

remove_additional_data_by_key(key)#

Remove additional data by a key from the image.

Parameters:: key (str) – The key of the additional data.
Returns:: True when the removal procedure was successful otherwise False.
Return type:: bool

replace_data(key, new_data, add_if_missing=False)#

Replace data by a new value.

Parameters:

key (str) – The key of the additional data.
new_data (Any) – The new additional data.
add_if_missing (bool) – If True, the additional data will be added if the key is not existing (default: False).

Returns:

True if the additional data is replaced successfully, False otherwise.

Return type:

bool

set_image_data(image)#

Set the image data.

Parameters:: image (Union[sitk.Image, itk.Image]) – The image to be set.
Return type:: None
Returns:: None

set_modality(modality)#

Set the Modality.

Parameters:: modality (Modality) – The Modality.
Return type:: None
Returns:: None

set_transform_tape(tape)#

Set the TransformTape.

Parameters:: tape (TransformTape) – The TransformTape.
Return type:: None
Returns:: None

class ImageProperties(image, **kwargs)[source]#

Bases: object

A class to store image properties. This class is predominantly used in combination with a TransformTapeV2 to keep track of the image properties before or after a transformation has been applied.

Parameters:

image (Union[sitk.Image, itk.Image]) – The image to extract the properties from.
**kwargs – Additional information.

get_entry(key)[source]#

Get entry from additional information.

Parameters:: key (str) – Key of the entry.
Returns:: The value of the entry or None if the key is not existing.
Return type:: Any

set_entry(key, value)[source]#

Set an entry as additional information.

Parameters:

key (str) – Key of the entry.
value (Any) – Value of the entry.

Return type:

None

Returns:

None

property origin: Tuple[float, ...]#

Get the origin of the image.

Returns:: The origin of the image.
Return type:: Tuple[float, …]

property spacing: Tuple[float, ...]#

Get the spacing of the image.

Returns:: The spacing of the image.
Return type:: Tuple[float, …]

property direction: Tuple[float, ...]#

Get the direction of the image.

Returns:: The direction of the image.
Return type:: Tuple[float, …]

property size: Tuple[int, ...]#

Get the size of the image.

Returns:: The size of the image.
Return type:: Tuple[int, …]

has_equal_origin_direction(other)[source]#

Check if the origin and direction of another ImageProperties instance is equal.

Parameters:: other (ImageProperties) – The other image properties.
Returns:: True if the origin and direction are equal, False otherwise.
Return type:: bool