opentps.core.data.images package

Module contents

class CTImage(imageArray=None, name='CT image', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID='', frameOfReferenceUID='', sliceLocation=None, sopInstanceUIDs=None, patient=None)

Bases: Image3D

Class for CT images. Inherits from Image3D and all its attributes.

Variables:

• name (str (default: "CT image")) – Name of the image.

• frameOfReferenceUID (str) – UID of the frame of reference.

• sliceLocation (float) – Location of the slice.

• sopInstanceUIDs (list of str) – List of SOP instance UIDs.

copy()

Returns a copy of the CTImage object.

Return type:

CTImage

classmethod fromImage3D(image, **kwargs)

Creates a CTImage from an Image3D object.

Parameters:

• image (Image3D) – Image3D object to be converted.

• kwargs (dict (optional)) – Additional keyword arguments. - imageArray : numpy.ndarray

  Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

Returns:

The created CTImage object.

Return type:

CTImage

class Deformation3D(imageArray=None, name='Deformation', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID='', velocity=None, displacement=None, patient=None)

Bases: Image3D

Class for 3D deformations (velocity and/or displacement fields). Inherits from Image3D and its attributes.

Variables:

• velocity (VectorField3D) – Velocity field of the deformation.

• displacement (VectorField3D) – Displacement field of the deformation.

Raises:

Error if both velocity and displacement are initialized but have different origin or spacing. –

copy()

Create a copy of the deformation.

Returns:

Copy of the deformation.

Return type:

Deformation3D

deformImage(image, fillValue='closest', outputType=<class 'numpy.float32'>, tryGPU=True)

Deform 3D image using linear interpolation.

Parameters:

• image – image to be deformed.

• fillValue (scalar) – interpolation value for locations outside the input voxel grid.

Return type:

Deformed image.

dumpableCopy()

Create a copy of the deformation that can be dumped to disk.

Returns:

Copy of the deformation that can be dumped to disk.

Return type:

Deformation3D

property gridSize

Compute the voxel grid size of the deformation.

Returns:

Grid size of velocity field and/or displacement field.

Return type:

np.array

initFromDisplacementField(field)

Initialize deformation using the input field as displacement.

Parameters:

field (numpy array) – field used as displacement in the deformation.

initFromImage(image)

Initialize deformation using the voxel grid of the input image.

Parameters:

image (numpy array) – image from which the voxel grid is copied.

initFromVelocityField(field)

Initialize deformation using the input field as velocity.

Parameters:

field (numpy array) – field used as velocity in the deformation.

resample(spacing, gridSize, origin, fillValue=0, outputType=None, tryGPU=True)

Resample deformation (velocity and/or displacement field) according to new voxel grid using linear interpolation.

Parameters:

• gridSize (list) – size of the resampled deformation voxel grid.

• origin (list) – origin of the resampled deformation voxel grid.

• spacing (list) – spacing of the resampled deformation voxel grid.

• fillValue (scalar) – interpolation value for locations outside the input voxel grid.

• outputType (numpy data type) – type of the output.

setDisplacement(displacement)

Set displacement field of the deformation. Velocity field is set to None.

Parameters:

displacement (VectorField3D) – Displacement field of the deformation.

setDisplacementArray(displacementArray)

Set the image array of the displacement field of the deformation. Velocity field is set to None.

Parameters:

displacementArray (numpy array) – Image array of the displacement field of the deformation.

setDisplacementArrayXYZ(displacementArrayX, displacementArrayY, displacementArrayZ)

Set the image array of the displacement field of the deformation. Velocity field is set to None.

Parameters:

• displacementArrayX (numpy array) – Image array of the displacement field of the deformation in x direction.

• displacementArrayY (numpy array) – Image array of the displacement field of the deformation in y direction.

• displacementArrayZ (numpy array) – Image array of the displacement field of the deformation in z direction.

setVelocity(velocity)

Set velocity field of the deformation. Displacement field is set to None.

Parameters:

velocity (VectorField3D) – Velocity field of the deformation.

setVelocityArray(velocityArray)

Set the image array of the velocity field of the deformation. Displacement field is set to None.

Parameters:

velocityArray (numpy array) – Image array of the velocity field of the deformation.

setVelocityArrayXYZ(velocityArrayX, velocityArrayY, velocityArrayZ)

Set the image array of the velocity field of the deformation. Displacement field is set to None.

Parameters:

• velocityArrayX (numpy array) – Image array of the velocity field of the deformation in x direction.

