DICOM Conversion Module#

Module: pyradise.fileio.dicom_conversion

General#

The dicom_conversion module provides functionality to convert from and to DICOM data. This functionality is especially useful if working in the clinical context where the input and / or output data is provided in the DICOM format.

Class Overview#

The following Converter classes are provided:

Class	Description
`Converter`	Base class for all `Converter` classes.
`DicomImageSeriesConverter`	A `Converter` to convert DICOM image files to `IntensityImage` s (incl. registration if provided).
`DicomRTSSSeriesConverter`	A `Converter` to convert DICOM-RTSS files to `SegmentationImage` s (incl. registration if provided).
`SubjectToRTSSConverter`	A `Converter` to convert a `Subject` to a DICOM-RTSS `Dataset`.
`RTSSToSegmentConverter`	A low level `Converter` to convert a DICOM-RTSS `Dataset` to `SegmentationImage` s.
`SegmentToRTSSConverter2D`	A low level `Converter` to convert `SegmentationImage` s to a DICOM-RTSS `Dataset` using a 2D algorithm.
`SegmentToRTSSConverter3D`	A low level `Converter` to convert `SegmentationImage` s to a DICOM-RTSS `Dataset` using a 3D algorithm.
`RTSSMetaData`	A class defining the DICOM-RTSS metadata (used in combination with `SubjectToRTSSConverter`).
`RTSSConverter2DConfiguration`	A class specifying the conversion parameters (e.g., smoothing) for a `SegmentToRTSSConverter2D`
`RTSSConverter3DConfiguration`	A class specifying the conversion parameters (e.g., smoothing, decimation) for a `SegmentToRTSSConverter3D`

Details#

class Converter[source]#

Bases: ABC

An abstract base class for all Converter classes. Typically, the Converter classes are used to convert DICOM data from and to other representations. For example, the DicomImageSeriesConverter converts DICOM image series to IntensityImage instances and applies the associated DICOM registration if provided.

abstract convert()[source]#

Convert the provided DicomSeriesInfo.

Returns:: The converted data.
Return type:: Any

class DicomImageSeriesConverter(image_info, registration_info=())[source]#

Bases: Converter

A Converter class for converting DICOM image series to one or multiple IntensityImage instances.

Parameters:

image_info (Tuple[DicomSeriesImageInfo, ...]) – The DicomSeriesImageInfo entries of the images to convert.
registration_info (Tuple[DicomSeriesRegistrationInfo, ...]) – The DicomSeriesRegistrationInfo entries (default: tuple()).

convert()[source]#

Convert the provided DicomSeriesImageInfo entries to one or multiple IntensityImage instances.

Returns:: The converted IntensityImage instances.
Return type:: Tuple[IntensityImage, …]

class DicomRTSSSeriesConverter(rtss_infos, image_infos, registration_infos, fill_hole_search_distance=0)[source]#

Bases: Converter

A Converter class for converting a DICOM-RTSS (i.e. DicomSeriesRTSSInfo) to one or multiple SegmentationImage instances.

Notes

The user may provide all available DicomSeriesImageInfo and DicomSeriesRegistrationInfo entries to the corresponding image_infos and registration_infos, respectively. In this case the DicomRTSSSeriesConverter will sort out unused entries.

Parameters:

rtss_infos (Union[DicomSeriesRTSSInfo, Tuple[DicomSeriesRTSSInfo, ...]]) – The DicomSeriesRTSSInfo instance holding the information to be converted.
image_infos (Tuple[DicomSeriesImageInfo, ...]) – The DicomSeriesImageInfo entries which are referenced in the DicomSeriesRTSSInfo instance.
registration_infos (Optional[Tuple[DicomSeriesRegistrationInfo, ...]]) – The DicomSeriesRegistrationInfo entries referencing the DICOM image or DICOM-RTSS.
fill_hole_search_distance (int) – The search distance for the hole filling algorithm. If the search distance is set to zero the hole filling algorithm is omitted. The search distance must be an odd number larger than 1 (default: 0).

convert()[source]#

Convert the DicomSeriesRTSSInfo instances into one or multiple SegmentationImage instances.

Returns:: The converted SegmentationImage instances.
Return type:: Tuple[SegmentationImage, …]

