mrpro.operators.SliceProjectionOp

class mrpro.operators.SliceProjectionOp(input_shape: SpatialDimension[int], slice_rotation: Rotation | None = None, slice_shift: float | Tensor = 0.0, slice_profile: Callable[[Tensor], Tensor] | ndarray | _NestedSequence[Callable[[Tensor], Tensor]] | float = 2.0, optimize_for: Literal['forward', 'adjoint', 'both'] = 'both')[source]

Bases: LinearOperator

Slice Projection Operator.

This operation samples from a 3D Volume a slice with a given rotation and shift (relative to the center of the volume) according to the slice_profile. It can, for example, be used to describe the slice selection of a 2D MRI sequence from the 3D Volume.

The projection will be done by sparse matrix multiplication.

Rotation, shift, and profile can have (multiple) batch dimensions. These dimensions will be broadcasted to a common shape and added to the front of the volume. Different settings for different volume batches are NOT supported, consider creating multiple operators if required.

__init__(input_shape: SpatialDimension[int], slice_rotation: Rotation | None = None, slice_shift: float | Tensor = 0.0, slice_profile: Callable[[Tensor], Tensor] | ndarray | _NestedSequence[Callable[[Tensor], Tensor]] | float = 2.0, optimize_for: Literal['forward', 'adjoint', 'both'] = 'both')[source]

Create a module that represents the ‘projection’ of a volume onto a plane.

This operation samples from a 3D Volume a slice with a given rotation and shift (relative to the center of the volume) according to the slice_profile. It can, for example, be used to describe the slice selection of a 2D MRI sequence from the 3D Volume.

The projection will be done by sparse matrix multiplication.

Rotation, shift, and profile can have (multiple) batch dimensions. These dimensions will be broadcasted to a common shape and added to the front of the volume. Different settings for different volume batches are NOT supported, consider creating multiple operators if required.

Parameters:

  • input_shape – Shape of the 3D volume to sample from (z, y, x)

  • slice_rotation – Rotation that describes the orientation of the plane. If None, an identity rotation is used.

  • slice_shift – Offset of the plane in the volume perpendicular plane from the center of the volume. (The center of a 4 pixel volume is between 1 and 2.)

  • slice_profile – A function returning the relative intensity of the slice profile at a position x (relative to the nominal profile center). This can also be a nested Sequence or an numpy array of functions. If it is a single float, it will be interpreted as the FWHM of a rectangular profile.

  • optimize_for – Whether to optimize for forward or adjoint operation or both. Optimizing for both takes more memory but is faster for both operations.

adjoint(x: Tensor) → tuple[Tensor][source]

Transform from a 2D slice to a 3D Volume.

Parameters:

x – 2D Slice with shape (…, 1, max(z, y, x), (max(z, y, x))) with z, y, x matching the input_shape

Returns:

with z, y, x matching the input_shape

Return type:

A 3D Volume with shape (…, z, y, x)

forward(x: Tensor) → tuple[Tensor][source]

Transform from a 3D Volume to a 2D Slice.

Parameters:

x – 3D Volume with shape (…, z, y, x) with z, y, x matching the input_shape

Return type:

A 2D slice with shape (…, 1, max(z, y, x), (max(z, y, x)))

static join_matrices(matrices: Sequence[Tensor]) → Tensor[source]

Join multiple sparse matrices into a block diagonal matrix.

Parameters:

matrices – List of sparse matrices to join by stacking them as a block diagonal matrix

operator_norm(initial_value: Tensor, dim: Sequence[int] | None, max_iterations: int = 20, relative_tolerance: float = 0.0001, absolute_tolerance: float = 1e-05, callback: Callable[[Tensor], None] | None = None) → Tensor

Power iteration for computing the operator norm of the linear operator.

Parameters:

  • initial_value – initial value to start the iteration; if the initial value contains a zero-vector for one of the considered problems, the function throws an value error.

  • dim – the dimensions of the tensors on which the operator operates. For example, for a matrix-vector multiplication example, a batched matrix tensor with shape (4,30,80,160), input tensors of shape (4,30,160) to be multiplied, and dim = None, it is understood that the matrix representation of the operator corresponds to a block diagonal operator (with 4*30 matrices) and thus the algorithm returns a tensor of shape (1,1,1) containing one single value. In contrast, if for example, dim=(-1,), the algorithm computes a batched operator norm and returns a tensor of shape (4,30,1) corresponding to the operator norms of the respective matrices in the diagonal of the block-diagonal operator (if considered in matrix representation). In any case, the output of the algorithm has the same number of dimensions as the elements of the domain of the considered operator (whose dimensionality is implicitly defined by choosing dim), such that the pointwise multiplication of the operator norm and elements of the domain (to be for example used in a Landweber iteration) is well-defined.

  • max_iterations – maximum number of iterations

  • relative_tolerance – absolute tolerance for the change of the operator-norm at each iteration; if set to zero, the maximal number of iterations is the only stopping criterion used to stop the power iteration

  • absolute_tolerance – absolute tolerance for the change of the operator-norm at each iteration; if set to zero, the maximal number of iterations is the only stopping criterion used to stop the power iteration

  • callback – user-provided function to be called at each iteration

Return type:

an estimaton of the operator norm

static projection_matrix(input_shape: SpatialDimension[int], output_shape: SpatialDimension[int], rotation: Rotation, offset: Tensor, w: int, slice_function: Callable[[Tensor], Tensor], rotation_center: Tensor | None = None) → Tensor[source]

Create a sparse matrix that represents the projection of a volume onto a plane.

Outside the volume values are approximately zero padded

Parameters:

  • input_shape – Shape of the volume to sample from

  • output_shape – Shape of the resulting plane, 2D. Only the x and y values are used.

  • rotation – Rotation that describes the orientation of the plane

  • offset (Tensor) – Shift of the plane from the center of the volume in the rotated coordinate system in units of the 3D volume, order z, y, x

  • w (int) – Factor that determines the number of pixels that are considered in the projection along the slice profile direction.

  • slice_function – Function that describes the slice profile.

  • rotation_center – Center of rotation, if None the center of the volume is used, i.e. for 4 pixels 0 1 2 3 it is between 1 and 2

Returns:

Sparse matrix that represents the projection of the volume onto the plane

Return type:

torch.sparse_coo_matrix

property H: LinearOperator

Adjoint operator.

property gram: LinearOperator

Gram operator.

For a LinearOperator \(A\), the self-adjoint Gram operator is defined as \(A^H A\).

Note: This is a default implementation that can be overwritten by subclasses for more efficient implementations.