Skip to content

jitfields.pushpull

This module contains a function (pull) for sampling values at arbitrary coordinates into a continuous function encoded by regularly spaced splines.

The numerical adjoint of this function (push) is also defined. The operation performed by the adjoint is commonly known as "splatting" in computer visions, since it associates each input value with a coordinate into the output volume.

The count function is equivalent to applying push to an image of ones, but uses a faster implementation.

Finally, grad is related to pull, as it allows to sample the directional gradients of the continuous function at arbitrary locations.

Notes

In all cases, the last dimension of grid assumes a "left to right" order of indices, such that if the shape of inp is (Nx, Ny, Nz, Nc), each element in grid contains the indices (x, y, z). This differs from PyTorch, where indices (x, y, z) index into a tensor ordered as (Nb, Nc, Nz, Ny, Nx).

Furthermore, indices are expressed in voxels, and are therefore expected in the range (0, N-1). Indices outside of this range are dealt with using one of the boundary conditions that are implemented. This again differs form PyTorch, where indices are in the normalized range (-1, 1).

Functions

pull Sample a tensor using spline interpolation grad Sample the spatial gradients of a tensor using spline interpolation push Splat a tensor using spline interpolation count Splat ones using spline interpolation

pull 

pull(inp, grid, order=2, bound='dct2', extrapolate=True, prefilter=False, out=None)

Sample a tensor using spline interpolation

Note

By default, inp is assumed to contain the coefficients of a continuous function encoded by regularly spaced cubic splines. Instead, when prefilter is True, pull interpolates the values of inp. To this end, inp is first converted to spline coefficients (i.e., prefiltered).

Parameters:

Name Type Description Default
inp `(..., *inshape, channel) tensor`

Input tensor with shape (..., *inshape, channel).

 required
grid `(..., *outshape, ndim) tensor`

Tensor of coordinates into inp, with shape (..., *outshape, ndim).

 required
order `[sequence of] {0..7}`

Interpolation order (per dimension).

 2
bound `[sequence of] BoundType`

How to deal with out-of-bound values (per dimension).

 'dct2'
extrapolate `bool or {'center', 'edge'}`
  • True: use bound to extrapolate out-of-bound value
  • False or 'center': do not extrapolate values that fall outside of the centers of the first and last voxels.
  • 'edge': do not extrapolate values that fall outside of the edges of the first and last voxels.
 True
prefilter `bool`

Whether to first compute interpolating coefficients. Must be true for proper interpolation, otherwise this function merely performs a non-interpolating "spline sampling".

 False

Returns:

Name Type Description
out `(..., *outshape, channel) tensor`

Pulled tensor, with shape (..., *outshape, channel).

grad 

grad(inp, grid, order=2, bound='dct2', extrapolate=True, prefilter=False, abs=False, out=None)

Sample the spatial gradients of a tensor using spline interpolation

Note

By default, inp is assumed to contain the coefficients of a continuous function encoded by regularly spaced cubic splines. Instead, when prefilter is True, grad interpolates the values of inp. To this end, inp is first converted to spline coefficients (i.e., prefiltered).

Parameters:

Name Type Description Default
inp `(..., *inshape, channel) tensor`

Input tensor, with shape (..., *inshape, channel).

 required
grid `(..., *outshape, ndim) tensor`

Tensor of coordinates into inp, with shape (..., *outshape, ndim).

 required
order [sequence of] {0..7}

Interpolation order (per dimension).

 2
bound `[sequence of] BoundType`

How to deal with out-of-bound values (per dimension).

 'dct2'
extrapolate `bool or {'center', 'edge'}`
  • True: use bound to extrapolate out-of-bound value
  • False or 'center': do not extrapolate values that fall outside of the centers of the first and last voxels.
  • 'edge': do not extrapolate values that fall outside of the edges of the first and last voxels.
 True
prefilter bool

Whether to first compute interpolating coefficients. Must be true for proper interpolation, otherwise this function merely performs a non-interpolating "spline sampling".

 False
abs bool

Take the absolute value of the corresponding matrix operator. Can be useful in minimization-majorization contexts.

Advanced users only

