fiery.interpol

High-order spline interpolation in PyTorch.

Functions:

grid_pull

grid_pull(input: Tensor, grid: Tensor, interpolation: OrderLike | Sequence[OrderLike] = 'linear', bound: BoundLike | Sequence[BoundLike] = 'zero', extrapolate: bool | int = False, prefilter: bool = False) -> Tensor

Sample an image with respect to a deformation field.

If the input dtype is not a floating point type, the input image is assumed to contain labels. In that case, the unique labels are extracted and resampled individually, which turns them into soft labels. The label map is then reconstructed from the individual soft labels by assigning, in each output voxel, the label with the largest soft value.

Notes

interpolation can be an int, a string or an InterpolationType. Possible values are:

0 or 'nearest'
1 or 'linear'
2 or 'quadratic'
3 or 'cubic'
4 or 'fourth'
5 or 'fifth'
etc.

A list of values can be provided, in the order [W, H, D], to specify dimension-specific interpolation orders.

bound can be an int, a string or a BoundType. Possible values are:

'replicate'  or 'nearest'     :  a  a  a  |  a  b  c  d  |  d  d  d
'dct1'       or 'mirror'      :  d  c  b  |  a  b  c  d  |  c  b  a
'dct2'       or 'reflect'     :  c  b  a  |  a  b  c  d  |  d  c  b
'dst1'       or 'antimirror'  : -b -a  0  |  a  b  c  d  |  0 -d -c
'dst2'       or 'antireflect' : -c -b -a  |  a  b  c  d  | -d -c -b
'dft'        or 'wrap'        :  b  c  d  |  a  b  c  d  |  a  b  c
'zero'       or 'zeros'       :  0  0  0  |  a  b  c  d  |  0  0  0

A list of values can be provided, in the order [W, H, D], to specify dimension-specific boundary conditions. Note that:

dft corresponds to circular padding;
dct2 corresponds to Neumann boundary conditions (symmetric);
dst2 corresponds to Dirichlet boundary conditions (antisymmetric).

See:

Parameters:

Name	Type	Description	Default
`input`	`(..., [channel], *inshape) tensor`	Input image.	required
`grid`	`(..., *outshape, dim) tensor`	Transformation field.	required
`interpolation`	`int or sequence[int]`	Interpolation order.	`1`
`bound`	`BoundType or sequence[BoundType]`	Boundary conditions.	`'zero'`
`extrapolate`	`bool or int`	Extrapolate out-of-bound data.	`False`
`prefilter`	`bool`	Apply the spline pre-filter, so that the spline interpolates the input.	`False`

Returns:

Name	Type	Description
`output`	`(..., [channel], *outshape) tensor`	Deformed image.

grid_push

grid_push(input: Tensor, grid: Tensor, shape: Sequence[int] | None = None, interpolation: OrderLike | Sequence[OrderLike] = 'linear', bound: BoundLike | Sequence[BoundLike] = 'zero', extrapolate: bool | int = False, prefilter: bool = False) -> Tensor

Splat an image with respect to a deformation field (pull adjoint).

Notes

interpolation can be an int, a string or an InterpolationType. Possible values are:

0 or 'nearest'
1 or 'linear'
2 or 'quadratic'
3 or 'cubic'
4 or 'fourth'
5 or 'fifth'
etc.

A list of values can be provided, in the order [W, H, D], to specify dimension-specific interpolation orders.

bound can be an int, a string or a BoundType. Possible values are:

'replicate'  or 'nearest'     :  a  a  a  |  a  b  c  d  |  d  d  d
'dct1'       or 'mirror'      :  d  c  b  |  a  b  c  d  |  c  b  a
'dct2'       or 'reflect'     :  c  b  a  |  a  b  c  d  |  d  c  b
'dst1'       or 'antimirror'  : -b -a  0  |  a  b  c  d  |  0 -d -c
'dst2'       or 'antireflect' : -c -b -a  |  a  b  c  d  | -d -c -b
'dft'        or 'wrap'        :  b  c  d  |  a  b  c  d  |  a  b  c
'zero'       or 'zeros'       :  0  0  0  |  a  b  c  d  |  0  0  0

A list of values can be provided, in the order [W, H, D], to specify dimension-specific boundary conditions. Note that:

dft corresponds to circular padding;
dct2 corresponds to Neumann boundary conditions (symmetric);
dst2 corresponds to Dirichlet boundary conditions (antisymmetric).

