align

Bases: object

__init__(**kwds)

A ‘bunch’ of values (a replacement of Enum)

This is a temporary replacement of Enum, which is not available on all versions of Python 2

Bases: Exception

Methods

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

Bases: Exception

Methods

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

Bases: object

Methods

__init__(affine, domain_grid_shape=None, domain_grid2world=None, codomain_grid_shape=None, codomain_grid2world=None)

AffineMap

Implements an affine transformation whose domain is given by domain_grid and domain_grid2world, and whose co-domain is given by codomain_grid and codomain_grid2world.

The actual transform is represented by the affine matrix, which operate in world coordinates. Therefore, to transform a moving image towards a static image, we first map each voxel (i,j,k) of the static image to world coordinates (x,y,z) by applying domain_grid2world. Then we apply the affine transform to (x,y,z) obtaining (x’, y’, z’) in moving image’s world coordinates. Finally, (x’, y’, z’) is mapped to voxel coordinates (i’, j’, k’) in the moving image by multiplying (x’, y’, z’) by the inverse of codomain_grid2world. The codomain_grid_shape is used analogously to transform the static image towards the moving image when calling transform_inverse.

If the domain/co-domain information is not provided (None) then the sampling information needs to be specified each time the transform or transform_inverse is called to transform images. Note that such sampling information is not necessary to transform points defined in physical space, such as stream lines.

Parameters:

affine : array, shape (dim + 1, dim + 1) the matrix defining the affine transform, where dim is the dimension of the space this map operates in (2 for 2D images, 3 for 3D images). If None, then self represents the identity transformation. domain_grid_shape : sequence, shape (dim,), optional the shape of the default domain sampling grid. When transform is called to transform an image, the resulting image will have this shape, unless a different sampling information is provided. If None, then the sampling grid shape must be specified each time the transform method is called. domain_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-world transform associated with the domain grid. If None (the default), then the grid-to-world transform is assumed to be the identity. codomain_grid_shape : sequence of integers, shape (dim,) the shape of the default co-domain sampling grid. When transform_inverse is called to transform an image, the resulting image will have this shape, unless a different sampling information is provided. If None (the default), then the sampling grid shape must be specified each time the transform_inverse method is called. codomain_grid2world : array, shape (dim + 1, dim + 1) the grid-to-world transform associated with the co-domain grid. If None (the default), then the grid-to-world transform is assumed to be the identity.

get_affine()

Returns the value of the transformation, not a reference!

Returns:	affine : ndarray Copy of the transform, not a reference.

set_affine(affine)

Sets the affine transform (operating in physical space)

Also sets self.affine_inv - the inverse of affine, or None if there is no inverse.

Parameters:	affine : array, shape (dim + 1, dim + 1) the matrix representing the affine transform operating in physical space. The domain and co-domain information remains unchanged. If None, then self represents the identity transformation.

transform(image, interp='linear', image_grid2world=None, sampling_grid_shape=None, sampling_grid2world=None, resample_only=False)

Transforms the input image from co-domain to domain space

By default, the transformed image is sampled at a grid defined by self.domain_shape and self.domain_grid2world. If such information was not provided then sampling_grid_shape is mandatory.

Parameters:

image : 2D or 3D array the image to be transformed interp : string, either ‘linear’ or ‘nearest’ the type of interpolation to be used, either ‘linear’ (for k-linear interpolation) or ‘nearest’ for nearest neighbor image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-world transform associated with image. If None (the default), then the grid-to-world transform is assumed to be the identity. sampling_grid_shape : sequence, shape (dim,), optional the shape of the grid where the transformed image must be sampled. If None (the default), then self.codomain_shape is used instead (which must have been set at initialization, otherwise an exception will be raised). sampling_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-world transform associated with the sampling grid (specified by sampling_grid_shape, or by default self.codomain_shape). If None (the default), then the grid-to-world transform is assumed to be the identity. resample_only : Boolean, optional If False (the default) the affine transform is applied normally. If True, then the affine transform is not applied, and the input image is just re-sampled on the domain grid of this transform. Returns ——- transformed : array, shape sampling_grid_shape or self.codomain_shape the transformed image, sampled at the requested grid

transform_inverse(image, interp='linear', image_grid2world=None, sampling_grid_shape=None, sampling_grid2world=None, resample_only=False)

Transforms the input image from domain to co-domain space

By default, the transformed image is sampled at a grid defined by self.codomain_shape and self.codomain_grid2world. If such information was not provided then sampling_grid_shape is mandatory.

Parameters:

image : 2D or 3D array the image to be transformed interp : string, either ‘linear’ or ‘nearest’ the type of interpolation to be used, either ‘linear’ (for k-linear interpolation) or ‘nearest’ for nearest neighbor image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-world transform associated with image. If None (the default), then the grid-to-world transform is assumed to be the identity. sampling_grid_shape : sequence, shape (dim,), optional the shape of the grid where the transformed image must be sampled. If None (the default), then self.codomain_shape is used instead (which must have been set at initialization, otherwise an exception will be raised). sampling_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-world transform associated with the sampling grid (specified by sampling_grid_shape, or by default self.codomain_shape). If None (the default), then the grid-to-world transform is assumed to be the identity. resample_only : Boolean, optional If False (the default) the affine transform is applied normally. If True, then the affine transform is not applied, and the input image is just re-sampled on the domain grid of this transform. Returns ——- transformed : array, shape sampling_grid_shape or self.codomain_shape the transformed image, sampled at the requested grid

Bases: object

Methods

__init__(metric=None, level_iters=None, sigmas=None, factors=None, method='L-BFGS-B', ss_sigma_factor=None, options=None, verbosity=1)

Initializes an instance of the AffineRegistration class

Parameters:

metric : None or object, optional an instance of a metric. The default is None, implying the Mutual Information metric with default settings. level_iters : sequence, optional the number of iterations at each scale of the scale space. level_iters[0] corresponds to the coarsest scale, level_iters[-1] the finest, where n is the length of the sequence. By default, a 3-level scale space with iterations sequence equal to [10000, 1000, 100] will be used. sigmas : sequence of floats, optional custom smoothing parameter to build the scale space (one parameter for each scale). By default, the sequence of sigmas will be [3, 1, 0]. factors : sequence of floats, optional custom scale factors to build the scale space (one factor for each scale). By default, the sequence of factors will be [4, 2, 1]. method : string, optional optimization method to be used. If Scipy version < 0.12, then only L-BFGS-B is available. Otherwise, method can be any gradient-based method available in dipy.core.Optimize: CG, BFGS, Newton-CG, dogleg or trust-ncg. The default is ‘L-BFGS-B’. ss_sigma_factor : float, optional If None, this parameter is not used and an isotropic scale space with the given factors and sigmas will be built. If not None, an anisotropic scale space will be used by automatically selecting the smoothing sigmas along each axis according to the voxel dimensions of the given image. The ss_sigma_factor is used to scale the automatically computed sigmas. For example, in the isotropic case, the sigma of the kernel will be \(factor * (2 ^ i)\) where \(i = 1, 2, ..., n_scales - 1\) is the scale (the finest resolution image \(i=0\) is never smoothed). The default is None. options : dict, optional extra optimization options. The default is None, implying no extra options are passed to the optimizer. verbosity: int (one of {0, 1, 2, 3}), optional Set the verbosity level of the algorithm: 0 : do not print anything 1 : print information about the current status of the algorithm 2 : print high level information of the components involved in the registration that can be used to detect a failing component. 3 : print as much information as possible to isolate the cause of a bug. Default: 1

