linear operators

class parallelproj.LinearOperator(xp)

Bases: ABC

abstract base class for linear operators

Parameters:

xp (ModuleType) –

__call__(x)

Call self as a function.

__init__(xp)

init method

Parameters:

xp (ModuleType) – numpy or cupy module

abstract _adjoint(y)

adjoint step x = A^H y

abstract _apply(x)

forward step y = Ax

adjoint(y)

adjoint step x = conj(scale) * A^H y

Parameters:

y (numpy or cupy array) –

Return type:

numpy or cupy array

adjointness_test(verbose=False, iscomplex=False, **kwargs)

test whether the adjoint is correctly implemented

Parameters:

• verbose (bool, optional) – verbose output

• iscomplex (bool, optional) – use complex arrays

apply(x)

forward step y = scale * Ax

Parameters:

x (numpy or cupy array) –

Return type:

numpy or cupy array

abstract property in_shape: tuple[int, ...]

shape of the input array

norm(num_iter=30, iscomplex=False, verbose=False)

estimate norm of the linear operator using power iterations

Parameters:

• num_iter (int, optional) – number of power iterations

• iscomplex (bool, optional) – use complex arrays

• verbose (bool, optional) – verbose output

Returns:

the norm of the linear operator

Return type:

float

abstract property out_shape: tuple[int, ...]

shape of the output array

property scale: int | float | complex

scalar factor applied to the linear operator

property xp: module

module type (numpy or cupy) of the operator

class parallelproj.MatrixOperator(A, xp)

Bases: LinearOperator

Linear Operator defined by dense matrix multiplication

__init__(A, xp)

init method

Parameters:

• A (2D numpy or cupy real of complex array) –

• xp (ModuleType) – numpy or cupy module

_adjoint(y)

adjoint step x = A^H y

_apply(x)

forward step y = Ax

property in_shape

shape of the input array

property out_shape

shape of the output array

class parallelproj.ElementwiseMultiplicationOperator(values, xp)

Bases: LinearOperator

Element-wise multiplication operator (multiplication with a diagonal matrix)

__init__(values, xp)

init method

Parameters:

• values (numpy or cupy array) – values of the diagonal matrix

• xp (ModuleType) – numpy or cupy module

_adjoint(y)

adjoint step x = A^H y

_apply(x)

forward step y = Ax

property in_shape

shape of the input array

property out_shape

shape of the output array

class parallelproj.GaussianFilterOperator(in_shape, ndimage_module, xp, **kwargs)

Bases: LinearOperator

Gaussian filter operator

__init__(in_shape, ndimage_module, xp, **kwargs)

init method

Parameters:

• in_shape (tuple[int, ...]) – shape of the input array

• ndimage_module (scipy or cupyx.scipy module) –

• xp (ModuleType) – numpy or cupy module

• **kwargs (sometype) – passed to the ndimage gaussian_filter function

_adjoint(y)

adjoint step x = A^H y

_apply(x)

forward step y = Ax

property in_shape

shape of the input array

property out_shape

shape of the output array

class parallelproj.CompositeLinearOperator(operators)

Bases: LinearOperator

Composite Linear Operator defined by a sequence of Linear Operators

Given a tuple of operators (A_0, …, A_{n-1}) the composite operator is defined as A(x) = A0( A1( … ( A_{n-1}(x) ) ) )

Parameters:

operators (tuple[LinearOperator, ...]) –

__init__(operators)

init method

Parameters:

operators (tuple[LinearOperator, ...]) – tuple of linear operators

_adjoint(y)

adjoint step x = A^H y

_apply(x)

forward step y = Ax

property in_shape

shape of the input array

property operators: tuple[parallelproj.operators.LinearOperator, ...]

tuple of linear operators

property out_shape

shape of the output array

class parallelproj.VstackOperator(operators)

Bases: LinearOperator

Stacking operator for stacking multiple linear operators vertically

Parameters:

operators (tuple[LinearOperator, ...]) –

__init__(operators)

init method

Parameters:

operators (tuple[LinearOperator, ...]) – tuple of linear operators

Return type:

None

_adjoint(y)

adjoint step x = A^H y

_apply(x)

forward step y = Ax

property in_shape

shape of the input array

property out_shape

shape of the output array

class parallelproj.SubsetOperator(operators)

Bases: object

Operator split into subsets

Parameters:

operators (tuple[LinearOperator, ...]) –

__call__(x)

Call self as a function.

__init__(operators)

init method

Parameters:

operators (tuple[LinearOperator, ...]) – tuple of linear operators

Return type:

None

adjoint(y)

A_i^H x for all subsets i

adjoint_subset(x, i)

A_i^H x for a given subset i

apply(x)

A_i x for all subsets i

apply_subset(x, i)

A_i x for a given subset i

norms()

norm(A_i) for all subsets i

high-level projection operators

class parallelproj.ParallelViewProjector2D(image_shape, radial_positions, view_angles, radius, image_origin, voxel_size, xp)

Bases: LinearOperator

2D non-TOF parallel view projector

__init__(image_shape, radial_positions, view_angles, radius, image_origin, voxel_size, xp)

init method

Parameters:

• image_shape (tuple[int, int, int]) – shape of the input image (1, n1, n2)

• radial_positions (numpy or cupy array) – radial positions of the projection views in world coordinates

• angles (view) – angles of the projection views in radians

• radius (float) – radius of the scanner

• image_origin (3 element numpy or cupy array) – world coordinates of the [0,0,0] voxel

• voxel_size (3 element numpy or cupy array) – the voxel size

• xp (numpy or cupy module) –

_adjoint(y)

adjoint step x = A^H y

_apply(x)

forward step y = Ax

property in_shape

shape of the input array

property out_shape

shape of the output array

show_views(views_to_show=None, image=None, **kwargs)

visualize the geometry of certrain projection views

Parameters:

• views_to_show (numpy array of integers) – view numbers to show

• image (numpy array or cupy array, optional) – show an image inside the projector geometry

• **kwargs (some type) – passed to matplotlib.pyplot.imshow

low-level non-TOF projector API

parallelproj.joseph3d_fwd(xstart, xend, img, img_origin, voxsize, img_fwd, threadsperblock=32, num_chunks=1)

Non-TOF Joseph 3D forward projector

Parameters:

• xstart (XPFloat32Array (float32 numpy or cupy array)) – start world coordinates of the LORs, shape (nLORs, 3)

• xend (XPFloat32Array (float32 numpy or cupy array)) – end world coordinates of the LORs, shape (nLORs, 3)

• img (XPFloat32Array (float32 numpy or cupy array)) – containing the 3D image to be projected

• img_origin (XPFloat32Array (float32 numpy or cupy array)) – containing the world coordinates of the image origin (voxel [0,0,0])

• voxsize (XPFloat32Array (float32 numpy or cupy array)) – array containing the voxel size

• img_fwd (XPFloat32Array (float32 numpy or cupy array)) – output array of length nLORs for storing the forward projection

• threadsperblock (int, optional) – by default 32

• num_chunks (int, optional) – break down the projection in hybrid mode into chunks to save memory on the GPU, by default 1

Return type:

None

parallelproj.joseph3d_back(xstart, xend, back_img, img_origin, voxsize, sino, threadsperblock=32, num_chunks=1)

Non-TOF Joseph 3D back projector

Parameters:

• xstart (XPFloat32Array (float32 numpy or cupy array)) – start world coordinates of the LORs, shape (nLORs, 3)

• xend (XPFloat32Array (float32 numpy or cupy array)) – end world coordinates of the LORs, shape (nLORs, 3)

• back_img (XPFloat32Array (float32 numpy or cupy array)) – output array for the back projection

• img_origin (XPFloat32Array (float32 numpy or cupy array)) – containing the world coordinates of the image origin (voxel [0,0,0])

• voxsize (XPFloat32Array (float32 numpy or cupy array)) – array containing the voxel size