See:

Parameters:

Name	Type	Description	Default
`input`	`(..., [channel], *inshape) tensor`	Input image.	required
`grid`	`(..., *inshape, dim) tensor`	Transformation field.	required
`shape`	`sequence[int]`	Output shape.	`inshape`
`interpolation`	`int or sequence[int]`	Interpolation order.	`1`
`bound`	`BoundType or sequence[BoundType]`	Boundary conditions.	`'zero'`
`extrapolate`	`bool or int`	Extrapolate out-of-bound data.	`False`
`prefilter`	`bool`	Apply the spline pre-filter to the splatted image.	`False`

Returns:

Name	Type	Description
`output`	`(..., [channel], *shape) tensor`	Splatted image.

grid_count

grid_count(grid: Tensor, shape: Sequence[int] | None = None, interpolation: OrderLike | Sequence[OrderLike] = 'linear', bound: BoundLike | Sequence[BoundLike] = 'zero', extrapolate: bool | int = False) -> Tensor

Splat the interpolation weights of a deformation field.

This is grid_push applied to an image of ones: each output voxel accumulates the weights with which it contributes to the pull, which is useful to normalize a splatted image.

Notes

interpolation can be an int, a string or an InterpolationType. Possible values are:

0 or 'nearest'
1 or 'linear'
2 or 'quadratic'
3 or 'cubic'
4 or 'fourth'
5 or 'fifth'
etc.

A list of values can be provided, in the order [W, H, D], to specify dimension-specific interpolation orders.

bound can be an int, a string or a BoundType. Possible values are:

'replicate'  or 'nearest'     :  a  a  a  |  a  b  c  d  |  d  d  d
'dct1'       or 'mirror'      :  d  c  b  |  a  b  c  d  |  c  b  a
'dct2'       or 'reflect'     :  c  b  a  |  a  b  c  d  |  d  c  b
'dst1'       or 'antimirror'  : -b -a  0  |  a  b  c  d  |  0 -d -c
'dst2'       or 'antireflect' : -c -b -a  |  a  b  c  d  | -d -c -b
'dft'        or 'wrap'        :  b  c  d  |  a  b  c  d  |  a  b  c
'zero'       or 'zeros'       :  0  0  0  |  a  b  c  d  |  0  0  0

A list of values can be provided, in the order [W, H, D], to specify dimension-specific boundary conditions. Note that:

dft corresponds to circular padding;
dct2 corresponds to Neumann boundary conditions (symmetric);
dst2 corresponds to Dirichlet boundary conditions (antisymmetric).

See:

Parameters:

Name	Type	Description	Default
`grid`	`(..., *inshape, dim) tensor`	Transformation field.	required
`shape`	`sequence[int]`	Output shape.	`inshape`
`interpolation`	`int or sequence[int]`	Interpolation order.	`1`
`bound`	`BoundType or sequence[BoundType]`	Boundary conditions.	`'zero'`
`extrapolate`	`bool or int`	Extrapolate out-of-bound data.	`False`

Returns:

Name	Type	Description
`output`	`(..., [1], *shape) tensor`	Splatted weights.

grid_grad

grid_grad(input: Tensor, grid: Tensor, interpolation: OrderLike | Sequence[OrderLike] = 'linear', bound: BoundLike | Sequence[BoundLike] = 'zero', extrapolate: bool | int = False, prefilter: bool = False) -> Tensor

Sample spatial gradients of an image along a deformation field.

The returned gradients are taken with respect to the coordinates of the input lattice: this function returns (∇f)∘φ, not ∇(f∘φ). To obtain gradients with respect to the output lattice, multiply the sampled gradients by the Jacobian field of the transformation.

Notes

interpolation can be an int, a string or an InterpolationType. Possible values are:

0 or 'nearest'
1 or 'linear'
2 or 'quadratic'
3 or 'cubic'
4 or 'fourth'
5 or 'fifth'
etc.

A list of values can be provided, in the order [W, H, D], to specify dimension-specific interpolation orders.

bound can be an int, a string or a BoundType. Possible values are:

'replicate'  or 'nearest'     :  a  a  a  |  a  b  c  d  |  d  d  d
'dct1'       or 'mirror'      :  d  c  b  |  a  b  c  d  |  c  b  a
'dct2'       or 'reflect'     :  c  b  a  |  a  b  c  d  |  d  c  b
'dst1'       or 'antimirror'  : -b -a  0  |  a  b  c  d  |  0 -d -c
'dst2'       or 'antireflect' : -c -b -a  |  a  b  c  d  | -d -c -b
'dft'        or 'wrap'        :  b  c  d  |  a  b  c  d  |  a  b  c
'zero'       or 'zeros'       :  0  0  0  |  a  b  c  d  |  0  0  0

A list of values can be provided, in the order [W, H, D], to specify dimension-specific boundary conditions. Note that:

dft corresponds to circular padding;
dct2 corresponds to Neumann boundary conditions (symmetric);
dst2 corresponds to Dirichlet boundary conditions (antisymmetric).

See:

Parameters:

Name	Type	Description	Default
`input`	`(..., [channel], *inshape) tensor`	Input image.	required
`grid`	`(..., *outshape, dim) tensor`	Transformation field.	required
`interpolation`	`int or sequence[int]`	Interpolation order.	`1`
`bound`	`BoundType or sequence[BoundType]`	Boundary conditions.	`'zero'`
`extrapolate`	`bool or int`	Extrapolate out-of-bound data.	`False`
`prefilter`	`bool`	Apply the spline pre-filter, so that the spline interpolates the input.	`False`

Returns:

Name	Type	Description
`output`	`(..., [channel], *outshape, dim) tensor`	Sampled gradients.

spline_coeff

spline_coeff(input: Tensor, interpolation: OrderLike | Sequence[OrderLike] = 'linear', bound: BoundLike | Sequence[BoundLike] = 'dct2', dim: int = -1, inplace: bool = False) -> Tensor

Compute the interpolating spline coefficients, for a given spline order and boundary conditions, along a single dimension.

Notes

interpolation can be an int, a string or an InterpolationType. Possible values are:

0 or 'nearest'
1 or 'linear'
2 or 'quadratic'
3 or 'cubic'
4 or 'fourth'
5 or 'fifth'
etc.

A list of values can be provided, in the order [W, H, D], to specify dimension-specific interpolation orders.

bound can be an int, a string or a BoundType. Possible values are:

'replicate'  or 'nearest'     :  a  a  a  |  a  b  c  d  |  d  d  d
'dct1'       or 'mirror'      :  d  c  b  |  a  b  c  d  |  c  b  a
'dct2'       or 'reflect'     :  c  b  a  |  a  b  c  d  |  d  c  b
'dst1'       or 'antimirror'  : -b -a  0  |  a  b  c  d  |  0 -d -c
'dst2'       or 'antireflect' : -c -b -a  |  a  b  c  d  | -d -c -b
'dft'        or 'wrap'        :  b  c  d  |  a  b  c  d  |  a  b  c
'zero'       or 'zeros'       :  0  0  0  |  a  b  c  d  |  0  0  0

A list of values can be provided, in the order [W, H, D], to specify dimension-specific boundary conditions. Note that:

dft corresponds to circular padding;
dct1 corresponds to mirroring about the center of the first and last voxels;
dct2 corresponds to mirroring about the edge of the first and last voxels.

See:

Warning: only dct1, dct2 and dft are implemented for interpolation orders greater than or equal to 6.

References

M. Unser, A. Aldroubi and M. Eden. "B-Spline Signal Processing: Part I-Theory," IEEE Transactions on Signal Processing 41(2):821-832 (1993).
M. Unser, A. Aldroubi and M. Eden. "B-Spline Signal Processing: Part II-Efficient Design and Applications," IEEE Transactions on Signal Processing 41(2):834-848 (1993).
M. Unser. "Splines: A Perfect Fit for Signal and Image Processing," IEEE Signal Processing Magazine 16(6):22-38 (1999).

Parameters:

Name	Type	Description	Default
`input`	`tensor`	Input image.	required
`interpolation`	`int or sequence[int]`	Interpolation order.	`1`
`bound`	`BoundType or sequence[BoundType]`	Boundary conditions.	`'dct2'`
`dim`	`int`	Dimension along which to process.	`-1`
`inplace`	`bool`	Process the volume in place.	`False`

Returns:

Name	Type	Description
`output`	`tensor`	Coefficient image.

spline_coeff_nd

spline_coeff_nd(input: Tensor, interpolation: OrderLike | Sequence[OrderLike] = 'linear', bound: BoundLike | Sequence[BoundLike] = 'dct2', dim: int | None = None, inplace: bool = False) -> Tensor

