radreader

Read 2-D X-ray (CR / DX) and mammography (MG) DICOMs as the image a radiologist would see. Pure pydicom, following the DICOM order: rescale → window / VOI LUT → MONOCHROME1 flip → padding. radreader is also a quality checker and a fixer for broken headers.

import radreader

img = radreader.read("chest.dcm")
img.pixels            # float32 (rows, cols) in [0, 1], no transpose needed
img.meta["voi"]       # {'source': 'window', 'center': 2048.0, 'width': 4096.0, 'function': 'LINEAR', ...}
img.issues            # [Issue(id='HDR_HIGHBIT_MISSING', severity='info', fixed_by='highbit_from_bits_stored', ...)]

Install

pip install radreader                 # numpy, pydicom, pylibjpeg + libjpeg (JPEG Lossless), python-gdcm
pip install "radreader[pylibjpeg]"    # + pylibjpeg-openjpeg (JPEG 2000)
pip install "radreader[torch]"        # radreader.torch.to_tensor
pip install "radreader[monai]"        # radreader.monai.RadReader

For development: uv sync --all-extras, then .venv/bin/python -m pytest tests/.

Reading

radreader.read(path, voi=True, voi_source="auto", window_index=0, window=None,
               out_range=(0.0, 1.0), qc="on", fix="header", fixers=None)

path can be a file path or a binary file object. meta holds the technical tags and the choices made, including photometric, transfer_syntax, decoder, windows (all options), voi (the one used), pixel_spacing (PixelSpacing, else ImagerPixelSpacing) with pixel_spacing_source, geometry, view, image_laterality, body_part, presentation_intent, vendor (cleaned, e.g. "GE Healthcare" → GE), padding_mask, steps and issues. No patient tags.

Errors: InvalidDicomError (not DICOM, partial download), UnsupportedImageError (no pixels, multi-frame, color), DecoderMissingError (with the install command), DecodeError. All are RadReaderError, with the step, transfer syntax and file in the message and the original exception chained.

What it handles

Spacing differs from ITK on purpose: radreader uses PixelSpacing (magnification corrected) first, ITK uses ImagerPixelSpacing for CR / DX / MG. Both raw values are in meta.

Quality checks

radreader.qc("x.dcm", level="header")        # list[Issue]; levels: file, header, pixel
rows = radreader.check("/data/folder", level="pixel", workers=16, out="report.csv")   # never stops on errors
issues, table = radreader.dataset_qc(rows)   # duplicates, mixed bit depth per vendor, intensity outliers
for r in radreader.scan("/data/folder"):     # headers only: ok / not_image / unsupported / error / hidden
    print(r.path, r.status)

The CSV report holds technical tags only (safe to share), plus SOPInstanceUID and a pixel hash for the duplicate checks. All issue ids: docs/qc_checks.md.

radreader qc /data/folder --level pixel --workers 16 --out report.csv   # summary by issue id x vendor
radreader fix in_folder out_folder --report changes.csv                   # repaired headers, pixels untouched

Fixers

Header fixers always run (the pixels need them) and are listed as issues with fixed_by. Image fixers are off by default, so the default output stays "what the DICOM says".

@radreader.fixer("PIX_LOW_CONTRAST", kind="image")
def my_clahe(pixels, ds, meta):
    ...
    return new_pixels

img = radreader.read(path, fixers=[my_clahe])      # or fix="image" for all registered image fixers
radreader.fix_file("in.dcm", "out.dcm")            # header fixes written to a new file; UIDs kept

After a fixer, its check runs again: pass → fixed_by is set; fail → the next fixer is tried. A fixer that raises is recorded as FIX_FAILED. Image fixers act on QC issues, so they do not run with qc="off".

PyTorch and MONAI

from radreader.torch import to_tensor
x = to_tensor(radreader.read(path))                 # (1, H, W) float32

import monai as mn
from radreader.monai import RadReader
load = mn.transforms.LoadImageD(keys="img", reader=RadReader(out_range=(-1, 1)))

RadReader gives (W, H) by default (swap_ij=True), like MONAI's ITKReader and PydicomReader, so it drops into a pipeline that already transposes. The 4x4 affine holds the spacing (DX / MG files usually have no position). It is picklable for DataLoader workers.

Speed

All pixel math (modality, VOI, flip, padding, output range) is one lookup table over every possible raw value, then out = lut[raw]. The table is cached by PixelParams. Each file is read once. Decoding is most of the time (about 75% for JPEG Lossless mammograms).

Design

Three stages, so 3-D can be added without a rewrite: params = parse(ds) (header → PixelParams), raw = decode(ds), pixels = render(raw, params) (any array shape). See docs/reading_steps.md and docs/plan_full.md.

License

Apache-2.0