Skip to main content

Python package for DICOM-SEG medical segmentation file reading and writing

Project description


License: MIT Python versions PyPI version DOI

Reading and writing of DICOM-SEG medical image segmentation storage files using pydicom as DICOM serialization/deserialization library.


Converting DICOM-SEG files into ITK compatible data formats, commonly used for research, is made possible by the dcmqi project for some time. However, the project is written in C++ and offers only access to the conversion via the binaries itkimage2segimage and segimage2itkimage. After a conversion of a DICOM-SEG file to ITK NRRD file format, the user has to scan the output directory for generated files, load them individually and potentially combine multiple files to the desired format.

This library aims to make this process much easier, by providing a Python native implementation of reading and writing functionality with support for numpy and SimpleITK. Additionally, common use cases like loading multi-class segmentations are supported out-of-the-box.


Install from PyPI

pip install pydicom-seg

Install from source

This package uses Poetry as build system.

git clone
cd pydicom-seg
poetry build
pip install dist/pydicom_seg-<version>-py3-none-any.whl

Getting Started

Loading binary segments

import pydicom
import pydicom_seg
import SimpleITK as sitk

dcm = pydicom.dcmread('segmentation.dcm')

reader = pydicom_seg.SegmentReader()
result =

for segment_number in result.available_segments:
    image_data = result.segment_data(segment_number)  # directly available
    image = result.segment_image(segment_number)  # lazy construction
    sitk.WriteImage(image, f'/tmp/segmentation-{segment_number}.nrrd', True)

Loading a multi-class segmentation

dcm = pydicom.dcmread('segmentation.dcm')

reader = pydicom_seg.MultiClassReader()
result =

image_data =  # directly available
image = result.image  # lazy construction
sitk.WriteImage(image, '/tmp/segmentation.nrrd', True)

Saving a multi-class segmentation

segmentation: SimpleITK.Image = ...  # A segmentation image with integer data type
                                     # and a single component per voxel
dicom_series_paths = [...]  # Paths to an imaging series related to the segmentation
source_images = [
    pydicom.dcmread(x, stop_before_pixels=True)
    for x in dicom_series_paths
template = pydicom_seg.template.from_dcmqi_metainfo('metainfo.json')
writer = pydicom_seg.MultiClassWriter(
    inplane_cropping=True,  # Crop image slices to the minimum bounding box on 
                            # x and y axes
    skip_empty_slices=True,  # Don't encode slices with only zeros
    skip_missing_segments=False,  # If a segment definition is missing in the
                                  # template, then raise an error instead of
                                  # skipping it.
dcm = writer.write(segmentation, source_images)


pydicom-seg is distributed under the MIT license.

Project details

Release history Release notifications

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pydicom-seg, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size pydicom_seg-0.1.0-py3-none-any.whl (16.9 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pydicom-seg-0.1.0.tar.gz (17.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page