pytomography.algorithms.osem#

This module contains classes that implement ordered-subset maximum liklihood iterative reconstruction algorithms. Such algorithms compute \(f_i^{n,m+1}\) from \(f_i^{n,m}\) where \(n\) is the index for an iteration, and \(m\) is the index for a subiteration (i.e. for a given subset). The notation is defined such that given \(M\) total subsets of equal size, \(f_i^{n+1,0} \equiv f_i^{n,M}\) (i.e. after completing a subiteration for each subset, we start the next iteration). Any class that inherits from this class must implement the forward method. __init__ initializes the reconstruction algorithm with the image data \(g_j\), the forward and back projections used (i.e. networks to compute \(\sum_i c_{ij} a_i\) and \(\sum_j c_{ij} b_j\)), the initial object guess \(f_i^{0,0}\), the estimated scatter contribution \(s_j\), and the Bayesian Prior function \(V(f)\). Once the class is initialized, the number of iterations and subsets are specified at recon time when the forward method is called.

Module Contents#

Classes#

OSML

Abstract class for different algorithms. The difference between subclasses of this class is the method by which they include prior information. If no prior function is used, they are all equivalent.

OSEMOSL

Implements the ordered subset expectation algorithm using the one-step-late method to include prior information: \(f_i^{n,m+1} = \frac{f_i^{n,m}}{\sum_j c_{ij} + \beta \frac{\partial V}{\partial f_r}|_{f_i=f_i^{n,m}}} \sum_j c_{ij}\frac{g_j}{\sum_i c_{ij}f_i^{n,m}+s_j}\).

OSEMBSR

Implements the ordered subset expectation algorithm using the block-sequential-regularized (BSREM) method to include prior information. In particular, each iteration consists of two steps: \(\tilde{f}_i^{n,m+1} = \frac{f_i^{n,m}}{\sum_j c_{ij}} \sum_j c_{ij}\frac{g_j^m}{\sum_i c_{ij}f_i^{n,m}+s_j}\) followed by \(f_i^{n,m+1} = \tilde{f}_i^{n,m+1} \left(1-\beta\frac{\alpha_n}{\sum_j c_{ij}}\frac{\partial V}{\partial \tilde{f}_i^{n,m+1}} \right)\).

Functions#

get_osem_net(projections_header[, scatter_headers, ...])

Function used to obtain an OSEMOSL given projection data and corrections one wishes to use.

class pytomography.algorithms.osem.OSML(image, forward_projection_net, back_projection_net, object_initial=None, scatter=0, prior=None)#

Bases: torch.nn.Module

Abstract class for different algorithms. The difference between subclasses of this class is the method by which they include prior information. If no prior function is used, they are all equivalent.

Parameters:
  • image (torch.tensor[batch_size, Lr, Ltheta, Lz]) – image data \(g_j\) to be reconstructed

  • object_initial (torch.tensor[batch_size, Lx, Ly, Lz]) – represents the initial object guess \(f_i^{0,0}\) for the algorithm in object space

  • forward_projection_net (ForwardProjectionNet) – the forward projection network used to compute \(\sum_{i} c_{ij} a_i\) where \(a_i\) is the object being forward projected.

  • back_projection_net (BackProjectionNet) – the back projection network used to compute \(\sum_{j} c_{ij} b_j\) where \(b_j\) is the image being back projected.

  • scatter (torch.tensor[batch_size, Lr, Ltheta, Lz]) – estimate of scatter contribution \(s_j\).

  • prior (Prior, optional) – the Bayesian prior; computes \(\beta \frac{\partial V}{\partial f_r}\). If None, then this term is 0. Defaults to None.

get_subset_splits(n_subsets, n_angles)#

Returns a list of arrays; each array contains indices, corresponding to projection numbers, that are used in ordered-subsets. For example, get_subsets_splits(2, 6) would return [[0,2,4],[1,3,5]]. :param n_subsets: number of subsets used in OSEM :type n_subsets: int :param n_angles: total number of projections :type n_angles: int

Returns:

list of index arrays for each subset

Return type:

list

Parameters:
  • n_subsets (int) –

  • n_angles (int) –

abstract forward(n_iters, n_subsets, callbacks=None)#

Abstract method for performing reconstruction: must be implemented by subclasses.

Parameters:
  • n_iters (int) – Number of iterations

  • n_subsets (int) – Number of subsets

  • callbacks (CallBack, optional) – CallBacks to be evaluated after each subiteration. Defaults to None.

Return type:

None

class pytomography.algorithms.osem.OSEMOSL(image, forward_projection_net, back_projection_net, object_initial=None, scatter=0, prior=None)#

Bases: OSML

Implements the ordered subset expectation algorithm using the one-step-late method to include prior information: \(f_i^{n,m+1} = \frac{f_i^{n,m}}{\sum_j c_{ij} + \beta \frac{\partial V}{\partial f_r}|_{f_i=f_i^{n,m}}} \sum_j c_{ij}\frac{g_j}{\sum_i c_{ij}f_i^{n,m}+s_j}\).

