med2image 2.6.6

Quick Overview

Convert DICOM or NIfTI inputs to jpg or png outputs.

Overview

med2image is a simple Python3 utility that converts medical image formatted files (such as DICOM and NifTI) to more web friendly ones, such as png and jpg.

Currently, NIfTI and DICOM input formats are understood, while any graphical output type that is supported by matplotlib can be generated.

At present med2image does not convert DICOM to NifTI, but this is planned for a future release.

Dependencies

Make sure that the following dependencies are installed on your host system (or even better, a python3 virtual env):

pfmisc : (a general miscellaneous module for color support, etc)
nibabel : (to read NIfTI files)
pydicom : (to read DICOM files)
matplotlib : (to save data in various image formats)
pillow : (to save data in jpg format)

Assumptions

This document assumes UNIX conventions and a bash shell. The script should work fine under Windows, but we have not actively tested on that platform -- our dev envs are Linux Ubuntu and macOS.

Installation


Python module

One method of installing this script and all of its dependencies is by fetching it from PyPI <https://pypi.org/project/med2image/>_.

.. code:: bash

    pip3 install med2image

Should you get an error about python3-tk not installed, simply do (for example on Ubuntu):

.. code:: bash

    sudo apt-get update
    sudo apt-get install -y python3-tk

Docker container


We also offer a docker container of ``med2image`` as a ChRIS-conformant platform plugin here https://github.com/FNNDSC/pl-med2img (see also the closely related https://github.com/FNNDSC/pl-dcm2img that performs conversions down a directory tree recursively) -- please that reference for information on running the dockerized container. The containerized version exposes a similar CLI and functionality as this module.

How to Use
----------

``med2image`` needs at a minimum (some of) the following required command line arguments:

- ``-i | --inputFile <inputFile>`` : Input file to convert. Typically a ``DICOM`` file or a ``NifTI`` volume.

- ``--inputFileSubStr <substr>`` : A short hand trick to specify the ``inputFile``. By only specifying a sub string that identifies the file, the first file in the ``inputDir`` that contains the sub string is tagged as the ``inputFile``. This saves a user from needing to specify long and cumbersome file names, esp in the case of many DICOM filenames.

- ``-d | --outputDir <outputDir> :`` The directory to contain the converted output image files.

**Example:**

.. code:: bash

    # Convert a NifTI file 'vol.nii' to JPEG and store
    # the results in a dirctory called 'out'.
    # The 'out' dir will contain a set of JPEG
    # images of form 'output-sliceXXX.jpg'.

    med2image -i vol.nii -d out

.. code:: bash

    # Convert a DICOM file 'file.dcm' to JPEG and store
    # the results in a dirctory called 'out'.
    # The 'out' dir will contain a set of JPEG
    # images of form 'output-sliceXXX.jpg'.

    # NOTE! If the directory containing 'file.dcm' contains
    # multiple DICOM files, *ALL* of these will be converted
    # to JPEG. See later for only converting a *single*
    # DICOM file.

    med2image -i file.dcm -d out

``NIfTI`` details
-----------------

**NOTE:** ``NifTI`` is typically a *volume* format. One ``NIfTI`` (``.nii``) volume contains multiple *slices*. Converting a ``NifTI`` volume results in multiple ``.jpg`` or ``.png`` results.

- ``NIfTI`` input data can be in 2 forms:

  - 3D : The ``.nii`` volume contains multiple 2D slices

  - 4D : The ``.nii`` file contains multiple 3D volumes that each contain multiple 2D slices

- ``med2image`` understands both types of inputs.

Pull ``NIfTI``
~~~~~~~~~~~~~~

The input should be a ``NIfTI`` volume with extension ``.nii``. We provide a sample volume here https://github.com/FNNDSC/SAG-anon-nii.git

- Clone this repository (``SAG-anon-nii``) to your local computer.

.. code:: bash

    git clone https://github.com/FNNDSC/SAG-anon-nii.git

Convert ``NIfTI``

NOTE:

If --outputDir | -d is not provided, outputs are created in the current directory.
if --sliceToConvert is not provided, all the slices of the .nii volume are converted.

Both 3D and 4D NIfTI input data are understood. In the case of 4D NIfTI, a specific frame (--frameToConvert) can be additionally provided in conjunction with a specific slice index. Conversion options include:

all slices (default)
middle slice only, with the CLI --sliceToConvert m
someSpecificSlice, with the CLI --sliceToConvert <N>

