dicom-ecg-plot

A Python tool to render 12-lead ECG waveforms from DICOM files.

The input can be a local .dcm file or a WADO triplet (studyUID seriesUID objectUID); in the latter case the DICOM object is downloaded from the server configured in ecgconfig.py.

THE PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, BUT WITHOUT ANY WARRANTY OF ANY KIND.

About

ECG devices and PACS systems store electrocardiograms in the DICOM Waveform format (Supplement 30), but most viewers either require proprietary software or render the tracing as a static image embedded in the DICOM file itself. dicom-ecg-plot reads the raw waveform samples directly, applies standard signal processing, and produces a publication-quality plot you can embed in reports, share as a PDF, or pipe into automated workflows.

It is designed for use in clinical informatics and research environments where ECGs need to be extracted from a PACS/RIS and converted to an open, portable format without depending on the originating device's software.

Features

• Reads raw DICOM waveform data — decodes waveform samples, lead labels, and metadata directly from DICOM tags, independent of the device manufacturer
• Multiple lead layouts — 3x4_1 (standard 12-lead + rhythm strip), 3x4, 6x2, 12x1; custom layouts configurable in ecgconfig.py
• WADO retrieval — fetches DICOM objects from a PACS via WADO-URI using a studyUID / seriesUID / objectUID triplet
• Signal filtering — 2nd-order 40 Hz lowpass Butterworth filter to remove high-frequency noise
• Standard ECG grid — 5 mm major grid with optional 1 mm minor grid
• Automated interpretation — optionally renders the machine-generated interpretation text stored in the DICOM file
• Flexible output — writes PDF, PNG, SVG, TIFF and other Matplotlib-supported formats; streams to stdout for pipeline use
• Configurable branding — institution name can be read from the DICOM tag or overridden in config

Online demo

ecg.galliera.it — upload your own DICOM files or explore preloaded samples from different ECG device models.

Install

python3 -m venv ecg
. ecg/bin/activate
pip install dicom-ecg-plot

Usage

dicom-ecg-plot <inputfile> [options]
dicom-ecg-plot <studyUID> <seriesUID> <objectUID> [options]
dicom-ecg-plot --help

Options

Output formats

eps, jpeg, jpg, pdf, pgf, png, ps, raw, rgba, svg, svgz, tif, tiff

When --output is given the format is inferred from the file extension.
When no output file is given, --format must be specified and the result is written to stdout.

Layouts

Custom layouts can be added to ecgconfig.py by extending the LAYOUT dictionary.

Examples

# Local file → PDF
dicom-ecg-plot anonymous_ecg.dcm --output anonymous_ecg.pdf

# Custom layout → PNG
dicom-ecg-plot anonymous_ecg.dcm --layout 6x2 --output anonymous_ecg.png

# Pipe to stdout
dicom-ecg-plot anonymous_ecg.dcm --format svg > anonymous_ecg.svg

# Letter paper with minor grid
dicom-ecg-plot anonymous_ecg.dcm --paper letter --minor-grid --output anonymous_ecg.pdf

# Include automated interpretation
dicom-ecg-plot anonymous_ecg.dcm --interpretation --output anonymous_ecg.pdf

# WADO retrieval
dicom-ecg-plot <studyUID> <seriesUID> <objectUID> --format pdf > anonymous_ecg.pdf

Configuration

Copy or edit ecgconfig.py to customise the tool:

# WADO server URL
WADOSERVER = "http://your-wado-server/"

# Institution name displayed on the plot (None = read from DICOM tag InstitutionName)
INSTITUTION = None

# Custom layouts: list of rows, each row is a list of lead indices (0–11)
LAYOUT = { ... }

Signal processing

Signals are filtered with a 2nd-order 40 Hz lowpass Butterworth filter. The grid follows standard ECG conventions: 5 mm major grid, optional 1 mm minor grid.

References

• DICOM Supplement 30 — Waveforms
• DICOM lookup — Waveform modules
• ECG signal encoding in DICOM
• Mortara ECG DICOM Conformance Statement

License

MIT — see LICENSE.

Authors

Marco De Benedetto, Simone Ferretti, Francesco Formisano