macromax.utils.ft package

Submodules

macromax.utils.ft.grid module

class macromax.utils.ft.grid.Grid(shape=None, step=None, *, extent=None, first=None, center=None, last=None, include_last=False, ndim=None, flat=False, origin_at_center=True, center_at_index=True)[source]

Bases: Sequence

A class representing an immutable uniformly-spaced plaid Cartesian grid and its Fourier Transform. Unlike the MutableGrid, objects of this class cannot be changed after creation.

See also MutableGrid

__init__(shape=None, step=None, *, extent=None, first=None, center=None, last=None, include_last=False, ndim=None, flat=False, origin_at_center=True, center_at_index=True)[source]

Construct an immutable Grid object.

Its values are defined by shape, step, center, and the boolean flags include_last and`center_at_index`. If not specified, the values for shape, step, and center center are deduced from the other values, including first, last, and extent. A larger even shape is assumed in case of ambiguity. If all else fails, first the step is assumed to be 1, then the center is assumed to be as close as possible to 0, and finally the shape is assumed to be 1.

Specific invariants:

  • `shape * step == extent == last + step - first` if include_last

  • `shape * step == extent == last - first` if not include_last

  • `center == first + shape // 2 * step` if center_at_index

  • `center == first + (shape - 1) / 2 * step` if not center_at_index

General invariants:

  • `shape * step == extent == last + step * include_last - first`

  • `center == first + (shape // 2 * center_at_index + (shape - 1) / 2 * (1 - center_at_index)) * step`

Parameters:

  • shape – An integer vector array with the shape of the sampling grid.

  • step – A vector array with the spacing of the sampling grid. This defaults to 1 if no two of first, center, or last are specified.

  • extent – The extent of the sampling grid as shape * step = last - first.

  • first – A vector array with the first element for each dimension. The first element is the smallest element if step is positive, and the largest when step is negative.

  • center – A vector array with the central value for each dimension. The center value is that at the central index in the grid, rounded up if center_at_index==True, or the average of the surrounding values when False. The center value defaults to 0 if neither first nor last is specified.

  • last – A vector array with the last element for each dimension. Note that unless include_last is set to True for the associated dimension, all but the last element is returned when calling self[axis]!

  • include_last – A boolean vector array indicating whether the returned vectors, self[axis], should include the last element (True) or the penultimate element (default == False). When the step size is not specified, it is determined so that the step * (shape - 1) == extent.

  • ndim (int) – A scalar integer indicating the number of dimensions of the sampling space.

  • flat (Union[bool, Sequence, ndarray]) – A boolean vector array indicating whether the returned vectors, self[axis], should be flattened (True) or returned as an open grid (False)

  • origin_at_center (Union[bool, Sequence, ndarray]) – A boolean vector array indicating whether the origin should be fft-shifted (True) or be ifftshifted to the front (False) of the returned vectors for self[axis].

  • center_at_index (Union[bool, Sequence, ndarray]) – A boolean vector array indicating whether the center of an even dimension is included in the grid. When left as False and the shape has an even number of elements in the corresponding dimension, then the next index is used as the center, (self.shape / 2).astype(int). When set to True and the number of elements in the corresponding dimension is even, then the center value is not included, only its preceding and following elements.

static from_ranges(*ranges)[source]

Converts one or more ranges of numbers to a single Grid object representation. The ranges can be specified as separate parameters or as a tuple.

Parameters:

ranges (Union[int, float, complex, Sequence, ndarray]) – one or more ranges of uniformly spaced numbers.

Return type:

Grid

Returns:

A Grid object that represents the same ranges.

property ndim: int

The number of dimensions of the space this grid spans.

property shape: array

The number of sample points along each axis of the grid.

property step: ndarray

The sample spacing along each axis of the grid.

property center: ndarray

The central coordinate of the grid.

property center_at_index: array

