Getting Subimage

A collection of useful functions for getting subimages of lower dimension, e.g. a slice or a profile from a 3D image. The image must be an instance of a SimpleITK image and the same image, with the same dimension is returned. The subimages are calculated user defined interpolation. The interpolation of ‘nearest’, ‘linear’ and ‘spline’ with order from 0 to 5 are available.

fredtools.getSlice(img: Image, point: Iterable[int | float | number], plane: str = 'XY', displayInfo: bool = False, **kwargs) → Image

Get 2D slice from image.

The function calculates a 2D slice image through a specified point in a specified plane from an image defined as a SimpleITK image object. The slice is returned as an instance of a SimpleITK image object of the same dimension but describing a slice (the dimension of only two axes are different than one). The slice through a specified point is calculated with a specified interpolation type.

Parameters:

  • img (SimpleITK Image) – Object of a SimpleITK image.

  • point (array_like) – Point to generate the 2D slice through. It should have the length of the image dimension. A warning will be generated if the point is not inside the image extent and displayInfo is True.

  • plane (str, optional) – Plane to generate the 2D slice given as a string. The string should have the form of two letters from [XYZT] set with +/- signs (if no sign is provided, then + is assumed). For instance, it can be: XY,`ZY`,`-YX`, Y-T, etc. If the minus sign is found, then the image is flipped in the following direction. The order of the axis is important and the output will be generated in this way to be consistent with the axes displayed with matplotlib.pyplot.imshow. For instance, plane Z-X will display Z-axis on X-axis in imshow and Y-axis of imshow will be a reversed X-axis of the image. (def. ‘XY’)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

  • **kwargs (optional) –

    Additional keyword arguments determining the interpolation method:

    • interpolation : {‘linear’, ‘nearest’, ‘spline’}, determines the interpolation method (def. ‘linear’).

    • splineOrder : int, order of spline interpolation, must be in range 0-5 (def. 3).

Returns:

An instance of a SimpleITK image object describing a slice.

Return type:

SimpleITK Image

Raises:

  • TypeError – If img is not an instance of a 3D or 4D SimpleITK image object.

  • AttributeError – If the dimension of point does not match the img dimension, or if the plane parameter cannot be recognised.

See also

matplotlib.pyplot.imshow

displaying 2D images.

getExtent

get extent of the image in each direction.

arr

get squeezed array from image.

Examples

The example below shows how to generate and display a 2D slice along ‘ZX’ (with reversed X) axes from a 3D image through a specified point of the 3D image.

>>> img3D = fredtools.readMHD('imageCT.mhd', displayInfo = True)
### readMHD ###
# dims (xyz) =  [511 415 218]
# pixel 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 mm3  =>  25.92 litre
# 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 litre
# non-air (HU>-1000) voxels  = 15065800 (32.59%) => 8.45 litre
###############
>>> sl2D = fredtools.getSlice(img3D, point=[0,-212.42,-654.8], plane='Z-X', displayInfo=True)
### getSlice ###
# Point:  [   0.   -212.42 -654.8 ]
# Plane: 'Z-X'
# dims (xyz) =  [218   1 511]
# pixel size [mm] =  [1.2        0.68359375 0.68359375]
# origin [mm]     =  [-174.65820312 -212.42       -525.2       ]
# x-spatial voxel centre [mm] =  [  -525.200000,  -526.400000, ...,  -784.400000,  -785.600000 ]
# y-spatial voxel centre [mm] =  [  -212.420000 ]
# z-spatial voxel centre [mm] =  [  -174.658203,  -173.974609, ...,   173.291016,   173.974609 ]
# x-spatial extent [mm] =  [  -524.600000 ,  -786.200000 ] =>   261.600000
# y-spatial extent [mm] =  [  -212.761797 ,  -212.078203 ] =>     0.683594
# z-spatial extent [mm] =  [  -175.000000 ,   174.316406 ] =>   349.316406
# volume = 62467.60 mm3  =>  0.06 litre
# data type:  16-bit signed integer
# range: from  -1024  to  1803
# sum = -53645122 , mean = -481.56270310059426 ( 559.2583473799535 )
# non-zero (dose=0)  voxels  = 111051 (99.69%) => 0.06 litre
# non-air (HU>-1000) voxels  = 57831 (51.91%) => 0.03 litre
################
>>> matplotlib.pyplot.imshow(fredtools.arr(sl2D), extent=fredtools.getExtMpl(sl2D))
>>> matplotlib.pyplot.xlabel('Z [mm]')
>>> matplotlib.pyplot.ylabel('X [mm] (reversed)')
fredtools.getProfile(img: Image, point: Iterable[int | float | number], axis: str = 'X', displayInfo: bool = False, **kwargs) → Image