• sino (XPFloat32Array (float32 numpy or cupy array)) – array of length nLORs containing the values to be back projected

• threadsperblock (int, optional) – by default 32

• num_chunks (int, optional) – break down the back projection in hybrid mode into chunks to save memory on the GPU, by default 1

Return type:

None

low-level TOF projector API

parallelproj.joseph3d_fwd_tof_sino(xstart, xend, img, img_origin, voxsize, img_fwd, tofbin_width, sigma_tof, tofcenter_offset, nsigmas, ntofbins, threadsperblock=32, num_chunks=1)

TOF Joseph 3D sinogram forward projector

Parameters:

• xstart (XPFloat32Array (float32 numpy or cupy array)) – start world coordinates of the LORs, shape (nLORs, 3)

• xend (XPFloat32Array (float32 numpy or cupy array)) – end world coordinates of the LORs, shape (nLORs, 3)

• img (XPFloat32Array (float32 numpy or cupy array)) – containing the 3D image to be projected

• img_origin (XPFloat32Array (float32 numpy or cupy array)) – containing the world coordinates of the image origin (voxel [0,0,0])

• voxsize (XPFloat32Array (float32 numpy or cupy array)) – array containing the voxel size

• img_fwd (XPFloat32Array (float32 numpy or cupy array)) – output array of size (nLORs*ntofbins) for storing the forward projection

• tofbin_width (float) – width of the TOF bin in spatial units (same units as xstart)

• sigma_tof (XPFloat32Array (float32 numpy or cupy array)) – sigma of Gaussian TOF kernel in spatial units (same units as xstart) can be an array of length 1 -> same sigma for all LORs or an array of length nLORs -> LOR dependent sigma

• tofcenter_offset (XPFloat32Array (float32 numpy or cupy array)) – center offset of the central TOF bin in spatial units (same units as xstart) can be an array of length 1 -> same offset for all LORs or an array of length nLORs -> LOR dependent offset

• nsigmas (float) – number of sigmas to consider when Gaussian kernel is evaluated (truncated)

• ntofbins (int) – total number of TOF bins

• threadsperblock (int, optional) – by default 32

• num_chunks (int, optional) – break down the projection in hybrid mode into chunks to save memory on the GPU, by default 1

Return type:

None

parallelproj.joseph3d_back_tof_sino(xstart, xend, back_img, img_origin, voxsize, sino, tofbin_width, sigma_tof, tofcenter_offset, nsigmas, ntofbins, threadsperblock=32, num_chunks=1)

TOF Joseph 3D sinogram back projector

Parameters:

• xstart (XPFloat32Array (float32 numpy or cupy array)) – start world coordinates of the LORs, shape (nLORs, 3)

• xend (XPFloat32Array (float32 numpy or cupy array)) – end world coordinates of the LORs, shape (nLORs, 3)

• back_img (XPFloat32Array (float32 numpy or cupy array)) – output array to be back projected

• img_origin (XPFloat32Array (float32 numpy or cupy array)) – containing the world coordinates of the image origin (voxel [0,0,0])

• voxsize (XPFloat32Array (float32 numpy or cupy array)) – array containing the voxel size

• sino (XPFloat32Array (float32 numpy or cupy array)) – TOF sinogram of size (nLORs*ntofbins) to be back projected

• threadsperblock (int, optional) – by default 32

• sigma_tof (XPFloat32Array (float32 numpy or cupy array)) – sigma of Gaussian TOF kernel in spatial units (same units as xstart) can be an array of length 1 -> same sigma for all LORs or an array of length nLORs -> LOR dependent sigma

• tofcenter_offset (XPFloat32Array (float32 numpy or cupy array)) – center offset of the central TOF bin in spatial units (same units as xstart) can be an array of length 1 -> same offset for all LORs or an array of length nLORs -> LOR dependent offset

• nsigmas (float) – number of sigmas to consider when Gaussian kernel is evaluated (truncated)

• ntofbins (int) – total number of TOF bins

• num_chunks (int, optional) – break down the projection in hybrid mode into chunks to save memory on the GPU, by default 1