Boolean vector indicating whether the central coordinate is aligned with a grid point when the number of points is even along the associated axis. This has no effect when the the number of sample points is odd.

property flat: array

Boolean vector indicating whether self[axis] returns flattened (raveled) vectors (True) or not (False).

property origin_at_center: array

Boolean vector indicating whether self[axis] returns ranges that are monotonous (True) or ifftshifted so that the central index is the first element of the sequence (False).

property as_flat: Grid

return: A new Grid object where all the ranges are 1d-vectors (flattened or raveled)

property as_non_flat: Grid

return: A new Grid object where all the ranges are 1d-vectors (flattened or raveled)

property as_origin_at_0: Grid

return: A new Grid object where all the ranges are ifftshifted so that the origin as at index 0.

property as_origin_at_center: Grid

return: A new Grid object where all the ranges have the origin at the center index, even when the number of elements is odd.

swapaxes(axes)[source]

Reverses the order of the specified axes.

Return type:

Grid

transpose(axes=None)[source]

Reverses the order of all axes.

Return type:

Grid

project(axes_to_keep=None, axes_to_remove=None)[source]

Removes all but the specified axes and reduces the dimensions to the number of specified axes.

Parameters:
Return type:

Grid

Returns:

A Grid object with ndim == len(axes) and shape == shape[axes].

property first: ndarray

A vector with the first element of each range.

property extent: ndarray

The spatial extent of the sampling grid.

property size: int

The total number of sampling points as an integer scalar.

property dtype

The numeric data type for the coordinates.

property f: Grid

The equivalent frequency Grid.

property k: Grid

The equivalent k-space Grid.

__add__(term)[source]

Add a scalar or vector offset to the Grid coordinates.

Return type:

Grid

__mul__(factor)[source]

Scales all ranges with a factor.

Parameters:

factor (Union[int, float, complex, Sequence, array]) – A scalar factor for all dimensions, or a vector of factors, one for each dimension.

Return type:

Grid

Returns:

A new scaled Grid object.

__rmul__(factor)[source]

Scales all ranges with a factor.

Parameters:

factor (Union[int, float, complex, Sequence, array]) – A scalar factor for all dimensions, or a vector of factors, one for each dimension.

Return type:

Grid

Returns:

A new scaled Grid object.

__matmul__(other)[source]

Determines the Grid spanning the tensor space, with ndim equal to the sum of both ndims.

Parameters:

other (Grid) – The Grid with the right-hand dimensions.

Return type:

Grid

Returns:

A new Grid with ndim == self.ndim + other.ndim.

__sub__(term)[source]

Subtract a (scalar) value from all Grid coordinates.

Return type:

Grid

__truediv__(denominator)[source]

Divide the grid coordinates by a value.

Parameters:

denominator (Union[int, float, complex, Sequence, ndarray]) – The denominator to divide by.

Return type:

Grid

Returns:

A new Grid with the divided coordinates.

__neg__()[source]

Invert the coordinate values and the direction of the axes.

__len__()[source]

The number of axes in this sampling grid. Or, the number of elements when this object is not multi-dimensional.

Return type:

int

__iter__()[source]
property immutable: Grid

Return a new immutable Grid object.

property mutable: MutableGrid

Return a new MutableGrid object.

__eq__(other)[source]

Compares two Grid objects.

Return type:

bool

property multidimensional: bool

Single-dimensional grids behave as Sequences, multi-dimensional behave as a Sequence of vectors. TODO: Remove this feature? It tends to be a source of bugs.

__init_subclass__()

Function to initialize subclasses.

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

class macromax.utils.ft.grid.MutableGrid(shape=None, step=None, extent=None, first=None, center=None, last=None, include_last=False, ndim=None, flat=False, origin_at_center=True, center_at_index=True)[source]

Bases: Grid

A class representing a mutable uniformly-spaced plaid Cartesian grid and its Fourier Transform.

See also Grid