Get 1D profile from image along an axis.

The function calculates a 1D profile image through a specified point in a specified axis from an image defined as a SimpleITK image object. The profile is returned as an instance of a SimpleITK image object of the same dimension but describing a profile (the dimension of only one axes is different than one). The profile through a specified point is calculated with a specified interpolation type.

Parameters:

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

  • point (array_like) – Point to generate the 1D profile through. It should have the length of the image dimension. A warning will be generated if the point is not inside the image extent and displayInfo is True.

  • axis (str, optional) – Axis to generate the 1D profile given as a string. The string should have the form of one letter from [XYZT] set with +/- signs (if no sign is provided, then + is assumed). For instance, it can be: X,`Y`,`-Z`, etc. If the minus sign is found, then the image is flipped in the following direction. (def. ‘X’)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

  • **kwargs (optional) –

    Additional keyword arguments determining the interpolation method:

    • interpolation : {‘linear’, ‘nearest’, ‘spline’}, determines the interpolation method (def. ‘linear’).

    • splineOrder : int, order of spline interpolation, must be in range 0-5 (def. 3).

Returns:

An object of a SimpleITK image describing a profile.

Return type:

SimpleITK Image

Raises:

  • TypeError – If img is not an instance of a SimpleITK image object, or if it already describes a profile.

  • AttributeError – If the dimension of point does not match the img dimension, or if the axis parameter cannot be recognised.

See also

matplotlib.pyplot.plot

displaying profiles.

pos

get voxels’ centres for axes of size different than one.

vec

get a vector with values for the img describing a profile.

Examples

The example below shows how to generate and display a 1D profile along ‘Y’ (reversed) axis from a 3D image through a specified point of the 3D image.

>>> img3D = fredtools.readMHD('imageCT.mhd', displayInfo = True)
### readMHD ###
# dims (xyz) =  [511 415 218]
# pixel 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 mm3  =>  25.92 litre
# 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 litre
# non-air (HU>-1000) voxels  = 15065800 (32.59%) => 8.45 litre
###############
>>> pr1D = fredtools.getProfile(img3D, point=[0,-212.42,-654.8], axis='-Y', displayInfo=True)
### getProfile ###
# Point:  [   0.   -212.42 -654.8 ]
# Axis: '-Y'
# dims (xyz) =  [  1 415   1]
# pixel size [mm] =  [0.68359375 0.68359375 1.2       ]
# origin [mm]     =  [   0.          -71.27929688 -654.8       ]
# x-spatial voxel centre [mm] =  [     0.000000 ]
# y-spatial voxel centre [mm] =  [   -71.279297,   -71.962891, ...,  -353.603516,  -354.287109 ]
# z-spatial voxel centre [mm] =  [  -654.800000 ]
# x-spatial extent [mm] =  [    -0.341797 ,     0.341797 ] =>     0.683594
# y-spatial extent [mm] =  [   -70.937500 ,  -354.628906 ] =>   283.691406
# z-spatial extent [mm] =  [  -655.400000 ,  -654.200000 ] =>     1.200000
# volume = 232.72 mm3  =>  0.00 litre
# data type:  16-bit signed integer
# range: from  -1023  to  1336
# sum = -131818 , mean = -317.63373493975905 ( 487.9811134201045 )
# non-zero (dose=0)  voxels  = 414 (99.76%) => 0.00 litre
# non-air (HU>-1000) voxels  = 354 (85.30%) => 0.00 litre
##################
>>> matplotlib.pyplot.plot(fredtools.pos(pr1D), fredtools.vec(pr1D))
>>> matplotlib.pyplot.xlabel('Y [mm] (reversed)')
>>> matplotlib.pyplot.ylabel('Values')
fredtools.getPoint(img: Image, point: Iterable[int | float | number], displayInfo: bool = False, **kwargs)

Get point value from image.

The function calculates a point value in a specified point from an image defined as a SimpleITK image object. The point is returned as an instance of a SimpleITK image object of the same dimension but describing a point (the dimension of all axes is equal to one). The point value in a specified point is calculated with a specified interpolation type.

