Package: pydeform
deformdeform is an implementation of an efficient graph-cut based method for dense deformable image registration. If you find this useful, please citehttps://arxiv.org/abs/1810.08427.The method can be used either as a module through Python (recommended) or a standalone executable. Currently no pre-built binaries for the standalone executable are provided, but the Python module (excluding GPU support) can be installed through pip.InstallTo download and install the pre-compiled Python module from pip:pip install pydeformNote: to enable GPU-supported registration you're required to compile the software yourself. See the section below.BuildingPrerequisitesCMake :https://cmake.org/OptionalISPC :https://ispc.github.io/DownloadRetrieve the repository and associated dependencies by running$ git clone https://github.com/simeks/deform.git
$ cd deform
$ git submodule update --init --recursivePython# python setup.py installFlags accepted bysetup.py:--use-cuda: build with CUDA support--use-ispc: build with ISPC support--use-itk: build with ITK support--debug: build with debug symbolsAdditional flags starting with-Dare also recognised and forwarded to CMake. SeeC++ sectionfor available build options.C++Use CMake (>=3.8) to generate build options of your own choosing.If CMake cannot find the ISPC executable on your installation, it is possible
to hint the installation directory with-DISPC_DIR_HINTS, or to specify the
full path to the executable with-DISPC_EXECUTABLE.Build optionsThe build can be configured with the following CMake boolean options:DF_BUILD_TESTS: Build unit tests (default:OFF)DF_BUILD_DOCS: Build Sphinx docs (default:OFF)DF_BUILD_EXECUTABLE: Build registration executable (default:ON)DF_BUILD_PYTHON_WRAPPER: Build Python wrapper (default:OFF)DF_USE_CUDA: Enable CUDA support (default:OFF)DF_USE_ISPC: Enable ISPC support (default:OFF)DF_WARNINGS_ARE_ERRORS: Warnings are treated as errors (default:OFF)DF_BUILD_WITH_DEBUG_INFO: Include debug info in release builds (default:OFF)DF_ENABLE_FAST_MATH: Enable fast math (default:OFF)DF_ITK_BRIDGE: Add support to interoperate with ITK (default:OFF)DF_STACK_TRACE: Print a stack trace on errors (default:OFF)DF_ENABLE_MICROPROFILE: Enablemicroprofileprofiler (default:OFF)DF_ENABLE_NVTOOLSEXT: Enablenvtoolsextprofiler (default:OFF)RunExamplesExamples on how to run the registration can be found in theexamplessubfolder.PythonEverything needed for a simple registration setup is located in thepydeformpackage. The package provides two APIs; first usespydeform.Volumefor handling images and the second usesSimpleITK.pydeform APIThis API usespydeform.Volumewhich is a direct wrapper around the internalVolumeclass used within deform.importpydeformfixed=pydeform.read_volume('fixed_file.nrrd')moving=pydeform.read_volume('moving_file.nrrd')affine_transform=pydeform.read_affine_transform('affine.txt')settings={'pyramid_levels':4}df=pydeform.register(fixed,moving,settings=settings,affine_transform=affine_transform)pydeform.write_volume('result.nrrd',df)SimpleITK APISimpleITKis a simplified layer built on top ofITKthat provides a wide array of different filters and supports a larger variety of image formats compared to thepydeformAPI.The API itself is similar to thepydeformAPI with the exception that it takesSimpleITK.Imageas input for images andSimpleITK.AffineTransformas input for affine transforms. To use this API simply useimport pydeform.sitk_api as pydeform.importSimpleITKassitkimportpydeform.sitk_apiaspydeformfixed=sitk.ReadImage('fixed_file.nrrd')moving=sitk.ReadImage('moving_file.nrrd')affine_transform=sitk.ReadTransform('affine.txt')settings={'pyramid_levels':4}df=pydeform.register(fixed,moving,settings=settings,affine_transform=sitk.AffineTransform(affine_transform))sitk.WriteImage(df,'result.nrrd')SettingsThe Python API provides the sameparametersas the command-line interface. However, rather the specifying the parameters in a YAML-document, the parameters are set by passing adictobject to the registration.settings={'pyramid_levels':4,'levels':{'0':{'max_iteration_count':20}}'image_slots':[{'cost_function':'ncc'}]}pydeform.register(fixed,moving,settings=settings)Command-lineTo perform a registration using the standalone executabledeform registration -p <param file> -f0 <fixed_0> ... -f<i> <fixed_i> -m0 <moving_0> ... -m<i> <moving_i>Argument-f<i> <file>Filename of the i:th fixed image.†-m<i> <file>Filename of the i:th moving image.†-fm <file>Filename of the fixed mask.‡-mm <file>Filename of the moving mask.‡-fp <file>Filename for the fixed landmarks.-mp <file>Filename for the moving landmarks.-d0 <file>Filename for initial deformation field.-a <file>Filename for initial affine transformation-constraint_mask <file>Filename for constraint mask.-constraint_values <file>Filename for constraint values.-rm <file>Filename for regularization weight map-p <file>Filename of the parameter file.-o <file>Filename of the resulting deformation field-j <file>Filename of the resulting jacobian map-t <file>Filename of the transformed moving volume--gpuEnables GPU assisted registration.† Requires a matching number of fixed and moving images.‡ Fuzzy masks in floating point format, whose values denote the confidence on
the image intensity at each point.Parameter file examplepyramid_levels:6pyramid_stop_level:0solver:gcoupdate_rule:additiveconstraints_weight:1000.0landmarks_weight:1.0landmarks_decay:2.0landmarks_stop_level:0block_size:[16,16,16]block_energy_epsilon:1e-7max_iteration_count:-1step_size:0.5regularization_weight:0.1regularization_scale:1.0regularization_exponent:2.0levels:0:regularization_weight:0.11:regularization_weight:0.2step_size:0.01image_slots:# water-resampler:gaussiannormalize:truecost_function:-function:ssdweight:0.3-function:nccweight:0.4radius:2window:cube-function:miweight:0.6sigma:4.5bins:256update_interval:1interpolator:nearest-function:gradient_ssdweight:0.7sigma:1.0# sfcm-resampler:gaussiannormalize:truecost_function:ssdFirst two parameters,pyramid_levelsandpyramid_stop_level, defines the
size of the pyramid and at which level to stop the registration. Each level
halves the resolution of the input volumes. Settingpyramid_stop_levelto > 0
specifies that the registration should not be run on the original resolution
(level 0).solverselects which solver to use for the energy minimization. Available
solvers aregco,gridcut, andicm. Note: deform needs to be compiled withDF_ENABLE_GCOandDF_ENABLE_GRIDCUTforgcoandgridcutto be enabled.update_rulespecifies the update rule for updating the displacement field.
This can be eitheradditiveorcompositive. The first option updates the
displacement field according tou(x) = u(x) + delta, while the second uses
composition, i.e.,u(x) = u(x+delta) + delta. Compositive updates should
produce a more diffeomorphic transformation. Note: compositive updates are
still considered an experimental feature.constraints_weightsets the weight that is applied for constrained voxels. A
really high value means hard constraints while a lower value may allow
constraints to move a certain amount. Cost for constrained voxels are applied
as constraint_weight * squared_distance, where squared_distance is the distance
from the constraint target. See cost function for more info.landmarks_weightsets the weight for the landmark cost term when performing
landmark-based registration.  In order to perform landmark-based registration,
a set of fixed and moving landmarks must be supplied.  The implementation of
the landmark-based unary energy term is inspired to[2], but the cost in
each term of the sum is also proportional to the distance between the current
displacement and the landmark displacement. It is possible to limit the usage
of the landmarks up to a certain height of the resolution pyramid by assigning
tolandmarks_stop_levela value greater than zero.landmarks_decaycontrols
the exponential decay of the landmarks effect with respect to distance in image
space: higher values correspond to faster decay.block_sizesize of the block (in voxels) for the block-wise solver. A block
size of (0,0,0) will result in a single block for the whole volume.block_energy_epsilon, minimum percentage decrease of the block energy
required to accept a solution. Higher epsilon will result in lower run time but
also lower quality.max_iteration_count, maximum number of iterations run on each registration
level. Setting this to -1 (default) allows an unlimited number of iterations.step_size, this is the step size inmmthat the solver will use. Can be a
singlefloatvalue, in that case the same step size will be used in all
directions, or a sequence[sx, sy, sz]of threefloatspecifying the size
for each direction.regularization_weight,regularization_scale, andregularization_exponentcontrol the importance of the regularization term. The cost function is
specified ascost = D + a*((b*R)^c), whereD = Σw_i*C_iis the data term
given by the cost functionsC_iwith weightsw_i,Ris the regularization
term,ais the regularization weight,bthe regularization scale, andcthe regularization exponent.levels, specifies parameters on a per-level basis. The key indicates which
level the parameters apply to, where 0 is the bottom of the resolution pyramid
(last level). The level identifier can not exceedpyramid_levels. Parameters
available on a per-level basis are:constraints_weight,landmarks_weight,block_size,block_energy_epsilon,max_iteration_count,step_size, andregularization_weight.image_slots, specifies how to use the input images.resampleronly supportsgaussianfor now,normalizespecifies whether the volumes should be
normalized before the registration, andcost_functionallows to provide one
or more cost functions to use. Its value can be the name of a single function
(ssdfor squared distance,nccfor normalized cross correlation,mifor
mutual information,gradient_ssdfor squared distance of the gradients), in
which case its weight is assumed to be1.0, otherwise one or multiple
weighted components can be specified by listing each function and its weight.
Each function can accept a set of parameters.The parameters available for each function are:ssd: no parameters availablencc:window(string): shape of the correlation window, eithersphereorcube(default:spere). Note thatcubeis available only if the
program is built with ISPC support. For a given number of samples, the
sphere has a better spatial distribution of the samples, yielding a
slightly superior quality. When running on the CPU, for the same number
of samples (e.g., roughly, a sphere of radius2and a cube of radius1) the cube can be significantly faster to compute.radius(int): radius of the cross-correlation kernel (default:2).
Forwindow=sphere, given a point where NCC is evaluated, samples are
taken in all the voxels such that the Euclidean distance of each sample
from the point is lesser or equal toradius.  Forwindow=cube,
samples are taken on all voxels within a cube centred on the point and
with side2×radius + 1.mi:bins(int): number of histogram bins used in the approximation of
probability densities (default:255)sigma(float): standard deviation of the Gaussian kernel used to
approximate probability densities (default:4.5)update_interval(int): interval (in iterations) between updates of the
entropy estimates (default:1). If0, updates are disabled.interpolator('linear'or'nearest'): interpolator used in the update
the entropy estimates (default:'nearest')gradient_ssd:sigma(float): Gaussian smoothing applied to the images before
computing the Sobel operator (default:0.0)GPUGPU assisted registration is supported on newer CUDA supported hardware. First
step to enable GPU registration is to compile with theDF_USE_CUDA=1flag,
this is set when generating the project with CMake. When both these
prerequisites are met, you simply add the--gpuflag to the command-line.As for now the GPU implementation is considered a pre-release and not all cost
functions and features from the original registration implementation are
supported. Currently the only two supported cost functions aressdandncc.LoggingThe file name for the log file can be specified through the environment
variableDF_LOG_FILE. The minimum level for log messages to be reported can
be set through the environment variableDF_LOG_LEVEL, and the possible values
areVerbose,Info,Warning,Error, andFatal.MasksIt is possible to optionally specify fuzzy masks for the fixed and moving image
space. The two masks can be set independently, and it is possible to use no
mask, only one of the two (either fixed or moving) or both. The masks should be
given in floating point format, and they denote the level of confidence on
image intensity at each voxel. If the mask valuem(x, y, z)at a certain
location(x, y, z)is lesser than or equal to zero, then samples taken at
that location will not contribute to the matching cost. Ifm(x, y, z)is
greater than zero, then the sample will contribute and its cost given at that
location by the image metric will by multiplied bym(x, y, z).The fixed mask allows to denote a ROI in reference space, formed by all voxels
with strictly positive mask values; for all samples outside such ROI the cost
function will not be computed at all, having the side effect of making the
registration process faster. If a sample belongs to a valid region, then its
mapping through the displacement will be computed and, if a mask for the moving
image is specified, the sample will contribute only if it falls within a valid
ROI in the moving image space, otherwise it will be discarded. The
regularisation term is not weighted by the masks, and it will be always
computed over all the volume, regardless of the mask values.The moving mask should be used carefully because it can affect the quality of
the result, since there is no penalty for mapping from valid samples in
reference space to regions outside of the moving image mask.Regularization weight mapsIt is possible to impose voxel-wise regularization weights in the registration
by providing a regularization weight map. This is a map of scalar values the
same size as the fixed image. In the standard case the binary term is computed
aa|u(v)-u(w)|, whereais the regularization weight. Using a regularization
weight map, the weightais computed asa = 0.5*(W(v) - W(w)), whereWis
the weight map.References[1] Junhwan Kim, Vladimir Kolmogorov, Ramin Zabih:Visual correspondence using energy minimization and mutual information.Proceedings of the Ninth IEEE International Conference on Computer Vision,
1033-1040, 2003.[2] Herve Lombaert, Yiyong Sun, Farida Cheriet:Landmark-based non-rigid registration via graph cuts,
International Conference Image Analysis and Recognition, 166–175, 2007