__init__(shape=None, step=None, extent=None, first=None, center=None, last=None, include_last=False, ndim=None, flat=False, origin_at_center=True, center_at_index=True)[source]

Construct a mutable Grid object.

Parameters:

  • shape – An integer vector array with the shape of the sampling grid.

  • step – A vector array with the spacing of the sampling grid.

  • extent – The extent of the sampling grid as shape * step

  • first – A vector array with the first element for each dimension. The first element is the smallest element if step is positive, and the largest when step is negative.

  • center – A vector array with the center element for each dimension. The center position in the grid is rounded to the next integer index unless center_at_index is set to False for that partical axis.

  • last – A vector array with the last element for each dimension. Unless include_last is set to True for the associated dimension, all but the last element is returned when calling self[axis].

  • include_last – A boolean vector array indicating whether the returned vectors, self[axis], should include the last element (True) or all-but-the-last (False)

  • ndim (int) – A scalar integer indicating the number of dimensions of the sampling space.

  • flat (Union[bool, Sequence, ndarray]) – A boolean vector array indicating whether the returned vectors, self[axis], should be flattened (True) or returned as an open grid (False)

  • origin_at_center (Union[bool, Sequence, ndarray]) – A boolean vector array indicating whether the origin should be fft-shifted (True) or be ifftshifted to the front (False) of the returned vectors for self[axis].

  • center_at_index (Union[bool, Sequence, ndarray]) – A boolean vector array indicating whether the center of the grid should be rounded to an integer index for each dimension. If False and the shape has an even number of elements, the next index is used as the center, (self.shape / 2).astype(int).

property shape: array

The number of sample points along each axis of the grid.

property step: ndarray

The sample spacing along each axis of the grid.

property center: ndarray

The central coordinate of the grid.

property flat: array

Boolean vector indicating whether self[axis] returns flattened (raveled) vectors (True) or not (False).

property origin_at_center: array

Boolean vector indicating whether self[axis] returns ranges that are monotonous (True) or ifftshifted so that the central index is the first element of the sequence (False).

__add__(term)

Add a scalar or vector offset to the Grid coordinates.

Return type:

Grid

__eq__(other)

Compares two Grid objects.

Return type:

bool

__init_subclass__()

Function to initialize subclasses.

__iter__()
__len__()

The number of axes in this sampling grid. Or, the number of elements when this object is not multi-dimensional.

Return type:

int

__matmul__(other)

Determines the Grid spanning the tensor space, with ndim equal to the sum of both ndims.

Parameters:

other (Grid) – The Grid with the right-hand dimensions.

Return type:

Grid

Returns:

A new Grid with ndim == self.ndim + other.ndim.

__mul__(factor)

Scales all ranges with a factor.

Parameters:

factor (Union[int, float, complex, Sequence, array]) – A scalar factor for all dimensions, or a vector of factors, one for each dimension.

Return type:

Grid

Returns:

A new scaled Grid object.

__neg__()

Invert the coordinate values and the direction of the axes.

__rmul__(factor)

Scales all ranges with a factor.

Parameters:

factor (Union[int, float, complex, Sequence, array]) – A scalar factor for all dimensions, or a vector of factors, one for each dimension.

Return type:

Grid

Returns:

A new scaled Grid object.

__sub__(term)

Subtract a (scalar) value from all Grid coordinates.

Return type:

Grid

__truediv__(denominator)

Divide the grid coordinates by a value.

Parameters:

denominator (Union[int, float, complex, Sequence, ndarray]) – The denominator to divide by.

Return type:

Grid

Returns:

A new Grid with the divided coordinates.

property as_flat: Grid

return: A new Grid object where all the ranges are 1d-vectors (flattened or raveled)

property as_non_flat: Grid

return: A new Grid object where all the ranges are 1d-vectors (flattened or raveled)

property as_origin_at_0: Grid

return: A new Grid object where all the ranges are ifftshifted so that the origin as at index 0.

