Improve docs for linop.xray subpackage (#533)

* Add matplotlib-generated figure to api docs * Update submodule * Improve docs * Update submodule * Update submodule * Add missing typing import * Resolve ambiguity regarding detector orientation * Update submodule * Update submodule
lanl · Jun 17, 2024 · 81806fc · 81806fc
1 parent e7df8d2
commit 81806fc
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 4 deletions.
diff --git a/data b/data
diff --git a/docs/source/conf/20-extensions.py b/docs/source/conf/20-extensions.py
@@ -11,6 +11,7 @@
     "sphinx.ext.viewcode",
     "sphinxcontrib.bibtex",
     "sphinx.ext.inheritance_diagram",
+    "matplotlib.sphinxext.plot_directive",
     "sphinx.ext.todo",
     "nbsphinx",
 ]

diff --git a/scico/linop/xray/__init__.py b/scico/linop/xray/__init__.py
@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2023 by SCICO Developers
+# Copyright (C) 2023-2024 by SCICO Developers
 # All rights reserved. BSD 3-clause License.
 # This file is part of the SCICO package. Details of the copyright and
 # user license can be found in the 'LICENSE' file distributed with the
 # package.
 
-"""X-ray transform classes.
+r"""X-ray transform classes.
 
 The tomographic projections that are frequently referred to as Radon
 transforms are referred to as X-ray transforms in SCICO. While the Radon
@@ -14,6 +14,39 @@
 transform differ in higher numbers of dimensions, and it is the X-ray
 transform that is the appropriate mathematical model for beam attenuation
 based imaging in three or more dimensions.
+
+SCICO includes its own integrated 2D X-ray transform, and also provides
+interfaces to those implemented in the
+`ASTRA toolbox <https://github.com/astra-toolbox/astra-toolbox>`_
+and the `svmbir <https://github.com/cabouman/svmbir>`_ package. Each of
+these transforms uses a different convention for view angle directions,
+as illustrated in the figure below.
+
+.. plot:: figures/xray_2d_geom.py
+   :align: center
+   :include-source: False
+   :show-source-link: False
+   :caption: Comparison of 2D X-ray projector geometries. The red arrows
+      are are directed towards the detector, which is oriented with pixel
+      indices ordered in the same direction as clockwise rotation (e.g.
+      in the "scico" geometry, the :math:`\theta=0` projection
+      corresponds to row sums ordered from the top to the bottom of the
+      figure, while the :math:`\theta=\pi` projection
+      corresponds to row sums ordered from the bottom to the top of the
+      figure).
+
+|
+
+The conversion from the SCICO projection angle convention to those of the
+other two transforms is
+
+.. math::
+
+   \begin{aligned}
+   \theta_{\text{astra}} &= \theta_{\text{scico}} - \frac{\pi}{2} \\
+   \theta_{\text{svmbir}} &= 2 \pi - \theta_{\text{scico}} \;.
+   \end{aligned}
+
 """
 
 import sys

diff --git a/scico/numpy/util.py b/scico/numpy/util.py
@@ -11,7 +11,7 @@
 from __future__ import annotations
 
 from math import prod
-from typing import Any, List, Optional, Tuple, Union
+from typing import Any, List, Optional, Sequence, Tuple, Union
 
 import numpy as np