Compute the interpolating spline coefficients, for a given spline order and boundary conditions, along the last dim dimensions.

Notes

interpolation can be an int, a string or an InterpolationType. Possible values are:

0 or 'nearest'
1 or 'linear'
2 or 'quadratic'
3 or 'cubic'
4 or 'fourth'
5 or 'fifth'
etc.

A list of values can be provided, in the order [W, H, D], to specify dimension-specific interpolation orders.

bound can be an int, a string or a BoundType. Possible values are:

'replicate'  or 'nearest'     :  a  a  a  |  a  b  c  d  |  d  d  d
'dct1'       or 'mirror'      :  d  c  b  |  a  b  c  d  |  c  b  a
'dct2'       or 'reflect'     :  c  b  a  |  a  b  c  d  |  d  c  b
'dst1'       or 'antimirror'  : -b -a  0  |  a  b  c  d  |  0 -d -c
'dst2'       or 'antireflect' : -c -b -a  |  a  b  c  d  | -d -c -b
'dft'        or 'wrap'        :  b  c  d  |  a  b  c  d  |  a  b  c
'zero'       or 'zeros'       :  0  0  0  |  a  b  c  d  |  0  0  0

A list of values can be provided, in the order [W, H, D], to specify dimension-specific boundary conditions. Note that:

dft corresponds to circular padding;
dct1 corresponds to mirroring about the center of the first and last voxels;
dct2 corresponds to mirroring about the edge of the first and last voxels.

See:

Warning: only dct1, dct2 and dft are implemented for interpolation orders greater than or equal to 6.

References

M. Unser, A. Aldroubi and M. Eden. "B-Spline Signal Processing: Part I-Theory," IEEE Transactions on Signal Processing 41(2):821-832 (1993).
M. Unser, A. Aldroubi and M. Eden. "B-Spline Signal Processing: Part II-Efficient Design and Applications," IEEE Transactions on Signal Processing 41(2):834-848 (1993).
M. Unser. "Splines: A Perfect Fit for Signal and Image Processing," IEEE Signal Processing Magazine 16(6):22-38 (1999).

Parameters:

Name	Type	Description	Default
`input`	`(..., *spatial) tensor`	Input image.	required
`interpolation`	`int or sequence[int]`	Interpolation order.	`1`
`bound`	`BoundType or sequence[BoundType]`	Boundary conditions.	`'dct2'`
`dim`	`int`	Number of trailing dimensions to process.	`input.dim()`
`inplace`	`bool`	Process the volume in place.	`False`

Returns:

Name	Type	Description
`output`	`(..., *spatial) tensor`	Coefficient image.

identity_grid

identity_grid(shape: Sequence[int], dtype: dtype | None = None, device: device | None = None) -> Tensor

Return an identity deformation field.

Parameters:

Name	Type	Description	Default
`shape`	`(dim,) sequence of int`	Spatial shape of the field.	required
`dtype`	`dtype`	Data type.	`torch.get_default_dtype()`
`device`	`device`	Device.	`None`

Returns:

Name	Type	Description
`grid`	`(*shape, dim) tensor`	Transformation field.

add_identity_grid_

add_identity_grid_(disp)

Add the identity grid to a displacement field, in place.

Parameters:

Name	Type	Description	Default
`disp`	`(..., *spatial, dim) tensor`	Displacement field.	required

Returns:

Name	Type	Description
`grid`	`(..., *spatial, dim) tensor`	Transformation field.

add_identity_grid

add_identity_grid(disp)

Add the identity grid to a displacement field.

Parameters:

Name	Type	Description	Default
`disp`	`(..., *spatial, dim) tensor`	Displacement field.	required

Returns:

Name	Type	Description
`grid`	`(..., *spatial, dim) tensor`	Transformation field.

affine_grid

affine_grid(mat: Tensor, shape: Sequence[int]) -> Tensor

Create a dense transformation grid from an affine matrix.

Parameters:

Name	Type	Description	Default
`mat`	`(..., D[+1], D+1) tensor`	Affine matrix (or matrices). The last row may be omitted.	required
`shape`	`(D,) sequence[int]`	Shape of the grid, with length D.	required

Returns:

Name	Type	Description
`grid`	`(..., *shape, D) tensor`	Dense transformation grid.

Raises:

Type	Description
`ValueError`	If the size of the affine matrix is inconsistent with `shape`, or if `mat` does not have D or D+1 rows.