Parameters:
  • object_initial (torch.tensor[batch_size, Lx, Ly, Lz]) – represents the initial object guess \(f_i^{0,0}\) for the algorithm in object space

  • forward_projection_net (ForwardProjectionNet) – the forward projection network used to compute \(\sum_{i} c_{ij} a_i\) where \(a_i\) is the object being forward projected.

  • back_projection_net (BackProjectionNet) – the back projection network used to compute \(\sum_{j} c_{ij} b_j\) where \(b_j\) is the image being back projected.

  • prior (Prior, optional) – the Bayesian prior; computes \(\beta \frac{\partial V}{\partial f_r}\). If None, then this term is 0. Defaults to None.

  • image (torch.tensor) –

  • scatter (torch.tensor | float) –

forward(n_iters, n_subsets, callback=None, delta=1e-11)#

Performs the reconstruction using n_iters iterations and n_subsets subsets.

Parameters:
  • n_iters (int) – _description_

  • n_subsets (int) – _description_

  • callback (CallBack, optional) – Callback function to be evaluated after each subiteration. Defaults to None.

  • delta (float, optional) – Used to prevent division by zero when calculating ratio, defaults to 1e-11.

Returns:

reconstructed object

Return type:

torch.tensor[batch_size, Lx, Ly, Lz]

class pytomography.algorithms.osem.OSEMBSR(image, forward_projection_net, back_projection_net, object_initial=None, scatter=0, prior=None)#

Bases: OSML

Implements the ordered subset expectation algorithm using the block-sequential-regularized (BSREM) method to include prior information. In particular, each iteration consists of two steps: \(\tilde{f}_i^{n,m+1} = \frac{f_i^{n,m}}{\sum_j c_{ij}} \sum_j c_{ij}\frac{g_j^m}{\sum_i c_{ij}f_i^{n,m}+s_j}\) followed by \(f_i^{n,m+1} = \tilde{f}_i^{n,m+1} \left(1-\beta\frac{\alpha_n}{\sum_j c_{ij}}\frac{\partial V}{\partial \tilde{f}_i^{n,m+1}} \right)\).

Parameters:
  • object_initial (torch.tensor[batch_size, Lx, Ly, Lz]) – represents the initial object guess \(f_i^{0,0}\) for the algorithm in object space

  • forward_projection_net (ForwardProjectionNet) – the forward projection network used to compute \(\sum_{i} c_{ij} a_i\) where \(a_i\) is the object being forward projected.

  • back_projection_net (BackProjectionNet) – the back projection network used to compute \(\sum_{j} c_{ij} b_j\) where \(b_j\) is the image being back projected.

  • prior (Prior, optional) – the Bayesian prior; computes \(\beta \frac{\partial V}{\partial f_r}\). If None, then this term is 0. Defaults to None.

  • image (torch.tensor) –

  • scatter (torch.tensor | float) –

forward(n_iters, n_subsets, relaxation_function=lambda x: ..., callback=None, delta=1e-11)#

Performs the reconstruction using n_iters iterations and n_subsets subsets.

Parameters:
  • n_iters (int) – Number of iterations

  • n_subsets (int) – Number of subsets

  • relaxation_function (function) – Specifies relaxation sequence \(\alpha_n\) where \(n\) is the iteration number. Defaults to \(\alpha_n=1\) for all \(n\).

  • callback (CallBack, optional) – Callback function to be called after each subiteration. Defaults to None.

  • delta (_type_, optional) – Used to prevent division by zero when calculating ratio, defaults to 1e-11.

Returns:

reconstructed object

Return type:

torch.tensor[batch_size, Lx, Ly, Lz]

pytomography.algorithms.osem.get_osem_net(projections_header, scatter_headers=None, CT_header=None, psf_meta=None, file_type='simind', prior=None, object_initial=None, device='cpu')#

Function used to obtain an OSEMOSL given projection data and corrections one wishes to use.

Parameters:
  • projections_header (str) – Path to projection header data (in some modalities, this is also the data path i.e. DICOM). Data from this file is used to set the dimensions of the object [batch_size, Lx, Ly, Lz] and the image [batch_size, Ltheta, Lr, Lz] and the projection data one wants to reconstruct.

  • scatter_headers (Sequence[str]) – List of files corresponding to the lower and upper energy windows.

  • CT_header (str or list, optional) – File path pointing to CT data file or files. Defaults to None.

  • psf_meta (PSFMeta, optional) – Metadata specifying PSF correction parameters, such as collimator slope and intercept. Defaults to None.

  • file_type (str, optional) – The file type of the projections_header file. Options include simind output and DICOM. Defaults to ‘simind’.

  • prior (Prior, optional) – The prior used during reconstruction. If None, use no prior. Defaults to None.

  • object_initial (str or torch.tensor, optional) – Specifies initial object. In the case of ‘ones’, defaults to a tensor of shape [batch_size, Lx, Ly, Lz] containing all ones. Otherwise, takes in a specific initial guess. Defaults to ‘ones’.

  • device (str, optional) – The device used in pytorch for reconstruction. Graphics card can be used. Defaults to ‘cpu’.

Returns:

An initialized OSEMNet, ready to perform reconstruction.

Return type:

OSEMNet