(Python) utility to convert mgz volumes to jpg and png
Project description
Quick Overview
Convert .mgz inputs to jpg or png outputs.
Overview
mgz2imgslices is a simple Python utility that fiters “labels” from mgz volume files and saves each label set as slices of (by default) png files, organized into a series of directories, one per label set.
An mgz format file simply contains a 3D volume data structure of image values. Often these values are interpreted to be image intensities. Sometimes, however, they can be interpreted as label identifiers. Regardless of the interpretation, the volume image data is simply a number value in each voxel of the volume.
This script will scan across the input mgz volume, and for each voxel value create a new output directory. In that directory will be a set of (typically) png images, one per slice of the original volume. These images will only contain the voxels in the original dataset that all had that particular voxel value.
In this manner, mgz2imgslices can also be thought of as a dynamic filter of an mgz volume file that filters each voxel value into its own output directory of png image files.
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)
numpy : (to support large, multidimensional arrays and matrices)
imageio : (interface to read and write image data)
pandas : (data manipulation and analysis)
re : (support for regular expressions)
time : (support for various time related functions)
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.
pip3 install mgz2imgslices
Docker container
We also offer a docker container of mgz2imgslices as a ChRIS-conformant platform plugin here https://github.com/FNNDSC/pl-mgz2imgslices – please consult that page for information on running the dockerized container. The containerized version exposes a similar CLI and functionality as this module.
How to Use
mgz2imgslices needs at a minimum the following required command line arguments:
-i | --inputFile <inputFile>: The input .mgz file to convert.
-d | --outputDir <outputDir>: The output directory. This in turn will contain several subdirectores, one per image voxel value in the input mgz file. Each of these sub directories will contain png files, filtered to that voxel value.
Examples
First, let’s create a directory, say devel wherever you feel like it. We will place some test data in this directory to process with this plugin.
cd ~/
mkdir devel
cd devel
export DEVEL=$(pwd)
Now, we need to fetch sample MGZ data.
Pull MGZ data
We provide a sample directory of a few .mgz volumes here. (https://github.com/FNNDSC/mgz_converter_dataset.git)
Clone this repository (mgz_converter_dataset) to your local computer.
git clone https://github.com/FNNDSC/mgz_converter_dataset.git
Make sure the mgz_converter_dataset directory is placed in the devel directory.
Make sure your current working directory is devel. At this juncture it should contain mgz_converter_dataset.
Create an output directory named results in devel.
mkdir results && chmod 777 results
EXAMPLE-1
Run mgz2imgslices using the following command. Change the arguments according to your need.
mgz2imgslices
-I ${DEVEL}/mgz_converter_dataset/100307/ \
-inputFile aparc.a2009s+aseg.mgz \
--outputDir ${DEVEL}/results/ \
--outputFileStem sample \
--outputFileType jpg \
--label label \
--wholeVolume FullVolume \
--lookuptable __val__ \
--skipLabelValueList 0,4,7
The skipLabelValueList will skip any voxels in the input mgz that have numerical values of, in this case, 0, 4, 7. Note that each output filtered directory will have a name prefix string of label and should appear something similar to:
results/label-002/sample-000.jpg
...
results/label-002/sample-00255.jpg
...
...
results/label-0012175/sample-000.jpg
...
results/label-0012175/sample-00255.jpg
EXAMPLE-2
This example uses the “FreeSurferColorLUT.txt” file to lookup textual names of the voxel values and use more descriptive string for the directory stem.
Make sure that your LUT.txt file is present in the ([-I] [--inputDir]) (in this case: ${DEVEL}/mgz_converter_dataset/100307/) and follows the format of the FreeSurferColorLUT.txt file. (https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT)
Run mgz2imgslices using the following command. Change the arguments according to your need.
mgz2imgslices
-I ${DEVEL}/mgz_converter_dataset/100307/ \
-inputFile aparc.a2009s+aseg.mgz \
--outputDir ${DEVEL}/results/ \
--outputFileStem sample \
--outputFileType jpg \
--label label \
--wholeVolume FullVolume \
--lookuptable FreeSurferColorLUT.txt \
--skipLabelValueList 0,4,7
As above, this will skip some values in the input mgz file and create filtered directories in the output. However, instead of naming the output directories with the numerical value of the filtered (labelled) voxel value, the directory names will be looked up in the lookuptable file which associates a given voxel numerical value with a text name.
Note that as above also, the output filtered directories are prefixed in this case with the text string label.
results/label-Left-Cerebral-White-Matter/sample-000.jpg
...
results/label-Left-Cerebral-White-Matter/sample-00255.jpg
...
...
results/label-ctx_rh_S_temporal_transverse/sample-000.jpg
...
results/label-ctx_rh_S_temporal_transverse/sample-00255.jpg
Command Line Arguments
ARGS [-i] [--inputFile] <inputFile> Input file to convert. Should be a .mgz file. [-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. [-t] [--outputFileType] <outputFileType> The output file type. If different to <outputFileStem> extension, will override extension in favour of <outputFileType>. Should be a 'png' or 'jpg'. [--label] <prefixForLabelDirectories> Adds a prefix to each Label directory name. [-n] [--normalize] If specified, will normalize the output image pixels to 0 and 1 values. [-l] [--lookuptable] <LUTcolumnToNameDirectories> Specifies if the label directories that are created should be named according to Label Number or Label Name. Can be wither "__val__" or <LUTFilename.txt> provided by user from the inputdir Default is "__val__" which is Label Numbers. [-s] [--skipLabelValueList] <ListOfLabelNumbersToSkip> If specified as a comma separated string of label numbers, will not create directories of those label numbers. [-w] [--wholeVolume] If specified, creates a diretory called "WholeVolume" (within the outputdir) containing PNG/JPG files including all labels. [-h] [--help] If specified, show help message and exit. [--json] If specified, show json representation of app and exit. [--man] If specified, print (this) man page and exit. [--meta] If specified, print plugin meta np_data and exit. [--savejson <DIR>] If specified, save json representation file to DIR and exit. [-v <level>] [--verbosity <level>] Verbosity level for app. Not used currently. [--version] If specified, print version number and exit. [-y] [--synopsis] Show short synopsis.
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.