Optimisation Tools

A collection of functions useful for treatment plan optimisation.

fredtools.ft_optimisation.convertCTtoWER(img, HU, WER, displayInfo=False)

Convert CT map to WER map.

The function converts a 3D Computed Tomography (CT) map with Houndsfield Unit (HU) values, defined as a SimpleITK image object, to an image with Water-Equivalent Ratio values (WER). The two parameters, HU and WER, define the HU to WER conversion, whereas the missing HU values are interpolated linearly.

Parameters:

img (SimpleITK Image) – An object of a SimpleITK image with HU values.
HU (array_like) – An iterable with HU values. It must be of the same size as WER.
WER (array_like) – An iterable with WER values. It must be of the same size as HU.
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An instance of a SimpleITK image object with WER values.

Return type:

SimpleITK Image

See also

calcWETfromWER: calculate WET image from WER image for point-like source.

fredtools.ft_optimisation.calcWETfromWER(imgWER, SAD, imgMask=None, CPUNo='auto', displayInfo=False)

Calculate WET image from WER image for point-like source.

The function calculates Water-Equivalent Thickness (WET) for each voxel of an image defined as a SimpleITK image object containing Water-Equivalent Ratio values (WER), inside a mask, defined as a SimpleITK image object describing a binary mask. The WET values are calculated starting from a virtual source, located at [X,Y]=[0,0] position and with Z position defined with a two-element SAD, describing the source point in X and Y. Particularly, the WET is calculated for a virtual source, where rays are deflected in X and Y directions in different distances from the isocenter.

Parameters:

imgWER (SimpleITK Image) – An object of a SimpleITK image with WER values.
SAD (2-element array_like) – Z coordinates of the virtual point source for deflection in X and Y directions, respectively.
imgMask (SimpleITK Image or None, optional) – An object of a SimpleITK image describing a binary mask, or None, then all voxel positions will be calculated (def. None)
CPUNo ({'auto', 'none'}, scalar or None, optional) – Define whether multiprocessing should be used and how many cores should be exploited (def. ‘auto’). Can be None, then no multiprocessing will be used, a string ‘auto’, then the number of cores will be determined by os.cpu_count(), or a scalar defining the number of CPU cores to be used (def. ‘auto’).
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An instance of a SimpleITK image object with WET values.

Return type:

SimpleITK Image

See also

convertCTtoWER: convert CT map to WER map.

fredtools.ft_optimisation.generateIsoLayers(minRange, maxRange, beamParams)

Calculate iso-WET layers and corresponding energies.

The function calculates iso Water-Equivalent Thickness (WET) layers between minimum and maximum range based on predefined parameters of the beam.

Parameters:

minRange (scalar) – Minimum range to calculate layers.
maxRange (scalar) – Maximum range to calculate layers.
beamParams (pandas.DataFrame) – Parameters of the beam, i.e. dependance of the beam range and width with nominal energies. Must include at least columns: “nomEnergy”, “rangeProx” and “rangeDist”.

Returns:

An instance of pandas.DataFrame object describing the iso WET layers.

Return type:

pandas.DataFrame

fredtools.ft_optimisation.calcContours(imgMask, level=0.5, displayInfo=False)

Calculate contours from 2D binary mask.

The function calculates list of contours from a 2D image defined as a SimpleITK image object describing a binary or floating mask, along a level value.

Parameters:

imgMask (SimpleITK Image) – Object of a SimpleITK 2D image describing a binary mask.
level (scalar, optional) – Value along which to find contours in the image. (def. 0.5)
displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

A list of polygons defined as instances of shapely.polygon objects.

Return type:

list of shapely.polygon

Notes

The imgMask must be a 2D image describing a floating or binary mask. If an image is, for instance, a 3D image describing a slice, it must be squeezed to 2D first. It can be done, for instance by slicing the image, e.g. imgMask[:,:,0] for image where the third axis is single sized.

fredtools.ft_optimisation.convertRayTargetToIsoPlane(rayTarget, SAD)

Calculate beam positon in the isocentre plane.

The function calculates the beam positions in the isocentre plane, based on the target position and distance to the virtual point (SAD).

