WIP: Application doc

applications/README.md

@@ -2,28 +2,16 @@
 
 RTK provides command line applications which can be built from the C++ code by turning `ON` the `RTK_BUILD_APPLICATIONS` CMake option. A few of these applications have also been translated to Python and integrated in the [Pypi package](https://pypi.org/project/itk-rtk/). The options of each command line application can be listed with the `--help option`.
 
-The following are examples using RTK applications:
+The following groups collect the applications by purpose:
 
 ```{toctree}
 :maxdepth: 1
-
-./rtkfdk/README.md
-./rtkconjugategradient/README.md
-./rtkforwardprojections/README.md
-./rtkdrawgeometricphantom/README.md
-./rtkamsterdamshroud/README.md
-./rtkelektasynergygeometry/README.md
-./rtkvarianobigeometry/README.md
-./rtkadmmtotalvariation/README.md
-./rtkadmmwavelets/README.md
-./rtkfourdfdk/README.md
-./rtkfourdconjugategradient/README.md
-./rtkfourdsart/README.md
-./rtkfourdrooster/README.md
-./rtkshowgeometry/README.md
-./rtkosem/README.md
-./rtksart/README.md
-./rtksubselect/README.md
+../documentation/docs/applications/Geometry.md
+../documentation/docs/applications/Phantoms_and_Forward_Models.md
+../documentation/docs/applications/Projection_Processing.md
+../documentation/docs/applications/Reconstruction.md
+../documentation/docs/applications/Motion_and_Phase_Analysis.md
+../documentation/docs/applications/Utilities.md
 ```
 
 In [applications/rtktutorialapplication/](https://github.com/RTKConsortium/RTK/blob/main/applications/rtktutorialapplication), you will find a very basic RTK application that can be used as a starting point for building your own new application.

applications/rtkadmmtotalvariation/README.md

@@ -7,3 +7,15 @@ This script uses the SheppLogan phantom
 
 ```{literalinclude} TotalVariationRegularizedReconstruction.sh
 ```
+
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkadmmtotalvariation/rtkadmmtotalvariation.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkadmmwavelets/README.md

@@ -7,3 +7,15 @@ This script uses the SheppLogan phantom
 
 ```{literalinclude} DaubechiesWavelets.sh
 ```
+
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkadmmwavelets/rtkadmmwavelets.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkamsterdamshroud/README.md

@@ -26,3 +26,16 @@ rtkextractshroudsignal --input shroud.mha \
 Phase is commonly measured in radians, with values in $[0,2\pi[$, but in RTK it is normalized to $[0,1[$, where 0.3 corresponds to 30% in the respiratory cycle, i.e., frame 3 if you have a 10-frames 4D reconstruction or frame 6 if you have a 20-frames 4D reconstruction. The [resulting phase](https://data.kitware.com/api/v1/item/5be99af98d777f2179a2e160/download) is in green on top of the blue respiratory signal and the detected end-exhale peaks:
 
 ![Signal](../../documentation/docs/ExternalData/Signal.jpg){w=800px alt="Phase signal"}
+
+
+## Command line options
+
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkamsterdamshroud/rtkamsterdamshroud.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkamsterdamshroud/rtkamsterdamshroud.py

@@ -47,9 +47,7 @@ def process(args_info: argparse.Namespace):
     rtk.SetProjectionsReaderFromArgParse(reader, args_info)
 
     # Amsterdam Shroud
-    shroudFilter = rtk.AmsterdamShroudImageFilter[
-        OutputImageType, OutputImageType
-    ].New()
+    shroudFilter = rtk.AmsterdamShroudImageFilter[OutputImageType].New()
     shroudFilter.SetInput(reader.GetOutput())
     shroudFilter.SetUnsharpMaskSize(args_info.unsharp)
 

applications/rtkbackprojections/BackProjections.sh

@@ -0,0 +1,9 @@
+# Create a simulated geometry
+rtksimulatedgeometry -n 180 -o geometry.xml
+# You may add "--arc 200" to make the scan short or "--proj_iso_x 200" to offset the detector
+
+# Create projections of the phantom file
+rtkprojectshepploganphantom -g geometry.xml -o projections.mha --spacing 2 --size 200
+
+# Backproject the generated projections
+rtkbackprojections -p . -r projections.mha -g geometry.xml -o backproj.mha --bp Joseph --spacing 2 --size 128

applications/rtkbackprojections/README.md

@@ -0,0 +1,22 @@
+# Back projections
+
+![sin](../../documentation/docs/ExternalData/SheppLogan-Sinogram-3D.png){w=300px alt="SheppLogan sinogram 3D"}
+![img](../../documentation/docs/ExternalData/BackProjection.png){w=300px alt="Backprojection example"}
+
+Backprojects a volume according to a geometry file. See available projectors [here](../../documentation/docs/Projectors.md)
+
+```{literalinclude} BackProjections.sh
+```
+
+
+## Command line options
+
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkbackprojections/rtkbackprojections.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkbioscangeometry/README.md

@@ -0,0 +1,27 @@
+# Bioscan geometry
+
+Reader for Bioscan-format detector geometries. Generates an ITK-compatible geometry XML file from Bioscan header exports and associated projection image stacks.
+
+The command below uses this public RTK projection file: [bioscan.dcm](https://data.kitware.com/api/v1/item/5b179c728d777f15ebe201e2/download)
+
+The Bioscan geometry is stored in the DICOM projection headers, so `rtkbioscangeometry` reads the projection files directly.
+
+```bash
+rtkbioscangeometry \
+	--output bioscan_geometry.xml \
+	--path . \
+	--regexp 'bioscan.dcm' \
+	--verbose
+```
+
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+	:filename: applications/rtkbioscangeometry/rtkbioscangeometry.py
+	:func: build_parser
+	:nodescription:
+```
+::::

applications/rtkcheckimagequality/README.md

@@ -0,0 +1,29 @@
+# Quality Checker
+
+Checks the MSE of reconstructed volume(s) against reference volume(s).
+
+This utility compares one or more reconstructed images to reference image(s) and fails if the computed error exceeds the provided threshold(s).
+
+```bash
+# Single comparison
+rtkcheckimagequality -i reference.mha -j reconstruction.mha -t 1e-3
+
+# Multiple one-to-one comparisons (per-file thresholds)
+rtkcheckimagequality -i ref1.mha ref2.mha -j rec1.mha rec2.mha -t 1e-3 2e-3
+
+# Broadcast a single threshold to multiple comparisons
+rtkcheckimagequality -i ref1.mha ref2.mha -j rec1.mha rec2.mha -t 2e-3
+```
+
+
+## Command line options
+
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+	:filename: applications/rtkcheckimagequality/rtkcheckimagequality.py
+	:func: build_parser
+	:nodescription:
+```
+::::

applications/rtkconjugategradient/README.md

@@ -39,3 +39,16 @@ In the presence of noise, all projection data may not be equally reliable. The c
 ```
 ````
 `````
+
+
+## Command line options
+
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+	:filename: applications/rtkconjugategradient/rtkconjugategradient.py
+	:func: build_parser
+	:nodescription:
+```
+::::

applications/rtkdigisensgeometry/README.md

@@ -0,0 +1,23 @@
+# Digisens geometry
+
+Reader for DigiSens-format detector geometries. Generates an ITK-compatible geometry XML file from DigiSens calibration files
+
+The command below uses this public RTK file: [calibration.cal](https://data.kitware.com/api/v1/item/5b179c768d777f15ebe201e6/download)
+
+```bash
+rtkdigisensgeometry \
+  --xml_file calibration.cal \
+  -o geometry.xml
+```
+
+## Command line options
+
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkdigisensgeometry/rtkdigisensgeometry.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkdrawgeometricphantom/README.md

@@ -1,4 +1,4 @@
-# Create gammex phantom
+# Draw geometric phantom
 
 ![img](../../documentation/docs/ExternalData/GammexPhantom.png){w=400px alt="Gammex"}
 
@@ -8,3 +8,16 @@ This script uses the file [Gammex.txt](https://data.kitware.com/api/v1/file/6762
  # Create a 3D Gammex phantom
  rtkdrawgeometricphantom --phantomfile Gammex.txt -o gammex.mha
  ```
+
+
+## Command line options
+
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkdrawgeometricphantom/rtkdrawgeometricphantom.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkdrawshepploganphantom/README.md

@@ -0,0 +1,22 @@
+# Draw shepp-logan phantom
+
+Computes a 3D voxelized Shepp & Logan phantom with noise according to [https://www.slaney.org/pct/pct-errata.html]
+
+See rtkfdk example:
+
+```{literalinclude} ../rtkfdk/FDK3D.sh
+
+ ```
+
+
+## Command line options
+
+
+ ::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkdrawshepploganphantom/rtkdrawshepploganphantom.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkelektasynergygeometry/README.md

@@ -70,3 +70,15 @@ rtkfieldofview \
 You can visualize the result using a viewer (e.g., VV). The resulting image should look like the following:
 
 ![Elekta.jpg](../../documentation/docs/ExternalData/Elekta.png){w=400px alt="Elekta snapshot"}
+
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkelektasynergygeometry/rtkelektasynergygeometry.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkelektasynergygeometry/rtkelektasynergygeometry.py

@@ -34,9 +34,9 @@ def process(args_info: argparse.Namespace):
         reader.UpdateOutputData()
         geometry = reader.GetGeometry()
     elif (
-        args_info.image_db
-        and args_info.frame_db
-        and args_info.dicom_uid
+        args_info.image_db is None
+        and args_info.frame_db is None
+        and args_info.dicom_uid is None
         and args_info.xml is not None
     ):
         if args_info.verbose:

applications/rtkextractphasesignal/README.md

@@ -0,0 +1,27 @@
+# Extract Phase Signal
+
+This small utility reads a 1‑D signal image (e.g. a shroud-derived signal), applies optional preprocessing (moving average and unsharp masking), extracts the phase according to a chosen model, and writes the resulting phase as a plain-text file.
+
+
+```bash
+# Basic extraction (default model: LINEAR_BETWEEN_MINIMA)
+rtkextractphasesignal -i signal.mha -o phase.txt
+
+# Tune preprocessing parameters
+rtkextractphasesignal -i signal.mha -o phase.txt --movavg 3 --unsharp 53
+
+# Use LOCAL_PHASE model
+rtkextractphasesignal -i signal.mha -o phase.txt --model LOCAL_PHASE
+```
+
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkextractphasesignal/rtkextractphasesignal.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkextractshroudsignal/README.md

@@ -0,0 +1,18 @@
+# Extract shroud signal
+
+Extracts the breathing signal from a shroud image.
+
+This application reads a shroud image and extracts a respiratory signal using either a regularised 1D method (`Reg1D`) or dynamic programming (`DynamicProgramming`). It can also write an estimated Hilbert phase image.
+
+```bash
+# Basic extraction (default method: Reg1D)
+rtkextractshroudsignal -i shroud.mha -o breathing.txt
+
+# Use Dynamic Programming method (requires a maximum amplitude)
+rtkextractshroudsignal -i shroud.mha -o breathing.txt -m DynamicProgramming -a 30
+
+# Also write Hilbert phase text file and tune preprocessing
+rtkextractshroudsignal -i shroud.mha -o breathing.txt -p phase.txt --movavg 5 --unsharp 65 --model LOCAL_PHASE
+```
+
+See the [rtkamsterdamshroud documentation](../rtkamsterdamshroud/README.md) for a shroud-extraction workflow

applications/rtkfdk/README.md

@@ -162,7 +162,6 @@ Post-process with Matlab to obtain the phase signal, ensuring the phase ranges f
 
 ![Signal](../../documentation/docs/ExternalData/Signal.jpg){w=800px alt="Phase signal"}
 
----
 
 ### Motion-compensated cone-beam CT reconstruction
 
@@ -198,3 +197,14 @@ Toggle between uncorrected and motion-compensated reconstruction to appreciate t
 The 4D vector field is constructed with phase 50% as a reference. Modify the reference image to reconstruct other phases, such as the time-average position.
 ````
 `````
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkfdk/rtkfdk.py
+  :func: build_parser
+  :nodescription:
+```
+::::

applications/rtkfieldofview/README.md

@@ -0,0 +1,24 @@
+# Field of view
+
+Computes the field of view of a reconstruction using the acquisition geometry and the projections stack.
+
+By default this uses RTK's fast `FieldOfViewImageFilter` (suitable for standard circular/cylindrical scans). For non‑cylindrical or irregular acquisition geometries you can force a more robust (but slower) backprojection-based method with `--bp`, the program backprojects a stack of projections filled with ones and thresholds the result to derive the FOV footprint.
+
+```bash
+# Basic FOV mask (fast, preferred)
+rtkfieldofview -g geometry.xml -p /projections -r '.*.mha' --reconstruction recon.mha -o fov_mask.mha --mask
+
+# Backprojection-based FOV (non-cylindrical geometry)
+rtkfieldofview -g geometry.xml -p /projections -r '.*.mha' --reconstruction recon.mha -o fov_bp.mha --bp --mask --hardware cuda
+```
+
+## Command line options
+
+::::{container} argparse-no-usage
+```{eval-rst}
+.. argparse::
+  :filename: applications/rtkfieldofview/rtkfieldofview.py
+  :func: build_parser
+  :nodescription:
+```
+::::