property as_origin_at_center: Grid

return: A new Grid object where all the ranges have the origin at the center index, even when the number of elements is odd.

property center_at_index: array

Boolean vector indicating whether the central coordinate is aligned with a grid point when the number of points is even along the associated axis. This has no effect when the the number of sample points is odd.

count(value) → integer -- return number of occurrences of value
property extent: ndarray

The spatial extent of the sampling grid.

property f: Grid

The equivalent frequency Grid.

property first: ndarray

return: A vector with the first element of each range

static from_ranges(*ranges)

Converts one or more ranges of numbers to a single Grid object representation. The ranges can be specified as separate parameters or as a tuple.

Parameters:

ranges (Union[int, float, complex, Sequence, ndarray]) – one or more ranges of uniformly spaced numbers.

Return type:

Grid

Returns:

A Grid object that represents the same ranges.

property immutable: Grid

Return a new immutable Grid object.

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

property k: Grid

The equivalent k-space Grid.

property multidimensional: bool

Single-dimensional grids behave as Sequences, multi-dimensional behave as a Sequence of vectors. TODO: Remove this feature? It tends to be a source of bugs.

property mutable: MutableGrid

Return a new MutableGrid object.

property ndim: int

The number of dimensions of the space this grid spans.

project(axes_to_keep=None, axes_to_remove=None)

Removes all but the specified axes and reduces the dimensions to the number of specified axes.

Parameters:
Return type:

Grid

Returns:

A Grid object with ndim == len(axes) and shape == shape[axes].

property size: int

The total number of sampling points as an integer scalar.

swapaxes(axes)

Reverses the order of the specified axes.

Return type:

Grid

transpose(axes=None)

Reverses the order of all axes.

Return type:

Grid

property dtype

The numeric data type for the coordinates.

__iadd__(number)[source]
__imul__(number)[source]
__isub__(number)[source]
__idiv__(number)[source]

macromax.utils.ft.subpixel module

Classes and functions to register a subject array to a reference array with subpixel precision. This is based on the algorithm described in: Manuel Guizar-Sicairos, Samuel T. Thurman, and James R. Fienup, “Efficient subpixel image registration algorithms,” Optics Letters. 33, 156-158 (2008).

macromax.utils.ft.subpixel.register(subject=None, reference=None, precision=None)[source]

Registers a subject array to a reference array with subpixel precision. This is based on the algorithm described in Manuel Guizar-Sicairos, Samuel T. Thurman, and James R. Fienup, “Efficient subpixel image registration algorithms,” Optics Letters. 33, 156-158 (2008).

Parameters:
Return type:

Registration

Returns:

A Registration instance describing the registered image, the shift, and the amplitude.

macromax.utils.ft.subpixel.roll(subject, shift, axis=None)[source]

Rolls (shifting with wrapping around) and nd-array with sub-pixel precision.

Parameters:

  • subject (ndarray) – The to-be-shifted nd-array. Default: all zeros except first element.

  • shift (Union[int, float, Sequence, ndarray, None]) – The (fractional) shift. Default: all zeros except first element.

  • axis (Union[int, Sequence, ndarray, None]) – Optional int or sequence of ints. The axis or axes along which elements are shifted. Unlike numpy’s roll function, by default, the left-most axes are used.

Returns:

The shifted nd-array.

macromax.utils.ft.subpixel.roll_ft(subject_ft, shift, axes=None)[source]

Rolls (shifting with wrapping around) and nd-array with sub-pixel precision. The input and output array are Fourier transformed.

Parameters:

  • subject_ft (ndarray) – The Fourier transform of the to-be-shifted nd-array.

  • shift (Union[int, float, Sequence, ndarray, None]) – The (fractional) shift.

  • axes (Union[int, Sequence, ndarray, None]) – Optional int or sequence of ints. The axis or axes along which elements are shifted. Unlike numpy’s roll function, by default, the left-most axes are used.

