Package: med2image
Quick OverviewConvertDICOMorNIfTIinputs tojpgorpngoutputs.Overviewmed2imageis a simple Python3 utility that converts medical image formatted files (such asDICOMandNifTI) to more web friendly ones, such aspngandjpg.Currently,NIfTIandDICOMinput formats are understood, while any graphical output type that is supported by matplotlib can be generated.At presentmed2imagedoes not convertDICOMtoNifTI, but this is planned for a future release.DependenciesMake sure that the following dependencies are installed on your host system (or even better, apython3virtual 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 injpgformat)AssumptionsThis document assumes UNIX conventions and abashshell. The script should work fine under Windows, but we have not actively tested on that platform – our dev envs are Linux Ubuntu and macOS.InstallationPython moduleOne method of installing this script and all of its dependencies is by fetching it fromPyPI.pip3installmed2imageShould you get an error aboutpython3-tknot installed, simply do (for example on Ubuntu):sudoapt-getupdatesudoapt-getinstall-ypython3-tkDocker containerWe also offer a docker container ofmed2imageas a ChRIS-conformant platform plugin herehttps://github.com/FNNDSC/pl-med2img(see also the closely relatedhttps://github.com/FNNDSC/pl-dcm2imgthat 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 Usemed2imageneeds at a minimum (some of) the following required command line arguments:-i|--inputFile<inputFile>: Input file to convert. Typically aDICOMfile or aNifTIvolume.--inputFileSubStr<substr>: A short hand trick to specify theinputFile. By only specifying a sub string that identifies the file, the first file in theinputDirthat contains the sub string is tagged as theinputFile. 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:# 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-ivol.nii-dout# 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-ifile.dcm-doutNIfTIdetailsNOTE:NifTIis typically avolumeformat. OneNIfTI(.nii) volume contains multipleslices. Converting aNifTIvolume results in multiple.jpgor.pngresults.NIfTIinput data can be in 2 forms:3D : The.niivolume contains multiple 2D slices4D : The.niifile contains multiple 3D volumes that each contain multiple 2D slicesmed2imageunderstands both types of inputs.PullNIfTIThe input should be aNIfTIvolume with extension.nii. We provide a sample volume herehttps://github.com/FNNDSC/SAG-anon-nii.gitClone this repository (SAG-anon-nii) to your local computer.gitclonehttps://github.com/FNNDSC/SAG-anon-nii.gitConvertNIfTINOTE:If--outputDir|-dis not provided, outputs are created in thecurrentdirectory.if--sliceToConvertis not provided,allthe slices of the.niivolume are converted.Both 3D and 4DNIfTIinput data are understood. In the case of 4DNIfTI, a specific frame (--frameToConvert) can be additionally provided in conjunction with a specific slice index. Conversion options include:allslices (default)middleslice only, with the CLI--sliceToConvertmsomeSpecificSlice, with the CLI--sliceToConvert<N>CASE 1: All slices in a volumeNow, let’s convert all slices in the inputNIfTIvolumeSAG-anon.nii, and save the results to a nested subdirnifti-results/all-slices. We’ll use as output file name stemsampleand convert tojpg.Assuming you have cloned theSAG-anon-niirepo and assuming that you havemed2imageon your UNIX shell path,med2image-iSAG-anon-nii/SAG-anon.nii\-dnifti-results/all-slices\-osample.jpg-s-1or equivalently and more verbosely,med2image--inputFileSAG-anon-nii/SAG-anon.nii\--outputDirnifti-results/all-slices\--outputFileStemsample--outputFileTypejpg\--sliceToConvert-1resulting innifti-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.jpgNote that even if the nested output directory structure does not exist,med2imagewill create it for you.Case 2: Convert only a single sliceOften 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 anmto--sliceToConvert(or-sm):med2image-iSAG-anon-nii/SAG-anon.nii\-dnifti-results/middle-slice\-osample--outputFileTypejpg\--sliceToConvertmresulting innifti-results/middle-slice/sample-slice096.jpgAlternatively a specific slice index can be converted. Usemed2image-iSAG-anon-nii/SAG-anon.nii\-dnifti-results/specific-slice\-osample\--outputFileTypejpg\--sliceToConvert20to convert only the 20th slice of the volume.resulting innifti-results/specific-slice/sample-slice020.jpgDICOMNOTE:OneDICOM(.dcm) file typically corresponds to one.pngor.jpgfile (slice).Pull DICOMThe input should be aDICOMfile usually with extension.dcmWe provide a sample directory of.dcmimages hereFNNDSC/SAG-anon. (https://github.com/FNNDSC/SAG-anon.git)Clone this repository (SAG-anon) to your local computer.gitclonehttps://github.com/FNNDSC/SAG-anon.gitConvertDICOMNOTE:If--outputDir|-dis not provided, any output(s) are created in the current directory.if--sliceToConvertargument is not specified and if mutipledcmfiles are contained in the input directory with theDICOMinput, then all the.dcmfiles are converted.alternatively, specifying a--convertOnlySingleDICOMwill only convert the DICOM file specified with the--inputFileflag.Convert all DICOMS in a directory/seriesTo convert all theDICOMfiles in a directory, simply specify either--sliceToConvert-1(or just leave out the argument/value pair completely):med2image-iSAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm\-ddicom-results/all-slices\-osample\--outputFileTypejpg\--sliceToConvert-1# OR equivalentlymed2image-iSAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm\-ddicom-results/all-slices\-osample\--outputFileTypejpgresulting indicom-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.jpgConvert a singleDICOMfileMostly, 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 amto –sliceToConvert (or-s m)med2image-iSAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm\-ddicom-results/middle-slice\-osample--outputFileTypejpg\--sliceToConvertmresulting indicom-results/middle-slice/sample.jpgNote that even though the first slice in theSAG-anondirectory was supplied to the script,med2imagenonetheless found and converted the middle slice in the directory.Alternatively a specific slice index can be converted. Usemed2image-iSAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm\-ddicom-results/specific-slice\-osample--outputFileTypejpg\--sliceToConvert20resulting indicom-results/specific-slice/sample.jpgAgain, even though the first slice was supplied to the script,med2imageselected and converted the 20th slice in the directory.Special CasesForDICOMdata, the<outputFileStem>can optionally be set to the value of an internalDICOMtag. The tag is specified by preceding the tag name with a percent character%, so-o%PatientIDwill use theDICOMPatientIDto name the output file. Note that special characters (like spaces) in theDICOMvalue are replaced by underscores ‘_’.med2image-iSAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm\-ddicom-results/tags\-o%PatientID.jpg-smThis will create the following file in thetagssub-directory withindicom-resultsdirectory.dicom-results/tags/1449c1d.jpgMultiple tags can be specified, for example-o%PatientName%PatientID%ProtocolNameand the output filename will have eachDICOMtag string as specified in order, connected with dashes.med2image-iSAG-anon/0001-1.3.12.2.1107.5.2.19.45152.2013030808110258929186035.dcm\-ddicom-results/tags\-o%PatientName%PatientID%ProtocolName.jpg\-smThis will create the following file in thetagssub-directory withindicom-resultsdirectory.dicom-results/tags/anonymized-1449c1d-SAG_MPRAGE_220_FOV.jpgMultiple Direction ReslicingBy default, only the slice (or slices) in the acquisition direction are converted. However, by passing a–resliceto the script, all dimensions are converted. Since the script does not know the anatomical orientation of the image, the directions are simply labeledx,y, andz.Thezdirection is the original acquistion (slice) direction, whilexandycorrespond to planes normal to the row and column directions. Converted images are stored in subdirectories labeledx,y, andz.No interpolation in thexandydirections is performed. This often results in ugly images!NOTE:In case ofDICOMimages, the–resliceoption will work only if all slices in the directory are converted, i.e. converting with--sliceToConvert-1Special Operationsmed2imagealso supports some very basic image processing through a--func<functionName>CLI, which applies some canned transformation on the image. Currently supported is--func invertIntensitieswhich simply inverts the contrast intensity of the source image. Additional functions are planned for future releases.Command Line Arguments[-i|--inputFile <inputFile>]
Input file to convert. Typically a DICOM file or a nifti volume.

