mgz2imagetree 1.1.8
Quick Overview
Recursively walk down a directory tree and extract MGZ
labels,
creating image slices for each individual label preserving directory structure in output tree.
Overview
mgz2imagetree
is a simple Python utility that recursively walks down an inputdir
, extracts all the mgz
files, filters "labels" from mgz
volume files and saves each label set as slices of (by default) png
files (using the Python utility called mgz2imgslices
), organized into a series of directories, one per label set for each subject, and replicates the entire direcotry structure in the outputdir
.
This utility also allows to pass all the CLI arguments that are specific to mgz2imgslices
.
NOTE:
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.
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/MGZ files)
numpy
: (to support large, multidimensional arrays and matrices)
imageio
: (interface to read and write image data)
pftree
: Create a dictionary representation of a filesystem hierarchy.
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 mgz2imagetree
How to Use
mgz2imagetree
needs at a minimum the following required command line arguments:
-
[-I|--inputDir <inputDir>]
: Input directory to examine. By default, the first file in this directory is examined for its tag information. -
[-O|--outputDir <outputDir>]
: The output root directory that will contain a tree structure identical to the input directory, and each "leaf" node will contain the analysis results. -
[-o|--outputFileStem <outputFileStem>]
: The output file stem to store data. This should not have a file extension, or rather, any "." in the name are considered part of the stem and are not considered extensions. -
[--feature <MGZFileToConvertToLabelledSegments>]
: The feature file containing the cortical strip which needs to be filtered into it constituent cortical segments usingmgz2imgslices
-
[--imageFile <MGZFileImageFile>]
: The raw 3D mgz image file that needs to be split and stored as slices in the corresponding subject's output directory.
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.
mgz
data
Pull - 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 containmgz_converter_dataset
. - Create an output directory named
results
indevel
.
mkdir results && chmod 777 results
EXAMPLE 1
- Run
mgz2imgslices
using the following command. Change the arguments according to your need.
mgz2imagetree
--inputDir ${DEVEL}/mgz_converter_dataset/ \
--outputDir ${DEVEL}/results/ \
--feature aparc.a2009s+aseg.mgz \
--imageFile brain.mgz \
--outputFileStem sample \
--outputFileType jpg \
--label label \
--wholeVolume FullVolume \
--rawDirName RawImageDirectory \