• velocityArrayY (numpy array) – Image array of the velocity field of the deformation in y direction.

• velocityArrayZ (numpy array) – Image array of the velocity field of the deformation in z direction.

class DoseImage(imageArray=None, name='Dose image', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID=None, sopInstanceUID=None, referencePlan: RTPlan | None = None, referenceCT: CTImage | None = None, patient=None)

Bases: Image3D

Class for dose images. Inherits from Image3D and its attributes.

Variables:

• referenceCT (CTImage) – Reference CT image for the dose image.

• referencePlan (RTPlan) – Reference RTPlan for the dose image.

• sopInstanceUID (str) – SOP instance UID of the dose image.

copy()

Returns a copy of the DoseImage object.

Returns:

Copy of the DoseImage object.

Return type:

DoseImage

classmethod createEmptyDoseWithSameMetaData(image: Image3D, **kwargs)

Creates an empty DoseImage with the same meta data as the given Image3D object.

Parameters:

• image (Image3D) – Image3D object to be converted.

• kwargs (dict (optional)) –

  Additional keyword arguments.

  • imageArraynumpy.ndarray

    Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

dumpableCopy()

Returns a dumpable copy of the DoseImage object.

Returns:

Dumpable copy of the DoseImage object.

Return type:

DoseImage

exportDicom(outputFile, planUID=[])

classmethod fromImage3D(image: Image3D, **kwargs)

Creates a DoseImage from an Image3D object.

Parameters:

• image (Image3D) – Image3D object to be converted.

• kwargs (dict (optional)) – Additional keyword arguments. - imageArray : numpy.ndarray

  Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

Returns:

DoseImage object.

Return type:

DoseImage

class Image2D(imageArray=None, name='2D Image', origin=(0, 0, 0), spacing=(1, 1), angles=(0, 0, 0), seriesInstanceUID=None, patient=None)

Bases: PatientData

Class for 2D images. Inherits from PatientData.

Variables:

• name (str (default: "2D Image")) – Name of the image.

• imageArray (numpy array) – 2D numpy array containing the image data.

• origin (numpy array (default: (0,0,0))) – 1x3 numpy array containing the origin of the image.

• spacing (numpy array (default: (1,1))) – 1x2 numpy array containing the spacing of the image in mm.

• angles (numpy array (default: (0,0,0))) – 1x3 numpy array containing the angles of the image.

• gridSize (numpy array) – 1x2 numpy array containing the size of the image in voxels.

• gridSizeInWorldUnit (numpy array) – 1x2 numpy array containing the size of the image in mm.

property angles: ndarray

classmethod fromImage2D(image, **kwargs)

Creates a new Image2D from an existing Image2D.

Parameters:

• image (Image2D) – Image2D to copy.

• kwargs (dict (optional)) –

  Keyword arguments to be passed to the constructor.

  • imageArraynumpy.ndarray

    Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

getDataAtPosition(position: Sequence)

Returns the data from the image array at a given position in the image.

Parameters:

position (tuple of float) – Position in the image in mm.

Returns:

dataNumpy – Data from the image array at the given position.

Return type:

numpy.ndarray

getMeshGridPositions() → ndarray

Returns the meshgrid of the image in mm.

Returns:

meshgrid – Meshgrid of the image in mm.

Return type:

numpy.ndarray

getPositionFromVoxelIndex(index: Sequence[int]) → Sequence[float]

Returns the position in the image of a given voxel index.

Parameters:

index (tuple of int) – Voxel index in the image.

Returns:

position – Position in the image in mm.

Return type:

tuple of float

Raises:

ValueError – If the voxel index is outside of the image.

getVoxelIndexFromPosition(position: Sequence[float]) → Sequence[float]

Returns the voxel index of a given position in the image.

Parameters:

position (tuple of float) – Position in the image in mm.

Returns:

voxelIndex – Voxel index of the given position.

Return type:

tuple of int

Raises:

ValueError – If the voxel index is outside of the image.

property gridSize: ndarray

property gridSizeInWorldUnit: ndarray

hasSameGrid(otherImage) → bool

Check whether the voxel grid is the same as the voxel grid of another image given as input.

Parameters:

otherImage (numpy array) – image to which the voxel grid is compared.

Returns:

True if grids are identical, False otherwise.

Return type:

bool

property imageArray: ndarray

property origin: ndarray

property spacing: ndarray

class Image3D(imageArray=None, name='3D Image', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID=None, patient=None)

Bases: PatientData

Class for 3D images. Inherits from PatientData and its attributes.

Variables:

• name (str (default: '3D Image')) – Name of the image.

• imageArray (numpy array) – 3D array containing the image data.

• origin (numpy array (default: (0, 0, 0))) – 3D array containing the origin of the image.

• spacing (numpy array (default: (1, 1, 1))) – 3D array containing the spacing of the image.

• angles (numpy array (default: (0, 0, 0))) – 3D array containing the angles of the image.

• gridSize (numpy array) – 3D array containing the grid size of the image.

• gridSizeInWorldUnit (numpy array) – 3D array containing the grid size of the image in world units.

• numberOfVoxels (int) – Number of voxels in the image.

property angles: ndarray

copy()

Create a copy of the image.

Returns:

Copy of the image.

Return type:

Image3D

classmethod fromImage3D(image, **kwargs)

Create a new Image3D from an existing Image3D.

Parameters:

• image (Image3D) – Image to copy.

• kwargs (dict (optional)) –

  Additional keyword arguments to pass to the constructor.

  • imageArraynumpy.ndarray

    Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

Returns:

New Image3D object.

Return type:

Image3D

getDataAtPosition(position: Sequence)

Get the data value of the image array at a given position in the image.

Parameters:

position (Sequence) – Position in the image.

Returns:

Data value of the image array at the given position.

Return type:

np.ndarray

getMeshGridPositions() → ndarray

Get the mesh grid positions of the image in mm.

Returns:

Mesh grid positions of the image in mm.

Return type:

np.ndarray

getPositionFromVoxelIndex(index: Sequence[int]) → Sequence[float]

Get the position in the image from a given voxel index.

Parameters:

index (Sequence[int]) – Voxel index in the image.

Returns:

Position in the image from the given voxel index.

Return type:

Sequence[float]

getVoxelIndexFromPosition(position: Sequence[float]) → Sequence[float]

Get the voxel index of the image array at a given position in the image.

Parameters:

position (Sequence[float]) – Position in the image.

Returns:

Voxel index of the image array at the given position.

Return type:

Sequence[float]

property gridSize: ndarray

Compute the voxel grid size of the image.

Returns:

Image grid size.

Return type:

np.array

property gridSizeInWorldUnit: ndarray

hasSameGrid(otherImage) → bool

Check whether the voxel grid is the same as the voxel grid of another image given as input.

Parameters:

otherImage (numpy array) – image to which the voxel grid is compared.

Returns:

True if grids are identical, False otherwise.

Return type:

bool

property imageArray: ndarray

max()

Get the maximum value of the image array.

Returns:

Maximum value of the image array.

Return type:

float

min()

Get the minimum value of the image array.

Returns:

Minimum value of the image array.

Return type:

float

property numberOfVoxels

property origin: ndarray

resample(spacing, gridSize, origin, fillValue=0, outputType=None, tryGPU=True)

Resample image according to new voxel grid using linear interpolation.

Parameters:

• gridSize (list) – size of the resampled image voxel grid.

• origin (list) – origin of the resampled image voxel grid.

• spacing (list) – spacing of the resampled image voxel grid.

• fillValue (scalar) – interpolation value for locations outside the input voxel grid.

• outputType (numpy data type) – type of the output.

resampleOn(otherImage, fillValue=0, outputType=None, tryGPU=True)

Resample image using the voxel grid of another image given as input, using linear interpolation.

Parameters:

• otherImage (numpy array) – image from which the voxel grid is copied.

• fillValue (scalar) – interpolation value for locations outside the input voxel grid.

• outputType (numpy data type) – type of the output.

property spacing: ndarray

update()

class LETImage(imageArray=None, name='3D Image', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID=None, patient=None)

Bases: Image3D

Class for Linear Energy Transfer (LET) images. Inherits from Image3D.

class MRImage(imageArray=None, name='MR image', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID='', frameOfReferenceUID='', sliceLocation=None, sopInstanceUIDs=None, patient=None)

Bases: Image3D

Class for MR images. Inherits from Image3D.

Variables:

• name (str (default: "MR image")) – Name of the image.

• frameOfReferenceUID (str) – UID of the frame of reference.

• sliceLocation (float) – Location of the slice.

• sopInstanceUIDs (list of str) – List of SOP instance UIDs.

• bodyPartExamined (str) – Body part examined.

• scanningSequence (str) – Scanning sequence.

• sequenceVariant (str) – Sequence variant.

• scanOptions (str) – Scan options.

• mrArcquisitionType (str) – MR acquisition type.

• repetitionTime (float (default: 0.0)) – Repetition time.

