API Reference¶

class pydicom_seg.MultiClassReader¶

Bases: pydicom_seg.reader._ReaderBase

Reads multi-class segmentations from a DICOM-SEG file.

If all segments in a DICOM-SEG don’t overlap, then it is save to reduce n binary segmentations to a single segmentation with an integer index for the referenced segment at the spatial location. This is a common use-case, especially in computer vision applications, for analysing different regions in medical imaging. The read operation creates a MultiClassReadResult object with information about the spatial location and extent, as well as the multi-class segmentation data.

Example

dcm = pydicom.dcmread('segmentation.dcm')
reader = pydicom_seg.MultiClassReader()
result = reader.read(dcm)
data = result.data  # numpy array
image = result.image  # SimpleITK image

read(dataset: pydicom.dataset.Dataset) → pydicom_seg.reader.MultiClassReadResult¶

Read from a DICOM-SEG file.

Parameters: dataset – A pydicom.Dataset with DICOM-SEG content.
Returns: Result object with decoded numpy data and common information about the spatial location and extent of the volume.

class pydicom_seg.MultiClassWriter(template: pydicom.dataset.Dataset, inplane_cropping: bool = False, skip_empty_slices: bool = True, skip_missing_segment: bool = False)¶

Bases: object

Writer for DICOM-SEG files from multi-class segmentations.

Writing DICOM-SEGs can be optimized in respect to the required disk space. Empty slices/frames of a 3D volume, containing only zeros, can be omitted from the frame sequence. Furthermore, the segmentation might only span a small area in a slice and thus can be cropped to the minimal enclosing bounding box.

Example

segmentation = ...  # A multi-class segmentation as SimpleITK image
series_dcms = ...  # List of `pydicom.Dataset`s related to the segmentation

template = pydicom_seg.template.from_dcmqi_metainfo('metainfo.json')
writer = MultiClassWriter(template)
dcm = writer.write(segmentation, series_dcms)
dcm.save_as('<path>')

Parameters

template – A pydicom.Dataset holding all relevant meta information about the DICOM-SEG series. It has the same meaning as the metainfo.json file for the dcmqi binaries.
inplane_cropping – If enabled, slices will be cropped (Rows/Columns) to the minimum enclosing boundingbox of all labels across all slices. Warning: This is an experimental feature and might not be supported when decoding with other frameworks / DICOM viewers.
skip_empty_slices – If enabled, empty slices with only zeros (background label) will be ommited from the DICOM-SEG.
skip_missing_segment – If enabled, just emit a warning if segment information is missing in the template for a specific label. The segment won’t be included in the final DICOM-SEG. Otherwise, the encoding is aborted if segment information is missing.

write(segmentation: SimpleITK.SimpleITK.Image, source_images: List[Union[pydicom.dataset.Dataset, bytes, str, os.PathLike]]) → pydicom.dataset.Dataset¶

Writes a DICOM-SEG dataset from a segmentation image and the corresponding DICOM source images.

Parameters

segmentation – A SimpleITK.Image with integer labels and a single component per spatial location.
source_images – A list of pydicom.Dataset which are the source images for the segmentation image.

Returns

A pydicom.Dataset instance with all necessary information and meta information for writing the dataset to disk.

class pydicom_seg.SegmentReader¶

Bases: pydicom_seg.reader._ReaderBase

Reads binary segments from a DICOM-SEG file.

All segments in a DICOM-SEG file cover the same spatial extent, but might overlap. If a user wants to use each segment individually as a binary segmentation, then this reader extracts all segments as individual numpy arrays. The read operation creates a SegmentReadResult object with common information about the spatial location and extent shared by all segments, as well as the binary segmentation data for each segment.

Example

dcm = pydicom.dcmread('segmentation.dcm')
reader = pydicom_seg.SegmentReader()
result = reader.read(dcm)
data = result.segment_data(1)  # numpy array
image = result.segment_image(1)  # SimpleITK image

read(dataset: pydicom.dataset.Dataset) → pydicom_seg.reader.SegmentReadResult¶

Read from a DICOM-SEG file.

Parameters: dataset – A pydicom.Dataset with DICOM-SEG content.
Returns: Result object with decoded numpy data and common information about the spatial location and extent of the volume.

class pydicom_seg.reader.SegmentReadResult¶

Bases: pydicom_seg.reader._ReadResultBase

Read result for segment-based decoding of DICOM-SEGs.

property available_segments¶

segment_data(number: int) → numpy.ndarray¶

segment_image(number: int) → SimpleITK.SimpleITK.Image¶

class pydicom_seg.reader.MultiClassReadResult¶

Bases: pydicom_seg.reader._ReadResultBase

Read result for multi-class decoding of DICOM-SEGs.

data: np.ndarray = None¶

property image¶

class pydicom_seg.reader._ReadResultBase¶

Bases: object

Base data class for read results.

Contains common information about a decoded segmentation, e.g. origin, voxel spacing and the direction matrix.

dataset: pydicom.Dataset = None¶

direction: np.ndarray = None¶

origin: Tuple[float, ...] = None¶

property referenced_instance_uids¶

property referenced_series_uid¶

segment_infos: Dict[int, pydicom.Dataset] = None¶

size: Tuple[int, ...] = None¶

spacing: Tuple[float, ...] = None¶

pydicom_seg.template.from_dcmqi_metainfo(metainfo: Union[dict, bytes, str, os.PathLike]) → pydicom.dataset.Dataset¶

Converts a metainfo.json file from the dcmqi project to a pydicom.Dataset with the matching DICOM data elements set from JSON.

Those JSON files can be easilly created using the segmentation editor tool from QIICR/dcmqi: http://qiicr.org/dcmqi/#/seg When converting the JSON to a DICOM dataset, the validity of the provided JSON document is ensured using the official JSON schema files from the dcmqi project.

Parameters: metainfo – Either a str for a file path to read from or a dict with the JSON already imported or constructed in source code.
Returns: A pydicom.Dataset containg all values from the JSON document and some defaults if the elements were not available.