imwip.operators

Image warping is linear in terms of the input image (even if degree 3 is used for the splines). This means that the warp can be represented by a matrix M, such that for a (raveled) image x, the warped image is given by M @ x, where @ is Python’s matmul (matrix multiplication) operator. The adjoint warp is given by M.T @ x or x @ M. The matrix M can be obtained explicitly, using imwip.matrices.

This module provides Scipy LinearOperators which are equivalent to the matrix representation, but avoid the memory use of explicly storing the matrix. It replaces the matrix-vecor multiplication with the efficient GPU implementations of warps and adjoint warps. This allows for concise and expressive notation of many mathematical algorithms without any performance cost. It is compatible with other packages that use SciPy LinearOperators such as Pylops and the solvers of scipy.sparse.linalg.

imwip.operators.operators_dvf

file: operators_dvf.py
brief: High level access to the DVF warping functions through linear operators.
author: Jens Renders

class imwip.operators.operators_dvf.WarpingOperator2D(*args, **kwargs)

Bases: LinearOperator

A 2D warping operator defined by a DVF, represented as a scipy LinearOperator.

Parameters

u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
degree (1 or 3, optional) – Degree of the splines used for interpolation
adjoint_type (exact, negative or inverse) – Method to compute the adjoint. Defaults to exact.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba

class imwip.operators.operators_dvf.WarpingOperator3D(*args, **kwargs)

Bases: LinearOperator

A 3D warping operator defined by a DVF, represented as a scipy LinearOperator.

Parameters

u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
w (numpy.ndarray) – Third component of the DVF describing the warp
degree (1 or 3, optional) – Degree of the splines used for interpolation
adjoint_type (exact, negative or inverse) – Method to compute the adjoint. Defaults to exact.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba

imwip.operators.operators_dvf.diff_warping_operator_2D(image, u, v, approx=False, backend=None)

The derivative of a 2D image warping operator towards the DVF is a 3D tensor. Instead, this function returns the derivative of a warping operator applied to an image. This is a diagonal matrix which is returned as a Pylops LinearOperator.

Parameters

image (numpy.ndarray) –
u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
approx (bool, optional) – If exact, the exact derivative will be computed by differentiating the matrix coefficients. If approx, it will be approximated by applying an image gradient to the warped image, which ignores the interpolation method used. Defaults to exact.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba.

Returns

derivative of warped image, towards the DVF

Return type

LinearOperator

imwip.operators.operators_dvf.diff_warping_operator_3D(image, u, v, w, approx=False, backend=None)

The derivative of a 3D image warping operator towards the DVF is a 3D tensor. Instead, this function returns the derivative of a warping operator applied to an image. This is a diagonal matrix which is returned as a Pylops LinearOperator.

Parameters

image (numpy.ndarray) –
u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
w (numpy.ndarray) – Third component of the DVF describing the warp
approx (bool, optional) – If exact, the exact derivative will be computed by differentiating the matrix coefficients. If approx, it will be approximated by applying an image gradient to the warped image, which ignores the interpolation method used. Defaults to exact.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba.

Returns

derivative of warped image, towards the DVF

Return type

LinearOperator

imwip.operators.operators_dvf.partial_diff_warping_operator_3D(image, u, v, w, to, approx=False, backend=None)

Equivalent to diff_warping_operator_3D(), except it only differentiates to one of the DVF components, specified by the to parameter.

Parameters

image (numpy.ndarray) –
u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
w (numpy.ndarray) – Third component of the DVF describing the warp
to (0, 1 or 2) – To which component to differentiate
approx (bool, optional) – If exact, the exact derivative will be computed by differentiating the matrix coefficients. If approx, it will be approximated by applying an image gradient to the warped image, which ignores the interpolation method used. Defaults to exact.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba.

Returns

partial derivative of warped image, towards one compoment of the DVF

Return type

LinearOperator

imwip.operators.operators_affine

file: operators_affine.py
brief: High level access to the affine warping functions through linear operators. These operators also help with differentiation towards affine and rigid parameters.
author: Jens Renders

