algorithms.registration.histogram_registration

Module: algorithms.registration.histogram_registration

Inheritance diagram for nipy.algorithms.registration.histogram_registration:

digraph inheritance9b519716ed { rankdir=LR; size="8.0, 12.0"; "registration.histogram_registration.HistogramRegistration" [URL="#nipy.algorithms.registration.histogram_registration.HistogramRegistration",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="A class to reprensent a generic intensity-based image 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.

__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_imgnipy-like image

To image

from_binsinteger

Number of histogram bins to represent the from image

to_binsinteger

Number of histogram bins to represent the to image

from_maskarray-like

Mask to apply to the from image

to_maskarray-like

Mask to apply to the to image

similaritystr 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.

property interp

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.

subsample(spacing=None, npoints=None)

property similarity

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 method

epsilon : 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 method

epsilon : 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

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 and param 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

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

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