class SubjectToRTSSConverter(subject, infos, reference_modality, config, meta_data=RTSSMetaData(patient_name=None, patient_id=None, patient_birth_date=None, patient_sex=None, patient_age=None, patient_weight=None, patient_size=None, study_description=None, series_description=None, series_number='99', structure_set_label='Autogenerated', operators_name='NA', manufacturer='University of Bern, Switzerland', manufacturer_model_name='PyRaDiSe Package', institution_name='Unknown Institution', referring_physician_name='NA', approval_status='UNAPPROVED', roi_gen_algorithm='AUTOMATIC'), colors=None)[source]#

Bases: Converter

A Converter class for converting the SegmentationImage instances of a Subject instance to a Dataset instance.

Note

This class is typically used at the end of a processing pipeline to output a DICOM-RTSS file containing the segmentation results of the pipeline.

Note

This class can take a RTSSMetaData instance as input to specify certain DICOM attributes of the output DICOM-RTSS. If no instance is provided, the default values will be used.

Important

The config parameter defines the type of conversion algorithm. If specific conversion parameters are required for a certain SegmentationImage instance, they must be provided in the appropriate RTSSConverterConfiguration (i.e., RTSSConverter2DConfiguration or RTSSConverter3DConfiguration). Furthermore, the image_identifier parameter must be set to the organ name of the SegmentationImage instance. Otherwise, segmentation masks with specific parameters can not be identified.

Parameters:

subject (Subject) – The Subject instance to be converted to a DICOM-RTSS Dataset instance.
infos (Tuple[SeriesInfo, ...]) – The DicomSeriesInfo entries provided for the conversion (only DicomSeriesImageInfo will be considered).
reference_modality (Union[Modality, str]) – The reference Modality of the images to be used for the conversion to DICOM-RTSS.
config (Union[RTSSConverter2DConfiguration, RTSSConverter3DConfiguration]) – The configuration for the conversion procedure. The type of conversion configuration determines also the conversion algorithm (2D or 3D) that is used.
meta_data (RTSSMetaData) – The configuration to specify certain DICOM attributes (default: RTSSMetaData()).
colors (Optional[Tuple[Tuple[int, int, int], ...]]) – The colors to be used for the segmentation masks. If None, the default colors will be used (default: None).

convert()[source]#

Convert a Subject instance to a DICOM-RTSS Dataset instance.

Returns:: The DICOM-RTSS Dataset instance generated from the provided Subject instance.
Return type:: Dataset

class RTSSToSegmentConverter(rtss_dataset, image_datasets, registration_dataset=None, fill_hole_search_distance=0)[source]#

Bases: Converter

A low-level DICOM-RTSS to SimpleITK image Converter class converting the content of the DICOM-RTSS to one or multiple SimpleITK images. In contrast to the DicomRTSSSeriesConverter this class generates a dict of binary SimpleITK.Image instances and organ names instead of a tuple of SegmentationImage s.

Notes

Typically, this class is not used directly by the user but via the DicomRTSSSeriesConverter which processes DicomSeriesInfo entries directly.

This class can be used with a DICOM registration which will be applied to the reference image and the structure set. However, the registration must reference the corresponding DICOM image, otherwise the registration will not be applied.

Parameters:

rtss_dataset (Union[str, Dataset]) – The path to the DICOM-RTSS file or DICOM-RTSS Dataset.
image_datasets (Union[Tuple[str], Tuple[Dataset]]) – The path to the DICOM image files or the DICOM image Dataset entries which are referenced in the rtss_dataset.
registration_dataset (Union[str, Dataset, None]) – The path to a DICOM registration file or a DICOM registration Dataset entry which contains a reference to the DICOM image (default: None).
fill_hole_search_distance (int) – The search distance for the hole filling algorithm. If the search distance is set to zero the hole filling algorithm is omitted. The search distance must be an odd number larger than 1 (default: 0).

convert()[source]#

Convert a DICOM-RTSS Dataset instance into a dict of binary SimpleITK.Image instances including their associated ROINames as a key in the dict.

Returns:: The ROINames and the corresponding binary segmented SimpleITK.Image instances.
Return type:: Dict[str, sitk.Image]