• echoTime (float (default: 0.0)) – Echo time.

• nAverages (float (default: 0.0)) – Number of averages.

• imagingFrequency (str) – Imaging frequency.

• echoNumbers (int (default: 1)) – Number of echoes.

• magneticFieldStrength (float (default: 3.0)) – Magnetic field strength.

• spacingBetweenSlices (float (default: 2.0)) – Spacing between slices.

• nPhaseSteps (int (default: 1)) – Number of phase steps.

• echoTrainLength (int (default: 1)) – Echo train length.

• flipAngle (float (default: 90.0)) – Flip angle in degrees.

• sar (float (default: 0.0)) – Specific absorption rate.

copy()

Creates a copy of the MRImage.

Returns:

Copy of the MRImage.

Return type:

MRImage

classmethod fromImage3D(image, **kwargs)

Creates a MRImage from an Image3D.

Parameters:

• image (Image3D) – Image3D to be converted to MRImage.

• kwargs (dict (optional)) –

  Additional keyword arguments.

  • imageArraynumpy.ndarray

    Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

Returns:

MRImage created from the Image3D.

Return type:

MRImage

class Projection(imageArray=None, name='2D Image', origin=(0, 0, 0), spacing=(1, 1), seriesInstanceUID=None, projectionAngle=0, rotationAxis='Z', sourceImage=None, patient=None)

Bases: Image2D

Base class for all projections of 2D images. i.e. DRR, XRayImage. Inherits from Image2D.

Variables:

• projectionAngle (float) – Angle of projection in degrees.

• rotationAxis (str) – Axis of rotation. ‘X’, ‘Y’, or ‘Z’.

• sourceImage (Image2D) – Image from which the projection was created.

class ROIMask(imageArray=None, name='ROI contour', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), displayColor=(0, 0, 0), patient=None, seriesInstanceUID=None)

Bases: Image3D

Class for ROI mask. Inherits from Image3D. It is a binary image with 1 inside the ROI and 0 outside.

Variables:

• name (str (default: 'ROI contour')) – Name of the ROI mask

• color (str (default: '0,0,0')) – RGB of the color of the ROI mask, format : ‘r,g,b’ like ‘0,0,0’ for black for instance

• centerOfMass (numpy.ndarray) – Center of mass of the ROI mask

property centerOfMass: ndarray

closeMask(radius=1.0, struct=None, tryGPU=True)

Close the ROI mask.

Parameters:

• radius (float (default: 1.0)) – Radius of the closing in mm.

• struct (numpy.ndarray (default: None)) – Structuring element for the closing.

• tryGPU (bool (default: False)) – If True, the closing is performed on the GPU if possible.

property color

copy()

Create a copy of the ROI mask.

Returns:

Copy of the ROI mask.

Return type:

ROIMask

createMaskRings(nRings, radius)

Create a ring ROI to obtain nice gradient dose around the ROI

Parameters:

• nRings (int) – Number of rings to be created

• radius (float) – thickness of each ring in mm

dilateMask(radius=1.0, struct=None, tryGPU=False)

Dilate the ROI mask.

Parameters:

• radius (float (default: 1.0)) – Radius of the dilation in mm.

• struct (numpy.ndarray (default: None)) – Structuring element for the dilation.

• tryGPU (bool (default: False)) – If True, the dilation is performed on the GPU if possible.

erodeMask(radius=1.0, struct=None, tryGPU=True)

Erode the ROI mask.

Parameters:

• radius (float (default: 1.0)) – Radius of the erosion in mm.

• struct (numpy.ndarray (default: None)) – Structuring element for the erosion.

• tryGPU (bool (default: False)) – If True, the erosion is performed on the GPU if possible.

classmethod fromImage3D(image, **kwargs)

Create a ROIContour from an Image3D. The imageArray of the ROIContour is the same as the imageArray of the Image3D.

Parameters:

• image (Image3D) – Image3D from which the ROIContour is created

• kwargs (dict (optional)) –

  Additional arguments to be passed to the constructor of the ROIContour

  • imageArraynumpy.ndarray

    Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

  • namestr

    Name of the image.

getBinaryContourMask(internalBorder=False)

Get the binary contour mask of the ROI mask.

Parameters:

internalBorder (bool (default: False)) – If True the ROI is eroded before getting the contour mask, otherwise it is dilated.

Returns:

Binary contour mask of the ROI mask.

Return type:

ROIMask

getROIContour()

Get the ROI contour.

Returns:

ROI contour of the ROI mask.

