Image Analyse

A collection of useful functions for image analysis. The image must be an instance of a SimpleITK image.

fredtools.getExtent(img: Image, displayInfo: bool = False) → tuple[tuple[float, float], ...]

Get the extent of an image.

The function calculates the extent of an image, which is defined as the coordinates of the most side voxels’ borders in each direction. The extent is assumed to be in millimeters.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – If True, a summary of the function results will be displayed. (def. False)

Returns:

A tuple of extent values in the form ((xmin, xmax), (ymin, ymax), …)

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getExtMpl: Get the extent of a SimpleITK image object describing a slice in matplotlib format.

fredtools.getSize(img: Image, displayInfo: bool = False) → tuple[float, ...]

Get the size of an image.

This function calculates the size of an image in each direction. The size is defined as the absolute difference of the image extent. It is assumed that the coordinate system is in millimeters.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – If True, displays a summary of the function results. (def. False)

Returns:

A tuple of sizes in each direction in the form (xSize, ySize, …)

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getExtent: Get the extent of an image.

fredtools.getImageCenter(img: Image, displayInfo: bool = False) → tuple[float, ...]

Get the centre of an image.

The function calculates the centre of an image defined as a SimpleITK image object in each direction. It is assumed that the coordinate system is in [mm].

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A Tuple of image centre coordinates in form (xCenter,yCenter,…)

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getMassCenter: get the centre of mass of an image.
getMaxPosition: get the position of an image maximum.
getMinPosition: get the position of an image minimum.

fredtools.getMassCenter(img: Image, displayInfo: bool = False) → tuple[float, ...]

Get the centre of mass of an image.

The function calculates the centre of mass of an image defined as a SimpleITK image object in each direction. It is assumed that the coordinate system is in [mm]. Any NaN values are replaced with zeros.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A tuple of image centre of mass coordinates in form (xMassCenter,yMassCenter,…)

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getImageCenter: get the centre of an image.
getMaxPosition: get the position of an image maximum.
getMinPosition: get the position of an image minimum.

fredtools.getMaxPosition(img: Image, displayInfo: bool = False) → tuple[float, ...]

Get the maximum position of an image.

The function calculates the position of the maximum voxel of an image defined as a SimpleITK image object. It is assumed that the coordinate system is in [mm].

Parameters:

img (SimpleITK Image) – The object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A Tuple of image maximum voxel coordinates in form (xPosition,yPosition,…).

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getImageCenter: get the centre of an image.
getMassCenter: get the centre of mass of an image.
getMinPosition: get the position of an image minimum.

fredtools.getMinPosition(img: Image, displayInfo: bool = False) → tuple[float, ...]

Get the minimum position of an image.

The function calculates the position of the minimum voxel of an image defined as a SimpleITK image object. It is assumed that the coordinate system is in [mm].

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A Tuple of image minimum voxel coordinates in form (xPosition,yPosition,…).

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getImageCenter: get the centre of an image.
getMassCenter: get the centre of mass of an image.
getMaxPosition: get the position of an image maximum.

fredtools.getVoxelCentres(img: Image, displayInfo: bool = False) → tuple[tuple[float, ...], ...]

Get voxel centres.

The function gets voxels’ centres in each direction of an image defined as a SimpleITK image object. It is assumed that the coordinate system is in [mm].

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A tuple of tuples with voxels’ centres in each direction in form ([x0,x1,…],[y0,y1,…],…)

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getVoxelEdges: get voxel edges.

fredtools.getVoxelEdges(img: Image, displayInfo: bool = False) → tuple[tuple[float, ...], ...]

Get voxel edges.

The function gets voxels’ edges in each direction of an image defined as a SimpleITK image object. It is assumed that the coordinate system is in [mm].

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A tuple of tuples with voxels’ edges in each direction in form ([x0,x1,…],[y0,y1,…],…)

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getVoxelCentres: get voxel centres.

fredtools.getVoxelPhysicalPoints(img: Image, insideMask: bool = False, displayInfo: bool = False) → Iterable[Iterable[int | float | number]]

Get physical positions of voxels.

The function gets voxels’ physical positions of an image defined as a SimpleITK image object. If the image is a binary mask, then the voxel positions only inside the mask can be requested with insideMask parameter, otherwise all voxels’ positions will be returned.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
insideMask (bool, optional) – Determine if only the voxels’ positions inside the mask should be returned. The img must describe a binary mask. (def. False)
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A numpy array of size NxD where N is the number of voxel and D is the axis.

Return type:

NxD numpy.array

Raises:

TypeError – If img is not an instance of a SimpleITK image, or if insideMask is True and img does not describe a binary mask.

