Skip to main content

vicom

The vicom package is our tool for handling MRI data.

The dominant standard for medical image data is DICOM. However, due to its age and number of modalities, vendors, use cases, ..., dealing with DICOMs from numerous sources is messy to work with. With vicom, we provide a number of methods to load MR image data from different file formats into a more usable datastructure called a Volume.

A Volume represents a 3D volume of MRI data. Essentially, the datastructures stores the 3D numpy array of voxel data, a 4x4 numpy array of the affine transformation matrix, and a long list of "metadata", such as patient, study, series, and instance identifiers, or acquisition parameters. We make a number of simplifying assumptions about the data we work with in order to be able to simplify the DICOM standard into our simpler Volume format.

Key features and goals of vicom:

  • Conversion of medical image data (MRI data) in DICOM, Nifti, or SITK format into the Volume datastructure.
    • Note that only DICOM files encode relevant metadata (patient information, acquisition information, ...). Therefore, Volumes loaded from Nifti files will be very sparse, and mostly only contain pixel data and affine matrix information.
  • Export of a Volume into DICOM (Lossless conversion DICOM->Volume->DICOM->Volume->...)
  • Support for MRI images (T2, T1, DWI acquisitions), 3D segmentation masks, and 3D parametric maps (as created by mismo fitting procedures)

Installation​

The repository comes with a makefile script that can be run: make install executes pip install -e . and thereby installs the package to your local environment in editable mode. make install-dev additionally installs the dependencies required for development and initializes pre-commit hooks.

Setup​

The package requires a .env file in the root directory of the repository. In it you should declare a variable BASE_PATH to a path where the package can store temporary files, i.e. BASE_PATH=/path/to/base_folder.

Developing vicom​

Does vicom not work for your image data?

In case you have DICOM data at hand: the dicom submodule is your friend. Your DICOM data is likely coming from a new scanner, which stores data differently. Try determining where the attributes you need to read are stored and define a new VolumeScheme (in vicom.dicom.read).

In case you're dealing with an entirely new image format, you'll need to write a load_volumes_from_XYZ(...) -> Volume function.