Image Analyse

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

fredtools.getExtent(img, displayInfo=False)

Get the extent of an image.

The function gets the extent of an image defined as a SimpleITK image object. Extent means the coordinates of most side voxels’ borders 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 extent values in form ((xmin,xmax),(ymin,ymax),…)

Return type:

tuple

See also

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

fredtools.getSize(img, displayInfo=False)

Get the size of an image.

The function gets the size of an image defined as a SimpleITK image object in each direction. The size is defined as the absolute difference of the image extent. 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 sizes in each direction in form (xSize,ySize,…)

Return type:

tuple

See also

getExtent: get the extent of an image.

fredtools.getImageCenter(img, displayInfo=False)

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

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, displayInfo=False)

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].

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

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, displayInfo=False)

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

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, displayInfo=False)

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

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, displayInfo=False)

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

See also

getVoxelEdges: get voxel edges.

fredtools.getVoxelEdges(img, displayInfo=False)

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

See also

getVoxelCentres: get voxel centres.

fredtools.getVoxelPhysicalPoints(img, insideMask=False, displayInfo=False)

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 shuld 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 munpy array of size NxD where N is the number of voxel and D is the axis.

Return type:

NxD numpy.array

See also

getVoxelCentres: get voxel centres.

fredtools.displayImageInfo(img)

Display some image information.

The function displays information about an image given as a SimpleITK image object.

Parameters:: img (SimpleITK Image) – An object of a SimpleITK image.

Examples

Reading image from file and displaying the image information.

>>> imgCT=fredtools.readMHD('CT.mhd')
>>> fredtools.displayImageInfo(imgCT)
### displayImageInfo ###
# 3D image describing 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 ]
# y-spatial voxel centre [mm] =  [  -354.287109,  -353.603516, ...,   -71.962891,   -71.279297 ]
# z-spatial voxel centre [mm] =  [  -785.600000,  -784.400000, ...,  -526.400000,  -525.200000 ]
# x-spatial extent [mm] =  [  -175.000000 ,   174.316406 ] =>   349.316406
# y-spatial extent [mm] =  [  -354.628906 ,   -70.937500 ] =>   283.691406
# z-spatial extent [mm] =  [  -786.200000 ,  -524.600000 ] =>   261.600000
# volume = 25924053.15 mm³  =>  25.92 l
# voxel volume = 0.56 mm³  =>  0.56 ul
# data type:  16-bit signed integer
# range: from  -1024  to  3071
# sum = -33870013138 , mean = -732.6387321958799 ( 468.4351806663016 )
# non-zero (dose=0)  voxels  = 46188861 (99.91%) => 25.90 l
# non-air (HU>-1000) voxels  = 15065800 (32.59%) => 8.45 l
# Additional metadata:
########################

The same can be displayed when reading the image.

>>> imgCT=fredtools.readMHD('CT.mhd', displayInfo=True)
### readMHD ###
# 3D image describing 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 ]
# y-spatial voxel centre [mm] =  [  -354.287109,  -353.603516, ...,   -71.962891,   -71.279297 ]
# z-spatial voxel centre [mm] =  [  -785.600000,  -784.400000, ...,  -526.400000,  -525.200000 ]
# x-spatial extent [mm] =  [  -175.000000 ,   174.316406 ] =>   349.316406
# y-spatial extent [mm] =  [  -354.628906 ,   -70.937500 ] =>   283.691406
# z-spatial extent [mm] =  [  -786.200000 ,  -524.600000 ] =>   261.600000
# volume = 25924053.15 mm³  =>  25.92 l
# voxel volume = 0.56 mm³  =>  0.56 ul
# data type:  16-bit signed integer
# range: from  -1024  to  3071
# sum = -33870013138 , mean = -732.6387321958799 ( 468.4351806663016 )
# non-zero (dose=0)  voxels  = 46188861 (99.91%) => 25.90 l
# non-air (HU>-1000) voxels  = 15065800 (32.59%) => 8.45 l
# Additional metadata:
###############

fredtools.getExtMpl(img)

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

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.

fredtools.isPointInside(img, point, displayInfo=False)

Check if a point is inside the image extent.

The function checks if a point or list of points are inside the extent of an image defined as a SimpleITK image object The dimension of points must match the dimension of the img. 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 (NxD array_like) – 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 or a tuple of boolean values.

Return type:

single or tuple

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 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, displayInfo=False)

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.

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

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.compareImgFoR(img1, img2, decimals=3, displayInfo=False)

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.
decimals (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 field of reference.

Return type:

bool

See also

SimpleITK.StatisticsImageFilter: more about possible statistics.

fredtools.pos(img)

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

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)

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

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)

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

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, indices)

Transform indices to physical points.

The function transforms an iterable of indices into a tuple of physical points based on the field 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

See also

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

fredtools.transformContinuousIndexToPhysicalPoint(img, indices)

Transform indices to physical points.

The function transforms an iterable of indices into a tuple of physical points based on the field 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

See also

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

fredtools.transformPhysicalPointToIndex(img, points)

Transform physical points to indices.

The function transforms an iterable of points into a tuple of indices based on the field 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

See also

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

fredtools.transformPhysicalPointToContinuousIndex(img, points)

Transform physical points to continuous indices.

The function transforms an iterable of points into a tuple of continuous indices based on the field 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

See also

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