See also

getVoxelCentres: get voxel centres.

fredtools.displayImageInfo(img: Image, metadata: bool = True) → None

Display some image information.

The function displays information about an image given as a SimpleITK image object. The information is logged with the module logger at the INFO level.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
metadata (bool, optional) – Display additional metadata. (def. True)

Raises:

TypeError – If img is not an instance of a SimpleITK image.

Notes

The function sets the level of the module logger to INFO as a side effect, so that the image information is always displayed, regardless of the logging level configured before the call.

Examples

Reading image from file and displaying the image information.

>>> imgCT=fredtools.readMHD('CT.mhd')
>>> fredtools.displayImageInfo(imgCT)
displayImageInfo: Image info:
    3D image describing a volume (3D)
    dims (xyz)      = [511 415 218]
    voxel size [mm] = [0.68359375 0.68359375 1.2       ]
    origin [mm]     = [-174.65820312 -354.28710938 -785.6       ]
    x-spatial voxel centre [mm] = [  -174.658203,  -173.974609, ...,   173.291016,   173.974609 ]
    ...
    data type: 16-bit signed integer
    range: from -1024 to 3071
    ...

The same can be displayed when reading the image with displayInfo=True, for instance:

>>> imgCT=fredtools.readMHD('CT.mhd', displayInfo=True)

fredtools.getExtMpl(img: Image) → tuple[float, float, float, float]

Get the extent of a slice in a format consistent with imshow of matplotlib module.

The function gets the extent of an image defined as a SimpleITK image object describing a slice. Extent means the coordinates of the most side pixels’ borders in each direction and are returned in format (left, right, bottom, top), which is consistent with the extent optional parameter of imshow of matplotlib.pyplot module.

Parameters:: img (SimpleITK Image) – An object of a SimpleITK image describing a slice.
Returns:: A tuple of extent values in the form (left, right, bottom, top).
Return type:: tuple
Raises:: TypeError – If img is not an instance of a SimpleITK image describing a slice.

See also

matplotlib.pyplot.imshow: displaying 2D images.
getExtent: get the extent of the image in each direction.
getSize: get the size of the image in each direction.
arr: get squeezed array from image.

Examples

Assuming that the img is describing a slice (e.g. the shape is [100,1,300,1]), the line:

>>> matplotlib.pyplot.imshow(fredtools.arr(img), extent=fredtools.getExtMpl(img))

will display a 2D image of the shape 100x300 px in real coordinates.

Check if a point or a list of points is inside the extent of an image.

This function checks if a point or a list of points are inside the extent of an image defined as a SimpleITK image object. The points at the border of the image (equal to the image extent) are considered to be inside the image.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
point (Iterable[float] | Iterable[Iterable[float]]) – An iterable (numpy array, list of lists, etc) of N points. Every point must be of the image dimension size.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A single boolean value if a single point is provided, or a tuple of boolean values if a list of points is provided.

Return type:

bool | tuple[bool, …]

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getExtent: Get the extent of the image in each direction.

Examples

Let’s assume that the img is a 3D image with extent:

>>> fredtools.getExtent(img)
((-175.0, 174.3),
 (-354.6, -70.9),
 (-786.2, -524.6))

It means that the img expands from -175.0 to 174.3, from -354.6 to -70.9, and from -786.2 to -524.6 in the X, Y, and Z directions, respectively. Let’s check if the point [0,0,0] and a list of points [[0,0,0],[0,-100,-600],[-175,-354.6,-786.2]] are inside the image extent:

>>> fredtools.isPointInside(img, [0,0,0])
False
>>> fredtools.isPointInside(img, [[0,0,0],[0,-100,-600],[-175,-354.6,-786.2]])
(False, True, True)

fredtools.getStatistics(img: Image, displayInfo: bool = False) → StatisticsImageFilter

Get statistics of image

The function gets basic statistics of an image defined as a SimpleITK image object. It is a wrapper for SimpleITK.StatisticsImageFilter routine executed on the image. If the image is a vector image, it is silently converted to a scalar image being the sum of the vector components (with fredtools.sumVectorImg) and a warning is logged; the statistics are then calculated for the sum of vectors.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

SimpleITK image filter with image statistics.

Return type:

SimpleITK filter

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

SimpleITK.StatisticsImageFilter: more about possible statistics.

Examples

It is assumed that the image is a 3D dose distribution. Some statistics of the image, like the mean, standard deviation or sum can be calculated.

>>> stat=fredtools.getStatistics(img)
>>> stat.GetMean()
-732.6387321958799
>>> stat.GetSigma()
468.4351857326367
>>> stat.GetSum()
-33870013138.0

