DVH Analyse

A collection of useful functions for Dose-Volume Histograms (DVH) analysis.

fredtools.getDVHMask(img: Image, imgMask: Image, dosePrescribed: Annotated[float, Ge(ge=0)], displayInfo: bool = False) → DVH

Calculate DVH for the mask.

The function calculates a dose-volume histogram (DVH) for voxels inside a mask with the same field of reference (FoR). The mask must be defined as a SimpleITK image object describing a binary or floating mask. The routine exploits and returns DVH class to hold the DVH. The class has been adapted from dicompyler-core DVH module (https://dicompyler-core.readthedocs.io/en/latest/index.html)

Parameters:

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

  • imgMask (SimpleITK Image) – Object of a SimpleITK 3D image describing the binary or floating mask.

  • dosePrescribed (scalar) – Target prescription dose.

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

Returns:

An instance of a DVH class holding the DVH.

Return type:

DVH

Raises:

  • TypeError – If img or imgMask is not an instance of a 3D SimpleITK image, if imgMask does not describe a binary or floating mask, or if img and imgMask do not have the same FoR.

  • ValueError – If the image contains NaN values inside the mask.

See also

resampleImg

resample image.

mapStructToImg

map structure to image (refer for more information about mapping algorithms).

getDVHStruct

calculate DVH for structure.

fredtools.getDVHStruct(img: Image, RSfileName: str, structName: str, dosePrescribed: float, resampleImg: float | Iterable[float] | None = None, displayInfo: bool = False) → DVH

Calculate DVH for the structure.

The function calculates a dose-volume histogram (DVH) for voxels inside a structure named structName and is defined in the structure dicom file. The image can be resampled before mapping to increase the resolution. The routine exploits and returns DVH class to hold the DVH. The class has been adapted from dicompyler-core DVH module (https://dicompyler-core.readthedocs.io/en/latest/index.html)

Parameters:

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

  • RSfileName (path) – String path to RS dicom file.

  • structName (string) – Name of the structure to calculate the DVH in.

  • dosePrescribed (scalar) – Target prescription dose.

  • resampleImg (scalar, array_like or None, optional) – Define if and how to resample the image while mapping the structure. Can be a scalar, then the same number will be used for each axis, 3-element iterable defining the voxel size for each axis, or None meaning no interpolation. (def. None)

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

Returns:

An instance of a DVH class holding the DVH.

Return type:

DVH

Raises:

  • TypeError – If img is not an instance of a 3D SimpleITK image, or if RSfileName is not a proper dicom file describing structures.

  • AttributeError – If the structure structName cannot be found in the RSfileName dicom file.

  • ValueError – If the shape of resampleImg does not match the image dimension and is not a scalar.

See also

resampleImg

resample image.

mapStructToImg

map structure to image (refer for more information about mapping algorithms).

getDVHMask

calculate DVH for a mask.

Notes

The structure mapping is performed in ‘floating’ mode meaning that the fractional structure occupancy is assigned to each voxel of the image. Use getDVHMask to use a specially prepared mask for the DVH calculation.