:orphan:

Examples
========

These galleries progress from PET scanner geometry and projectors, through
iterative reconstruction algorithms (sinogram and listmode), to transmission and
joint activity/attenuation (MLAA) reconstruction, and finally PyTorch
integration.  If you are new to parallelproj, read the Quickstart first, then
work through the galleries roughly in numerical order.

Every example selects its array backend and device through the helper
``suggest_array_backend_and_device`` from ``parallelproj._examples_utils`` -- a
private, examples-only module shipped inside parallelproj -- so the same code
runs on CPU or GPU with nothing extra to install or download.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

PET scanner and sinogram geometry examples
------------------------------------------

These examples introduce the geometry objects that every projector is built
from: cylindrical regular-polygon scanners and modular block scanners, how
detector lines of response (LORs) map to sinogram bins, axial compression via
the Michelogram (span and maximum ring difference), and sinogram symmetries.
Start here to understand the building blocks used throughout the other
galleries.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to create and visualize PET scanners where the LOR endpoints can be modeled as a stack of regular polygons.">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_01_run_regular_polygon_pet_scanner_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/01_run_regular_polygon_pet_scanner`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Regular polygon PET scanner geometry</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In a scanner with &quot;cylindrical symmetry&quot;, all possible lines of response (LORs) between two LOR endpoints can be sorted into a sinogram containing a radial, view and plane dimension. This example shows how this can be done using the .RegularPolygonPETLORDescriptor">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_02_run_regular_polygon_pet_sino_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/02_run_regular_polygon_pet_sino`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">LOR descriptors and sinogram definition</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to setup a generic PET scanner consisting of multiple block modules where each block module consists of a regular grid of LOR endpoints. We also show how to define a LOR descriptor for this geometry using a description of which block pairs are in coincidence.">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_03_run_block_scanner_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/03_run_block_scanner`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Modularized (block) PET scanner geometry</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A Michelogram is a diagram of which ring pairs (s, e) form valid coincidences in a cylindrical PET scanner, and how they are grouped into sinogram planes under Siemens / STIR axial compression conventions.  Ring pairs are sorted by segment (a function of the ring difference rd = e - s) and, within each segment, by axial midpoint s + e.">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_04_run_michelogram_and_compression_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/04_run_michelogram_and_compression`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Michelograms and axial sinogram compression</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For a given sinogram view, a regular polygon PET scanner connects pairs of in-ring detector endpoints in a zig-zag pattern as the radial bin index moves from the central LOR toward the sinogram edges.  Two conventions exist for the ordering of those pairs:">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_05_run_zigzag_comparison_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/05_run_zigzag_comparison`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Zig-zag sampling of LORs in a sinogram view</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A cylindrically-symmetric PET scanner admits five families of symmetry that reduce the number of geometrically distinct sinogram bins This example focuses on the three axial (plane) symmetries and then quantifies the additional gain from the two in-plane symmetries.">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_06_run_sinogram_symmetries_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/06_run_sinogram_symmetries`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Sinogram symmetries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Mashing groups neighbouring detectors into larger virtual detectors located at the average endpoint position.  By reducing the number of detectors it dramatically reduces the number of lines of response (LORs), which shrinks the sinogram and speeds up reconstruction at the cost of spatial resolution.">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_07_run_detector_mashing_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/07_run_detector_mashing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Detector mashing: fewer, bigger virtual detectors</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="TOF mashing groups neighbouring time-of-flight (TOF) bins into fewer, wider bins.  This shrinks the TOF axis of a sinogram (less memory, faster reconstruction) at the cost of TOF resolution -- completely independent of any detector / LOR mashing along the spatial axes.">

.. only:: html

  .. image:: /auto_examples/01_pet_geometry/images/thumb/sphx_glr_08_run_tof_bin_mashing_thumb.png
    :alt:

  :doc:`/auto_examples/01_pet_geometry/08_run_tof_bin_mashing`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">TOF-bin mashing: fewer, wider time-of-flight bins</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

PET sinogram and listmode projector examples
--------------------------------------------