fredtools.getIntegral(img: Image, displayInfo: bool = False) → int | float | number

Get integral of image

The function calculates the integral of an image defined as a SimpleITK image object. The integral is calculated as the sum of all voxel values multiplied by the voxel volume, where the voxel volume is the product of the image spacing (assumed to be in mm), hence the integral is expressed in the voxel value units times mm³. If the image is a vector image, it is converted to a scalar image being the sum of the vector components (with fredtools.sumVectorImg) and a warning is logged; the integral is then calculated for the sum of vectors.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A float value with the integral of the image.

Return type:

float

Raises:

TypeError – If img is not an instance of a SimpleITK image.

See also

getStatistics: get basic statistics of the image.

fredtools.compareImg(img1: Image, img2: Image, decimal: int = 3, displayInfo: bool = False) → bool

Compare two images pixel by pixel.

The function gets two images defined as instances of a SimpleITK image object and compares them pixel by pixel. The comparison is done with a given decimal tolerance.

Parameters:

img1 (SimpleITK Image) – An object of a SimpleITK image.
img2 (SimpleITK Image) – An object of a SimpleITK image.
decimal (int, optional) – The number of decimal places to compare the images. (def. 3)
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A true/false value describing if the images are the same in the sense of the pixel values.

Return type:

bool

Raises:

TypeError – If img1 or img2 is not an instance of a SimpleITK image.

fredtools.compareImgFoR(img1: Image, img2: Image, decimal: int = 3, displayInfo: bool = False) → bool

Compare two images frame of reference

The function gets two images defined as instances of a SimpleITK image object and compares the frame of reference, i.e. dimension, size, origin, spacing and direction.

Parameters:

img1 (SimpleITK Image) – An object of a SimpleITK image.
img2 (SimpleITK Image) – An object of a SimpleITK image.
decimal (int, optional) – Use rounding to a given number of decimals when comparing origin and spacing. (def. 3)
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A true/false value describing if the images are the same in the sense of the frame of reference.

Return type:

bool

Raises:

TypeError – If img1 or img2 is not an instance of a SimpleITK image.

See also

compareImg: compare two images voxel by voxel.

fredtools.pos(img: Image) → tuple[float, ...] | tuple[tuple[float, ...], ...]

Get voxels’ centres for axes of the size different than one.

The function calculates the voxels’ centres of an image defined as a SimpleITK image object in each direction, only for those axes for which the size is more than one. The function is useful for plotting profiles.

Parameters:: img (SimpleITK Image) – An object of a SimpleITK image.
Returns:: A tuple with voxels’ centres for the image describing a profile (the size in only one direction is greater than one) or list of tuples for all directions for which the size is greater than one.
Return type:: tuple or list of tuples
Raises:: TypeError – If img is not an instance of a SimpleITK image.

See also

getVoxelCentres: get voxels’ centres of the image in each direction.
vec: get a vector with values for the image describing a profile.

Examples

Let’s assume that the img is a 3D image describing a profile, so is of size [1,200,1]. It is possible to get the voxels’ centres only in the Y direction:

>>> fredtools.pos(img)
(-174.658203125,
 -173.974609375,
 ...
)

This can be used for plotting profiles. The line:

>>> matplotlib.pyplot.plot(fredtools.pos(img), fredtools.vec(img))

will plot the profile in the Y direction of the image.

fredtools.arr(img: Image) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

Get squeezed array from image.

The function gets a squeezed array (with no unitary dimensions) from an image defined as a SimpleITK image object. This can be used for plotting

Parameters:: img (SimpleITK Image) – An object of a SimpleITK image.
Returns:: A numpy array with no unitary dimensions.
Return type:: numpy array
Raises:: TypeError – If img is not an instance of a SimpleITK image.

See also

pos: get voxels’ centres for axes of size different than one.
getExtMpl: Get the extent of a slice in a format consistent with imshow of matplotlib module.
vec: get a vector with values for the image describing a profile.

Examples

Assuming that the img is describing a slice (e.g. the shape is [100,1,300,1]), the line:

>>> matplotlib.pyplot.imshow(fredtools.arr(img), extent=fredtools.getExtMpl(img))

will display a 2D image of the shape 100x300 px in real coordinates.

fredtools.vec(img: Image) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

Get 1D array from image describing a profile.

The function gets a squeezed (with no unitary dimensions), 1D array from an image defined as a SimpleITK image object describing a profile. This can be used for plotting

Parameters:: img (SimpleITK Image) – An object of a SimpleITK image describing a profile.
Returns:: A 1D numpy array.
Return type:: numpy array
Raises:: TypeError – If img is not an instance of a SimpleITK image describing a profile.

