aprict 0.0.24.dev1__tar.gz → 0.0.27__tar.gz

{aprict-0.0.24.dev1/src/aprict.egg-info → aprict-0.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aprict
-Version: 0.0.24.dev1
+Version: 0.0.27
 Summary: Tools to simulate and reconstruct XCT transmission data.
 Author: Murdock Grewar
 Author-email: Murdock Grewar <murdock.grewar@anu.edu.au>

{aprict-0.0.24.dev1 → aprict-0.0.27}/pyproject.toml

@@ -49,6 +49,7 @@ dev = [
     "bandit>=1.9.4",
     "build>=1.6.1",
     "ipython>=9.11.0",
+    "pdoc>=16.0.0",
     "pre-commit>=4.5.1",
     "pytest>=9.0.2",
     "pytest-dependency>=0.6.1",

{aprict-0.0.24.dev1 → aprict-0.0.27}/setup.py

@@ -55,6 +55,9 @@ setup(
     # package_data={my_module_name: ["data/"]},
     entry_points={
         "console_scripts": [
+            my_module_name + " = " + my_module_name + ".scripts.cli:main",
+        ]
+        + [
             my_module_name
             + "-"
             + f"{_filename_to_command_name(script_name):s}"

aprict-0.0.27/src/aprict/__init__.py

@@ -0,0 +1,92 @@
+# Copyright (C) 2026  Murdock Grewar
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+[![Static Badge](https://img.shields.io/badge/ORCiD-0000--0002--0015--8284-green?logo=orcid)](https://orcid.org/0000-0002-0015-8284)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23632625.svg)](https://doi.org/10.5281/zenodo.23632625)
+![PyPI Version](https://img.shields.io/pypi/v/aprict)
+[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+
+`aprict` is a Python module and commandline program for simulating flat-panel transmission X-ray experiments.
+
+Recommended import pattern
+--
+
+The recommended import pattern for this module is
+```python
+import aprict
+from aprict.cb import flatpanel as cbfp
+```
+
+Main components
+--
+
+The main components of the end-user Python API are:
+ - [`aprict.FBVolume`](aprict/volume.html#FBVolume) - an attenuating volume defined in FORBILD format
+ - [`aprict.Volume`](aprict/volume.html#Volume) - an attenuating volume defined in voxelised format
+ - `aprict.cb.flatpanel` - a namespace for objects and functions applying to cone-beam imaging geometries
+
+Examples
+--
+
+For examples of Python API usage, see `aprict.examples`.
+
+Commandline interface
+--
+
+The entry point for the main commandline interface is the shell command `aprict`. This shell command should be available on `$PATH` if the module is installed in the current environment. All shell commands are self-documented:
+```bash
+$ aprict --help
+```
+"""  # ruff: ignore[ambiguous-unicode-character-docstring, blank-lines-between-header-and-content, mismatched-section-underline-length, missing-blank-line-after-summary, missing-trailing-period]
+
+# If we are just running the build script, then I don't want to initialise anything,
+# because the imports fail because it hasn't built yet.
+
+import os as _os
+
+if _os.environ.get("APRICT_BUILDMODE", ""):  # ruff: ignore[non-empty-init-module]
+    pass
+else:
+    # Ensure that numexpr max threads is set to the number of logical cores before importing numexpr either directly or indirectly through other imports.
+    _nethreads_max_env = _os.environ.get("NUMEXPR_MAX_THREADS", None)
+    if _nethreads_max_env is None:
+        _os.environ["NUMEXPR_MAX_THREADS"] = str(_os.process_cpu_count())
+
+    del _os
+    from . import cb as cb
+    from . import image_view as imview
+    from . import iterators, lib, phantoms, volume
+    from .cuda import structs as dtypes
+    from .volume import FBVolume as FBVolume
+
+    FBVolume.__doc__ = "@private\nAn alias to aprict.volume.FBVolume"  # Hide from pdoc documentation of this module
+    from .volume import Volume as Volume
+
+    Volume.__doc__ = "@private\nAn alias to aprict.volume.Volume"  # Hide from pdoc documentation of this module
+
+    # Note that __all__ determines what's listed in the documentation page.
+    # So, I'm selecting only those parts which I want to be documented on the main doc page here.
+    __all__ = [
+        "FBVolume",  # documented in aprict.volume
+        "Volume",  # documented in aprict.volume
+        "cb",
+        "dtypes",
+        "imview",
+        "iterators",
+        "lib",
+        "phantoms",
+        "volume",
+    ]

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/cb/flatpanel.py

@@ -15,7 +15,21 @@
 
 # flatpanel.py
 
-"""End-user interfaces to the flat-panel cone-beam projection and backprojection CUDA code."""
+"""
+End-user interfaces to the flat-panel cone-beam projection and backprojection CUDA code.
+
+The main provided methods are
+ - `project` - used to generate projection data from a `aprict.volume.Volume` or `aprict.volume.FBVolume` object.
+ - `backproject` - used to generate backprojection data from a `aprict.volume.Volume` or `aprict.volume.FBVolume` object.
+
+The main provided classes are
+ - `ProjGeom` - object to encode a flat-panel (back)projection geometry.
+ - `ProjectionSet` - object to hold a `ProjGeom` and associated projection data.
+ - `ConfigProject` - object to hold a collection of settings applied when computing projections with `project`.
+ - `ConfigBackproject` - object to hold a collection of settings applied when computing backprojections with `backproject`.
+
+Note that the `ConfigBackproject` object allows for configuring weighted backprojections and the like. The `backproj_weighting_preset` attribute passed to its constructor can significantly influence the behaviour of the backprojection, since this value is passed to the CUDA kernel, which performs some internal logic depending on this value. Currently, the end user has limited control over what kind of weightings are applied, since adding new presets requires editing the CUDA kernel. The available presets will be documented at a later time. The default value of `0` corresponds to the adjoint of the forward projection.
+"""
 
 import dataclasses
 import functools
@@ -42,7 +56,7 @@ _delay_compile: bool = (
 
 
 def force_compile(*, log_stream: object | None = None) -> None:
-    """Force the relevant CUDA kernels to compile."""
+    """Force the relevant CUDA kernels to compile, if they have not already."""
     _projection_module.compile(log_stream=log_stream)
     _backprojection_module.compile(log_stream=log_stream)
 
@@ -250,7 +264,7 @@ class ProjGeom:  # ruff: ignore[eq-without-hash]
         tuple[float, float, float],
         tuple[float, float, float],
     ]:
-        """Return a bounding box."""
+        """Return a bounding box like ((minx,miny,minz),(maxx,maxy,maxz))."""
         # Make a list of points such that the whole projection geometry
         # is contained in the convex hull. Then take the min x,y,z and max x,y,z
         # it = slice(None, None) if index_tuple is None else index_tuple
@@ -713,7 +727,7 @@ class ProjectionSet:
         tuple[float, float, float],
         tuple[float, float, float],
     ]:
-        """Return a bounding box."""
+        """Return a bounding box like ((minx,miny,minz),(maxx,maxy,maxz))."""
         return self._proj_geom.get_bbox(index_tuple=index_tuple)
 
     @property
@@ -809,19 +823,19 @@ class ProjectionSet:
 
 
 class ConfigProject:
-    """Configuration object for projections. Some options will have no effect if a Volume or FBVolume."""
+    """Configuration object for projections. This is to be passed to the `project` method. Some options will have no effect if applied improperly to a `Volume`/`FBVolume`."""
 
     _contents: np.dtype[structs.config_cb_project]  # ty:ignore[invalid-type-arguments]
     _contents_fb: np.dtype[structs.config_cb_project_FORBILD]  # ty:ignore[invalid-type-arguments]
 
     @property
     def contents(self) -> np.dtype[structs.config_cb_project]:  # ty:ignore[invalid-type-arguments]
-        """The configuration object underlying this object."""
+        """The configuration object underlying this object, when applied to `Volume`."""
         return self._contents.copy()  # ty:ignore[unresolved-attribute]
 
     @property
     def contents_fb(self) -> np.dtype[structs.config_cb_project_FORBILD]:  # ty:ignore[invalid-type-arguments]
-        """The configuration object underlying this object."""
+        """The configuration object underlying this object, when applied to `FBVolume`."""
         return self._contents_fb.copy()  # ty:ignore[unresolved-attribute]
 
     def __init__(

aprict-0.0.27/src/aprict/examples/__init__.py

@@ -0,0 +1,41 @@
+# Copyright (C) 2026  Murdock Grewar
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+A submodule containing example scripts using the Python API.
+
+Browse the `aprict` source code and navigate to this directory to see the examples.
+
+Examples can be run with e.g. `python -m aprict.examples.EXAMPLE_NAME`.
+
+"""
+
+from . import (
+    composite_human_sirt,
+    fan_beam_sirt,
+    helical_sirt,
+    lungs_sirt,
+    trajtest_A_sirt,
+    triangle_exp_fb,
+)
+
+__all__ = [
+    "composite_human_sirt",
+    "fan_beam_sirt",
+    "helical_sirt",
+    "lungs_sirt",
+    "trajtest_A_sirt",
+    "triangle_exp_fb",
+]

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/examples/composite_human_sirt.py

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Simulate an example experiment with a helical scan."""
+"""Simulate an example experiment and SIRT reconstruction using the composite human phantom."""
 
 import itertools
 import math
@@ -174,7 +174,7 @@ def main() -> None:  # ruff: ignore[complex-structure, undocumented-public-funct
     print("Voxel width (mm):        ", voxwid_mm)
     print()
     print("Creating volume... ", end="", flush=True)
-    vol: aprict.FBVolume = aprict.phantoms.FORBILD.CustomComposite
+    vol: aprict.FBVolume = aprict.phantoms.FORBILD.CustomComposite()
     if plot_volume:
         print("plotting volume... ", end="", flush=True)
         xs = np.linspace(-300, 300, num=601, endpoint=True)

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/examples/fan_beam_sirt.py

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Simulate an example experiment with a helical scan."""
+"""Simulate an example 2D fan-beam experiment and SIRT reconstruction."""
 
 import math
 import sys
@@ -99,7 +99,7 @@ def main() -> None:  # ruff: ignore[undocumented-public-function]
 
     # Create the volume to be projected
     print("Voxel width (mm):        ", voxwid_mm)
-    vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom
+    vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom()
     xyz_min, xyz_max = vol.minxyz_maxxyz
     volwid_mm = 1.1 * 2 * max(map(abs, (*xyz_min[:2], *xyz_max[:2])))
 

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/examples/helical_sirt.py

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Simulate an example experiment with a helical scan."""
+"""Simulate an example experiment and SIRT reconstruction with a helical scan."""
 
 import math
 import sys
@@ -106,7 +106,7 @@ def main() -> None:  # ruff: ignore[undocumented-public-function]
 
     # Create the volume to be projected
     print("Voxel width (mm):        ", voxwid_mm)
-    vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom
+    vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom()
     volwid_mm = 250  # in the future, fetch from the phantom
     # Scale up the volume
     vol.scale_len(scale_phantom_size)

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/examples/trajtest_A_sirt.py

@@ -1,3 +1,4 @@
+# ruff: ignore[invalid-module-name]
 # Copyright (C) 2026  Murdock Grewar
 #
 # This program is free software: you can redistribute it and/or modify
@@ -12,8 +13,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-"""Simulate an example experiment with a helical scan."""
+"""Simulate an example experiment and SIRT reconstruction with a cylindrical scan."""
 
 import math
 import sys
@@ -106,7 +106,7 @@ def main() -> None:  # ruff: ignore[undocumented-public-function]
 
     # Create the volume to be projected
     print("Voxel width (mm):        ", voxwid_mm)
-    vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom
+    vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom()
     volwid_mm = 275  # in the future, fetch from the phantom
     # Scale up the volume
     vol.scale_len(scale_phantom_size)
@@ -246,8 +246,8 @@ def main() -> None:  # ruff: ignore[undocumented-public-function]
         _lp_process, lp_dispatcher = liveplot.start_live_plot_2d(
             title="Live plot",
             histogram_label="Attenuation coefficient",
-            plotmin=0.0184 * voxwid_mm * (1 + default_plot_range_HU[0] / 1000),
-            plotmax=0.0184 * voxwid_mm * (1 + default_plot_range_HU[1] / 1000),
+            plotmin=0.0184 * (1 + default_plot_range_HU[0] / 1000),
+            plotmax=0.0184 * (1 + default_plot_range_HU[1] / 1000),
             show=False,
         )
 

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/examples/triangle_exp_fb.py

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Simulate an example experiment with a triangular scanning apparatus."""
+"""Simulate an example experiment and Landweber reconstruction with a triangular scanning apparatus."""
 
 import itertools
 import math
@@ -243,8 +243,8 @@ def main() -> None:  # ruff: ignore[undocumented-public-function]
 
     # Create the volume to be projected
     print("Voxel width (mm):        ", voxwid_mm)
-    # vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom
-    vol: aprict.FBVolume = aprict.phantoms.FORBILD.CustomComposite
+    # vol: aprict.FBVolume = aprict.phantoms.FORBILD.HeadPhantom()
+    vol: aprict.FBVolume = aprict.phantoms.FORBILD.CustomComposite()
     volwid_mm = 300  # in the future, fetch from the phantom
     # Scale up the volume
     vol.scale_len(scale_phantom_size)

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/phantoms/FORBILD_phantoms.py

@@ -14,9 +14,10 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Provides FORBILD phantoms from the files published by the Arbeitsgruppe Phantome."""
+"""Provides FORBILD phantoms from the files published by the Arbeitsgruppe Phantome, as well as others."""
 
 import dataclasses
+import functools
 import itertools
 import math
 import pathlib
@@ -30,19 +31,23 @@ from ..cuda.structs import FORBILD_volumes as fv
 from ..lib import process_pha_file as ppf
 from ..volume import FBVolume
 
-path_to_FORBILD_src = pathlib.Path(str(data.__path__[0])).joinpath("FORBILD")  # ruff: ignore[mixed-case-variable-in-global-scope]
+_path_to_FORBILD_src = pathlib.Path(str(data.__path__[0])).joinpath("FORBILD")  # ruff: ignore[mixed-case-variable-in-global-scope]
 
 
-# ruff: disable[invalid-function-name,missing-trailing-period]
+# ruff: disable[non-imperative-mood,invalid-function-name]
 
 
-class _MetaPhantomContainer(type):
-    @property
+class PhantomContainer:
+    """A container for the phantom objects."""
+
+    @classmethod
+    @functools.cache
     def CustomComposite(cls) -> FBVolume:
+        """A custom phantom stitching together and slightly modifying the Hip, Abdomen, Thorax, Head and Jaw phantom."""
         hi, ab, th, he, ja = [
             FBVolume(
                 ppf.convert_ph_file_to_shapes(
-                    path_to_FORBILD_src.joinpath("custom_composite/" + fn)
+                    _path_to_FORBILD_src.joinpath("custom_composite/" + fn)
                 )
             )
             for fn in (
@@ -105,12 +110,13 @@ class _MetaPhantomContainer(type):
         v = v.superimpose_onto(cavity)
         return v  # ruff: ignore[unnecessary-assign]
 
-    @property
+    @classmethod
+    @functools.cache
     def JawPhantom(cls) -> FBVolume:
-        """The JawPhantom.txt"""
+        """The [Jaw phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/jaw-phantom)."""
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath("jaw/JawPhantom.pha")
+                _path_to_FORBILD_src.joinpath("jaw/JawPhantom.pha")
             )
         )
         # Phantom is defined with centimeters as the unit of length.
@@ -118,12 +124,13 @@ class _MetaPhantomContainer(type):
         fbv.scale_len(10)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def HeadPhantom(cls) -> FBVolume:
-        """HeadPhantom.pha"""
+        """The [Head phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/head-phantom)."""
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath("head/HeadPhantom.pha")
+                _path_to_FORBILD_src.joinpath("head/HeadPhantom.pha")
             )
         )
         # Phantom is defined with centimeters as the unit of length.
@@ -131,12 +138,13 @@ class _MetaPhantomContainer(type):
         fbv.scale_len(10)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def HipPhantom(cls) -> FBVolume:
-        """HipPhantom.pha"""
+        """The [Hip phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/hip-phantom)."""
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath("hip/HipPhantom.pha")
+                _path_to_FORBILD_src.joinpath("hip/HipPhantom.pha")
             )
         )
         # Phantom is defined with centimeters as the unit of length.
@@ -144,13 +152,14 @@ class _MetaPhantomContainer(type):
         fbv.scale_len(10)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def AbdomenPhantom(cls) -> FBVolume:
-        """Fixed AbdomenPhantom.txt"""
+        """Fixed [Abdomen phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/abdominal-phantom)."""
         # The AbdomenPhantom.pha file has a bug in it. Load a manually fixed version.
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath(
+                _path_to_FORBILD_src.joinpath(
                     "abdomen/AbdomenPhantom_fixed.pha"
                 )
             )
@@ -160,13 +169,14 @@ class _MetaPhantomContainer(type):
         fbv.scale_len(10)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def LungPhantom3Generations(cls) -> FBVolume:
-        """LungPhantom3Generations.pha"""
+        """The [Lung phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/lung-phantom) to 3 generations."""
         # DEV NOTE: make sure this phantom loads the reference file published by the Arbeitsgruppe Phantome. This is used in a unittest to ensure that the generation procedure for N generations matches in this case.
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath(
+                _path_to_FORBILD_src.joinpath(
                     "lungs/LungPhantom3Generations.pha"
                 )
             )
@@ -175,12 +185,13 @@ class _MetaPhantomContainer(type):
         fbv.flip(axis="z")
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def ThoraxPhantom(cls) -> FBVolume:
-        """ThoraxPhantom.pha"""
+        """The [Thorax phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/thorax-phantom)."""
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath("thorax/ThoraxPhantom.pha")
+                _path_to_FORBILD_src.joinpath("thorax/ThoraxPhantom.pha")
             )
         )
         # Phantom is defined with centimeters as the unit of length.
@@ -188,11 +199,13 @@ class _MetaPhantomContainer(type):
         fbv.scale_len(10)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def RockCanisterAl(cls) -> FBVolume:
+        """A phantom resembling a 6-millimeter-wide double-chambered tube of rocks."""
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath(
+                _path_to_FORBILD_src.joinpath(
                     "custom_other/rock_canister_01.pha"
                 ),
                 skip_preprocessing=True,  # I know that this file doesn't require preprocessing
@@ -202,26 +215,30 @@ class _MetaPhantomContainer(type):
         fbv.multiply_attenuation(0.55)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def RockCanisterCavities1e5(cls) -> FBVolume:
+        """An appendage to the RockCanisterAl phantom which adds small cavities to the aluminium canister."""
         return FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath(
+                _path_to_FORBILD_src.joinpath(
                     "custom_other/rock_canister_01_cavities_1e5.pha"
                 ),
                 skip_preprocessing=True,  # I know that this file doesn't require preprocessing
             )
         )
 
-    @property
+    @classmethod
+    @functools.cache
     def RockCanisterAlWithHoles(cls) -> FBVolume:
+        """A phantom resembling a 6-millimeter-wide double-chambered tube of rocks, with small cavities inthe aluminium cylinder."""
         fbv = FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath(
+                _path_to_FORBILD_src.joinpath(
                     "custom_other/rock_canister_01.pha"
                 ),
                 append_files=(
-                    path_to_FORBILD_src.joinpath(
+                    _path_to_FORBILD_src.joinpath(
                         "custom_other/rock_canister_01_cavities_1e5.pha"
                     ),
                 ),
@@ -232,18 +249,16 @@ class _MetaPhantomContainer(type):
         fbv.multiply_attenuation(0.55)
         return fbv
 
-    @property
+    @classmethod
+    @functools.cache
     def UnitCyl_z(cls) -> FBVolume:
+        """Unit z cylinder."""
         return FBVolume(
             ppf.convert_ph_file_to_shapes(
-                path_to_FORBILD_src.joinpath("custom_other/unit_Cyl_z.pha")
+                _path_to_FORBILD_src.joinpath("custom_other/unit_Cyl_z.pha")
             )
         )
 
-
-class PhantomContainer(metaclass=_MetaPhantomContainer):
-    """A container for the phantom objects."""
-
     @classmethod
     def _LungPhantom_phastring(  # ruff: ignore[complex-structure]
         cls,
@@ -254,7 +269,7 @@ class PhantomContainer(metaclass=_MetaPhantomContainer):
         fix: bool
         | None = None,  # Leave at None for default configuration. Turning this True will fix what appear to be errors in the original phantom. These errors are particularly noticeable with e.g. taper=True.
     ) -> str:
-        """Generate the Lung phantom (by Marc Kachelrieß) up to generation n."""
+        """Generate the [Lung phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/lung-phantom) (by Markus Blank and Marc Kachelrieß) up to generation n."""
         if type(generation) is not int or generation < 2:
             msg = "'generation' must be an integer >=2"
             raise ValueError(msg)
@@ -534,7 +549,7 @@ class PhantomContainer(metaclass=_MetaPhantomContainer):
         fix: bool
         | None = None,  # Leave at None for default configuration. Turning this True will fix what appear to be errors in the original phantom. These errors are particularly noticeable with e.g. taper=True.
     ) -> FBVolume:
-        """Generate the Lung phantom (by Marc Kachelrieß) up to generation n."""
+        """Generate the [Lung phantom](https://www.dkfz.de/en/x-ray-imaging-and-computed-tomography/lung-phantom) (by Markus Blank and Marc Kachelrieß) up to generation n."""
         phastr: str = cls._LungPhantom_phastring(
             generation=generation,
             scale_factor=scale_factor,
@@ -657,7 +672,7 @@ class PhantomContainer(metaclass=_MetaPhantomContainer):
         randomise_parity: bool = False,
         seed: int | None = None,
     ) -> FBVolume:
-        """Generate a disc-shaped resolution phantom."""
+        """Generate a disc-shaped resolution phantom (use as a 2D phantom with z=0)."""
         if generation < 1:
             msg = "Generation should be a positive integer."
             raise ValueError(msg)
@@ -996,4 +1011,4 @@ class PhantomContainer(metaclass=_MetaPhantomContainer):
         return FBVolume(np.array(shapes, dtype=fv.Shape))
 
 
-# ruff: enable[invalid-function-name,missing-trailing-period]
+# ruff: enable[non-imperative-mood,invalid-function-name]

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/phantoms/__init__.py

@@ -13,7 +13,11 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Phantom objects useful for simulations and testing."""
+"""
+Phantom objects useful for simulations and testing.
+
+These can be loaded with e.g. `aprict.phantoms.FORBILD.HeadPhantom()`.
+"""
 
 from .FORBILD_phantoms import (
     PhantomContainer as FORBILD,  # ruff: ignore[camelcase-imported-as-constant]

aprict-0.0.27/src/aprict/scripts/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (C) 2026  Murdock Grewar
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Scripts to use `aprict` with a commandline interface.
+
+The recommended entry point is `aprict.scripts.cli`, which is a wrapper for the other scirpts. When `aprict` is installed in the current environment, this can be called from the shell with `aprict-cli`.
+"""

{aprict-0.0.24.dev1 → aprict-0.0.27}/src/aprict/scripts/cli.py

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""aprict-cli: the main command-line interface to aprict."""
+"""The main command-line interface to aprict."""
 
 import click_extra as ce
 
@@ -36,7 +36,7 @@ _cs = {
 }
 
 
-@ce.group(name="aprict-cli", params=None, help=_progdesc, context_settings=_cs)
+@ce.group(name="aprict", params=None, help=_progdesc, context_settings=_cs)
 @ce.version_option(version=version)  # add --version from click_extra
 @ce.tree_option()  # add --tree option from click_extra
 # not including the man_option because it includes incorrect information, like possible exit codes etc.