docstring_addendum = 'verbosity: int (one of {0, 1, 2, 3}), optional\n Set the verbosity level of the algorithm:\n 0 : do not print anything\n 1 : print information about the current status of the algorithm\n 2 : print high level information of the components involved in\n the registration that can be used to detect a failing\n component.\n 3 : print as much information as possible to isolate the cause\n of a bug.\n Default: 1\n '

optimize(static, moving, transform, params0, static_grid2world=None, moving_grid2world=None, starting_affine=None, ret_metric=False)

Starts the optimization process

Parameters:

static : 2D or 3D array the image to be used as reference during optimization. moving : 2D or 3D array the image to be used as “moving” during optimization. It is necessary to pre-align the moving image to ensure its domain lies inside the domain of the deformation fields. This is assumed to be accomplished by “pre-aligning” the moving image towards the static using an affine transformation given by the ‘starting_affine’ matrix transform : instance of Transform the transformation with respect to whose parameters the gradient must be computed params0 : array, shape (n,) parameters from which to start the optimization. If None, the optimization will start at the identity transform. n is the number of parameters of the specified transformation. static_grid2world : array, shape (dim+1, dim+1), optional the voxel-to-space transformation associated with the static image. The default is None, implying the transform is the identity. moving_grid2world : array, shape (dim+1, dim+1), optional the voxel-to-space transformation associated with the moving image. The default is None, implying the transform is the identity. starting_affine : string, or matrix, or None, optional If string: ‘mass’: align centers of gravity ‘voxel-origin’: align physical coordinates of voxel (0,0,0) ‘centers’: align physical coordinates of central voxels If matrix: array, shape (dim+1, dim+1). If None: Start from identity. The default is None. ret_metric : boolean, optional if True, it returns the parameters for measuring the similarity between the images (default ‘False’). The metric containing optimal parameters and the distance between the images.

Returns:

affine_map : instance of AffineMap the affine resulting affine transformation xopt : optimal parameters the optimal parameters (translation, rotation shear etc.) fopt : Similarity metric the value of the function at the optimal parameters.

Bases: dipy.align.scalespace.ScaleSpace

Methods

__init__(image, factors, sigmas, image_grid2world=None, input_spacing=None, mask0=False)

IsotropicScaleSpace

Computes the Scale Space representation of an image using isotropic smoothing kernels for all scales. The scale space is simply a list of images produced by smoothing the input image with a Gaussian kernel with different smoothing parameters.

This specialization of ScaleSpace allows the user to provide custom scale and smoothing factors for all scales.

Parameters:

image : array, shape (r,c) or (s, r, c) where s is the number of slices, r is the number of rows and c is the number of columns of the input image. factors : list of floats custom scale factors to build the scale space (one factor for each scale). sigmas : list of floats custom smoothing parameter to build the scale space (one parameter for each scale). image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-space transform of the image grid. The default is the identity matrix. input_spacing : array, shape (dim,), optional the spacing (voxel size) between voxels in physical space. The default if 1.0 along all axes. mask0 : Boolean, optional if True, all smoothed images will be zero at all voxels that are zero in the input image. The default is False.

Bases: object

Methods

__init__(nbins=32, sampling_proportion=None)

Initializes an instance of the Mutual Information metric

This class implements the methods required by Optimizer to drive the registration process.

Parameters:

nbins : int, optional the number of bins to be used for computing the intensity histograms. The default is 32. sampling_proportion : None or float in interval (0, 1], optional There are two types of sampling: dense and sparse. Dense sampling uses all voxels for estimating the (joint and marginal) intensity histograms, while sparse sampling uses a subset of them. If sampling_proportion is None, then dense sampling is used. If sampling_proportion is a floating point value in (0,1] then sparse sampling is used, where sampling_proportion specifies the proportion of voxels to be used. The default is None.

Notes

Since we use linear interpolation, images are not, in general, differentiable at exact voxel coordinates, but they are differentiable between voxel coordinates. When using sparse sampling, selected voxels are slightly moved by adding a small random displacement within one voxel to prevent sampling points from being located exactly at voxel coordinates. When using dense sampling, this random displacement is not applied.

distance(params)

Numeric value of the negative Mutual Information

We need to change the sign so we can use standard minimization algorithms.

Parameters:	params : array, shape (n,) the parameter vector of the transform currently used by the metric (the transform name is provided when self.setup is called), n is the number of parameters of the transform
Returns:	neg_mi : float the negative mutual information of the input images after transforming the moving image by the currently set transform with params parameters

distance_and_gradient(params)

Numeric value of the metric and its gradient at given parameters

Parameters:	params : array, shape (n,) the parameter vector of the transform currently used by the metric (the transform name is provided when self.setup is called), n is the number of parameters of the transform
Returns:	neg_mi : float the negative mutual information of the input images after transforming the moving image by the currently set transform with params parameters neg_mi_grad : array, shape (n,) the gradient of the negative Mutual Information

gradient(params)

Numeric value of the metric’s gradient at the given parameters

Parameters:	params : array, shape (n,) the parameter vector of the transform currently used by the metric (the transform name is provided when self.setup is called), n is the number of parameters of the transform
Returns:	grad : array, shape (n,) the gradient of the negative Mutual Information

setup(transform, static, moving, static_grid2world=None, moving_grid2world=None, starting_affine=None)

Prepares the metric to compute intensity densities and gradients

The histograms will be setup to compute probability densities of intensities within the minimum and maximum values of static and moving

Parameters:

transform: instance of Transform the transformation with respect to whose parameters the gradient must be computed static : array, shape (S, R, C) or (R, C) static image moving : array, shape (S’, R’, C’) or (R’, C’) moving image. The dimensions of the static (S, R, C) and moving (S’, R’, C’) images do not need to be the same. static_grid2world : array (dim+1, dim+1), optional the grid-to-space transform of the static image. The default is None, implying the transform is the identity. moving_grid2world : array (dim+1, dim+1) the grid-to-space transform of the moving image. The default is None, implying the spacing along all axes is 1. starting_affine : array, shape (dim+1, dim+1), optional the pre-aligning matrix (an affine transform) that roughly aligns the moving image towards the static image. If None, no pre-alignment is performed. If a pre-alignment matrix is available, it is recommended to provide this matrix as starting_affine instead of manually transforming the moving image to reduce interpolation artifacts. The default is None, implying no pre-alignment is performed.

Bases: object

Methods

__init__(fun, x0, args=(), method='L-BFGS-B', jac=None, hess=None, hessp=None, bounds=None, constraints=(), tol=None, callback=None, options=None, evolution=False)

A class for handling minimization of scalar function of one or more variables.

Parameters:

fun : callable Objective function. x0 : ndarray Initial guess. args : tuple, optional Extra arguments passed to the objective function and its derivatives (Jacobian, Hessian). method : str, optional Type of solver. Should be one of ‘Nelder-Mead’ ‘Powell’ ‘CG’ ‘BFGS’ ‘Newton-CG’ ‘Anneal’ ‘L-BFGS-B’ ‘TNC’ ‘COBYLA’ ‘SLSQP’ ‘dogleg’ ‘trust-ncg’ jac : bool or callable, optional Jacobian of objective function. Only for CG, BFGS, Newton-CG, dogleg, trust-ncg. If jac is a Boolean and is True, fun is assumed to return the value of Jacobian along with the objective function. If False, the Jacobian will be estimated numerically. jac can also be a callable returning the Jacobian of the objective. In this case, it must accept the same arguments as fun. hess, hessp : callable, optional Hessian of objective function or Hessian of objective function times an arbitrary vector p. Only for Newton-CG, dogleg, trust-ncg. Only one of hessp or hess needs to be given. If hess is provided, then hessp will be ignored. If neither hess nor hessp is provided, then the hessian product will be approximated using finite differences on jac. hessp must compute the Hessian times an arbitrary vector. bounds : sequence, optional Bounds for variables (only for L-BFGS-B, TNC and SLSQP). (min, max) pairs for each element in x, defining the bounds on that parameter. Use None for one of min or max when there is no bound in that direction. constraints : dict or sequence of dict, optional Constraints definition (only for COBYLA and SLSQP). Each constraint is defined in a dictionary with fields: type : str Constraint type: ‘eq’ for equality, ‘ineq’ for inequality. fun : callable The function defining the constraint. jac : callable, optional The Jacobian of fun (only for SLSQP). args : sequence, optional Extra arguments to be passed to the function and Jacobian. Equality constraint means that the constraint function result is to be zero whereas inequality means that it is to be non-negative. Note that COBYLA only supports inequality constraints. tol : float, optional Tolerance for termination. For detailed control, use solver-specific options. callback : callable, optional Called after each iteration, as callback(xk), where xk is the current parameter vector. Only available using Scipy >= 0.12. options : dict, optional A dictionary of solver options. All methods accept the following generic options: maxiter : int Maximum number of iterations to perform. disp : bool Set to True to print convergence messages. For method-specific options, see show_options(‘minimize’, method). evolution : bool, optional save history of x for each iteration. Only available using Scipy >= 0.12.

See also

scipy.optimize.minimize

evolution

fopt

message

nfev

nit

print_summary()

xopt

Bases: object

Methods

__init__()

Computes joint histogram and derivatives with Parzen windows

Base class to compute joint and marginal probability density functions and their derivatives with respect to a transform’s parameters. The smooth histograms are computed by using Parzen windows [Parzen62] with a cubic spline kernel, as proposed by Mattes et al. [Mattes03]. This implementation is not tied to any optimization (registration) method, the idea is that information-theoretic matching functionals (such as Mutual Information) can inherit from this class to perform the low-level computations of the joint intensity distributions and its gradient w.r.t. the transform parameters. The derived class can then compute the similarity/dissimilarity measure and gradient, and finally communicate the results to the appropriate optimizer.

Parameters:	nbins : int the number of bins of the joint and marginal probability density functions (the actual number of bins of the joint PDF is nbins**2)

Notes

We need this class in cython to allow _joint_pdf_gradient_dense_2d and _joint_pdf_gradient_dense_3d to use a nogil Jacobian function (obtained from an instance of the Transform class), which allows us to evaluate Jacobians at all the sampling points (maybe the full grid) inside a nogil loop.

The reason we need a class is to encapsulate all the parameters related to the joint and marginal distributions.

References

[Parzen62] E. Parzen. On the estimation of a probability density

function and the mode. Annals of Mathematical Statistics, 33(3), 1065-1076, 1962.

[Mattes03] Mattes, D., Haynor, D. R., Vesselle, H., Lewellen, T. K.,

& Eubank, W. PET-CT image registration in the chest using free-form deformations. IEEE Transactions on Medical Imaging, 22(1), 120-8, 2003.

bin_index

Bin index associated with the given normalized intensity

The return value is an integer in [padding, nbins - 1 - padding]

Parameters:	xnorm : float intensity value normalized to the range covered by the histogram
Returns:	bin : int the bin index associated with the given normalized intensity

bin_normalize_moving

Maps intensity x to the range covered by the moving histogram

If the input intensity is in [self.mmin, self.mmax] then the normalized intensity will be in [self.padding, self.nbins - self.padding]

Parameters:	x : float the intensity to be normalized
Returns:	xnorm : float normalized intensity to the range covered by the moving histogram

bin_normalize_static

Maps intensity x to the range covered by the static histogram

If the input intensity is in [self.smin, self.smax] then the normalized intensity will be in [self.padding, self.nbins - self.padding]

Parameters:	x : float the intensity to be normalized
Returns:	xnorm : float normalized intensity to the range covered by the static histogram

setup

Compute histogram settings to store the PDF of input images

Parameters:

static : array static image moving : array moving image smask : array mask of static object being registered (a binary array with 1’s inside the object of interest and 0’s along the background). If None, the behaviour is equivalent to smask=ones_like(static) mmask : array mask of moving object being registered (a binary array with 1’s inside the object of interest and 0’s along the background). If None, the behaviour is equivalent to mmask=ones_like(static)

update_gradient_dense

Computes the Gradient of the joint PDF w.r.t. transform parameters

Computes the vector of partial derivatives of the joint histogram w.r.t. each transformation parameter.

The gradient is stored in self.joint_grad.

Parameters:

theta : array, shape (n,) parameters of the transformation to compute the gradient from transform : instance of Transform the transformation with respect to whose parameters the gradient must be computed static : array, shape (S, R, C) static image moving : array, shape (S, R, C) moving image grid2world : array, shape (4, 4) we assume that both images have already been sampled at a common grid. This transform must map voxel coordinates of this common grid to physical coordinates of its corresponding voxel in the moving image. For example, if the moving image was sampled on the static image’s grid (this is the typical setting) using an aligning matrix A, then grid2world = A.dot(static_affine) where static_affine is the transformation mapping static image’s grid coordinates to physical space. mgradient : array, shape (S, R, C, 3) the gradient of the moving image smask : array, shape (S, R, C), optional mask of static object being registered (a binary array with 1’s inside the object of interest and 0’s along the background). The default is None, indicating all voxels are considered. mmask : array, shape (S, R, C), optional mask of moving object being registered (a binary array with 1’s inside the object of interest and 0’s along the background). The default is None, indicating all voxels are considered.

update_gradient_sparse

Computes the Gradient of the joint PDF w.r.t. transform parameters

Computes the vector of partial derivatives of the joint histogram w.r.t. each transformation parameter.

The list of intensities sval and mval are assumed to be sampled from the static and moving images, respectively, at the same physical points. Of course, the images may not be perfectly aligned at the moment the sampling was performed. The resulting gradient corresponds to the paired intensities according to the alignment at the moment the images were sampled.

The gradient is stored in self.joint_grad.

Parameters:

theta : array, shape (n,) parameters to compute the gradient at transform : instance of Transform the transformation with respect to whose parameters the gradient must be computed sval : array, shape (m,) sampled intensities from the static image at sampled_points mval : array, shape (m,) sampled intensities from the moving image at sampled_points sample_points : array, shape (m, 3) coordinates (in physical space) of the points the images were sampled at mgradient : array, shape (m, 3) the gradient of the moving image at the sample points

update_pdfs_dense

Computes the Probability Density Functions of two images

The joint PDF is stored in self.joint. The marginal distributions corresponding to the static and moving images are computed and stored in self.smarginal and self.mmarginal, respectively.

Parameters:

static : array, shape (S, R, C) static image moving : array, shape (S, R, C) moving image smask : array, shape (S, R, C) mask of static object being registered (a binary array with 1’s inside the object of interest and 0’s along the background). If None, ones_like(static) is used as mask. mmask : array, shape (S, R, C) mask of moving object being registered (a binary array with 1’s inside the object of interest and 0’s along the background). If None, ones_like(moving) is used as mask.

update_pdfs_sparse

Computes the Probability Density Functions from a set of samples