CASE 1: All slices in a volume ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now, let's convert all slices in the input NIfTI volume SAG-anon.nii, and save the results to a nested subdir nifti-results/all-slices. We'll use as output file name stem sample and convert to jpg.

Assuming you have cloned the SAG-anon-nii repo and assuming that you have med2image on your UNIX shell path,

.. code:: bash

med2image -i SAG-anon-nii/SAG-anon.nii                 \
          -d nifti-results/all-slices                  \
          -o sample.jpg -s -1

or equivalently and more verbosely,

.. code:: bash

med2image --inputFile SAG-anon-nii/SAG-anon.nii         \
          --outputDir nifti-results/all-slices          \
          --outputFileStem sample  --outputFileType jpg \
          --sliceToConvert -1

resulting in

nifti-results/all-slices/sample-slice000.jpg
nifti-results/all-slices/sample-slice001.jpg
nifti-results/all-slices/sample-slice002.jpg
nifti-results/all-slices/sample-slice003.jpg
...
nifti-results/all-slices/sample-slice188.jpg
nifti-results/all-slices/sample-slice189.jpg
nifti-results/all-slices/sample-slice190.jpg
nifti-results/all-slices/sample-slice191.jpg

Note that even if the nested output directory structure does not exist, med2image will create it for you.

Case 2: Convert only a single slice ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Often times, you might only want to convert the "middle" slice in a volume (for example to generate a representative thumbnail of the volume). To do this, simply specify an m to --sliceToConvert (or -s m):

.. code:: bash

med2image -i SAG-anon-nii/SAG-anon.nii    \
          -d nifti-results/middle-slice   \
          -o sample --outputFileType jpg  \
          --sliceToConvert m

resulting in

nifti-results/middle-slice/sample-slice096.jpg

Alternatively a specific slice index can be converted. Use

.. code:: bash

med2image -i SAG-anon-nii/SAG-anon.nii    \
          -d nifti-results/specific-slice \
          -o sample                       \
          --outputFileType jpg            \
          --sliceToConvert 20

to convert only the 20th slice of the volume.

resulting in

nifti-results/specific-slice/sample-slice020.jpg

`DICOM`

NOTE: One DICOM (.dcm) file typically corresponds to one .png or .jpg file (slice).

Pull DICOM


The input should be a ``DICOM`` file usually with extension ``.dcm``

We provide a sample directory of ``.dcm`` images here ``FNNDSC/SAG-anon``. (https://github.com/FNNDSC/SAG-anon.git)

- Clone this repository (``SAG-anon``) to your local computer.

.. code:: bash

    git clone https://github.com/FNNDSC/SAG-anon.git

Convert ``DICOM``

NOTE:

If --outputDir | -d is not provided, any output(s) are created in the current directory.
if --sliceToConvert argument is not specified and if mutiple dcm files are contained in the input directory with the DICOM input, then all the .dcm files are converted.
alternatively, specifying a --convertOnlySingleDICOM will only convert the DICOM file specified with the --inputFile flag.

Convert all DICOMS in a directory/series ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To convert all the DICOM files in a directory, simply specify either --sliceToConvert -1 (or just leave out the argument/value pair completely):

.. code:: bash

med2image -i SAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm   \
          -d dicom-results/all-slices      \
          -o sample                        \
          --outputFileType jpg             \
          --sliceToConvert -1

# OR equivalently

med2image -i SAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm  \
          -d dicom-results/all-slices      \
          -o sample                        \
          --outputFileType jpg

resulting in

dicom-results/all-slices/sample-slice000.jpg
dicom-results/all-slices/sample-slice001.jpg
dicom-results/all-slices/sample-slice002.jpg
dicom-results/all-slices/sample-slice003.jpg
...
dicom-results/all-slices/sample-slice188.jpg
dicom-results/all-slices/sample-slice189.jpg
dicom-results/all-slices/sample-slice190.jpg
dicom-results/all-slices/sample-slice191.jpg

Convert a single DICOM file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Mostly, you'll probably only want to convert the "middle" slice in a DICOM directory (for example to generate a representative thumbnail of the directory). To do this, simply specify a m to --sliceToConvert (or -s m)

.. code:: bash

med2image -i SAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm    \
          -d dicom-results/middle-slice  \
          -o sample --outputFileType jpg \
          --sliceToConvert m

resulting in

dicom-results/middle-slice/sample.jpg

Note that even though the first slice in the SAG-anon

Med2image

Install / Use

README

med2image 2.6.6

Quick Overview

Overview

Dependencies

Assumptions

`DICOM`

Related Skills