Medical images via MedVol

napari reader and writer for medical images (NIfTI, NRRD, MetaImage, MGH/MGZ, DICOM) through MedVol, with correct physical geometry and orientation.

  • Karol Gotkowski

PyPI Python Version Tests napari hub License

A napari reader and writer for medical images: NIfTI, NRRD, MetaImage, MGH/MGZ and DICOM, shown where they physically are and in the orientation radiologists expect. Despite its name it reads every format MedVol reads; MLArray (.mla) files are opened by napari-mlarray.

pip install napari-nifti            # into an existing napari installation
pip install "napari-nifti[all]"     # with napari and Qt

Drag files into napari or use File > Open. For a DICOM series, open its folder (File > Open Folder).

What you see

MedVol reads the file faithfully (its own geometry rules, every ambiguity resolved by a named policy and reported), and napari-mlarray turns the result into layers. NIfTI, NRRD, MetaImage, MGH, DICOM and .mla files therefore look the same and overlay correctly:

plane (viewer.dims.order) screen up screen right
axial (0, 1, 2) anterior patient left (radiological)
coronal (1, 0, 2) superior patient left
sagittal (2, 0, 1) superior posterior
  • Every voxel is placed exactly from the file's geometry, whatever the storage order (axial, sagittal, flipped, RAS or LPS). The world axes point to I, P, L (labelled on the dims sliders), and the 3-D view is not mirrored.
  • Oblique images are resampled onto world-aligned axes for display; rotations below a tenth of a voxel over the image (scanner round-off) are ignored. See napari-mlarray for the neurological convention and other options.
  • Values are shown physically: scaling (NIfTI scl_slope, DICOM rescale) is applied, e.g. Hounsfield units.
  • Label maps become Labels layers: DICOM SEG with names, colours and codes, and integer images whose values look like class ids (0, 1, 2, ... with few gaps, at most 256 of them), such as nnU-Net or TotalSegmentator segmentations. napari_nifti.set_labels("never" | "always" | "auto") or NAPARI_NIFTI_LABELS changes that.
  • A DICOM folder with several series or stacks opens as one layer each. MedVol's warnings (e.g. qform and sform disagree) are shown as napari notifications; the full report is in layer.metadata["medvol"].

Saving

File > Save Selected Layer(s) writes Image and Labels layers as .nii.gz, .nii, .nrrd, .nhdr, .mha, .mhd, .mgz or .mgh:

  • A layer opened with this plugin is written in its original array order. Saved to the format it came from, its header is kept (descriptions, extensions, custom keys); only what the image defines (geometry, size, data type) is rewritten. The layer's current position is saved, so a layer you moved stays where it is shown.
  • Saved to another format, the geometry and values are converted and what the format cannot store is reported.
  • New layers (labels you painted on an image) are written in the image's patient frame, so they line up with it in any other tool.

DICOM is read but not written from napari: writing a DICOM series or SEG needs the original or referenced series, which MedVol supports from Python (medvol.write(image, "seg.dcm", reference="ct_dir/")).

Python

import napari
from napari_nifti import read_layers

viewer = napari.Viewer()
for data, kwargs, layer_type in read_layers("ct.nii.gz", nifti_form="qform"):   # MedVol policies as keywords
    getattr(viewer, f"add_{layer_type}")(data, **kwargs)

Development

pip install -e ".[test]"
pytest

The tests check every voxel's position for NIfTI (RAS, LPS, sagittal, mirrored) and NRRD written by nibabel and pynrrd, MetaImage and MGZ, a DICOM series, the label rule and save round trips.

License

Distributed under the terms of the Apache Software License 2.0.

    

This repository is developed and maintained by the Applied Computer Vision Lab (ACVL) of Helmholtz Imaging and the Division of Medical Image Computing at DKFZ.

Version:

  • 1.0.0

Last updated:

  • 2026-11-06

First released:

  • 2023-04-18

License:

  • Apache

Supported data:

  • Information not submitted

Plugin type:

Python versions supported:

Operating system:

  • Information not submitted

Requirements:

  • numpy
  • medvol[dicom]>=1.0.1
  • napari-mlarray>=1.1.0
  • napari[all]>=0.6; extra == "all"
  • pytest; extra == "test"
  • napari[qt]>=0.6; extra == "test"
Website by the napari team, original design by CZI.