Parameters:

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

  • point (array_like) – Point to generate the value. It should have the length of the image dimension. A warning will be generated if the point is not inside the image extent and displayInfo is True.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

  • **kwargs (optional) –

    Additional keyword arguments determining the interpolation method:

    • interpolation : {‘linear’, ‘nearest’, ‘spline’}, determines the interpolation method (def. ‘linear’).

    • splineOrder : int, order of spline interpolation, must be in range 0-5 (def. 3).

Returns:

An instance of a SimpleITK image object describing a point.

Return type:

SimpleITK Image

Raises:

  • TypeError – If img is not an instance of a SimpleITK image object, or if it already describes a point.

  • AttributeError – If the dimension of point does not match the img dimension.

Examples

The example below shows how to generate a point value for various interpolation types from a 3D image in a specified point of the 3D image.

>>> img3D = fredtools.readMHD('imageCT.mhd', displayInfo = True)
### readMHD ###
# dims (xyz) =  [511 415 218]
# pixel 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 mm3  =>  25.92 litre
# 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 litre
# non-air (HU>-1000) voxels  = 15065800 (32.59%) => 8.45 litre
###############
>>> pointValue = fredtools.getPoint(img3D, point=[0,-212.42,-654.8], displayInfo=True)
### getPoint ###
# Point:  [   0.   -212.42 -654.8 ]
# Value:  45
# dims (xyz) =  [1 1 1]
# pixel size [mm] =  [0.68359375 0.68359375 1.2       ]
# origin [mm]     =  [   0.   -212.42 -654.8 ]
# x-spatial voxel centre [mm] =  [     0.000000 ]
# y-spatial voxel centre [mm] =  [  -212.420000 ]
# z-spatial voxel centre [mm] =  [  -654.800000 ]
# x-spatial extent [mm] =  [    -0.341797 ,     0.341797 ] =>     0.683594
# y-spatial extent [mm] =  [  -212.761797 ,  -212.078203 ] =>     0.683594
# z-spatial extent [mm] =  [  -655.400000 ,  -654.200000 ] =>     1.200000
# volume = 0.56 mm3  =>  0.00 litre
# data type:  16-bit signed integer
# range: from  45  to  45
# sum = 45 , mean = 45.0 ( 0.0 )
# non-zero (dose=0)  voxels  = 1 (100.00%) => 0.00 litre
# non-air (HU>-1000) voxels  = 1 (100.00%) => 0.00 litre
################
>>> ft.arr(pointValue)
array(45, dtype=int16)
>>> fredtools.arr(fredtools.getPoint(img3D, point=[0,-212.42,-654.8], interpolation='nearest'))
array(37, dtype=int16)
>>> fredtools.arr(fredtools.getPoint(img3D, point=[0,-212.42,-654.8], interpolation='linear'))
array(45, dtype=int16)
>>> fredtools.arr(fredtools.getPoint(img3D, point=[0,-212.42,-654.8], interpolation='spline', splineOrder=5))
array(43, dtype=int16)
fredtools.getInteg(img: Image, axis: str = 'X', displayInfo: bool = False) → Image

Get 1D integral profile from an image.

The function calculates a 1D integral profile image along the specified axis from an image defined as a SimpleITK image object. The integral profile is returned as an instance of a SimpleITK image object of the same dimension but describing a profile (the dimension of only one axes is different than one). The integral means the sum of the voxel values multiplied by the voxel size along the accumulated directions. The routine is useful to calculate integral depth dose (IDD) distributions.

Parameters:

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

  • axis (str, optional) – Axis to generate the 1D integral profile given as a string. The string should have the form of one letter from [XYZT] set with +/- signs (if no sign is provided, then + is assumed). For instance, it can be: X, Y, -Z, etc. If the minus sign is found, then the image is flipped in the following direction. (def. “X”)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Instance of a SimpleITK image object describing a profile.

Return type:

SimpleITK Image

Raises:

  • TypeError – If img is not an instance of a SimpleITK image object, or if it already describes a profile.

  • AttributeError – If the axis parameter cannot be recognised.

See also

matplotlib.pyplot.plot

displaying profiles.

pos

get voxels’ centres for axes of size different than one.

vec

get a vector with values for the img describing a profile.

Examples

The example below shows how to generate and display a 1D integral profile along Y axis from a 3D image.