The list of intensities sval and mval are assumed to be sampled from the static and moving images, respectively, at the same physical points. Of course, the images may not be perfectly aligned at the moment the sampling was performed. The resulting distributions corresponds to the paired intensities according to the alignment at the moment the images were sampled.

The joint PDF is stored in self.joint. The marginal distributions corresponding to the static and moving images are computed and stored in self.smarginal and self.mmarginal, respectively.

Parameters:	sval : array, shape (n,) sampled intensities from the static image at sampled_points mval : array, shape (n,) sampled intensities from the moving image at sampled_points

Bases: object

Methods

__init__(image, num_levels, image_grid2world=None, input_spacing=None, sigma_factor=0.2, mask0=False)

ScaleSpace

Computes the Scale Space representation of an image. The scale space is simply a list of images produced by smoothing the input image with a Gaussian kernel with increasing smoothing parameter. If the image’s voxels are isotropic, the smoothing will be the same along all directions: at level L = 0, 1, …, the sigma is given by \(s * ( 2^L - 1 )\). If the voxel dimensions are not isotropic, then the smoothing is weaker along low resolution directions.

Parameters:

image : array, shape (r,c) or (s, r, c) where s is the number of slices, r is the number of rows and c is the number of columns of the input image. num_levels : int the desired number of levels (resolutions) of the scale space image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-space transform of the image grid. The default is the identity matrix input_spacing : array, shape (dim,), optional the spacing (voxel size) between voxels in physical space. The default is 1.0 along all axes sigma_factor : float, optional the smoothing factor to be used in the construction of the scale space. The default is 0.2 mask0 : Boolean, optional if True, all smoothed images will be zero at all voxels that are zero in the input image. The default is False.

get_affine(level)

Voxel-to-space transformation at a given level

Returns the voxel-to-space transformation associated with the sub-sampled image at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get affine transform from
Returns:	the affine (voxel-to-space) transform at the requested resolution or None if an invalid level was requested

get_affine_inv(level)

Space-to-voxel transformation at a given level

Returns the space-to-voxel transformation associated with the sub-sampled image at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the inverse transform from
Returns:	the inverse (space-to-voxel) transform at the requested resolution or None if an invalid level was requested

get_domain_shape(level)

Shape the sub-sampled image must have at a particular level

Returns the shape the sub-sampled image must have at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the sub-sampled shape from
Returns:	the sub-sampled shape at the requested resolution or None if an invalid level was requested

get_expand_factors(from_level, to_level)

Ratio of voxel size from pyramid level from_level to to_level

Given two scale space resolutions a = from_level, b = to_level, returns the ratio of voxels size at level b to voxel size at level a (the factor that must be used to multiply voxels at level a to ‘expand’ them to level b).

Parameters:	from_level : int, 0 <= from_level < L, (L = number of resolutions) the resolution to expand voxels from to_level : int, 0 <= to_level < from_level the resolution to expand voxels to
Returns:	factors : array, shape (k,), k = 2, 3 the expand factors (a scalar for each voxel dimension)

get_image(level)

Smoothed image at a given level

Returns the smoothed image at the requested level in the Scale Space.

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the smooth image from
Returns:	the smooth image at the requested resolution or None if an invalid level was requested

get_scaling(level)

Adjustment factor for input-spacing to reflect voxel sizes at level

Returns the scaling factor that needs to be applied to the input spacing (the voxel sizes of the image at level 0 of the scale space) to transform them to voxel sizes at the requested level.

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the scalings from
Returns:	the scaling factors from the original spacing to the spacings at the requested level

get_sigmas(level)

Smoothing parameters used at a given level

Returns the smoothing parameters (a scalar for each axis) used at the requested level of the scale space

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the smoothing parameters from
Returns:	the smoothing parameters at the requested level

get_spacing(level)

Spacings the sub-sampled image must have at a particular level

Returns the spacings (voxel sizes) the sub-sampled image must have at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the sub-sampled shape from
Returns:	the spacings (voxel sizes) at the requested resolution or None if an invalid level was requested

print_level(level)

Prints properties of a pyramid level

Prints the properties of a level of this scale space to standard output

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to be printed

Bases: object

__init__(**kwds)

A ‘bunch’ of values (a replacement of Enum)

This is a temporary replacement of Enum, which is not available on all versions of Python 2

Bases: object

Methods

__init__(dim, disp_shape, disp_grid2world=None, domain_shape=None, domain_grid2world=None, codomain_shape=None, codomain_grid2world=None, prealign=None)

DiffeomorphicMap

Implements a diffeomorphic transformation on the physical space. The deformation fields encoding the direct and inverse transformations share the same domain discretization (both the discretization grid shape and voxel-to-space matrix). The input coordinates (physical coordinates) are first aligned using prealign, and then displaced using the corresponding vector field interpolated at the aligned coordinates.

Parameters:

dim : int, 2 or 3 the transformation’s dimension disp_shape : array, shape (dim,) the number of slices (if 3D), rows and columns of the deformation field’s discretization disp_grid2world : the voxel-to-space transform between the def. fields grid and space domain_shape : array, shape (dim,) the number of slices (if 3D), rows and columns of the default discretizatio of this map’s domain domain_grid2world : array, shape (dim+1, dim+1) the default voxel-to-space transformation between this map’s discretization and physical space codomain_shape : array, shape (dim,) the number of slices (if 3D), rows and columns of the images that are ‘normally’ warped using this transformation in the forward direction (this will provide default transformation parameters to warp images under this transformation). By default, we assume that the inverse transformation is ‘normally’ used to warp images with the same discretization and voxel-to-space transformation as the deformation field grid. codomain_grid2world : array, shape (dim+1, dim+1) the voxel-to-space transformation of images that are ‘normally’ warped using this transformation (in the forward direction). prealign : array, shape (dim+1, dim+1) the linear transformation to be applied to align input images to the reference space before warping under the deformation field.

allocate()

Creates a zero displacement field

Creates a zero displacement field (the identity transformation).

compute_inversion_error()

Inversion error of the displacement fields

Estimates the inversion error of the displacement fields by computing statistics of the residual vectors obtained after composing the forward and backward displacement fields.

Returns:	residual : array, shape (R, C) or (S, R, C) the displacement field resulting from composing the forward and backward displacement fields of this transformation (the residual should be zero for a perfect diffeomorphism) stats : array, shape (3,) statistics from the norms of the vectors of the residual displacement field: maximum, mean and standard deviation

Notes

Since the forward and backward displacement fields have the same discretization, the final composition is given by

comp[i] = forward[ i + Dinv * backward[i]]

where Dinv is the space-to-grid transformation of the displacement fields

expand_fields(expand_factors, new_shape)

Expands the displacement fields from current shape to new_shape

Up-samples the discretization of the displacement fields to be of new_shape shape.

Parameters:	expand_factors : array, shape (dim,) the factors scaling current spacings (voxel sizes) to spacings in the expanded discretization. new_shape : array, shape (dim,) the shape of the arrays holding the up-sampled discretization

get_backward_field()

Deformation field to transform an image in the backward direction

Returns the deformation field that must be used to warp an image under this transformation in the backward direction (note the ‘is_inverse’ flag).

get_forward_field()

Deformation field to transform an image in the forward direction

Returns the deformation field that must be used to warp an image under this transformation in the forward direction (note the ‘is_inverse’ flag).

get_simplified_transform()

Constructs a simplified version of this Diffeomorhic Map

The simplified version incorporates the pre-align transform, as well as the domain and codomain affine transforms into the displacement field. The resulting transformation may be regarded as operating on the image spaces given by the domain and codomain discretization. As a result, self.prealign, self.disp_grid2world, self.domain_grid2world and self.codomain affine will be None (denoting Identity) in the resulting diffeomorphic map.

