Changes to linop.xray.astra module (#551)

* Add typing, fix docstrings, change  convert_to_scico_geometry interface

* Improve docs

* Bug fix

* Fix function call in test

examples/scripts/ct_projector_comparison_3d.py

@@ -132,8 +132,8 @@
 Convert ASTRA geometry to SCICO and project.
 """
 
-P_from_astra = scico.linop.xray.astra.convert_to_scico_geometry(H_astra.vol_geom, H_astra.proj_geom)
-H_scico_from_astra = XRayTransform(XRayTransform3D(in_shape, P_from_astra, out_shape))
+P_from_astra = scico.linop.xray.astra._astra_to_scico_geometry(H_astra.vol_geom, H_astra.proj_geom)
+H_scico_from_astra = XRayTransform3D(in_shape, P_from_astra, out_shape)
 
 y_scico_from_astra = H_scico_from_astra @ x
 HTy_scico_from_astra = H_scico_from_astra.T @ y_scico_from_astra

scico/linop/xray/__init__.py

@@ -15,12 +15,16 @@
 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
+SCICO includes its own integrated 2D and 3D X-ray transforms, 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.
+and the `svmbir <https://github.com/cabouman/svmbir>`_ package.
+
+
+**2D Transforms**
+
+The SCICO, ASTRA, and svmbir transforms use different conventions for
+view angle directions, as illustrated in the figure below.
 
 .. plot:: pyfigures/xray_2d_geom.py
    :align: center
@@ -43,12 +47,33 @@
    \theta_{\text{svmbir}} &= 2 \pi - \theta_{\text{scico}} \;.
    \end{aligned}
 
+
+**3D Transforms**
+
+There are more significant differences in the interfaces for the 3D SCICO
+and ASTRA transforms. The SCICO 3D transform :class:`.xray.XRayTransform3D`
+defines the projection geometry in terms of a set of projection matrices,
+while the geometry for the ASTRA 3D transform
+:class:`.astra.XRayTransform3D` may either be specified in terms of a set
+of view angles, or via a more general set of vectors specifying projection
+direction and detector orientation. A number of support functions are
+provided for convering between these conventions.
+
+Note that the SCICO transform is implemented in JAX and can be run on
+both CPU and GPU devices, while the ASTRA transform is implemented in
+CUDA, and can only be run on GPU devices.
 """
 
+import sys
 
 from ._xray import XRayTransform2D, XRayTransform3D
 
 __all__ = [
     "XRayTransform2D",
     "XRayTransform3D",
 ]
+
+
+# Imported items in __all__ appear to originate in top-level xray module
+for name in __all__:
+    getattr(sys.modules[__name__], name).__module__ = __name__