Return type:

ROIContour

getVolume(inVoxels=False)

Get the volume of the ROI mask.

Parameters:

inVoxels (bool (default: False)) – If True, the volume is returned in voxels, otherwise in mm^3.

openMask(radius=1.0, struct=None, tryGPU=True)

Open the ROI mask.

Parameters:

• radius (float (default: 1.0)) – Radius of the opening in mm.

• struct (numpy.ndarray (default: None)) – Structuring element for the opening.

• tryGPU (bool (default: False)) – If True, the opening is performed on the GPU if possible.

class RSPImage(imageArray=None, name='RSP image', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID=None, frameOfReferenceUID=None, sliceLocation=[], sopInstanceUIDs=[], patient=None)

Bases: Image3D

Class for Relative Stopping Power images. Inherits from Image3D.

Variables:

• name (str (default: "RSP image")) – Name of the image.

• frameOfReferenceUID (str) – Frame of reference UID.

• sliceLocation (list of float) – Slice location.

• sopInstanceUIDs (list of str) – SOP instance UID.

computeCumulativeWEPL(beam: PlanIonBeam | None = None, sad=inf, roi=None) → Image3D

Compute the cumulative water equivalent path length (WEPL) of the image.

Parameters:

• beam (PlanIonBeam (optional)) – Ion beam object.

• roi (ROICountour or ROIMask (optional))

Returns:

Image3D object.

Return type:

Image3D

classmethod fromCT(ct: CTImage, calibration: AbstractCTCalibration, energy: float = 100.0)

Create a new RSPImage from a CTImage object by converting the Housefield units to relative stopping power according to the calibration.

Parameters:

• ct (CTImage) – CTImage object.

• calibration (AbstractCTCalibration) – CT calibration object.

• energy (float (default: 100.)) – Energy of the beam in MeV.

Returns:

RSPImage object.

Return type:

RSPImage

classmethod fromImage3D(image, **kwargs)

Create a new RSPImage from an Image3D object.

Parameters:

• image (Image3D) – Image3D object.

• kwargs (dict (optional)) –

  Additional keyword arguments.

  • imageArraynumpy.ndarray

    Image array of the image.

  • origintuple of float

    Origin of the image.

  • spacingtuple of float

    Spacing of the image.

  • anglestuple of float

    Angles of the image.

  • seriesInstanceUIDstr

    Series instance UID of the image.

  • patientPatient

    Patient object of the image.

get_SPR_at_position(position)

Get the stopping power ratio at a given position. If the position is outside the image, the SPR is set to 0.001.

Parameters:

position (tuple of float) – Position in mm.

Returns:

Stopping power ratio.

Return type:

float

class VectorField3D(imageArray=None, name='Vector Field', origin=(0, 0, 0), spacing=(1, 1, 1), angles=(0, 0, 0), seriesInstanceUID=None, patient=None)

Bases: Image3D

Class for 3D vector fields. Inherits from Image3D.

Variables:

• name (str (default: "Vector Field")) – Name of the vector field.

• gridSize (tuple of int) – Size of the voxel grid.

computeFieldNorm()

Compute the voxel-wise norm of the vector field.

Returns:

Voxel-wise norm of the vector field.

Return type:

numpy array

copy()

Create a copy of the vector field.

Returns:

Copy of the vector field.

Return type:

VectorField3D

exponentiateField(outputType=<class 'numpy.float32'>, tryGPU=True)

Exponentiate the vector field (e.g. to convert velocity in to displacement).

Parameters:

• outputType (numpy type (default: np.float32)) – output data type.

• tryGPU (bool (default: True)) – if True, try to use GPU for warping.

Returns:

Displacement field.

Return type:

numpy array

property gridSize

Compute the voxel grid size of the deformation.

Returns:

Grid size of velocity field and/or displacement field.

Return type:

np.array

initFromImage(image)

Initialize vector field using the voxel grid of the input image.

Parameters:

image (Image3D) – image from which the voxel grid is copied.

warp(data, fillValue='closest', outputType=<class 'numpy.float32'>, tryGPU=True)

Warp 3D data using linear interpolation.

Parameters:

• data (numpy array) – data to be warped.

• fillValue (scalar or ‘closest’ (default: ‘closest’)) – interpolation value for locations outside the input voxel grid. If ‘closest’, the closest voxel value is used.

• outputType (numpy type (default: np.float32)) – output data type.

• tryGPU (bool (default: True)) – if True, try to use GPU for warping.

Returns:

Warped data.

Return type:

numpy array