interpret_matrix(obj)

Try to interpret obj as a matrix

Some operations are performed faster if we know in advance if a matrix is the identity (so we can skip the actual matrix-vector multiplication). This function returns None if the given object is None or the ‘identity’ string. It returns the same object if it is a numpy array. It raises an exception otherwise.

Parameters:	obj : object any object
Returns:	obj : object the same object given as argument if obj is None or a numpy array. None if obj is the ‘identity’ string.

inverse()

Inverse of this DiffeomorphicMap instance

Returns a diffeomorphic map object representing the inverse of this transformation. The internal arrays are not copied but just referenced.

Returns:	inv : DiffeomorphicMap object the inverse of this diffeomorphic map.

shallow_copy()

Shallow copy of this DiffeomorphicMap instance

Creates a shallow copy of this diffeomorphic map (the arrays are not copied but just referenced)

Returns:	new_map : DiffeomorphicMap object the shallow copy of this diffeomorphic map

transform(image, interpolation='linear', image_world2grid=None, out_shape=None, out_grid2world=None)

Warps an image in the forward direction

Transforms the input image under this transformation in the forward direction. It uses the “is_inverse” flag to switch between “forward” and “backward” (if is_inverse is False, then transform(…) warps the image forwards, else it warps the image backwards).

Parameters:

image : array, shape (s, r, c) if dim = 3 or (r, c) if dim = 2 the image to be warped under this transformation in the forward direction interpolation : string, either ‘linear’ or ‘nearest’ the type of interpolation to be used for warping, either ‘linear’ (for k-linear interpolation) or ‘nearest’ for nearest neighbor image_world2grid : array, shape (dim+1, dim+1) the transformation bringing world (space) coordinates to voxel coordinates of the image given as input out_shape : array, shape (dim,) the number of slices, rows and columns of the desired warped image out_grid2world : the transformation bringing voxel coordinates of the warped image to physical space

Returns:

warped : array, shape = out_shape or self.codomain_shape if None the warped image under this transformation in the forward direction

Notes

See _warp_forward and _warp_backward documentation for further information.

transform_inverse(image, interpolation='linear', image_world2grid=None, out_shape=None, out_grid2world=None)

Warps an image in the backward direction

Transforms the input image under this transformation in the backward direction. It uses the “is_inverse” flag to switch between “forward” and “backward” (if is_inverse is False, then transform_inverse(…) warps the image backwards, else it warps the image forwards)

Parameters:

image : array, shape (s, r, c) if dim = 3 or (r, c) if dim = 2 the image to be warped under this transformation in the forward direction interpolation : string, either ‘linear’ or ‘nearest’ the type of interpolation to be used for warping, either ‘linear’ (for k-linear interpolation) or ‘nearest’ for nearest neighbor image_world2grid : array, shape (dim+1, dim+1) the transformation bringing world (space) coordinates to voxel coordinates of the image given as input out_shape : array, shape (dim,) the number of slices, rows and columns of the desired warped image out_grid2world : the transformation bringing voxel coordinates of the warped image to physical space

Returns:

warped : array, shape = out_shape or self.codomain_shape if None warped image under this transformation in the backward direction

Notes

See _warp_forward and _warp_backward documentation for further information.

warp_endomorphism(phi)

Composition of this DiffeomorphicMap with a given endomorphism

Creates a new DiffeomorphicMap C with the same properties as self and composes its displacement fields with phi’s corresponding fields. The resulting diffeomorphism is of the form C(x) = phi(self(x)) with inverse C^{-1}(y) = self^{-1}(phi^{-1}(y)). We assume that phi is an endomorphism with the same discretization and domain affine as self to ensure that the composition inherits self’s properties (we also assume that the pre-aligning matrix of phi is None or identity).

Parameters:	phi : DiffeomorphicMap object the endomorphism to be warped by this diffeomorphic map
Returns:	composition : the composition of this diffeomorphic map with the endomorphism given as input

Notes

The problem with our current representation of a DiffeomorphicMap is that the set of Diffeomorphism that can be represented this way (a pre-aligning matrix followed by a non-linear endomorphism given as a displacement field) is not closed under the composition operation.

Supporting a general DiffeomorphicMap class, closed under composition, may be extremely costly computationally, and the kind of transformations we actually need for Avants’ mid-point algorithm (SyN) are much simpler.

Bases: abc.NewBase

Methods

__init__(metric=None)

Diffeomorphic Registration

This abstract class defines the interface to be implemented by any optimization algorithm for diffeomorphic registration.

Parameters:	metric : SimilarityMetric object the object measuring the similarity of the two images. The registration algorithm will minimize (or maximize) the provided similarity.

get_map()

Returns the resulting diffeomorphic map after optimization

optimize()

Starts the metric optimization

This is the main function each specialized class derived from this must implement. Upon completion, the deformation field must be available from the forward transformation model.

set_level_iters(level_iters)

Sets the number of iterations at each pyramid level

Establishes the maximum number of iterations to be performed at each level of the Gaussian pyramid, similar to ANTS.

Parameters:	level_iters : list the number of iterations at each level of the Gaussian pyramid. level_iters[0] corresponds to the finest level, level_iters[n-1] the coarsest, where n is the length of the list

Bases: object

Methods

__init__(image, num_levels, image_grid2world=None, input_spacing=None, sigma_factor=0.2, mask0=False)

ScaleSpace

Computes the Scale Space representation of an image. The scale space is simply a list of images produced by smoothing the input image with a Gaussian kernel with increasing smoothing parameter. If the image’s voxels are isotropic, the smoothing will be the same along all directions: at level L = 0, 1, …, the sigma is given by \(s * ( 2^L - 1 )\). If the voxel dimensions are not isotropic, then the smoothing is weaker along low resolution directions.

Parameters:

image : array, shape (r,c) or (s, r, c) where s is the number of slices, r is the number of rows and c is the number of columns of the input image. num_levels : int the desired number of levels (resolutions) of the scale space image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-space transform of the image grid. The default is the identity matrix input_spacing : array, shape (dim,), optional the spacing (voxel size) between voxels in physical space. The default is 1.0 along all axes sigma_factor : float, optional the smoothing factor to be used in the construction of the scale space. The default is 0.2 mask0 : Boolean, optional if True, all smoothed images will be zero at all voxels that are zero in the input image. The default is False.

get_affine(level)

Voxel-to-space transformation at a given level

Returns the voxel-to-space transformation associated with the sub-sampled image at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get affine transform from
Returns:	the affine (voxel-to-space) transform at the requested resolution or None if an invalid level was requested

get_affine_inv(level)

Space-to-voxel transformation at a given level

Returns the space-to-voxel transformation associated with the sub-sampled image at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the inverse transform from
Returns:	the inverse (space-to-voxel) transform at the requested resolution or None if an invalid level was requested

get_domain_shape(level)

Shape the sub-sampled image must have at a particular level

Returns the shape the sub-sampled image must have at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the sub-sampled shape from
Returns:	the sub-sampled shape at the requested resolution or None if an invalid level was requested

get_expand_factors(from_level, to_level)

Ratio of voxel size from pyramid level from_level to to_level

Given two scale space resolutions a = from_level, b = to_level, returns the ratio of voxels size at level b to voxel size at level a (the factor that must be used to multiply voxels at level a to ‘expand’ them to level b).