>>> img3D = fredtools.readMHD('imageCT.mhd', displayInfo = True)
### readMHD ###
# dims (xyz) =  [511 415 218]
# pixel 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 mm3  =>  25.92 litre
# 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 litre
# non-air (HU>-1000) voxels  = 15065800 (32.59%) => 8.45 litre
###############
>>> in1D = fredtools.getInteg(img3D, axis='Y', displayInfo=True)
### getInteg ###
# Axis: 'Y'
# dims (xyz) =  [  1 415   1]
# pixel size [mm] =  [349.31640625   0.68359375 261.6       ]
# origin [mm]     =  [ 1.46800622e+09 -3.54287109e+02 -7.85000000e+02]
# x-spatial voxel centre [mm] =  [ 1468006225.000000 ]
# y-spatial voxel centre [mm] =  [  -354.287109,  -353.603516, ...,   -71.962891,   -71.279297 ]
# z-spatial voxel centre [mm] =  [  -785.000000 ]
# x-spatial extent [mm] =  [ 1468006050.341797 , 1468006399.658203 ] =>   349.316406
# y-spatial extent [mm] =  [  -354.628906 ,   -70.937500 ] =>   283.691406
# z-spatial extent [mm] =  [  -915.800000 ,  -654.200000 ] =>   261.600000
# volume = 25924053.15 mm3  =>  25.92 litre
# data type:  64-bit float
# range: from  -91384297.26562846  to  -43597831.757814154
# sum = -27783995152.26668 , mean = -66949385.90907634 ( 17496118.62771702 )
# non-zero (dose=0)  voxels  = 415 (100.00%) => 25.92 litre
# non-air (HU>-1000) voxels  = 0 (0.00%) => 0.00 litre
################
>>> matplotlib.pyplot.plot(fredtools.pos(in1D), fredtools.vec(in1D))
>>> matplotlib.pyplot.xlabel('Y [mm]')
>>> matplotlib.pyplot.ylabel('Values per unitary volume')
fredtools.getCumSum(img: Image, axis: str = 'X', displayInfo: bool = False) → Image

Get cumulative sum image.

The function calculates a cumulative sum image along the specified axis from an image defined as a SimpleITK image object. The cumulative sum image is returned as an instance of a SimpleITK image object of the same dimension.

Parameters:

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

  • axis (str, optional) – An axis is used to generate the cumulative sum given as a string. The string should have the form of one letter from [XYZT] set. (def. “X”)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Instance of a SimpleITK image object describing the cumulative sum image (same size as img).

Return type:

SimpleITK Image

Raises:

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

  • AttributeError – If the axis parameter cannot be recognised.

See also

getInteg

get 1D integral profile from an image.

fredtools.getProfilePoints(img: Image, pointA: Iterable[int | float | number], pointB: Iterable[int | float | number], spacing: int | float | number = 1, origin: Literal['start', 'center', 'image'] | Iterable[int | float | number] = 'center', displayInfo: bool = False, **kwargs) → Tuple[tuple, tuple]

Get 1D profile between points.

The function gets a profile of an image defined as a SimpleITK image object, between two points, pointA and pointB, with a given step size (spacing). The values at the given points are interpolated from the image.

Parameters:

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

  • pointA (array_like) – The starting point of the profile.

  • pointB (array_like) – The ending point of the profile.

  • spacing (scalar, optional) – The spacing between profile points. (def. 1)

  • origin ({'start', 'center', 'image'} or array_like, optional) –

    The origin for the calculation of the profile positions. The following options are available:

    • ’start’: positions calculated starting from pointA.

    • ’center’: positions calculated with respect to the line centre.

    • ’image’: positions calculated with respect to the image 0 point.

    • array_like: positions calculated with respect to the given point.

    (def. ‘center’)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

  • **kwargs (optional) –

    Additional keyword arguments determining the interpolation method:

    • interpolation : {‘linear’, ‘nearest’, ‘spline’}, determines the interpolation method (def. ‘linear’).

    • splineOrder : int, order of spline interpolation, must be in range 0-5 (def. 3).

Returns:

A tuple of the positions along the profile line and a tuple of the interpolated values at the profile points. The points outside the image extent get numpy.nan values.

Return type:

tuple of two tuples

Raises:

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

  • ValueError – If the dimension of pointA, pointB or the origin point does not match the img dimension, or if the origin parameter cannot be recognised.