algorithms.registration.histogram_registration¶
Module: algorithms.registration.histogram_registration
¶
Inheritance diagram for nipy.algorithms.registration.histogram_registration
:

Intensity-based image registration
Class¶
HistogramRegistration
¶
-
class
nipy.algorithms.registration.histogram_registration.
HistogramRegistration
(from_img, to_img, from_bins=256, to_bins=None, from_mask=None, to_mask=None, similarity='crl1', interp='pv', smooth=0, renormalize=False, dist=None)¶ Bases:
object
A class to reprensent a generic intensity-based image registration algorithm.
Methods
eval
(T)Evaluate similarity function given a world-to-world transform. eval_gradient
(T[, epsilon])Evaluate the gradient of the similarity function wrt transformation parameters. eval_hessian
(T[, epsilon, diag])Evaluate the Hessian of the similarity function wrt transformation parameters. explore
(T, *args)Evaluate the similarity at the transformations specified by sequences of parameter values. optimize
(T[, optimizer])Optimize transform T with respect to similarity measure. set_fov
([spacing, corner, size, npoints])Defines a subset of the from image to restrict joint histogram computation. subsample
([spacing, npoints])-
__init__
(from_img, to_img, from_bins=256, to_bins=None, from_mask=None, to_mask=None, similarity='crl1', interp='pv', smooth=0, renormalize=False, dist=None)¶ - Creates a new histogram registration object.
Parameters: from_img : nipy-like image
From image
- to_img : nipy-like image
To image
- from_bins : integer
Number of histogram bins to represent the from image
- to_bins : integer
Number of histogram bins to represent the to image
- from_mask : array-like
Mask to apply to the from image
- to_mask : array-like
Mask to apply to the to image
- similarity : str or callable
Cost-function for assessing image similarity. If a string, one of ‘cc’: correlation coefficient, ‘cr’: correlation ratio, ‘crl1’: L1-norm based correlation ratio, ‘mi’: mutual information, ‘nmi’: normalized mutual information, ‘slr’: supervised log-likelihood ratio. If a callable, it should take a two-dimensional array representing the image joint histogram as an input and return a float.
dist: None or array-like :
Joint intensity probability distribution model for use with the ‘slr’ measure. Should be of shape (from_bins, to_bins).
interp : str
Interpolation method. One of ‘pv’: Partial volume, ‘tri’: Trilinear, ‘rand’: Random interpolation. See
joint_histogram.c
smooth : float
Standard deviation in millimeters of an isotropic Gaussian kernel used to smooth the To image. If 0, no smoothing is applied.
-
eval
(T)¶ Evaluate similarity function given a world-to-world transform.
Parameters: T : Transform
Transform object implementing
apply
method
-
eval_gradient
(T, epsilon=0.1)¶ Evaluate the gradient of the similarity function wrt transformation parameters.
The gradient is approximated using central finite differences at the transformation specified by T. The input transformation object T is modified in place unless it has a
copy
method.Parameters: T : Transform
Transform object implementing
apply
methodepsilon : float
Step size for finite differences in units of the transformation parameters
Returns: g : ndarray
Similarity gradient estimate
-
eval_hessian
(T, epsilon=0.1, diag=False)¶ Evaluate the Hessian of the similarity function wrt transformation parameters.
The Hessian or its diagonal is approximated at the transformation specified by T using central finite differences. The input transformation object T is modified in place unless it has a
copy
method.Parameters: T : Transform
Transform object implementing
apply
methodepsilon : float
Step size for finite differences in units of the transformation parameters
diag : bool
If True, approximate the Hessian by a diagonal matrix.
Returns: H : ndarray
Similarity Hessian matrix estimate
-
explore
(T, *args)¶ Evaluate the similarity at the transformations specified by sequences of parameter values.
For instance:
s, p = explore(T, (0, [-1,0,1]), (4, [-2.,2]))
Parameters: T : object
Transformation around which the similarity function is to be evaluated. It is modified in place unless it has a
copy
method.args : tuple
Each element of args is a sequence of two elements, where the first element specifies a transformation parameter axis and the second element gives the successive parameter values to evaluate along that axis.
Returns: s : ndarray
Array of similarity values
p : ndarray
Corresponding array of evaluated transformation parameters
-
interp
¶
-
optimize
(T, optimizer='powell', **kwargs)¶ Optimize transform T with respect to similarity measure.
The input object T will change as a result of the optimization.
Parameters: T : object or str
An object representing a transformation that should implement
apply
method andparam
attribute or property. If a string, one of ‘rigid’, ‘similarity’, or ‘affine’. The corresponding transformation class is then initialized by default.optimizer : str
Name of optimization function (one of ‘powell’, ‘steepest’, ‘cg’, ‘bfgs’, ‘simplex’)
**kwargs : dict
keyword arguments to pass to optimizer
Returns: T : object
Locally optimal transformation
-
set_fov
(spacing=None, corner=(0, 0, 0), size=None, npoints=None)¶ Defines a subset of the from image to restrict joint histogram computation.
Parameters: spacing : sequence (3,) of positive integers
Subsampling of image in voxels, where None (default) results in the subsampling to be automatically adjusted to roughly match a cubic grid with npoints voxels
corner : sequence (3,) of positive integers
Bounding box origin in voxel coordinates
size : sequence (3,) of positive integers
Desired bounding box size
npoints : positive integer
Desired number of voxels in the bounding box. If a spacing argument is provided, then npoints is ignored.
-
similarity
¶
-
subsample
(spacing=None, npoints=None)¶
-
Functions¶
-
nipy.algorithms.registration.histogram_registration.
approx_gradient
(f, x, epsilon)¶ Approximate the gradient of a function using central finite differences
Parameters: f: callable :
The function to differentiate
x: ndarray :
Point where the function gradient is to be evaluated
epsilon: float :
Stepsize for finite differences
Returns: g: ndarray :
Function gradient at x
-
nipy.algorithms.registration.histogram_registration.
approx_hessian
(f, x, epsilon)¶ Approximate the full Hessian matrix of a function using central finite differences
Parameters: f: callable :
The function to differentiate
x: ndarray :
Point where the Hessian is to be evaluated
epsilon: float :
Stepsize for finite differences
Returns: H: ndarray :
Hessian matrix at x
-
nipy.algorithms.registration.histogram_registration.
approx_hessian_diag
(f, x, epsilon)¶ Approximate the Hessian diagonal of a function using central finite differences
Parameters: f: callable :
The function to differentiate
x: ndarray :
Point where the Hessian is to be evaluated
epsilon: float :
Stepsize for finite differences
Returns: h: ndarray :
Diagonal of the Hessian at x
-
nipy.algorithms.registration.histogram_registration.
clamp
(x, bins, mask=None)¶ Clamp array values that fall within a given mask in the range [0..bins-1] and reset masked values to -1.
Parameters: x : ndarray
The input array
bins : number
Desired number of bins
mask : ndarray, tuple or slice
Anything such that x[mask] is an array.
Returns: y : ndarray
Clamped array, masked items are assigned -1
bins : number
Adjusted number of bins
-
nipy.algorithms.registration.histogram_registration.
ideal_spacing
(data, npoints)¶ Tune spacing factors so that the number of voxels in the output block matches a given number.
Parameters: data : ndarray or sequence
Data image to subsample
npoints : number
Target number of voxels (negative values will be ignored)
Returns: spacing: ndarray :
Spacing factors
-
nipy.algorithms.registration.histogram_registration.
smallest_bounding_box
(msk)¶ Extract the smallest bounding box from a mask
Parameters: msk : ndarray
Array of boolean
Returns: corner: ndarray :
3-dimensional coordinates of bounding box corner
size: ndarray :
3-dimensional size of bounding box
-
nipy.algorithms.registration.histogram_registration.
smooth_image
(data, affine, sigma)¶ Smooth an image by an isotropic Gaussian filter
Parameters: data: ndarray :
Image data array
affine: ndarray :
Image affine transform
sigma: float :
Filter standard deviation in mm
Returns: sdata: ndarray :
Smoothed data array