See also

pos: get voxels’ centres for axes of the size different than one.
arr: Get squeezed array from image.

Examples

Assuming that the img is describing a profile (e.g. the shape is [1,1,300,1]), the line:

>>> matplotlib.pyplot.plot(fredtools.pos(img), fredtools.vec(img))

will plot the profile in the Z direction of the image.

fredtools.transformIndexToPhysicalPoint(img: Image, indices: Iterable[Iterable[int | float | number]]) → Tuple[Tuple[float, ...], ...]

Transform indices to physical points.

The function transforms an iterable of indices into a tuple of physical points based on the frame of reference (FoR) of an image defined as an instance of a SimpleITK image object. The function is a wrapper for TransformIndexToPhysicalPoint SimpleITK function, but it works for multiple points. The shape of indices must be NxD, where N is the number of points to be converted, and D is the dimension of the image.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
indices (NxD array_like) – An iterable (numpy array, list of lists, etc) of N points. Every index must be of the image dimension size and of any integer type (int64, uint16, etc.).

Returns:

A NxD tuple of tuples with physical points.

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.
AttributeError – If indices is not of an integer type or is not of the NxD shape, where D is the image dimension.

See also

transformContinuousIndexToPhysicalPoint: transform continuous indices to physical points.
transformPhysicalPointToIndex: transform physical points to indices.
transformPhysicalPointToContinuousIndex: transform physical points to continuous indices.

fredtools.transformContinuousIndexToPhysicalPoint(img: Image, indices: Iterable[Iterable[int | float | number]]) → Tuple[Tuple[float, ...], ...]

Transform continuous indices to physical points.

The function transforms an iterable of indices into a tuple of physical points based on the frame of reference (FoR) of an image defined as an instance of a SimpleITK image object. The function is a wrapper for TransformContinuousIndexToPhysicalPoint SimpleITK function, but it works for multiple points. The shape of indices must be NxD, where N is the number of points to be converted, and D is the dimension of the image.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
indices (NxD array_like) – An iterable (numpy array, list of lists, etc) of N points. Every index must be of the image dimension size and can be of float or integer type.

Returns:

A NxD tuple of tuples with physical points.

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.
AttributeError – If indices is not of the NxD shape, where D is the image dimension.

See also

transformIndexToPhysicalPoint: transform indices to physical points.
transformPhysicalPointToIndex: transform physical points to indices.
transformPhysicalPointToContinuousIndex: transform physical points to continuous indices.

fredtools.transformPhysicalPointToIndex(img: Image, points: Iterable[Iterable[int | float | number]]) → Tuple[Tuple[int, ...], ...]

Transform physical points to indices.

The function transforms an iterable of points into a tuple of indices based on the frame of reference (FoR) of an image defined as an instance of a SimpleITK image object. The function is a wrapper for TransformPhysicalPointToIndex SimpleITK function, but it works for multiple points. The shape of points must be NxD, where N is the number of points to be converted, and D is the dimension of the image.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
points (NxD array_like) – An iterable (numpy array, list of lists, etc) of N points. Every point must be of the image dimension size.

Returns:

A NxD tuple of tuples with indices.

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.
AttributeError – If points is not of the NxD shape, where D is the image dimension.

See also

transformIndexToPhysicalPoint: transform indices to physical points.
transformContinuousIndexToPhysicalPoint: transform continuous indices to physical points.
transformPhysicalPointToContinuousIndex: transform physical points to continuous indices.

fredtools.transformPhysicalPointToContinuousIndex(img: Image, points: Iterable[Iterable[int | float | number]]) → Tuple[Tuple[float, ...], ...]

Transform physical points to continuous indices.

The function transforms an iterable of points into a tuple of continuous indices based on the frame of reference (FoR) of an image defined as an instance of a SimpleITK image object. The function is a wrapper for TransformPhysicalPointToContinuousIndex SimpleITK function, but it works for multiple points. The shape of points must be NxD, where N is the number of points to be converted, and D is the dimension of the image.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image.
points (NxD array_like) – An iterable (numpy array, list of lists, etc) of N points. Every point must be of the image dimension size.

Returns:

A NxD tuple of tuples with continuous indices.

Return type:

tuple

Raises:

TypeError – If img is not an instance of a SimpleITK image.
AttributeError – If points is not of the NxD shape, where D is the image dimension.

See also

transformIndexToPhysicalPoint: transform indices to physical points.
transformContinuousIndexToPhysicalPoint: transform continuous indices to physical points.
transformPhysicalPointToIndex: transform physical points to indices.