class SegmentToRTSSConverter2D(label_images, ref_image_datasets, roi_names, colors, meta_data=RTSSMetaData(patient_name=None, patient_id=None, patient_birth_date=None, patient_sex=None, patient_age=None, patient_weight=None, patient_size=None, study_description=None, series_description=None, series_number='99', structure_set_label='Autogenerated', operators_name='NA', manufacturer='University of Bern, Switzerland', manufacturer_model_name='PyRaDiSe Package', institution_name='Unknown Institution', referring_physician_name='NA', approval_status='UNAPPROVED', roi_gen_algorithm='AUTOMATIC'), config=<pyradise.fileio.dicom_conversion.RTSSConverter2DConfiguration object>)[source]#

Bases: SegmentToRTSSConverterBase

A low-level 2D-based Converter class for converting one or multiple SegmentationImage instances to a DICOM-RTSS Dataset. In contrast to the SegmentToRTSSConverter3D class, this class generates the DICOM-RTSS contours using a two-dimensional approach. This reduces the computation time and leads to a more robust conversion procedure. However, this class has limitations such as the inability to smooth contours in all three dimensions. Furthermore, the resulting contours may appear to be artificially generated and not as smooth as the ones generated by the SegmentToRTSSConverter3D class.

Warning

The provided label_images must be binary, otherwise the conversion will fail.

Note

Typically, this class is not used directly by the used but via the SubjectToRTSSConverter which processes DicomSeriesInfo entries and thus provides a more suitable interface.

Note

This class can take a RTSSMetaData instance as input to specify certain DICOM attributes of the output DICOM-RTSS. If no instance is provided, the default values will be used.

Parameters:

label_images (Union[Tuple[str, ...], Tuple[sitk.Image, ...]]) – The path to the images or a sequence of SimpleITK.Image instances.
ref_image_datasets (Union[Tuple[str, ...], Tuple[Dataset, ...]]) – The referenced DICOM image Dataset instances.
roi_names (Union[Tuple[str, ...], Dict[int, str], None]) – The label names which will be assigned to the ROIs.
colors (Optional[Tuple[Tuple[int, int, int], ...]]) – The colors which will be assigned to the ROIs.
meta_data (RTSSMetaData) – The configuration to specify certain DICOM attributes (default: RTSSMetaData()).
config (RTSSConverter2DConfiguration) – The configuration to specify certain conversion parameters (default: RTSSConverter2DConfiguration()).

convert()[source]#

Convert the provided SimpleITK.Image instances to a DICOM-RTSS Dataset instance using a two-dimensional reconstruction algorithm.

Returns:: The generated DICOM-RTSS Dataset.
Return type:: Dataset

class SegmentToRTSSConverter3D(label_images, ref_image_datasets, roi_names, colors, meta_data=RTSSMetaData(patient_name=None, patient_id=None, patient_birth_date=None, patient_sex=None, patient_age=None, patient_weight=None, patient_size=None, study_description=None, series_description=None, series_number='99', structure_set_label='Autogenerated', operators_name='NA', manufacturer='University of Bern, Switzerland', manufacturer_model_name='PyRaDiSe Package', institution_name='Unknown Institution', referring_physician_name='NA', approval_status='UNAPPROVED', roi_gen_algorithm='AUTOMATIC'), config=<pyradise.fileio.dicom_conversion.RTSSConverter3DConfiguration object>)[source]#

Bases: SegmentToRTSSConverterBase

A low-level 3D-based Converter class for converting one or multiple SegmentationImage instances to a DICOM-RTSS Dataset. In contrast to the SegmentToRTSSConverter2D class, this class generates the DICOM-RTSS contours using a three-dimensional approach. This reduces spatial inconsistencies but comes at the cost of a longer computation time and higher memory consumption. Furthermore, this converter is less robust than its two-dimensional counterpart. However, the resulting contours are more accurate and appear more natural it the converter is applied with appropriate parameterization.

Warning

The provided label_images must be binary, otherwise the conversion will fail.

Note

Typically, this class is not used directly by the used but via the SubjectToRTSSConverter which processes DicomSeriesInfo entries and thus provides a more suitable interface.

Note

This class can take a RTSSMetaData instance as input to specify certain DICOM attributes of the output DICOM-RTSS. If no instance is provided, the default values will be used.

