(Python) utility to convert medical images to jpg and png
Project description
# med2image
## Quick Overview
* Convert DICOM or NIfTI to jpg or png
## Overview
<tt>med2image</tt> is a simple Python utility that converts medical image formatted files to more visual friendly ones, such as <tt>png</tt> and <tt>jpg</tt>.
Currently, NIfTI and DICOM input formats are understood, while any graphical output type that is supported by <tt>matplotlib</tt> can be generated.
## Dependencies
Make sure that the following dependencies are installed on the host system:
* 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)
### FNNDSC script checkout
An alternate method of installing this script and <b>some</b> of its internal dependencies (<tt>error.py, dgmsocket.py, message.py</tt>) is to checkout the FNNDSC github scripts repository, https://github.com/FNNDSC/scripts.
## Command line arguments
-i|--inputFile <inputFile>
Input file to convert. Typically a DICOM file or a nifti volume.
[-d|--outputDir <outputDir>]
The directory to contain the converted output image files.
-o|--outputFileStem <outputFileStem>
The output file stem to store conversion. If this is specified
with an extension, this extension will be used to specify the
output file type.
SPECIAL CASES:
For DICOM data, the <outputFileStem> can be set to the value of
an internal DICOM tag. The tag is specified by preceding the tag
name with a percent character '%', so
-o %ProtocolName
will use the DICOM 'ProtocolName' to name the output file. Note
that special characters (like spaces) in the DICOM value are
replaced by underscores '_'.
Multiple tags can be specified, for example
-o %PatientName%PatientID%ProtocolName
and the output filename will have each DICOM tag string as
specified in order, connected with dashes.
A special %inputFile is available to specify the input file that
was read (without extension).
[-t|--outputFileType <outputFileType>]
The output file type. If different to <outputFileStem> extension,
will override extension in favour of <outputFileType>.
[-s|--sliceToConvert <sliceToConvert>]
In the case of volume files, the slice (z) index to convert. Ignored
for 2D input data. If a '-1' is sent, then convert *all* the slices.
If an 'm' is specified, only convert the middle slice in an input
volume.
[-f|--frameToConvert <sliceToConvert>]
In the case of 4D volume files, the volume (V) containing the
slice (z) index to convert. Ignored for 3D input data. If a '-1' is
sent, then convert *all* the frames. If an 'm' is specified, only
convert the middle frame in the 4D input stack.
[--showSlices]
If specified, render/show image slices as they are created.
[--reslice]
For 3D data only. Assuming [i,j,k] coordinates, the default is to save
along the 'k' direction. By passing a --reslice image data in the 'i' and
'j' directions are also saved. Furthermore, the <outputDir> is subdivided into
'slice' (k), 'row' (i), and 'col' (j) subdirectories.
[-x|--man]
Show full help.
[-y|--synopsis]
Show brief help.
## NIfTI conversion
Both 3D and 4D NIfTI input data are understood. In the case of 4D NIfTI, a specific <b>frame</b> can be specified in conjunction with a specific <b>slice</b> index. In most cases, only a <b>slice</b> is required since most NIfTI data is 3D. Furthermore, all slices can be converted, or just the middle one.
### Examples
### All slices in a volume
To convert <b>all</b> slices in an input NIfTI volume called <tt>vol.nii</tt>, to save the results in a directory called <tt>out</tt> and to use as output the file stem name <tt>image</tt>, do
```med2image.py -i vol.nii -d out -o image.jpg -s -1```
or equivalently and more verbosely,
med2image.py --inputFile vol.nii --outputDir out \
--outputFileStem image --outputFileType jpg \
--sliceToConvert -1
This will create the following files in <tt>out</tt>
```
image-slice000.jpg
image-slice001.jpg
image-slice002.jpg
image-slice003.jpg
image-slice004.jpg
image-slice005.jpg
image-slice006.jpg
image-slice007.jpg
...
image-slice049.jpg
image-slice050.jpg
image-slice051.jpg
image-slice052.jpg
image-slice053.jpg
```
### Convert only a single slice
Mostly, you'll probably 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 a <tt>m</tt> to <tt>--sliceToConvert</tt>
```med2image.py -i input.nii -o input.jpg -s m```
or, again, slightly more verbosely and with an outputDirectory specifier
```med2image.py -i input.nii -d out -o vol --outputFileType jpg --sliceToConvert m```
Alternatively a specific slice index can be converted. Use
```med2image.py -i input.nii -d out -o vol --outputFileType jpg --sliceToConvert 20```
to convert only the 20th slice of the volume.
## DICOM conversion
### Convert a single DICOM file
To convert a single DICOM file called <tt>slice.dcm</tt> to <tt>slice.jpg</tt>, do:
```med2image.py -i slice.dcm -o slice.jpg```
which will create a single file, <tt>slice.jpg</tt> in the current directory.
### Convert all DICOMS in a directory/series
To convert all the DICOMS in a directory, simply specifiy a '-1' to the sliceIndex:
```med2image.py -i inputDir/slice.dcm -d outputDir -o slice.jpg -s -1```
Note that this assumes all the DICOM files in the directory <tt>inputDir</tt> belong to the same series.
## Multiple Direction Reslicing
By default, only the slice (or slices) in the acquisition direction are converted. However, by passing a <tt>-r</tt> to the script, all dimensions are converted. Since the script does not know the anatomical orientation of the image, the directions are simply labeled <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>.
The <tt>z</tt> direction is the original acquistion (slice) direction, while <tt>x</tt> and <tt>y</tt> correspond to planes normal to the row and column directions.
Converted images are stored in subdirectories labeled <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>.
## Quick Overview
* Convert DICOM or NIfTI to jpg or png
## Overview
<tt>med2image</tt> is a simple Python utility that converts medical image formatted files to more visual friendly ones, such as <tt>png</tt> and <tt>jpg</tt>.
Currently, NIfTI and DICOM input formats are understood, while any graphical output type that is supported by <tt>matplotlib</tt> can be generated.
## Dependencies
Make sure that the following dependencies are installed on the host system:
* 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)
### FNNDSC script checkout
An alternate method of installing this script and <b>some</b> of its internal dependencies (<tt>error.py, dgmsocket.py, message.py</tt>) is to checkout the FNNDSC github scripts repository, https://github.com/FNNDSC/scripts.
## Command line arguments
-i|--inputFile <inputFile>
Input file to convert. Typically a DICOM file or a nifti volume.
[-d|--outputDir <outputDir>]
The directory to contain the converted output image files.
-o|--outputFileStem <outputFileStem>
The output file stem to store conversion. If this is specified
with an extension, this extension will be used to specify the
output file type.
SPECIAL CASES:
For DICOM data, the <outputFileStem> can be set to the value of
an internal DICOM tag. The tag is specified by preceding the tag
name with a percent character '%', so
-o %ProtocolName
will use the DICOM 'ProtocolName' to name the output file. Note
that special characters (like spaces) in the DICOM value are
replaced by underscores '_'.
Multiple tags can be specified, for example
-o %PatientName%PatientID%ProtocolName
and the output filename will have each DICOM tag string as
specified in order, connected with dashes.
A special %inputFile is available to specify the input file that
was read (without extension).
[-t|--outputFileType <outputFileType>]
The output file type. If different to <outputFileStem> extension,
will override extension in favour of <outputFileType>.
[-s|--sliceToConvert <sliceToConvert>]
In the case of volume files, the slice (z) index to convert. Ignored
for 2D input data. If a '-1' is sent, then convert *all* the slices.
If an 'm' is specified, only convert the middle slice in an input
volume.
[-f|--frameToConvert <sliceToConvert>]
In the case of 4D volume files, the volume (V) containing the
slice (z) index to convert. Ignored for 3D input data. If a '-1' is
sent, then convert *all* the frames. If an 'm' is specified, only
convert the middle frame in the 4D input stack.
[--showSlices]
If specified, render/show image slices as they are created.
[--reslice]
For 3D data only. Assuming [i,j,k] coordinates, the default is to save
along the 'k' direction. By passing a --reslice image data in the 'i' and
'j' directions are also saved. Furthermore, the <outputDir> is subdivided into
'slice' (k), 'row' (i), and 'col' (j) subdirectories.
[-x|--man]
Show full help.
[-y|--synopsis]
Show brief help.
## NIfTI conversion
Both 3D and 4D NIfTI input data are understood. In the case of 4D NIfTI, a specific <b>frame</b> can be specified in conjunction with a specific <b>slice</b> index. In most cases, only a <b>slice</b> is required since most NIfTI data is 3D. Furthermore, all slices can be converted, or just the middle one.
### Examples
### All slices in a volume
To convert <b>all</b> slices in an input NIfTI volume called <tt>vol.nii</tt>, to save the results in a directory called <tt>out</tt> and to use as output the file stem name <tt>image</tt>, do
```med2image.py -i vol.nii -d out -o image.jpg -s -1```
or equivalently and more verbosely,
med2image.py --inputFile vol.nii --outputDir out \
--outputFileStem image --outputFileType jpg \
--sliceToConvert -1
This will create the following files in <tt>out</tt>
```
image-slice000.jpg
image-slice001.jpg
image-slice002.jpg
image-slice003.jpg
image-slice004.jpg
image-slice005.jpg
image-slice006.jpg
image-slice007.jpg
...
image-slice049.jpg
image-slice050.jpg
image-slice051.jpg
image-slice052.jpg
image-slice053.jpg
```
### Convert only a single slice
Mostly, you'll probably 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 a <tt>m</tt> to <tt>--sliceToConvert</tt>
```med2image.py -i input.nii -o input.jpg -s m```
or, again, slightly more verbosely and with an outputDirectory specifier
```med2image.py -i input.nii -d out -o vol --outputFileType jpg --sliceToConvert m```
Alternatively a specific slice index can be converted. Use
```med2image.py -i input.nii -d out -o vol --outputFileType jpg --sliceToConvert 20```
to convert only the 20th slice of the volume.
## DICOM conversion
### Convert a single DICOM file
To convert a single DICOM file called <tt>slice.dcm</tt> to <tt>slice.jpg</tt>, do:
```med2image.py -i slice.dcm -o slice.jpg```
which will create a single file, <tt>slice.jpg</tt> in the current directory.
### Convert all DICOMS in a directory/series
To convert all the DICOMS in a directory, simply specifiy a '-1' to the sliceIndex:
```med2image.py -i inputDir/slice.dcm -d outputDir -o slice.jpg -s -1```
Note that this assumes all the DICOM files in the directory <tt>inputDir</tt> belong to the same series.
## Multiple Direction Reslicing
By default, only the slice (or slices) in the acquisition direction are converted. However, by passing a <tt>-r</tt> to the script, all dimensions are converted. Since the script does not know the anatomical orientation of the image, the directions are simply labeled <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>.
The <tt>z</tt> direction is the original acquistion (slice) direction, while <tt>x</tt> and <tt>y</tt> correspond to planes normal to the row and column directions.
Converted images are stored in subdirectories labeled <tt>x</tt>, <tt>y</tt>, and <tt>z</tt>.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
med2image-0.1.tar.gz
(25.7 kB
view hashes)