Processing

compute_suv_map

MEDimage.processing.compute_suv_map.compute_suv_map(raw_pet: ndarray, dicom_h: Dataset) → ndarray[source]

Computes the suv_map of a raw input PET volume. It is assumed that the calibration factor was applied beforehand to the PET volume. E.g: raw_pet = raw_pet*RescaleSlope + RescaleIntercept.

Parameters:

  • raw_pet (ndarray) – 3D array representing the PET volume in raw format.

  • dicom_h (pydicom.dataset.FileDataset) – DICOM header of one of the corresponding slice of raw_pet.

Returns:

raw_pet converted to SUVs (standard uptake values).

Return type:

ndarray

discretisation

MEDimage.processing.discretisation.discretize(vol_re: ndarray, discr_type: str, n_q: float | None = None, user_set_min_val: float | None = None, ivh=False) → Tuple[ndarray, float][source]

Quantisizes the image intensities inside the ROI.

Note

For ‘FBS’ type, it is assumed that re-segmentation with proper range was already performed

Parameters:

  • vol_re (ndarray) – 3D array of the image volume that will be studied with NaN value for the excluded voxels (voxels outside the ROI mask).

  • discr_type (str) – Discretisaion approach/type must be: “FBS”, “FBN”, “FBSequal” or “FBNequal”.

  • n_q (float) – Number of bins for FBS algorithm and bin width for FBN algorithm.

  • user_set_min_val (float) – Minimum of range re-segmentation for FBS discretisation, for FBN discretisation, this value has no importance as an argument and will not be used.

  • ivh (bool) – Must be set to True for IVH (Intensity-Volume histogram) features.

Returns:

2-element tuple containing

  • ndarray: Same input image volume but with discretised intensities.

  • float: bin width.

MEDimage.processing.discretisation.equalization(vol_re: ndarray) → ndarray[source]

Performs histogram equalisation of the ROI imaging intensities.

Note

This is a pure “what is contained within the roi” equalization. this is not influenced by the user_set_min_val() used for FBS discretisation.

Parameters:

vol_re (ndarray) – 3D array of the image volume that will be studied with NaN value for the excluded voxels (voxels outside the ROI mask).

Returns:

Same input image volume but with redistributed intensities.

Return type:

ndarray

interpolation

MEDimage.processing.interpolation.interp_volume(vol_obj_s: image_volume_obj, medscan: MEDscan | None = None, vox_dim: List | None = None, interp_met: str | None = None, round_val: float | None = None, image_type: str | None = None, roi_obj_s: image_volume_obj | None = None, box_string: str | None = None, texture: bool = False) → image_volume_obj[source]

3D voxel interpolation on the input volume.

Parameters:

  • vol_obj_s (image_volume_obj) – Imaging that will be interpolated.

  • medscan (object) – The MEDscan class object.

  • vox_dim (array) – Array of the voxel dimension. The following format is used [Xin,Yin,Zslice], where Xin and Yin are the X (left to right) and Y (bottom to top) IN-PLANE resolutions, and Zslice is the slice spacing, no matter the orientation of the volume (i.e. axial , sagittal, coronal).

  • interp_met (str) – {nearest, linear, spline, cubic} optional, Interpolation method

  • round_val (float) – Rounding value. Must be between 0 and 1 for ROI interpolation and to a power of 10 for Image interpolation.

  • image_type (str) – ‘image’ for imaging data interpolation and ‘roi’ for ROI mask data interpolation.

  • roi_obj_s (image_volume_obj) – Mask data, will be used to compute a new specific box and the new imref3d object for the imaging data.

  • box_string (str) –

    Specifies the size if the box containing the ROI

    • ’full’: full imaging data as output.

    • ’box’: computes the smallest bounding box.

    • Ex: ‘box10’: 10 voxels in all three dimensions are added to the smallest bounding box. The number after ‘box’ defines the number of voxels to add.

    • Ex: ‘2box’: Computes the smallest box and outputs double its size. The number before ‘box’ defines the multiplication in size.

  • texture (bool) – If True, the texture voxel spacing of MEDscan will be used for interpolation.

Returns:

3D array of 1’s and 0’s defining the ROI mask.

Return type:

ndarray

resegmentation

MEDimage.processing.resegmentation.outlier_re_seg(vol: ndarray, roi: ndarray, outliers='') → ndarray[source]

Removes voxels with outlier intensities from the given mask using the Collewet method.

Parameters:

  • vol (ndarray) – Imaging data.

  • roi (ndarray) – ROI mask with values of 0 and 1.

  • outliers (str, optional) – Algo used to define outliers. (For now this methods only implements “Collewet” method).

Returns:

An array with values of 0 and 1.

Return type:

ndarray

Raises:

ValueError – If outliers is not “Collewet” or None.

Todo

  • Delete outliers argument or implements others outlining methods.

MEDimage.processing.resegmentation.range_re_seg(vol: ndarray, roi: ndarray, im_range=None) → ndarray[source]

Removes voxels from the intensity mask that fall outside the given range (intensities outside the range are set to 0).

