This is the code repository for Nonparametric Density Flows for MRI Intensity Normalisation, presented at the MICCAI 2018 conference. We have also made available an extended manuscript on arXiv, including some mathematical proofs and additional experimental results.
If you would like to use this tool, please consider citing our work according to the following BibTeX entry:
@inproceedings{castro2018ndflow,
title = {Nonparametric Density Flows for {MRI} Intensity Normalisation},
author = {Castro, Daniel C. and Glocker, Ben},
year = {2018}
booktitle = {Medical Image Computing and Computer-Assisted Intervention -- MICCAI 2018},
pages = {206--214},
series = {LNCS},
volume = {11070},
publisher = {Springer, Cham},
address = {Granada, Spain},
doi = {10.1007/978-3-030-00928-1_24},
eprint = {arXiv:1806.02613},
}
- Python 3.6 (not tested with earlier versions)
numpy
scipy
SimpleITK
(only for the scripts)matplotlib
(only for the scripts and if you use the--interactive
option)
Simply clone the Git repository, cd
into the directory and run pip install .
.
The most important functionality is made available in the ndflow
namespace, which includes the
following functions (see corresponding docstrings in ndflow/api.py
for details):
ndflow.estimate
: GMM fittingndflow.align
: affine alignment between GMMsndflow.match
: minimise L2 divergence between GMMsndflow.warp
: simulate diffeomorphic flow between two GMM densities
These functions should be used if dealing directly with numpy
arrays and
ndflow.models.mixture.MixtureModel
instances.
We mirror the API with scripts that also handle I/O (with SimpleITK) and workflow-specific tasks
like GMM averaging, available in the ndflow.tools
package:
estimate.py
: fit GMMs to one or a collection of image filesaverage.py
: compute an 'average' GMM out of a collection of GMMsmatch.py
: match one or a collection of GMMs to a target GMMwarp.py
: transform intensities in one or a collection of images according to the respective matched GMMs
These scripts wrap functions which may also be used programmatically.
If ndflow
is installed with pip
, these scripts are directly accessible as terminal commands:
ndflow-estimate
, ndflow-average
, ndflow-match
, and ndflow-warp
, respectively. These are
the usage instructions as obtained with the -h
option:
usage: ndflow-estimate [-h] [-b BACKGROUND] [-l LEVELS] input output
NDFlow - density estimation
positional arguments:
input input image file or directory. If a directory is
given, will process all image files inside it.
output output directory to store density estimation results
(*.pickle).
optional arguments:
-h, --help show this help message and exit
-b BACKGROUND, --background BACKGROUND
threshold for background intensities. If given, voxels
with intensity <= background will be excluded,
otherwise the entire image will be used.
-l LEVELS, --levels LEVELS
number of levels at which to quantise the intensities.
If omitted, data will be cast to integer.
usage: ndflow-average [-h] [-i] input output
NDFlow - GMM averaging
positional arguments:
input input GMMs directory
output output GMM file
optional arguments:
-h, --help show this help message and exit
-i, --interactive plot the results
usage: ndflow-match [-h] [-o OUTPUT] source target
NDFlow - density matching
positional arguments:
source source GMM file or directory. If a directory is given,
will process all GMM files inside it.
target target GMM file
optional arguments:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
output directory. Defaults to source directory.
usage: ndflow-warp [-h] [-m MATCH] input output
NDFlow - image intensity warping
positional arguments:
input input image file or directory. If a directory is
given, will process all image files inside it.
output output image directory. Should be different from input
directory, as normalised image(s) will be saved with
the same filename.
optional arguments:
-h, --help show this help message and exit
-m MATCH, --match MATCH
matches directory. Defaults to input image directory.
imgs_dir
: Input images directorygmms_dir
: Directory for the estimated Gaussian mixture models (GMMs)average_gmm_file
: File path for the average GMM (i.e. 'intensity atlas')matches_dir
: Directory for density matching resultsout_imgs_dir
: Normalised images directory (different fromimgs_dir
, as images will be saved with the same filename)
> ndflow-estimate <imgs_dir> <gmms_dir>
> ndflow-average <gmms_dir> <average_gmm_file>
> ndflow-match <gmms_dir> <average_gmm_file> -m <matches_dir>
> ndflow-warp <imgs_dir> <matches_dir> -o <out_imgs_dir>
src_img_file
: Source image filetgt_img_file
: Target image filesrc_gmm_file
: Source GMM file (in source image directory withsrc_img_file
prefix)tgt_gmm_file
: Target GMM file (in target image directory withtgt_img_file
prefix)out_img_dir
: Normalised image directory (different fromimgs_dir
, as image will be saved with the same filename)
> ndflow-estimate <src_img_file>
> ndflow-estimate <tgt_img_file>
> ndflow-match <src_gmm_file> <tgt_gmm_file>
> ndflow-warp <src_img_file> <out_img_dir>