Parameters:	from_level : int, 0 <= from_level < L, (L = number of resolutions) the resolution to expand voxels from to_level : int, 0 <= to_level < from_level the resolution to expand voxels to
Returns:	factors : array, shape (k,), k = 2, 3 the expand factors (a scalar for each voxel dimension)

get_image(level)

Smoothed image at a given level

Returns the smoothed image at the requested level in the Scale Space.

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the smooth image from
Returns:	the smooth image at the requested resolution or None if an invalid level was requested

get_scaling(level)

Adjustment factor for input-spacing to reflect voxel sizes at level

Returns the scaling factor that needs to be applied to the input spacing (the voxel sizes of the image at level 0 of the scale space) to transform them to voxel sizes at the requested level.

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the scalings from
Returns:	the scaling factors from the original spacing to the spacings at the requested level

get_sigmas(level)

Smoothing parameters used at a given level

Returns the smoothing parameters (a scalar for each axis) used at the requested level of the scale space

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the smoothing parameters from
Returns:	the smoothing parameters at the requested level

get_spacing(level)

Spacings the sub-sampled image must have at a particular level

Returns the spacings (voxel sizes) the sub-sampled image must have at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the sub-sampled shape from
Returns:	the spacings (voxel sizes) at the requested resolution or None if an invalid level was requested

print_level(level)

Prints properties of a pyramid level

Prints the properties of a level of this scale space to standard output

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to be printed

Bases: dipy.align.imwarp.DiffeomorphicRegistration

Methods

__init__(metric, level_iters=None, step_length=0.25, ss_sigma_factor=0.2, opt_tol=1e-05, inv_iter=20, inv_tol=0.001, callback=None)

Symmetric Diffeomorphic Registration (SyN) Algorithm

Performs the multi-resolution optimization algorithm for non-linear registration using a given similarity metric.

Parameters:

metric : SimilarityMetric object the metric to be optimized level_iters : list of int the number of iterations at each level of the Gaussian Pyramid (the length of the list defines the number of pyramid levels to be used) opt_tol : float the optimization will stop when the estimated derivative of the energy profile w.r.t. time falls below this threshold inv_iter : int the number of iterations to be performed by the displacement field inversion algorithm step_length : float the length of the maximum displacement vector of the update displacement field at each iteration ss_sigma_factor : float parameter of the scale-space smoothing kernel. For example, the std. dev. of the kernel will be factor*(2^i) in the isotropic case where i = 0, 1, …, n_scales is the scale inv_tol : float the displacement field inversion algorithm will stop iterating when the inversion error falls below this threshold callback : function(SymmetricDiffeomorphicRegistration) a function receiving a SymmetricDiffeomorphicRegistration object to be called after each iteration (this optimizer will call this function passing self as parameter)

get_map()

Returns the resulting diffeomorphic map Returns the DiffeomorphicMap registering the moving image towards the static image.

optimize(static, moving, static_grid2world=None, moving_grid2world=None, prealign=None)

Starts the optimization

Parameters:

static : array, shape (S, R, C) or (R, C) the image to be used as reference during optimization. The displacement fields will have the same discretization as the static image. moving : array, shape (S, R, C) or (R, C) the image to be used as “moving” during optimization. Since the deformation fields’ discretization is the same as the static image, it is necessary to pre-align the moving image to ensure its domain lies inside the domain of the deformation fields. This is assumed to be accomplished by “pre-aligning” the moving image towards the static using an affine transformation given by the ‘prealign’ matrix static_grid2world : array, shape (dim+1, dim+1) the voxel-to-space transformation associated to the static image moving_grid2world : array, shape (dim+1, dim+1) the voxel-to-space transformation associated to the moving image prealign : array, shape (dim+1, dim+1) the affine transformation (operating on the physical space) pre-aligning the moving image towards the static

Returns:

static_to_ref : DiffeomorphicMap object the diffeomorphic map that brings the moving image towards the static one in the forward direction (i.e. by calling static_to_ref.transform) and the static image towards the moving one in the backward direction (i.e. by calling static_to_ref.transform_inverse).

update(current_displacement, new_displacement, disp_world2grid, time_scaling)

Composition of the current displacement field with the given field

Interpolates new displacement at the locations defined by current_displacement. Equivalently, computes the composition C of the given displacement fields as C(x) = B(A(x)), where A is current_displacement and B is new_displacement. This function is intended to be used with deformation fields of the same sampling (e.g. to be called by a registration algorithm).

Parameters:

current_displacement : array, shape (R’, C’, 2) or (S’, R’, C’, 3) the displacement field defining where to interpolate new_displacement new_displacement : array, shape (R, C, 2) or (S, R, C, 3) the displacement field to be warped by current_displacement disp_world2grid : array, shape (dim+1, dim+1) the space-to-grid transform associated with the displacements’ grid (we assume that both displacements are discretized over the same grid) time_scaling : float scaling factor applied to d2. The effect may be interpreted as moving d1 displacements along a factor (time_scaling) of d2.

Returns:

updated : array, shape (the same as new_displacement) the warped displacement field mean_norm : the mean norm of all vectors in current_displacement

Bases: dipy.align.metrics.SimilarityMetric

Methods

__init__(dim, sigma_diff=2.0, radius=4)

Normalized Cross-Correlation Similarity metric.

Parameters:	dim : int (either 2 or 3) the dimension of the image domain sigma_diff : the standard deviation of the Gaussian smoothing kernel to be applied to the update field at each iteration radius : int the radius of the squared (cubic) neighborhood at each voxel to be considered to compute the cross correlation

compute_backward()

Computes one step bringing the static image towards the moving.

Computes the update displacement field to be used for registration of the static image towards the moving image

compute_forward()

Computes one step bringing the moving image towards the static.

Computes the update displacement field to be used for registration of the moving image towards the static image

free_iteration()

Frees the resources allocated during initialization

get_energy()

Numerical value assigned by this metric to the current image pair

Returns the Cross Correlation (data term) energy computed at the largest iteration

initialize_iteration()

Prepares the metric to compute one displacement field iteration.

Pre-computes the cross-correlation factors for efficient computation of the gradient of the Cross Correlation w.r.t. the displacement field. It also pre-computes the image gradients in the physical space by re-orienting the gradients in the voxel space using the corresponding affine transformations.

Bases: dipy.align.metrics.SimilarityMetric

Methods

__init__(dim, smooth=1.0, inner_iter=5, q_levels=256, double_gradient=True, step_type='gauss_newton')

Expectation-Maximization Metric

Similarity metric based on the Expectation-Maximization algorithm to handle multi-modal images. The transfer function is modeled as a set of hidden random variables that are estimated at each iteration of the algorithm.

Parameters:

dim : int (either 2 or 3) the dimension of the image domain smooth : float smoothness parameter, the larger the value the smoother the deformation field inner_iter : int number of iterations to be performed at each level of the multi- resolution Gauss-Seidel optimization algorithm (this is not the number of steps per Gaussian Pyramid level, that parameter must be set for the optimizer, not the metric) q_levels : number of quantization levels (equal to the number of hidden variables in the EM algorithm) double_gradient : boolean if True, the gradient of the expected static image under the moving modality will be added to the gradient of the moving image, similarly, the gradient of the expected moving image under the static modality will be added to the gradient of the static image. step_type : string (‘gauss_newton’, ‘demons’) the optimization schedule to be used in the multi-resolution Gauss-Seidel optimization algorithm (not used if Demons Step is selected)

compute_backward()

Computes one step bringing the static image towards the moving.

Computes the update displacement field to be used for registration of the static image towards the moving image