• tofbin_width (float) – width of the TOF bin in spatial units (same units as xstart)

Return type:

None

low-level TOF listmode projector API

parallelproj.joseph3d_fwd_tof_lm(xstart, xend, img, img_origin, voxsize, img_fwd, tofbin_width, sigma_tof, tofcenter_offset, nsigmas, tofbin, threadsperblock=32, num_chunks=1)

TOF Joseph 3D listmode forward projector

Parameters:

• xstart (XPFloat32Array (float32 numpy or cupy array)) – start world coordinates of the LORs, shape (nLORs, 3)

• xend (XPFloat32Array (float32 numpy or cupy array)) – end world coordinates of the LORs, shape (nLORs, 3)

• img (XPFloat32Array (float32 numpy or cupy array)) – containing the 3D image to be projected

• img_origin (XPFloat32Array (float32 numpy or cupy array)) – containing the world coordinates of the image origin (voxel [0,0,0])

• voxsize (XPFloat32Array (float32 numpy or cupy array)) – array containing the voxel size

• img_fwd (XPFloat32Array (float32 numpy or cupy array)) – output array of size (xstart.shape[0] / nevents) for storing the forward projection

• tofbin_width (float) – width of the TOF bin in spatial units (same units as xstart)

• sigma_tof (XPFloat32Array (float32 numpy or cupy array)) – sigma of Gaussian TOF kernel in spatial units (same units as xstart) can be an array of length 1 -> same sigma for all LORs or an array of length nLORs -> LOR dependent sigma

• tofcenter_offset (XPFloat32Array (float32 numpy or cupy array)) – center offset of the central TOF bin in spatial units (same units as xstart) can be an array of length 1 -> same offset for all LORs or an array of length nLORs -> LOR dependent offset

• nsigmas (float) – number of sigmas to consider when Gaussian kernel is evaluated (truncated)

• tofbin (XPShortArray) – array containing the tof bin of the events

• threadsperblock (int, optional) – by default 32

• num_chunks (int, optional) – break down the projection in hybrid mode into chunks to save memory on the GPU, by default 1

Return type:

None

parallelproj.joseph3d_back_tof_lm(xstart, xend, back_img, img_origin, voxsize, lst, tofbin_width, sigma_tof, tofcenter_offset, nsigmas, tofbin, threadsperblock=32, num_chunks=1)

TOF Joseph 3D listmode back projector

Parameters:

• xstart (XPFloat32Array (float32 numpy or cupy array)) – start world coordinates of the LORs, shape (nLORs, 3)

• xend (XPFloat32Array (float32 numpy or cupy array)) – end world coordinates of the LORs, shape (nLORs, 3)

• back_img (XPFloat32Array (float32 numpy or cupy array)) – output array to be back projected

• img_origin (XPFloat32Array (float32 numpy or cupy array)) – containing the world coordinates of the image origin (voxel [0,0,0])

• voxsize (XPFloat32Array (float32 numpy or cupy array)) – array containing the voxel size

• lst (XPFloat32Array (float32 numpy or cupy array)) – “list” of values to be projected

• threadsperblock (int, optional) – by default 32

• sigma_tof (XPFloat32Array (float32 numpy or cupy array)) – sigma of Gaussian TOF kernel in spatial units (same units as xstart) can be an array of length 1 -> same sigma for all LORs or an array of length nLORs -> LOR dependent sigma

• tofcenter_offset (XPFloat32Array (float32 numpy or cupy array)) – center offset of the central TOF bin in spatial units (same units as xstart) can be an array of length 1 -> same offset for all LORs or an array of length nLORs -> LOR dependent offset

• nsigmas (float) – number of sigmas to consider when Gaussian kernel is evaluated (truncated)

• tofbin (XPShortArray) – array containing the tof bin of the events

• num_chunks (int, optional) – break down the projection in hybrid mode into chunks to save memory on the GPU, by default 1

• tofbin_width (float) – width of the TOF bin in spatial units (same units as xstart)

Return type:

None