Backpropagation is not implemented when abs=True

 False

Returns:

Name Type Description
out `(..., *outshape, channel, ndim) tensor`

Pulled gradients, with shape (..., *outshape, channel, ndim).

hess 

hess(inp, grid, order=2, bound='dct2', extrapolate=True, prefilter=False, abs=False, out=None)

Sample the spatial Hessians of a tensor using spline interpolation

Autograd not supported for this function

Note

By default, inp is assumed to contain the coefficients of a continuous function encoded by regularly spaced cubic splines. Instead, when prefilter is True, hess interpolates the values of inp. To this end, inp is first converted to spline coefficients (i.e., prefiltered).

Parameters:

Name Type Description Default
inp `(..., *inshape, channel) tensor`

Input tensor, with shape (..., *inshape, channel).

 required
grid `(..., *outshape, ndim) tensor`

Tensor of coordinates into inp, with shape (..., *outshape, ndim).

 required
order [sequence of] {0..7}

Interpolation order (per dimension).

 2
bound `[sequence of] BoundType`

How to deal with out-of-bound values (per dimension).

 'dct2'
extrapolate `bool or {'center', 'edge'}`
  • True: use bound to extrapolate out-of-bound value
  • False or 'center': do not extrapolate values that fall outside of the centers of the first and last voxels.
  • 'edge': do not extrapolate values that fall outside of the edges of the first and last voxels.
 True
prefilter bool

Whether to first compute interpolating coefficients. Must be true for proper interpolation, otherwise this function merely performs a non-interpolating "spline sampling".

 False
abs bool

Take the absolute value of the corresponding matrix operator. Can be useful in minimization-majorization contexts.

Advanced users only

Backpropagation is not implemented when abs=True

 False

Returns:

Name Type Description
out `(..., *outshape, channel, ndim*(ndim+1)//2) tensor`

Pulled hessians, with shape (..., *outshape, channel, ndim*(ndim+1)//2).

push 

push(inp, grid, shape=None, order=2, bound='dct2', extrapolate=True, prefilter=False, out=None)

Splat a tensor using spline interpolation

Parameters:

Name Type Description Default
inp `(..., *inshape, channel) tensor`

Input tensor, with shape (..., *inshape, channel).

 required
grid `(..., *inshape, ndim) tensor`

Tensor of coordinates into inp, with shape (..., *inshape, ndim).

 required
shape `sequence[int]`

Output spatial shape. Default is inshape.

 `inshape`
order `[sequence of] {0..7}`

Interpolation order (per dimension).

 2
bound `[sequence of] BoundType`

How to deal with out-of-bound values (per dimension).

 'dct2'
extrapolate `bool or {'center', 'edge'}`
  • True: use bound to extrapolate out-of-bound value
  • False or 'center': do not extrapolate values that fall outside of the centers of the first and last voxels.
  • 'edge': do not extrapolate values that fall outside of the edges of the first and last voxels.
 True
prefilter `bool`

Whether to compute interpolating coefficients at the end. If the value for prefilter is matched across pull and push, they are adjoint of each other.

 False

Returns:

Name Type Description
out `(..., *shape, channel) tensor`

Pushed tensor, with shape (..., *shape, channel).

count 

count(grid, shape=None, order=2, bound='dct2', extrapolate=True, out=None)

Splat ones using spline interpolation

Parameters:

Name Type Description Default
grid `(..., *inshape, ndim) tensor`

Tensor of coordinates, with shape (..., *inshape, ndim)

 required
shape `sequence[int]`

Output spatial shape. Default is inshape.

 `inshape`
order `[sequence of] {0..7}`

Interpolation order (per dimension).

 2
bound `[sequence of] BoundType`

How to deal with out-of-bound values (per dimension).

 'dct2'
extrapolate `bool or {'center', 'edge'}`
  • True: use bound to extrapolate out-of-bound value
  • False or 'center': do not extrapolate values that fall outside of the centers of the first and last voxels.
  • 'edge': do not extrapolate values that fall outside of the edges of the first and last voxels.
 True

Returns:

Name Type Description
out `(..., *shape) tensor`

Pushed ones, with shape (..., *shape).