compute_demons_step(forward_step=True)

Demons step for EM metric

Parameters:	forward_step : boolean if True, computes the Demons step in the forward direction (warping the moving towards the static image). If False, computes the backward step (warping the static image to the moving image)
Returns:	displacement : array, shape (R, C, 2) or (S, R, C, 3) the Demons step

compute_forward()

Computes one step bringing the reference image towards the static.

Computes the forward update field to register the moving image towards the static image in a gradient-based optimization algorithm

compute_gauss_newton_step(forward_step=True)

Computes the Gauss-Newton energy minimization step

Computes the Newton step to minimize this energy, i.e., minimizes the linearized energy function with respect to the regularized displacement field (this step does not require post-smoothing, as opposed to the demons step, which does not include regularization). To accelerate convergence we use the multi-grid Gauss-Seidel algorithm proposed by Bruhn and Weickert et al [Bruhn05]

Parameters:	forward_step : boolean if True, computes the Newton step in the forward direction (warping the moving towards the static image). If False, computes the backward step (warping the static image to the moving image)
Returns:	displacement : array, shape (R, C, 2) or (S, R, C, 3) the Newton step

References

[Bruhn05] Andres Bruhn and Joachim Weickert, “Towards ultimate motion

estimation: combining highest accuracy with real-time performance”, 10th IEEE International Conference on Computer Vision, 2005. ICCV 2005.

free_iteration()

Frees the resources allocated during initialization

get_energy()

The numerical value assigned by this metric to the current image pair

Returns the EM (data term) energy computed at the largest iteration

initialize_iteration()

Prepares the metric to compute one displacement field iteration.

Pre-computes the transfer functions (hidden random variables) and variances of the estimators. Also pre-computes the gradient of both input images. Note that once the images are transformed to the opposite modality, the gradient of the transformed images can be used with the gradient of the corresponding modality in the same fashion as diff-demons does for mono-modality images. If the flag self.use_double_gradient is True these gradients are averaged.

use_moving_image_dynamics(original_moving_image, transformation)

This is called by the optimizer just after setting the moving image.

EMMetric takes advantage of the image dynamics by computing the current moving image mask from the original_moving_image mask (warped by nearest neighbor interpolation)

Parameters:

original_moving_image : array, shape (R, C) or (S, R, C) the original moving image from which the current moving image was generated, the current moving image is the one that was provided via ‘set_moving_image(…)’, which may not be the same as the original moving image but a warped version of it. transformation : DiffeomorphicMap object the transformation that was applied to the original_moving_image to generate the current moving image

use_static_image_dynamics(original_static_image, transformation)

This is called by the optimizer just after setting the static image.

EMMetric takes advantage of the image dynamics by computing the current static image mask from the originalstaticImage mask (warped by nearest neighbor interpolation)

Parameters:

original_static_image : array, shape (R, C) or (S, R, C) the original static image from which the current static image was generated, the current static image is the one that was provided via ‘set_static_image(…)’, which may not be the same as the original static image but a warped version of it (even the static image changes during Symmetric Normalization, not only the moving one). transformation : DiffeomorphicMap object the transformation that was applied to the original_static_image to generate the current static image

Bases: dipy.align.metrics.SimilarityMetric

Methods

__init__(dim, smooth=4, inner_iter=10, step_type='demons')

Sum of Squared Differences (SSD) Metric

Similarity metric for (mono-modal) nonlinear image registration defined by the sum of squared differences (SSD)

Parameters:

dim : int (either 2 or 3) the dimension of the image domain smooth : float smoothness parameter, the larger the value the smoother the deformation field inner_iter : int number of iterations to be performed at each level of the multi- resolution Gauss-Seidel optimization algorithm (this is not the number of steps per Gaussian Pyramid level, that parameter must be set for the optimizer, not the metric) step_type : string the displacement field step to be computed when ‘compute_forward’ and ‘compute_backward’ are called. Either ‘demons’ or ‘gauss_newton’

compute_backward()

Computes one step bringing the static image towards the moving.

Computes the update displacement field to be used for registration of the static image towards the moving image

compute_demons_step(forward_step=True)

Demons step for SSD metric

Computes the demons step proposed by Vercauteren et al.[Vercauteren09] for the SSD metric.

Parameters:	forward_step : boolean if True, computes the Demons step in the forward direction (warping the moving towards the static image). If False, computes the backward step (warping the static image to the moving image)
Returns:	displacement : array, shape (R, C, 2) or (S, R, C, 3) the Demons step

References

[Vercauteren09] Tom Vercauteren, Xavier Pennec, Aymeric Perchant,

Nicholas Ayache, “Diffeomorphic Demons: Efficient Non-parametric Image Registration”, Neuroimage 2009

compute_forward()

Computes one step bringing the reference image towards the static.

Computes the update displacement field to be used for registration of the moving image towards the static image

compute_gauss_newton_step(forward_step=True)

Computes the Gauss-Newton energy minimization step

Minimizes the linearized energy function (Newton step) defined by the sum of squared differences of corresponding pixels of the input images with respect to the displacement field.

Parameters:	forward_step : boolean if True, computes the Newton step in the forward direction (warping the moving towards the static image). If False, computes the backward step (warping the static image to the moving image)
Returns:	displacement : array, shape = static_image.shape + (3,) if forward_step==True, the forward SSD Gauss-Newton step, else, the backward step

free_iteration()

Nothing to free for the SSD metric

get_energy()

The numerical value assigned by this metric to the current image pair

Returns the Sum of Squared Differences (data term) energy computed at the largest iteration

initialize_iteration()

Prepares the metric to compute one displacement field iteration.

Pre-computes the gradient of the input images to be used in the computation of the forward and backward steps.

Bases: abc.NewBase

Methods

__init__(dim)

Similarity Metric abstract class

A similarity metric is in charge of keeping track of the numerical value of the similarity (or distance) between the two given images. It also computes the update field for the forward and inverse displacement fields to be used in a gradient-based optimization algorithm. Note that this metric does not depend on any transformation (affine or non-linear) so it assumes the static and moving images are already warped

Parameters:	dim : int (either 2 or 3) the dimension of the image domain

compute_backward()

Computes one step bringing the static image towards the moving.

Computes the backward update field to register the static image towards the moving image in a gradient-based optimization algorithm

compute_forward()

Computes one step bringing the reference image towards the static.

Computes the forward update field to register the moving image towards the static image in a gradient-based optimization algorithm

free_iteration()

Releases the resources no longer needed by the metric

This method is called by the RegistrationOptimizer after the required iterations have been computed (forward and / or backward) so that the SimilarityMetric can safely delete any data it computed as part of the initialization

get_energy()

Numerical value assigned by this metric to the current image pair

Must return the numeric value of the similarity between the given static and moving images

initialize_iteration()

Prepares the metric to compute one displacement field iteration.

This method will be called before any compute_forward or compute_backward call, this allows the Metric to pre-compute any useful information for speeding up the update computations. This initialization was needed in ANTS because the updates are called once per voxel. In Python this is unpractical, though.

set_levels_above(levels)

Informs the metric how many pyramid levels are above the current one

Informs this metric the number of pyramid levels above the current one. The metric may change its behavior (e.g. number of inner iterations) accordingly

Parameters:	levels : int the number of levels above the current Gaussian Pyramid level

set_levels_below(levels)

Informs the metric how many pyramid levels are below the current one

Informs this metric the number of pyramid levels below the current one. The metric may change its behavior (e.g. number of inner iterations) accordingly