Parameters:

label_images (Union[Tuple[str, ...], Tuple[sitk.Image, ...]]) – The path to the images or a sequence of SimpleITK.Image instances.
ref_image_datasets (Union[Tuple[str, ...], Tuple[Dataset, ...]]) – The referenced DICOM image Dataset instances.
roi_names (Union[Tuple[str, ...], Dict[int, str], None]) – The label names which will be assigned to the ROIs.
colors (Optional[Tuple[Tuple[int, int, int], ...]]) – The colors which will be assigned to the ROIs.
meta_data (RTSSMetaData) – The configuration to specify certain DICOM attributes (default: RTSSMetaData()).
config (RTSSConverter3DConfiguration) – The configuration to specify certain conversion parameters (default: RTSSConverter3DConfiguration()).

preprocess_image(image_sitk)[source]#

Preprocess the provided SimpleITK.Image instance such that the image has the same properties as the referenced DICOM image series.

Parameters:: image_sitk (sitk.Image) – The SimpleITK.Image instance to preprocess.
Returns:: The preprocessed SimpleITK.Image instance.
Return type:: sitk.Image

convert()[source]#

Convert the provided SimpleITK.Image instances to a DICOM-RTSS Dataset instance using a three-dimensional reconstruction algorithm.

Returns:: The generated DICOM-RTSS Dataset.
Return type:: Dataset

class RTSSMetaData(patient_name=None, patient_id=None, patient_birth_date=None, patient_sex=None, patient_age=None, patient_weight=None, patient_size=None, study_description=None, series_description=None, series_number='99', structure_set_label='Autogenerated', operators_name='NA', manufacturer='University of Bern, Switzerland', manufacturer_model_name='PyRaDiSe Package', institution_name='Unknown Institution', referring_physician_name='NA', approval_status='UNAPPROVED', roi_gen_algorithm='AUTOMATIC')[source]#

Bases: object

A class to define metadata of a new DICOM-RTSS dataset.

Note

Some attributes can take None as a value. This means that the attribute will be copied from the reference DICOM image dataset.

Note

For some attributes, the value must follow the value representation of the DICOM standard. For example, the PatientSex attribute must be either 'M', 'F', or 'O'. For more information, we refer to the DICOM standard part 5 chapter 6.2.

Parameters:

patient_name (Optional[str]) – The patient name.
patient_id (Optional[str]) – The patient ID.
patient_birth_date (Optional[str]) – The patient birth date (format: YYYYMMDD).
patient_sex (Optional[str]) – The patient sex (valid values: ‘F’ (female), ‘M’ (male), ‘O’ (other)).
patient_weight (Optional[str]) – The patient weight (unit: kilograms with decimals).
patient_size (Optional[str]) – The patient size (unit: meters with decimals).
study_description (Optional[str]) – The study description.
series_description (Optional[str]) – The series description.
series_number (Optional[str]) – The series number (default: ‘99’).
structure_set_label (str) – The structure set label (default: ‘Autogenerated’).
operators_name (str) – The operator’s name (default: ‘NA’).
manufacturer (str) – The manufacturer (default: ‘University of Bern, Switzerland’).
manufacturer_model_name (str) – The manufacturer model name (default: ‘PyRaDiSe Package’).
institution_name (str) – The institution name (default: ‘Unknown Institution’).
referring_physician_name (str) – The referring physician name (default: ‘NA’).
approval_status (str) – The approval status (valid values: ‘APPROVED’, ‘UNAPPROVED’, ‘REJECTED’, default: ‘UNAPPROVED’).
roi_gen_algorithm (str) – The ROI generation algorithm (valid values: ‘AUTOMATIC’, ‘SEMIAUTOMATIC’, ‘MANUAL’, default: ‘AUTOMATIC’).

class RTSSConverter2DConfiguration(smoothing=True, smoothing_sigma=1.0, smoothing_kernel_size=8)[source]#

Bases: RTSSConverterConfiguration

A configuration class to parameterize a SegmentToRTSSConverter2D instance.

The configuration can be used to set the general and image specific conversion parameters of the converter. The general parameters are applied to all images except if image specific parameters are provided. used for the image.

The parameters define the following:

smoothing: Indicates if Gaussian smoothing is applied.
smoothing_sigma: The variance of the discrete Gaussian smoothing kernel.
smoothing_kernel_size: The size of the discrete Gaussian smoothing kernel.

Parameters:

smoothing (bool) – Whether to smooth the contours or not (default: True).
smoothing_sigma (float) – The variance of the Gaussian smoothing (default: 1.0).
smoothing_kernel_size (int) – The size of the Gaussian smoothing kernel (default: 8).

set_general_params(smoothing, smoothing_sigma, smoothing_kernel_size)[source]#

Set the general parameters for all images except those that have specific parameters.

Parameters:

smoothing (bool) – Whether to apply Gaussian smoothing.
smoothing_sigma (float) – The sigma of the Gaussian filter.
smoothing_kernel_size (int) – The kernel size of the Gaussian filter.

Return type:

None

Returns:

None

set_image_params(image_identifier, smoothing, smoothing_sigma, smoothing_kernel_size)[source]#

Set the parameters of the converter for a specific image using the Organ instance.

Parameters:

image_identifier (str) – The image to set the parameter(s) for.
smoothing (bool) – Whether to apply Gaussian smoothing to the image.
smoothing_sigma (float) – The sigma value for the Gaussian smoothing kernel.
smoothing_kernel_size (int) – The kernel size for the Gaussian smoothing kernel.

Return type:

None

Returns:

None

get_general_params(name=None)#

Get all or a specific general parameter for the converter.

Parameters:: name (Optional[str]) – The name of the parameter to get. If None, all parameters are returned (default: None).
Returns:: All or the selected parameter.
Return type:: Optional[Union[Dict[str, Any], Any]]

get_image_params(image_identifier, name=None)#

Get all parameters for a specific image using its identifier.

Parameters:

image_identifier (str) – The identifier of the image
name (Optional[str]) – The name of the parameter to get. If None, all parameters are returned (default: None).

Returns:

All or the selected parameter belonging to the specific image

Return type:

Optional[Union[Dict[str, Any], Any]]

class RTSSConverter3DConfiguration(image_smoothing=False, image_smoothing_sigma=2.0, image_smoothing_radius=1.0, image_smoothing_threshold=0.0, decimate_reduction=0.5, decimate_threshold=0.0, model_smoothing_iterations=10, model_smoothing_pass_band=0.25, min_segment_lines=0)[source]#

Bases: RTSSConverterConfiguration

A configuration class to parameterize a SegmentToRTSSConverter3D instance.

The parameters define the following:

image_smoothing: Whether to apply Gaussian smoothing to the image before 3D model construction.
image_smoothing_sigma: The standard deviation value for the Gaussian smoothing kernel.
image_smoothing_radius: The radius of the Gaussian smoothing kernel.
image_smoothing_threshold: The threshold value for the Gaussian smoothing. All segmentation masks that have less foreground voxels than this threshold are not smoothed to avoid deletion.
decimate_reduction: The reduction factor for the decimation of the 3D model. This factor defines how much vertices are removed from the model during the decimation process (0 = none, 1: all).
decimate_threshold: The threshold value for the decimation of the 3D model. All models that arise from a segmentation mask with less than the threshold number of foreground voxels are not decimated to avoid deletion.
model_smoothing_iterations: The number of iterations for the smoothing of the 3D model (Sinc-Filter). Typically, 10 to 20 iterations are sufficient for smoothing.
model_smoothing_pass_band: The pass band for the smoothing of the 3D model (Sinc-Filter). The closer this value is to zero (e.g., 0.001) the stronger the smoothing is. The higher the value (e.g., 0.4) the less the smoothing is.
min_segment_lines: The minimum number of lines that a segment must have to be considered for the RTSS. All segments smaller than this value are discarded.

Parameters:

image_smoothing (bool) – Whether to smooth the image before 3D model construction or not (default: False).
image_smoothing_sigma (float) – The standard deviation of the Gaussian smoothing before 3D model construction (default: 2.).
image_smoothing_radius (float) – The radius of the Gaussian smoothing before 3D model construction (default: 1.).
image_smoothing_threshold (float) – The minimum number of foreground voxels that must be contained in the segmentation mask to trigger Gaussian smoothing (default: 0).
decimate_reduction (float) – The reduction factor for the 3D decimation. The decimation factor is valid between 0 and 1 and the lower it is the more smoothing is applied (default: 0.5).
decimate_threshold (float) – The minimum number of foreground voxels that must be contained in the segmentation mask to trigger 3D decimation (default: 0).
model_smoothing_iterations (int) – The number of 3D smoothing steps (typically 10 - 20 steps) (default: 10).
model_smoothing_pass_band (bool) – The strength of the 3D smoothing (0.001 - 0.1 = strong smoothing, 0.1 - 0.5 = intermediate smoothing, 0.5 - 1 = almost no smoothing) (default: 0.25).
min_segment_lines (int) – The minimum number of lines that a segment must have to be considered for the RTSS (default: 0).

set_general_params(image_smoothing, image_smoothing_sigma, image_smoothing_radius, image_smoothing_threshold, decimate_reduction, decimate_threshold, model_smoothing_iterations, model_smoothing_pass_band, min_segment_lines)[source]#

Set the general parameters for all images except those that have specific parameters.

Parameters:

image_smoothing (bool) – Whether to smooth the image before 3D model construction or not.
image_smoothing_sigma (float) – The standard deviation of the Gaussian smoothing before 3D model construction.
image_smoothing_radius (float) – The radius of the Gaussian smoothing before 3D model construction.
image_smoothing_threshold (float) – The minimum number of foreground voxels that must be contained in the segmentation mask to trigger Gaussian smoothing.
decimate_reduction (float) – The reduction factor for the 3D decimation. The decimation factor is valid between 0 and 1 and the lower it is the more smoothing is applied.
decimate_threshold (float) – The minimum number of foreground voxels that must be contained in the segmentation mask to trigger 3D decimation.
model_smoothing_iterations (int) – The number of 3D smoothing steps (typically 15 - 20 steps).
model_smoothing_pass_band (bool) – The strength of the 3D smoothing (0.001 - 0.1 = strong smoothing, 0.5 - 1 = almost no smoothing).
min_segment_lines (int) – The minimum number of lines that a segment must have to be considered for the RTSS.

Return type:

None

Returns:

None

set_image_params(image_identifier, image_smoothing, image_smoothing_sigma, image_smoothing_radius, image_smoothing_threshold, decimate_reduction, decimate_threshold, model_smoothing_iterations, model_smoothing_pass_band, min_segment_lines)[source]#

Set the parameters of the converter for a specific image using an identifier.

Parameters:

image_identifier (str) – The identifier that identifies the segmentation mask for which the parameters are set.
image_smoothing (bool) – Whether to smooth the image before 3D model construction or not.
image_smoothing_sigma (float) – The variance of the Gaussian smoothing before 3D model construction.
image_smoothing_radius (float) – The radius of the Gaussian smoothing before 3D model construction.
image_smoothing_threshold (float) – The minimum number of foreground voxels that must be contained in the segmentation mask to trigger Gaussian smoothing.
decimate_reduction (float) – The reduction factor for the 3D decimation. The decimation factor is valid between 0 and 1 and the lower it is the more smoothing is applied.
decimate_threshold (float) – The minimum number of foreground voxels that must be contained in the segmentation mask to trigger 3D decimation.
model_smoothing_iterations (int) – The number of 3D smoothing steps (typically 15 - 20 steps).
model_smoothing_pass_band (bool) – The strength of the 3D smoothing (0.001 - 0.1 = strong smoothing, 0.5 - 1 = almost no smoothing).
min_segment_lines (int) – The minimum number of lines that a segment must have to be considered for the RTSS.

Return type:

None

Returns:

None

get_general_params(name=None)#

Get all or a specific general parameter for the converter.

Parameters:: name (Optional[str]) – The name of the parameter to get. If None, all parameters are returned (default: None).
Returns:: All or the selected parameter.
Return type:: Optional[Union[Dict[str, Any], Any]]

get_image_params(image_identifier, name=None)#

Get all parameters for a specific image using its identifier.

Parameters:

image_identifier (str) – The identifier of the image
name (Optional[str]) – The name of the parameter to get. If None, all parameters are returned (default: None).

Returns:

All or the selected parameter belonging to the specific image

Return type:

Optional[Union[Dict[str, Any], Any]]