[--inputFileSubStr <substr>]
As a convenience, the input file can be determined via a substring
search of all the files in the <inputDir> using this flag. The first
filename hit that contains the <substr> will be assigned the
<inputFile>.

This flag is useful is input names are long and cumbersome, but
a short substring search would identify the file. For example, an
input file of

   0043-1.3.12.2.1107.5.2.19.45152.2013030808110149471485951.dcm

can be specified using ``--inputFileSubStr 0043-``

[-I|--inputDir <inputDir>]
If specified, a directory containing the <inputFile>. In this case
<inputFile> should be specified as relative to <inputDir>.

[-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.

[--convertOnlySingleDICOM]
If specified, will only convert the single DICOM specified by the
'--inputFile' flag. This is useful for the case when an input
directory has many DICOMS but you specifially only want to convert
the named file. By default the script assumes that multiple DICOMS
should be converted en mass otherwise.

[--preserveDICOMinputName]
If specified, use the input DICOM name as the stem of the output
filename, with the specified type ('jpg' or 'png') as the extension.
In the case where [--reslice] is additionally specified, only the
slice or 'z' direction will preserve original DICOM names.

[-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.

[--rot <3DbinVector>]
A per dimension binary rotation vector. Useful to rotate individual
dimensions by an angle specified with [--rotAngle <angle>]. Default
is '110', i.e. rotate 'x' and 'y' but not 'z'. Note that for a
non-reslice selection, only the 'z' (or third) element of the vector
is used.

[--rotAngle <angle>]
Default 90 -- the rotation angle to apply to a given dimension of the
<3DbinVector>.

[--func <functionName>]
Apply the specified transformation function before saving. Currently
support functions:

    * invertIntensities
      Inverts the contrast intensity of the source image.

[--reslice]
For 3D data only. Assuming [x,y,z] coordinates, the default is to save
along the 'z' direction. By passing a --reslice image data in the 'x'
and 'y' directions are also saved. Furthermore, the <outputDir> is
subdivided into 'slice' (z), 'row' (x), and 'col' (y) subdirectories.

[-x|--man]
Show full help.

[-y|--synopsis]
Show brief help.

[--verbosity <level=1>]
Control how chatty med2image is. Set to '0' for blissful silence, '1'
for sane progress and '3' for full information.