Here you build projectors and run forward and back projections: non-TOF and TOF
sinogram projectors for cylindrical scanners, the equal-block projector for
modular scanners, the listmode projector, and the unlister that maps listmode
events to sinograms.  These examples show the core ``proj(image)`` /
``proj.adjoint(sinogram)`` interface that the reconstruction galleries rely on.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we will show how to setup and use a PET sinogram projector consisting of a geometrical forward projector (Joseph&#x27;s method), a resolution model and the modeling of attenuation.">

.. only:: html

  .. image:: /auto_examples/02_pet_sinogram_projections/images/thumb/sphx_glr_01_run_pet_non_tof_sinogram_projector_thumb.png
    :alt:

  :doc:`/auto_examples/02_pet_sinogram_projections/01_run_pet_non_tof_sinogram_projector`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PET non-TOF sinogram projector</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we will show how to setup and use a TOF PET sinogram projector consisting of a geometrical TOF forward projector (Joseph&#x27;s method), a resolution model and the modeling of attenuation.">

.. only:: html

  .. image:: /auto_examples/02_pet_sinogram_projections/images/thumb/sphx_glr_02_run_pet_tof_sinogram_projector_thumb.png
    :alt:

  :doc:`/auto_examples/02_pet_sinogram_projections/02_run_pet_tof_sinogram_projector`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PET TOF sinogram projector</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to perform non-TOF and TOF projections using a PET scanner consisting of multiple block modules where each block module consists of a regular grid of LOR endpoints.">

.. only:: html

  .. image:: /auto_examples/02_pet_sinogram_projections/images/thumb/sphx_glr_03_run_equalblock_projector_thumb.png
    :alt:

  :doc:`/auto_examples/02_pet_sinogram_projections/03_run_equalblock_projector`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Non-TOF and TOF projections using a modularized (block) PET scanner geometry</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how to setup and use a PET listmode projector for both non-TOF and TOF acquisitions, including geometrical forward projection in listmode, image-based resolution model, and a listmode attenuation model.">

.. only:: html

  .. image:: /auto_examples/02_pet_sinogram_projections/images/thumb/sphx_glr_04_run_pet_listmode_projector_thumb.png
    :alt:

  :doc:`/auto_examples/02_pet_sinogram_projections/04_run_pet_listmode_projector`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PET listmode projector (non-TOF and TOF)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates .regular_polygon_events_to_sinogram, which histograms listmode events into a sinogram.">

.. only:: html

  .. image:: /auto_examples/02_pet_sinogram_projections/images/thumb/sphx_glr_05_run_unlister_thumb.png
    :alt:

  :doc:`/auto_examples/02_pet_sinogram_projections/05_run_unlister`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Listmode to sinogram unlisting</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Emission tomography reconstruction algorithms (sinogram data)
-------------------------------------------------------------

A tour of reconstruction algorithms for the (regularised) Poisson problem,
all built on the data-fidelity and prior objects in ``parallelproj.functions``.
Start with the MLEM / OSEM / SVRG convergence comparison, then explore the
stochastic-gradient variants, PDHG / SPDHG with edge-preserving priors,
filtered back projection, De Pierro's MAP-EM, the effect of TOF on variance,
and out-of-core (memory-mapped) OSEM.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example compares the convergence speed (per epoch) of three algorithms for minimising the negative Poisson log-likelihood">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_00_run_mlem_osem_svrg_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/00_run_mlem_osem_svrg`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Convergence comparison: MLEM vs OSEM vs SVRG</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example compares the convergence speed (per epoch) of two algorithms for minimising the regularised negative Poisson log-likelihood">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_01_run_sgd_svrg_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/01_run_sgd_svrg`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Convergence comparison: SGD vs SVRG with logcosh regularization</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the primal-dual hybrid gradient (PDHG) algorithm and its stochastic variant (SPDHG) applied to the regularized PET reconstruction problem">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_02_run_pdhg_spdhg_dtv_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/02_run_pdhg_spdhg_dtv`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PDHG and SPDHG for PET reconstruction with a directional TV prior</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the run 2D filtered back projection (FBP) on pre-corrected Poisson emission data.">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_03_run_fbp_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/03_run_fbp`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">2D non-TOF filtered back projection (FBP) of Poisson data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the use of DePierro&#x27;s algorithm to minimize the negative Poisson log-likelihood function combined with a quadratic intensity prior:">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_04_run_depierro_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/04_run_depierro`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">DePierro's algorithm to optimize the Poisson logL with quadratic intensity prior</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Why TOF reduces image noise ----------------------------">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_05_run_tof_variance_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/05_run_tof_variance`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">TOF vs non-TOF: variance reduction in a uniform cylinder</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Demonstrates a memory-efficient OSEM variant in which full TOF sinograms are never held in RAM simultaneously.  Instead they are stored on disk in a subset-contiguous binary layout via numpy.memmap, and only one subset&#x27;s data is loaded at a time during each OSEM update.">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_06_run_osem_memmap_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/06_run_osem_memmap`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">RAM-efficient OSEM with disk-backed TOF sinograms</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip=".NegPoissonLogL offers two evaluation modes:">

.. only:: html

  .. image:: /auto_examples/03_algorithms/images/thumb/sphx_glr_07_run_mlem_negpoissonlogl_modes_thumb.png
    :alt:

  :doc:`/auto_examples/03_algorithms/07_run_mlem_negpoissonlogl_modes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Exact vs. "safe epsilon" mode of the negative Poisson log-likelihood</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Emission tomography reconstruction algorithms (listmode data)
-------------------------------------------------------------

The same families of algorithms as the sinogram gallery, but operating directly
on listmode (event-by-event) data through the listmode projector: listmode
MLEM / OSEM / SVRG, stochastic-gradient variants, and listmode SPDHG.  Listmode
is the natural choice for sparse, high-resolution (e.g. TOF) data.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to run MLEM, OSEM, and SVRG using listmode (event-by-event) data, and compares all algorithms with their sinogram equivalents via a convergence plot of the negative Poisson log-likelihood.">

.. only:: html

  .. image:: /auto_examples/04_listmode_algorithms/images/thumb/sphx_glr_00_run_listmode_mlem_osem_svrg_thumb.png
    :alt:

  :doc:`/auto_examples/04_listmode_algorithms/00_run_listmode_mlem_osem_svrg`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Listmode MLEM, OSEM, and SVRG</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example compares sinogram and listmode variants of SGD and SVRG for minimising the regularised negative Poisson log-likelihood">

.. only:: html

  .. image:: /auto_examples/04_listmode_algorithms/images/thumb/sphx_glr_01_run_listmode_sgd_svrg_thumb.png
    :alt:

  :doc:`/auto_examples/04_listmode_algorithms/01_run_listmode_sgd_svrg`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Convergence comparison: SGD vs SVRG with regularization (sinogram and listmode)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the use of the primal dual hybrid gradient (PDHG) algorithm, the listmode stochastic PDHG (LM-SPDHG) to minimize the negative Poisson log-likelihood function combined with a total variation regularizer:">

.. only:: html

  .. image:: /auto_examples/04_listmode_algorithms/images/thumb/sphx_glr_02_lm_spdhg_thumb.png
    :alt:

  :doc:`/auto_examples/04_listmode_algorithms/02_lm_spdhg`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PDHG and LM-SPDHG to optimize the Poisson logL and total variation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Transmission and joint activity/attenuation (MLAA) examples
-----------------------------------------------------------

Reconstruction of the attenuation image from transmission data using the exact
Poisson model (no log-linearisation) with a strictly positive scatter
background: MLTR and separable paraboloidal surrogates (SPS), their
ordered-subset and SVRG variants, and penalised transmission reconstruction
(MAPTR) with an edge-preserving prior.  The final example extends these ideas to
joint activity-and-attenuation estimation (MLAA) from a single TOF emission scan.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example reconstructs a linear attenuation image \mu from transmission data using the exact Poisson model (no log-linearisation into a weighted least squares problem) including a strictly positive, smooth scatter background s with known mean:">

.. only:: html

  .. image:: /auto_examples/05_transmission/images/thumb/sphx_glr_00_mltr_sps_thumb.png
    :alt:

  :doc:`/auto_examples/05_transmission/00_mltr_sps`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Transmission reconstruction: MLTR, SPS and L-BFGS-B</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example accelerates the transmission MLTR reconstruction of 00_mltr_sps.py with subset-based algorithms.  The model is the exact transmission Poisson likelihood with a strictly positive, smooth scatter background s of known mean,">

.. only:: html

  .. image:: /auto_examples/05_transmission/images/thumb/sphx_glr_01_os_mltr_svrg_thumb.png
    :alt:

  :doc:`/auto_examples/05_transmission/01_os_mltr_svrg`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Accelerating MLTR with ordered subsets (OS-MLTR) and SVRG</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example adds an edge-preserving smoothing prior to the ordered-subset transmission reconstruction of 01_os_mltr_svrg.py (MAPTR -- maximum a posteriori transmission reconstruction).  We now minimise the penalised objective">

.. only:: html

  .. image:: /auto_examples/05_transmission/images/thumb/sphx_glr_02_run_maptr_thumb.png
    :alt:

  :doc:`/auto_examples/05_transmission/02_run_maptr`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Penalised transmission reconstruction (MAPTR) with an edge-preserving prior</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Maximum Likelihood Activity and Attenuation (MLAA) jointly estimates the activity image \lambda and the attenuation image \mu from a single (TOF) emission scan, without a separate transmission/CT measurement.  The TOF emission model is">

.. only:: html

  .. image:: /auto_examples/05_transmission/images/thumb/sphx_glr_03_mlaa_thumb.png
    :alt:

  :doc:`/auto_examples/05_transmission/03_mlaa`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Joint activity and attenuation reconstruction (MLAA) for TOF PET</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Custom parallelproj pytorch layer examples
------------------------------------------

How to wrap a parallelproj operator as a differentiable PyTorch layer, with an
autograd-compatible forward and adjoint, so that projectors can be embedded in
deep-learning reconstruction pipelines (e.g. unrolled / model-based networks).


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we show how to define a custom pytorch layer that can be used to define a feed forward neural network that includes a parallelproj forward and back backward projections (or any .LinearOperator) that can be used with pytorch&#x27;s autograd engine.">

.. only:: html

  .. image:: /auto_examples/06_torch/images/thumb/sphx_glr_01_run_projection_layer_thumb.png
    :alt:

  :doc:`/auto_examples/06_torch/01_run_projection_layer`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">pytorch parallelproj projection layer</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/01_pet_geometry/index.rst
   /auto_examples/02_pet_sinogram_projections/index.rst
   /auto_examples/03_algorithms/index.rst
   /auto_examples/04_listmode_algorithms/index.rst
   /auto_examples/05_transmission/index.rst
   /auto_examples/06_torch/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: auto_examples_python.zip </auto_examples/auto_examples_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip </auto_examples/auto_examples_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_