Parameters:

  • vol (ndarray) – Imaging data.

  • roi (ndarray) – ROI mask with values of 0’s and 1’s.

  • im_range (ndarray) – 1-D array with shape (1,2) of the re-segmentation intensity range.

Returns:

Intensity mask with intensities within the re-segmentation range.

Return type:

ndarray

segmentation

MEDimage.processing.segmentation.compute_bounding_box(mask: ndarray) → ndarray[source]

Computes the indexes of the ROI (Region of interest) enclosing box in all dimensions.

Parameters:

mask (ndarray) – ROI mask with values of 0 and 1.

Returns:

An array containing the indexes of the bounding box.

Return type:

ndarray

MEDimage.processing.segmentation.compute_box(vol: ndarray, roi: ndarray, spatial_ref: imref3d, box_string: str) → Tuple[ndarray, ndarray, imref3d][source]

Computes a new box around the ROI (Region of interest) from the original box and updates the volume and the spatial_ref.

Parameters:

  • vol (ndarray) – ROI mask with values of 0 and 1.

  • roi (ndarray) – ROI mask with values of 0 and 1.

  • spatial_ref (imref3d) – imref3d object (same functionality of MATLAB imref3d class).

  • box_string (str) –

    Specifies the new box to be computed

    • ’full’: full imaging data as output.

    • ’box’: computes the smallest bounding box.

    • Ex: ‘box10’ means 10 voxels in all three dimensions are added to the smallest bounding box. The number after ‘box’ defines the number of voxels to add.

    • Ex: ‘2box’ computes the smallest box and outputs double its size. The number before ‘box’ defines the multiplication in size.

Returns:

3-element tuple containing

  • ndarray: 3D array of imaging data defining the smallest box containing the ROI.

  • ndarray: 3D array of 1’s and 0’s defining the ROI in ROIbox.

  • imref3d: The associated imref3d object imaging data.

Todo

  • I would not recommend parsing different settings into a string. Provide two or more parameters instead, and use None if one or more are not used.

  • There is no else statement, so “new_spatial_ref” might be unset

MEDimage.processing.segmentation.compute_roi(roi_xyz: ndarray, spatial_ref: imref3d, orientation: str, scan_type: str, interp=False) → ndarray[source]

Computes the ROI (Region of interest) mask using the XYZ coordinates.

Parameters:

  • roi_xyz (ndarray) – array of (x,y,z) triplets defining a contour in the Patient-Based Coordinate System extracted from DICOM RTstruct.

  • spatial_ref (imref3d) – imref3d object (same functionality of MATLAB imref3d class).

  • orientation (str) – Imaging data orientation (axial, sagittal or coronal).

  • scan_type (str) – Imaging modality (MRscan, CTscan…).

  • interp (bool) –

    Specifies if we need to use an interpolation process prior to get_polygon_mask() in the slice axis direction.

    • True: Interpolation is performed in the slice axis dimensions. To be further tested, thus please use with caution (True is safer).

    • False (default): No interpolation. This can definitely be safe when the RTstruct has been saved specifically for the volume of interest.

Returns:

3D array of 1’s and 0’s defining the ROI mask.

Return type:

ndarray

Todo

  • Using interpolation: this part needs to be further tested.

  • Consider changing to ‘if statement’. Changing interp variable here will change the interp variable everywhere

MEDimage.processing.segmentation.crop_box(image_data: ndarray, roi_data: ndarray, crop_shape: List[int], center: Sequence[int] | None = None) → Tuple[ndarray, ndarray][source]

Crops the imaging data and the ROI mask.

Parameters:

  • image_data (ndarray) – Imaging data that will be cropped.

  • roi_data (ndarray) – Mask data that will be cropped.

  • crop_shape (List[int]) – The dimension of the region to crop in term of number of voxel.

  • center (Union[Sequence[int], None]) – A list that indicate the center of the cropping box in term of spatial position.

Returns:

Two numpy arrays of the cropped image and roi

Return type:

Tuple[ndarray, ndarray]

MEDimage.processing.segmentation.crop_nifti_box(image: Nifti1Image, roi: Nifti1Image, crop_shape: List[int], center: Sequence[int] | None = None) → Tuple[Nifti1Image, Nifti1Image][source]

Crops the Nifti image and ROI.

Parameters:

  • image (Nifti1Image) – Class for the file NIfTI1 format image that will be cropped.

  • roi (Nifti1Image) – Class for the file NIfTI1 format ROI that will be cropped.

  • crop_shape (List[int]) – The dimension of the region to crop in term of number of voxel.

  • center (Union[Sequence[int], None]) – A list that indicate the center of the cropping box in term of spatial position.

Returns:

Two Nifti images of the cropped image and roi

Return type:

Tuple[Nifti1Image, Nifti1Image]

MEDimage.processing.segmentation.find_spacing(points: ndarray, scan_type: str) → float[source]

Finds the slice spacing in mm.

Note

This function works for points from at least 2 slices. If only one slice is present, the function returns a None.

Parameters:

  • points (ndarray) – Array of (x,y,z) triplets defining a contour in the Patient-Based Coordinate System extracted from DICOM RTstruct.

  • scan_type (str) – Imaging modality (MRscan, CTscan…)