Returns:

The Fourier transform of the shifted nd-array.

class macromax.utils.ft.subpixel.Registration(shift, factor=1.0, error=0.0, original_ft=None, original=None, registered_ft=None, registered=None)[source]

Bases: object

A class to represent the result of a registration of reference class.

__init__(shift, factor=1.0, error=0.0, original_ft=None, original=None, registered_ft=None, registered=None)[source]

Constructs a registration result.

Parameters:

  • shift (Union[int, float, Sequence, ndarray]) – translation in pixels of the registered with respect to original reference

  • factor (complex) – scaling factor between registered and original reference image

  • error (float) – The root-mean-square difference after registration. See `register` for more details.

  • original_ft (Union[int, float, Sequence, ndarray, None]) – The Fourier transform of the original image, prior to registration.

  • original (Union[int, float, Sequence, ndarray, None]) – The original image, prior to registration.

  • registered_ft (Union[int, float, Sequence, ndarray, None]) – The Fourier transform of the registered image, identical to the original but with a sub-pixel shift.

  • registered (Union[int, float, Sequence, ndarray, None]) – The registered image, identical to the original but with a sub-pixel shift.

property shift: ndarray

Vector indicating subpixel shift between the original and registration image.

property ndim: int

The number of registration dimensions.

property factor

(Complex) scaling factor indicating the ratio between original and registered image.

property error: float

The rms difference between the registered and the original image including rescaling factor.

property image_ft: ndarray

Fourier transform of the registered and renormalized array.

property image: ndarray

Registered and renormalized array. It is shifted and scaled so that it is as close as possible to the reference. I.e. it minimizes the l2-norm of the difference.

__array__()[source]

Return the registered and renormalized image as an array.

Return type:

ndarray

property original_ft: ndarray

Fourier transform of the original reference array.

property original: ndarray

Original reference array.

class macromax.utils.ft.subpixel.Reference(reference_image=None, precision=None, axes=None, ndim=None, reference_image_ft=None)[source]

Bases: object

Represents a reference ‘image’ (which can be n-dimensional) to be used to register against. Multi-channel arrays should be handled iteratively or by averaging over the channels.

__init__(reference_image=None, precision=None, axes=None, ndim=None, reference_image_ft=None)[source]

Construct a reference ‘image’ object. If neither reference_image or its Fourier transform reference_image_ft are specified, a point-reference is assumed, where the point is in the first element of the nd-array (top-left corner).

Parameters:

  • reference_image (Union[int, float, Sequence, ndarray, None]) – The reference image nd-array. As an alternative, its unshifted Fourier transform can be specified as reference_image_ft.

  • precision (Optional[float]) – (optional) The default sub-pixel precision (default: 1/128).

  • axes (Union[int, float, Sequence, ndarray, None]) – (optional) The axes to operate on. If not specified, all dimensions of the reference image or its Fourier transform are used.

  • ndim (Optional[int]) – The number of dimensions is usually determined from . If neither is specified, ndim determines the number of dimensions to operate on.

  • reference_image_ft (Union[int, float, Sequence, ndarray, None])

property ndim: int
property shape
register(subject=None, subject_ft=None, precision=None)[source]

Register an nd-image to sub-pixel precision.

Algorithm based on the 2-d implementation of: Manuel Guizar-Sicairos, Samuel T. Thurman, and James R. Fienup, “Efficient subpixel image registration algorithms,” Opt. Lett. 33, 156-158 (2008).

Parameters:

  • subject (Optional[array]) – The subject image as an nd-array. If this is not specified, its Fourier transform should be.

  • subject_ft (Optional[array]) – (optional) The (non-fftshifted) Fourier transform of the subject image.

  • precision (float) – (optional) The sub-pixel precision in units of pixel (default: 1/128).

Return type:

Registration

Returns:

A Registration object representing the registered image as well as the shift, global phase change, and error.