class imwip.operators.operators_affine.AffineWarpingOperator2D(*args, **kwargs)

Bases: LinearOperator

A 2D warping operator represented as a scipy LinearOperator. It is defined by an affine transformation \(Ax + b\) or other affine or rigid parameters such as scaling, rotations and translations.

Parameters

im_shape (tuple of ints) – shape of the images to be warped
A (numpy.ndarray, optional) – 2x2 matrix A of the affine transformation Ax + b.
b (numpy.ndarray, optional) – Vector b of the affine transformation Ax + b. It should have length 2.
scale (float or sequence of floats, optional) – Scaling parameters of the transformation. If a float, scaling will be equal in all axes.
rotation (float, optional) – Rotation parameter of the transformation, in radians.
translation (sequence of floats, optional) – Translation parameters of the transformation.
centered (bool, optional) – Whether to use the image center as center for the transformation, instead of the (0,0) coordinate. Defaults to True.
degree (1 or 3, optional) – Degree of the splines used for interpolation
adjoint_type (exact or inverse, optional) – Method to compute the adjoint. Defaults to exact.
derivative_type (exact or approx, optional) – Method to compute the derivatives. Defaults to exact.
indexing (ij or xy, optional) – ij uses standard numpy array indexing. “xy” reversed the order of the indexes, making the vertical axis the first index. This can be more intuitive for 2D arrays. Defaults to ij.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba

derivative(x, to=['b'])

Computes the derivative of M @ x where M is this operator and x is a raveled image. You can differentiate towards any of the available parameters for defining the operator, independend of which ones you used to define it. For example, you can define the operator using A en b and then differentiate it towards the rotation parameter.

Parameters

x (numpy.ndarray) – A raveled image x on which this operator acts.
to (sequence of strings) – The parameters to differentiate towards.

Returns

The derivative as a dense matrix

Return type

numpy.ndarray

class imwip.operators.operators_affine.AffineWarpingOperator3D(*args, **kwargs)

Bases: LinearOperator

A 3D warping operator represented as a scipy LinearOperator. It is defined by an affine transformation \(Ax + b\) or other affine or rigid parameters such as scaling, rotations and translations.

Parameters

im_shape (tuple of ints) – shape of the images to be warped
A (numpy.ndarray, optional) – 3x3 matrix A of the affine transformation Ax + b.
b (numpy.ndarray, optional) – Vector b of the affine transformation Ax + b. It should have length 3.
scale (float or sequence of floats, optional) – Scaling parameters of the transformation. If a float, scaling will be equal in all axes.
rotation (sequence of floats, optional) – Rotation parameters of the transformation, in radians, one for each axis. The rotations will be applied in the order of the axes.
cayley (sequence of floats, optional) – Three Cayley parameters. This is an alternative parametrisation of a 3D rotation using the Cayley transform, which is numerically more favorable. It can be interpreted as the rotation corresponding to the quaternion 1+ix+jy+kz, where x, y and z are the Cayley parameters.
translation (sequence of floats, optional) – Translation parameters of the transformation.
centered (bool, optional) – Whether to use the provided center as center for the transformation, instead of the (0,0,0) coordinate. Defaults to True.
center (numpy.ndarray, optional) – The center of the transformation. If None, it will be set to the image center. Defaults to None.
degree (1 or 3, optional) – Degree of the splines used for interpolation
adjoint_type (exact or inverse, optional) – Method to compute the adjoint. Defaults to exact.
derivative_type (exact or approx, optional) – Method to compute the derivatives. Defaults to exact.
indexing (ij or xy, optional) – ij uses standard numpy array indexing. “xy” reversed the order of the indexes.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba

derivative(x, to=['b'])

Computes the derivative of M @ x where M is this operator and x is a raveled image. You can differentiate towards any of the available parameters for defining the operator, independend of which ones you used to define it. For example, you can define the operator using the rotation parameters and then differentiate it towards the caylay parameters.

Parameters

x (numpy.ndarray) – A raveled image x on which this operator acts.
to (sequence of strings) – The parameters to differentiate towards.

Returns

The derivative as a dense matrix

Return type

numpy.ndarray