Returns:

Slice spacing in mm.

Return type:

float

MEDimage.processing.segmentation.get_polygon_mask(roi_xyz: ndarray, spatial_ref: imref3d) → ndarray[source]

Computes the indexes of the ROI (Region of interest) enclosing box in all dimensions.

Parameters:

  • roi_xyz (ndarray) – array of (x,y,z) triplets defining a contour in the Patient-Based Coordinate System extracted from DICOM RTstruct.

  • spatial_ref (imref3d) – imref3d object (same functionality of MATLAB imref3d class).

Returns:

3D array of 1’s and 0’s defining the ROI mask.

Return type:

ndarray

MEDimage.processing.segmentation.get_roi(medscan: MEDscan, name_roi: str, box_string: str, interp=False) → image_volume_obj[source]

Computes the ROI box (box containing the region of interest) and associated mask from MEDscan object.

Parameters:

  • medscan (MEDscan) – The MEDscan class object.

  • name_roi (str) – name of the ROI since the a volume can have multuiple ROIs.

  • box_string (str) –

    Specifies the size if the box containing the ROI

    • ’full’: full imaging data as output.

    • ’box’: computes the smallest bounding box.

    • Ex: ‘box10’: 10 voxels in all three dimensions are added to the smallest bounding box. The number after ‘box’ defines the number of voxels to add.

    • Ex: ‘2box’: Computes the smallest box and outputs double its size. The number before ‘box’ defines the multiplication in size.

  • interp (bool) – True if we need to use an interpolation for box computation.

Returns:

2-element tuple containing

  • image_volume_obj: 3D array of imaging data defining box containing the ROI. vol.data is the 3D array, vol.spatialRef is its associated imref3d object.

  • image_volume_obj: 3D array of 1’s and 0’s defining the ROI. roi.data is the 3D array, roi.spatialRef is its associated imref3d object.

MEDimage.processing.segmentation.get_roi_from_indexes(medscan: MEDscan, name_roi: str, box_string: str) → Tuple[image_volume_obj, image_volume_obj][source]

Extracts the ROI box (+ smallest box containing the region of interest) and associated mask from the indexes saved in medscan scan.

Parameters:

  • medscan (MEDscan) – The MEDscan class object.

  • name_roi (str) – name of the ROI since the a volume can have multiple ROIs.

  • box_string (str) –

    Specifies the size if the box containing the ROI

    • ’full’: Full imaging data as output.

    • ’box’: computes the smallest bounding box.

    • Ex: ‘box10’: 10 voxels in all three dimensions are added to the smallest bounding box. The number after ‘box’ defines the number of voxels to add.

    • Ex: ‘2box’: Computes the smallest box and outputs double its size. The number before ‘box’ defines the multiplication in size.

Returns:

2-element tuple containing

  • ndarray: vol_obj, 3D array of imaging data defining the smallest box containing the region of interest.

  • ndarray: roi_obj, 3D array of 1’s and 0’s defining the ROI in ROIbox.

MEDimage.processing.segmentation.get_sep_roi_names(name_roi_in: str, delimiters: List) → Tuple[List[int], ndarray][source]

Seperated ROI names present in the given ROI name. An ROI name can have multiple ROI names seperated with curly brackets and delimeters. .. note:: Works only for delimiters “+” and “-“.

Parameters:

  • name_roi_in (str) – Name of ROIs that will be extracted from the imagign volume. Separated with curly brackets and delimeters. Ex: ‘{ED}+{ET}’.

  • delimiters (List) – List of delimeters of “+” and “-“.

Returns:

2-element tuple containing

  • List[int]: List of ROI names seperated and excluding curly brackets.

  • ndarray: array of 1’s and -1’s that defines the regions that will included and/or excluded in/from the imaging data.

Examples

>>> get_sep_roi_names('{ED}+{ET}', ['+', '-'])
['ED', 'ET'], [1]
>>> get_sep_roi_names('{ED}-{ET}', ['+', '-'])
['ED', 'ET'], [-1]
MEDimage.processing.segmentation.roi_extract(vol: ndarray, roi: ndarray) → ndarray[source]

Replaces volume intensities outside the ROI with NaN.

Parameters:

  • vol (ndarray) – Imaging data.

  • roi (ndarray) – ROI mask with values of 0’s and 1’s.

Returns:

Imaging data with original intensities in the ROI and NaN for intensities outside the ROI.

Return type:

ndarray

MEDimage.processing.segmentation.spatial_to_voxel(affine: ndarray, spatial_pos: list) → array[source]

Convert spatial position into voxel position

Parameters:

  • affine (ndarray) – Affine matrix.

  • spatial_pos (list) – A list that correspond to the spatial location in mm.

Returns:

A numpy array that correspond to the position in the voxel.

Return type:

ndarray

MEDimage.processing.segmentation.voxel_to_spatial(affine: ndarray, voxel_pos: list) → array[source]

Convert voxel position into spatial position.

Parameters:

  • affine (ndarray) – Affine matrix.

  • voxel_pos (list) – A list that correspond to the location in voxel.

Returns:

A numpy array that correspond to the spatial position in mm.

Return type:

ndarray