Parameters:	levels : int the number of levels below the current Gaussian Pyramid level

set_moving_image(moving_image, moving_affine, moving_spacing, moving_direction)

Sets the moving image being compared against the static one.

Sets the moving image. The default behavior (of this abstract class) is simply to assign the reference to an attribute, but generalizations of the metric may need to perform other operations

Parameters:	moving_image : array, shape (R, C) or (S, R, C) the moving image

set_static_image(static_image, static_affine, static_spacing, static_direction)

Sets the static image being compared against the moving one.

Sets the static image. The default behavior (of this abstract class) is simply to assign the reference to an attribute, but generalizations of the metric may need to perform other operations

Parameters:	static_image : array, shape (R, C) or (S, R, C) the static image

use_moving_image_dynamics(original_moving_image, transformation)

This is called by the optimizer just after setting the moving image

This method allows the metric to compute any useful information from knowing how the current static image was generated (as the transformation of an original static image). This method is called by the optimizer just after it sets the static image. Transformation will be an instance of DiffeomorficMap or None if the original_moving_image equals self.moving_image.

Parameters:	original_moving_image : array, shape (R, C) or (S, R, C) original image from which the current moving image was generated transformation : DiffeomorphicMap object the transformation that was applied to original image to generate the current moving image

use_static_image_dynamics(original_static_image, transformation)

This is called by the optimizer just after setting the static image.

This method allows the metric to compute any useful information from knowing how the current static image was generated (as the transformation of an original static image). This method is called by the optimizer just after it sets the static image. Transformation will be an instance of DiffeomorficMap or None if the original_static_image equals self.moving_image.

Parameters:	original_static_image : array, shape (R, C) or (S, R, C) original image from which the current static image was generated transformation : DiffeomorphicMap object the transformation that was applied to original image to generate the current static image

Bases: dipy.align.scalespace.ScaleSpace

Methods

__init__(image, factors, sigmas, image_grid2world=None, input_spacing=None, mask0=False)

IsotropicScaleSpace

Computes the Scale Space representation of an image using isotropic smoothing kernels for all scales. The scale space is simply a list of images produced by smoothing the input image with a Gaussian kernel with different smoothing parameters.

This specialization of ScaleSpace allows the user to provide custom scale and smoothing factors for all scales.

Parameters:

image : array, shape (r,c) or (s, r, c) where s is the number of slices, r is the number of rows and c is the number of columns of the input image. factors : list of floats custom scale factors to build the scale space (one factor for each scale). sigmas : list of floats custom smoothing parameter to build the scale space (one parameter for each scale). image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-space transform of the image grid. The default is the identity matrix. input_spacing : array, shape (dim,), optional the spacing (voxel size) between voxels in physical space. The default if 1.0 along all axes. mask0 : Boolean, optional if True, all smoothed images will be zero at all voxels that are zero in the input image. The default is False.

Bases: object

Methods

__init__(image, num_levels, image_grid2world=None, input_spacing=None, sigma_factor=0.2, mask0=False)

ScaleSpace

Computes the Scale Space representation of an image. The scale space is simply a list of images produced by smoothing the input image with a Gaussian kernel with increasing smoothing parameter. If the image’s voxels are isotropic, the smoothing will be the same along all directions: at level L = 0, 1, …, the sigma is given by \(s * ( 2^L - 1 )\). If the voxel dimensions are not isotropic, then the smoothing is weaker along low resolution directions.

Parameters:

image : array, shape (r,c) or (s, r, c) where s is the number of slices, r is the number of rows and c is the number of columns of the input image. num_levels : int the desired number of levels (resolutions) of the scale space image_grid2world : array, shape (dim + 1, dim + 1), optional the grid-to-space transform of the image grid. The default is the identity matrix input_spacing : array, shape (dim,), optional the spacing (voxel size) between voxels in physical space. The default is 1.0 along all axes sigma_factor : float, optional the smoothing factor to be used in the construction of the scale space. The default is 0.2 mask0 : Boolean, optional if True, all smoothed images will be zero at all voxels that are zero in the input image. The default is False.

get_affine(level)

Voxel-to-space transformation at a given level

Returns the voxel-to-space transformation associated with the sub-sampled image at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get affine transform from
Returns:	the affine (voxel-to-space) transform at the requested resolution or None if an invalid level was requested

get_affine_inv(level)

Space-to-voxel transformation at a given level

Returns the space-to-voxel transformation associated with the sub-sampled image at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the inverse transform from
Returns:	the inverse (space-to-voxel) transform at the requested resolution or None if an invalid level was requested

get_domain_shape(level)

Shape the sub-sampled image must have at a particular level

Returns the shape the sub-sampled image must have at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the sub-sampled shape from
Returns:	the sub-sampled shape at the requested resolution or None if an invalid level was requested

get_expand_factors(from_level, to_level)

Ratio of voxel size from pyramid level from_level to to_level

Given two scale space resolutions a = from_level, b = to_level, returns the ratio of voxels size at level b to voxel size at level a (the factor that must be used to multiply voxels at level a to ‘expand’ them to level b).

Parameters:	from_level : int, 0 <= from_level < L, (L = number of resolutions) the resolution to expand voxels from to_level : int, 0 <= to_level < from_level the resolution to expand voxels to
Returns:	factors : array, shape (k,), k = 2, 3 the expand factors (a scalar for each voxel dimension)

get_image(level)

Smoothed image at a given level

Returns the smoothed image at the requested level in the Scale Space.

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the smooth image from
Returns:	the smooth image at the requested resolution or None if an invalid level was requested

get_scaling(level)

Adjustment factor for input-spacing to reflect voxel sizes at level

Returns the scaling factor that needs to be applied to the input spacing (the voxel sizes of the image at level 0 of the scale space) to transform them to voxel sizes at the requested level.

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the scalings from
Returns:	the scaling factors from the original spacing to the spacings at the requested level

get_sigmas(level)

Smoothing parameters used at a given level

Returns the smoothing parameters (a scalar for each axis) used at the requested level of the scale space

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the smoothing parameters from
Returns:	the smoothing parameters at the requested level

get_spacing(level)

Spacings the sub-sampled image must have at a particular level

Returns the spacings (voxel sizes) the sub-sampled image must have at a particular resolution of the scale space (note that this object does not explicitly subsample the smoothed images, but only provides the properties the sub-sampled images must have).

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to get the sub-sampled shape from
Returns:	the spacings (voxel sizes) at the requested resolution or None if an invalid level was requested

print_level(level)

Prints properties of a pyramid level

Prints the properties of a level of this scale space to standard output

Parameters:	level : int, 0 <= from_level < L, (L = number of resolutions) the scale space level to be printed

Bases: dipy.align.streamlinear.BundleMinDistanceMetric

Asymmetric Bundle-based Minimum distance

This is a cost function that can be used by the StreamlineLinearRegistration class.

Methods

__init__(num_threads=None)

An abstract class for the metric used for streamline registration

If the two sets of streamlines match exactly then method distance of this object should be minimum.

Parameters:	num_threads : int Number of threads. If None (default) then all available threads will be used. Only metrics using OpenMP will use this variable.

distance(xopt)

Distance calculated from this Metric

Parameters:	xopt : sequence List of affine parameters as an 1D vector

Bases: dipy.align.streamlinear.StreamlineDistanceMetric

Bundle-based Minimum Distance aka BMD

This is the cost function used by the StreamlineLinearRegistration

Notes

The difference with BundleMinDistanceMetric is that this creates the entire distance matrix and therefore requires more memory.

Methods