FileFormats-Medimage
FileFormats-Medimage is an extension of the FileFormats package for the file formats used in medical imaging, particularly medical imaging research. It provides Python classes for validating, detecting and typing:
- DICOM: single files, and series of them, either in a directory (
DicomDir) or as a set of files (DicomSeries) - NIfTI: NIfTI-1/2, gzipped, with BIDS JSON side-cars,
and with FSL-style diffusion encodings (e.g.
NiftiGzX,NiftiGzBvec) - other image formats from neuroimaging and image analysis tools: Analyze, FreeSurfer MGH, NRRD, MetaImage, VTK, GIPL and GIFTI surfaces
- raw data: MRI k-space and spectroscopy, and PET list-mode, sinograms, count rates and normalisation
- deidentification recipes for the deid package, with declarative side-cars for values that have to be computed
Like the main package, the format classes have no external dependencies. Multi-file
formats, e.g. a NIfTI image with its JSON side-car or a DICOM series, are handled as single
objects that can be validated, copied, moved and hashed together. Classifiers describing
the contents of an image (modality, contrast, anatomy, derivatives) can be attached to
formats to type data more specifically, e.g. NiftiGz[T1w].
Functionality that needs external libraries is implemented in the sister package fileformats-medimage-extras: reading image data and headers, generating sample data, converting between formats (e.g. DICOM to NIfTI with dcm2niix), and deidentifying DICOMs.
See the documentation for the full list of formats and the extras they support.
Installation
FileFormats-Medimage can be installed for Python >= 3.11 from PyPI with
$ python3 -m pip install fileformats-medimage
To read image data and metadata, convert between formats and deidentify images, also install the extras package
$ python3 -m pip install fileformats-medimage-extras
The converters wrap command-line tools that need to be installed separately: dcm2niix for DICOM to NIfTI conversion, and MRtrix3 for conversion to Analyze and MRtrix formats. On Ubuntu, for example
$ sudo apt install libopenjp2-7
$ curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip
$ unzip dcm2niix_lnx.zip && sudo mv dcm2niix /usr/local/bin
$ conda install -c mrtrix3 mrtrix3
(on macOS, use Homebrew in place of apt).
Examples
Instantiating a format class checks that the files are of that format, raising a
FormatMismatchError if they aren't
from pathlib import Path
from fileformats.medimage import DicomSeries, NiftiGzX
series = DicomSeries(Path("/path/to/dicoms").iterdir())
nifti = NiftiGzX("/path/to/sub-01_T1w.nii.gz", "/path/to/sub-01_T1w.json")
nifti.json_file # the BIDS side-car
Formats that aren't registered with IANA are identified by "MIME-like" strings in the
medimage namespace, and classifiers can be attached to formats with square brackets
from fileformats.core import from_mime, to_mime
from fileformats.medimage import NiftiGz, T1w
from_mime("medimage/dicom-series") # -> DicomSeries
to_mime(NiftiGz[T1w], official=False) # -> 'medimage/t1-weighted+nifti-gz'
With the extras installed, headers can be read and data converted
series.metadata["SeriesDescription"] # read with pydicom
nifti = NiftiGzX.convert(series) # converted with dcm2niix
nifti.dims(), nifti.vox_sizes()
Deidentification
All formats holding medical imaging data have a deidentify method, which is implemented
for DICOM in the extras using deid recipes. A recipe can
have side-cars: a .transforms.yaml file declaring the values of the computed var: and
func: references in the recipe (e.g. a salted hash of the patient ID), and a .salt file
holding the key to salt hashes with
from fileformats.medimage import DeidRecipeX
recipe = DeidRecipeX("/path/to/specs/dicom-series.deid").load()
deidentified = series.deidentify("/path/to/output", recipe=recipe)
Each deidentify implementation declares the format its recipe is loaded from with a
Loaded[<recipe format>] annotation, so other packages can add deidentification for their
own formats, with their own recipe formats. See
Deidentification
in the docs.
Contributing
Pull requests adding formats, and implementations of the extras for formats that don't have them yet, are welcome. See the FileFormats developer guide for how formats and extras are defined.
License
This work is licensed under a Creative Commons Attribution 4.0 International License
Acknowledgements
The authors acknowledge the facilities and scientific and technical assistance of the National Imaging Facility, a National Collaborative Research Infrastructure Strategy (NCRIS) capability.
1 maintainer
Metadata
1 maintainer
Release files for fileformats-medimage 0.15.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| fileformats_medimage-0.15.2.tar.gz | 99.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fileformats_medimage-0.15.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 135.0 kB
Release files / fileformats_medimage-0.15.2.tar.gz
| Download URL | fileformats_medimage-0.15.2.tar.gz |
|---|---|
| Size | 99.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
978b49ac9d363d793d909e9cc1b1aa87ae9265965864a1580f466881c05384be
|
|
BLAKE2b-256 checksum How to use checksums |
6935d7dcaa0a6c1f746b42efbccc7cf764b66382eff3806eb7ebf25700586f0b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / fileformats_medimage-0.15.2-py3-none-any.whl
| Download URL | fileformats_medimage-0.15.2-py3-none-any.whl |
|---|---|
| Size | 35.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
486d482754ce3ff4b465ba4a06955994888f06517b1bbccb4223ced89b076f86
|
|
BLAKE2b-256 checksum How to use checksums |
e65b457bf8ae88f8fe45bd8c183ee43e377eb915910ad63a4f85d92317efaceb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