Parameters:

rayTarget (3xN array_like) – Target positions in the format of 3xN iterable.
SAD (2-element array_like) – Z coordinates of the virtual point source for deflection in X and Y directions, respectively.

Returns:

A 3xN array with the ray position in the isocentre plane.

Return type:

3xN numpy array

Notes

The function assumes that the beam goes along +Z direction.

fredtools.ft_optimisation.optimiseBeamPositions(contourPolygon, spotDistance, algorithm='regular', **kwargs)

Calculate and optimize the beam positions in a contour.

The function calculates optimized beam positions in a contour defined as an instance of the shapely.Polygon object. Various optimization algorithms are implemented. Refer to ‘See Also’ section to read more about each algorithm.

Parameters:

contourPolygon (shapely Polygon) – Object of the shapely.Polygon.
spotDistance (scalar) – The nominal spot distance is to be used to optimize the beam positions. Depending on the algorithm, the distance between neighboring spots does not have to be equal to this parameter. Therefore it describes only the nominal distance.
algorithm ({'regular', 'hexagonal', 'concentric', 'delaunay'}, optional) – Algorithm to be used to optimize the beam positions. Only ‘regular’ and ‘hexagonal’ are implemented so far. (def. ‘regular’)
**kwargs (keyword args, optional) – Additional parameters are passed to the given optimization algorithm. Refer to the given algorithm routine for more description. (def. None)

Returns:

Numpy array of size (Nx2) describing the position of N beams, where the first column is X and the second Y directions.

Return type:

numpy array (Nx2)

See also

optimiseBeamPositionsRegular: Optimise beam positions in a regular grid.
optimiseBeamPositionsHexagonal: Optimise beam positions in a hexagonal grid.

fredtools.ft_optimisation.optimiseBeamPositionsRegular(contourPolygon, spotDistance)

Calculate the beam positions using regular grid algorithm.

The function calculates beam positions in a contour defined as an instance of the shapely.Polygon object using regular grid algorithm. The algorithm is optimized to place the central beam position at the polygon centroid.

Parameters:

contourPolygon (shapely Polygon) – Object of the shapely.Polygon.
spotDistance (scalar) – The spot distance to be used to calculate regular grid beam positions.

Returns:

Numpy array of size (Nx2) describing the position of N beams, where the first column is X and the second Y directions.

Return type:

numpy array (Nx2)

See also

optimiseBeamPositions: Optimise beam positions using various algorithms.

Notes

The regular grid algorithm distributes the beams with the same spacing in X and Y directions. The grid size is calculated to fit the given contour polygon and is moved so that the central beam is at the polygon centroid. All the beam positions which are not inside the polygon are removed.

fredtools.ft_optimisation.optimiseBeamPositionsHexagonal(contourPolygon, spotDistance, direction='X')

Calculate the beam positions using the hexagonal grid algorithm.

The function calculates beam positions in a contour defined as an instance of the shapely.Polygon object using hexagonal grid algorithm. The algorithm is optimized to place the central beam position at the polygon centroid.

Parameters:

contourPolygon (shapely Polygon) – Object of the shapely.Polygon.
spotDistance (scalar) – The spot distance is to be used to calculate regular grid beam positions.
direction ({'X', 'Y'}, optional) – The direction along which the beams should be shifted to create a hexagonal grid. This parameter can be used to align the hexagonal direction to the faster direction of the pencil beam scanning. (def. ‘X’)

Returns:

Numpy array of size (Nx2) describing the position of N beams, where the first column is X and the second Y directions.

Return type:

numpy array (Nx2)

See also

optimiseBeamPositions: Optimise beam positions using various algorithms.

Notes

The hexagonal grid algorithm distributes the beams with the same spacing in X (or in Y) and every second row (or column) of the beam positions is shifted by half of the spotDistance. The grid size is calculated to fit the given contour polygon and is moved so that the central beam is at the polygon centroid. All the beam positions which are not inside the polygon are removed.

The user can choose in which direction, X or Y, the hexagonal grid should be aligned. This might be important when optimizing the beam positions for a given machine where the scanning is faster in one direction than in the other.