Find center by metric method

docs/source/reference/api.rst

@@ -4,7 +4,7 @@
 API reference
 ==========================
 
-This section contains the API reference and usage information for HttomolibGPU.
+This section contains the API reference and usage information for HTTomolibGPU.
 
 HTTomolibGPU Modules
 ---------------------

docs/source/reference/methods.rst

@@ -11,6 +11,7 @@ Here we present a list of methods of the HTTomolibGPU library with more detailed
    methods_list/correction_methods
    methods_list/stripe_removal_methods
    methods_list/phase_contrast_methods
+   methods_list/cor_finder_methods
    methods_list/reconstruction_methods
    methods_list/denoising_methods
    methods_list/rescale_methods

docs/source/reference/methods_list/cor_finder/find_center_metric_recon.rst

@@ -0,0 +1,77 @@
+.. _find_center_metric_recon_doc:
+
+Find center by metric
+^^^^^^^^^^^^^^^^^^^^^
+
+**Description**
+
+The optimal centre of rotation is found by minimising a metric of the reconstructed image:
+
+.. math::
+
+     c^{*} = \arg\min_{c\in\mathcal{C}} M(c),
+
+where :math:`\mathcal{C}` is the set of candidate centres and :math:`M` is an image-quality metric.
+
+The choice of metric is important because different metrics respond differently to noise, background, contrast, and reconstruction artefacts. It is therefore useful to compare several metrics rather than relying on a single measure.
+
+
+**Where and how to use it:**
+
+Use it when the centre of rotation is unknown and needs to be found automatically.
+
+This method can be applied to any data, however the main benefit of this method
+is when the data is incomplete, i.e., limited angle/missing wedge data.
+
+.. note:: For parallel-beam tomography, projections separated by approximately 180 degrees contain complementary information. With a correctly determined COR, the projections should exhibit the expected geometrical relationship. Other methods, such as, :mod:`httomolibgpu.recon.rotation.find_center_vo` and :mod:`httomolibgpu.recon.rotation.find_center_pc`, rely on that assumption. So it is advisable to use other methods first, if the data is complete.
+
+**What are the adjustable parameters:**
+
+There are quite a lot of parameters that can be adjusted to improve the performance of this method.
+The most important ones are:
+
+* :code:`metric_type` the choice of metrics to be computed on the reconstructed image. Choose from:
+
+     * :code:`'entropy'` - Shannon entropy measures the information content or complexity of an image intensity distribution. For a discrete intensity distribution with probabilities :math:`p_i`, the entropy is :math:`H = -\sum_i p_i \log_2(p_i)`. A higher entropy indicates a broader or more complex intensity distribution. For an image, the intensity distribution can be estimated using a histogram This metric is sensitive to noise and background, but less sensitive to contrast and reconstruction artefacts. Normally a second best choice after :code:`'tv'` metric.
+
+     * :code:`'tv'` - the total variation (the sum of the magnitude of the image gradient) of the reconstructed image. :math:`|\nabla I| = \sqrt{\left(\frac{\partial I}{\partial x}\right)^2 + \left(\frac{\partial I}{\partial y}\right)^2}`. The :code:`'tv'` metric is the sum of gradient's magnitude: :math:`M_\mathrm{grad} = \sum{(|\nabla I|)}`. Default choice and of the most robust metrics.
+
+     * :code:`'sharpness'` - the variance of of the Laplacian. The metric is defined as :math:`M_\mathrm{Lap} = \operatorname{Var}(\nabla^2 I)`, where :math:`I` is the reconstructed image. Very sensitive to high-frequency noise.
+
+
+.. note:: We found that smoothing the image before computing any of the metrics with :code:`'gaussian_filter_sigma'` can improve the performance of the correct CoR estimation significantly. Usually the range between 1 and 3 is a good choice for the :code:`'gaussian_filter_sigma'` parameter (see images below).
+
+* :code:`reconstruction_method` is set to :code:`'LPRec3d_tomobar'` by default, however the iterative methods such as :code:`'SIRT3d_tomobar'`, :code:`'CGLS3d_tomobar'` are also available. In some cases (especially limited angle data) the iterative methods can provide better results than the default direct methods. Set :code:`'gaussian_filter_sigma' = None'` if iterative methods are enabled.
+
+* :code:`cor_initialisation_value` is the initial guess of the centre of rotation. The search for the optimal CoR will be performed in the range :code:`[cor_initialisation_value - cor_search_range, cor_initialisation_value + cor_search_range]`. The default value is set to :code:`None`, which means that the initialisation value will be set to the middle of the detector.
+
+* :code:`squared_mask_x_y_size` is a very important parameter as it defines the squared mask that is applied to the reconstructed image BEFORE computing the metric. The mask can be placed in any position on the reconstructed image. Very frequently, the optimal location of the mask leads to optimal performance of the estimation. However, placing the mask on the ring/streak artifacts or at the edge of the reconstruction leads to incorrect results.
+
+  The mask is defined as a :code:`list` with 3 values :code:`[X, Y, size]`. The positive offsets :code:`X, Y` place the mask with respect to the left top corner of the reconstructed image and the third parameter is the size of the cropped image in percents with respect to the whole reconstructed image.
+
+  Example: :code:`squared_mask_x_y_size = [10, 20, 50]` will apply a mask that is 10 pixels away from the left top corner in the horizontal direction and 20 pixels away in the vertical direction, the mask will be 50% in size of the reconstructed image size.
+
+  The default value when  :code:`squared_mask_x_y_size = None` is the mask in the center of the reconstructed image (not always the best position as many ring artifacts are present) with a size of 50% of the reconstructed image size.
+
+* :code:`save_recon_tiff` - this feature is useful for debugging. When set to a valid path, the reconstructed image together with the mask after smoothing are saved in to a specified folder. This allows for visual inspection of the reconstruction and mask placement.
+
+**Practical example:**
+
+In this example we demonstrate how the choice of smoothing can affect the performance of the CoR estimation.
+
+.. list-table::
+
+
+    * - .. figure:: ../../../_static/figures/center_find/find_center_entropy_1263_no_smoothing.jpg
+
+           :code:`metric_type = entropy`, :code:`squared_mask_x_y_size = None` (center), :code:`gaussian_filter_sigma = None`. Incorrect CoR found as the masked image is not smoothed.
+
+      - .. figure:: ../../../_static/figures/center_find/find_center_entropy_1253_smoothing3.jpg
+
+           :code:`metric_type = entropy`, :code:`squared_mask_x_y_size = None` (center), :code:`gaussian_filter_sigma = 3`. Correct CoR found as the masked image is smoothed.
+
+
+
+
+
+

docs/source/reference/methods_list/cor_finder_methods.rst

@@ -0,0 +1,14 @@
+.. _cor_finder_module:
+
+Centre of Rotation
+******************
+
+Methods from :mod:`httomolibgpu.recon.rotation` module are used for automatic determination of the centre of rotation (COR). The centre of rotation (COR) is a critical parameter in tomographic reconstruction. An incorrect COR introduces characteristic reconstruction artefacts, including blurring, double edges, and duplicated structures. See more about CoR `here <https://diamondlightsource.github.io/httomo/howto/httomo_features/centering.html>`_
+
+
+.. toctree::
+   :maxdepth: 2
+
+   cor_finder/find_center_metric_recon
+
+

httomolibgpu/__init__.py

@@ -26,4 +26,9 @@
     ADMM3d_tomobar,
 )
 
-from httomolibgpu.recon.rotation import find_center_vo, find_center_360, find_center_pc
+from httomolibgpu.recon.rotation import (
+    find_center_vo,
+    find_center_360,
+    find_center_pc,
+    find_center_metric_recon,
+)

httomolibgpu/misc/blend.py

@@ -18,7 +18,11 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 5 August 2026
 # ---------------------------------------------------------------------------
-"""Module for data type morphing functions"""
+"""Module for data type morphing functions:
+
+* :mod:`httomolibgpu.misc.blend.seam_blend_stitched_data`
+
+"""
 
 import numpy as np
 from httomolibgpu import cupywrapper

httomolibgpu/misc/corr.py

@@ -18,7 +18,13 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 21/October/2022
 # ---------------------------------------------------------------------------
-"""Module for data correction. For more detailed information see :ref:`data_correction_module`."""
+"""Module for data correction. For more detailed information see :ref:`data_correction_module`.
+
+* :mod:`httomolibgpu.misc.corr.median_filter`
+
+* :mod:`httomolibgpu.misc.corr.remove_outlier`
+
+"""
 
 from httomolibgpu import cupywrapper
 

httomolibgpu/misc/denoise.py

@@ -18,7 +18,13 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 18/December/2024
 # ---------------------------------------------------------------------------
-"""Module for data denoising. For more detailed information see :ref:`data_denoising_module`."""
+"""Module for data denoising. For more detailed information see :ref:`data_denoising_module`:
+
+* :mod:`httomolibgpu.misc.denoise.total_variation_ROF`
+
+* :mod:`httomolibgpu.misc.denoise.total_variation_PD`
+
+"""
 
 from httomolibgpu import cupywrapper
 

httomolibgpu/misc/morph.py

@@ -18,7 +18,15 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 23 March 2023
 # ---------------------------------------------------------------------------
-"""Module for data type morphing functions"""
+"""Module for data type morphing functions:
+
+* :mod:`httomolibgpu.misc.morph.sino_360_to_180`
+
+* :mod:`httomolibgpu.misc.morph.data_resampler`
+
+* :mod:`httomolibgpu.misc.morph.average_projection_frames`
+
+"""
 
 import numpy as np
 from httomolibgpu import cupywrapper

httomolibgpu/misc/rescale.py

@@ -18,7 +18,11 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 1 March 2024
 # ---------------------------------------------------------------------------
-"""Module for data rescaling. For more detailed information see :ref:`data_rescale_module`."""
+"""Module for data rescaling. For more detailed information see :ref:`data_rescale_module` :
+
+* :mod:`httomolibgpu.misc.rescale.rescale_to_int`
+
+"""
 
 import numpy as np
 from httomolibgpu import cupywrapper

httomolibgpu/prep/alignment.py

@@ -18,7 +18,11 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 01 November 2022
 # ---------------------------------------------------------------------------
-"""Modules for data correction"""
+"""Modules for data correction:
+
+* :mod:`httomolibgpu.prep.alignment.distortion_correction_proj_discorpy`
+
+"""
 
 from httomolibgpu import cupywrapper
 

httomolibgpu/prep/normalize.py

@@ -18,7 +18,13 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 01 November 2022
 # ---------------------------------------------------------------------------
-"""Modules for raw projection data normalization"""
+"""Modules for flat/dark-field correction of projection data and normalisation:
+
+* :mod:`httomolibgpu.prep.normalize.dark_flat_field_correction`
+
+* :mod:`httomolibgpu.prep.normalize.minus_log`
+
+"""
 
 from httomolibgpu import cupywrapper
 import numpy as np

httomolibgpu/prep/phase.py

@@ -18,7 +18,13 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 01 November 2022
 # ---------------------------------------------------------------------------
-"""Modules for phase retrieval and phase-contrast enhancement. For more detailed information, see :ref:`phase_contrast_module`."""
+"""Modules for phase retrieval and phase-contrast enhancement. For more detailed information, see :ref:`phase_contrast_module`.
+
+* :mod:`httomolibgpu.prep.phase.paganin_filter`
+
+* :mod:`httomolibgpu.prep.phase.paganin_filter_savu_legacy`
+
+"""
 
 import numpy as np
 from httomolibgpu import cupywrapper

httomolibgpu/prep/stripe.py

@@ -18,7 +18,19 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 01 November 2022
 # ---------------------------------------------------------------------------
-"""Module for stripes removal"""
+"""Module for stripes removal (ring artifacts suppression), see more in :ref:`stripes_removal_module`.
+
+* :mod:`httomolibgpu.prep.stripe.remove_stripe_based_sorting`
+
+* :mod:`httomolibgpu.prep.stripe.remove_stripe_fw`
+
+* :mod:`httomolibgpu.prep.stripe.remove_stripe_ti`
+
+* :mod:`httomolibgpu.prep.stripe.remove_all_stripe`
+
+* :mod:`httomolibgpu.prep.stripe.raven_filter`
+
+"""
 
 import numpy as np
 import pywt

httomolibgpu/recon/algorithm.py

@@ -18,7 +18,25 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Changes relative to ToMoBAR 2024.01 version
 # ---------------------------------------------------------------------------
-"""Module for tomographic reconstruction. For more detailed information, see :ref:`image_reconstruction_module`"""
+"""Module for tomographic reconstruction. For more detailed information, see :ref:`image_reconstruction_module`
+
+* :mod:`httomolibgpu.recon.algorithm.FBP2d_astra`
+
+* :mod:`httomolibgpu.recon.algorithm.FBP3d_tomobar`
+
+* :mod:`httomolibgpu.recon.algorithm.LPRec3d_tomobar`
+
+* :mod:`httomolibgpu.recon.algorithm.SIRT3d_tomobar`
+
+* :mod:`httomolibgpu.recon.algorithm.CGLS3d_tomobar`
+
+* :mod:`httomolibgpu.recon.algorithm.FISTA3d_tomobar`
+
+* :mod:`httomolibgpu.recon.algorithm.ADMM3d_tomobar`
+
+* :mod:`httomolibgpu.recon.algorithm.OSEM3d_tomobar`
+
+"""
 
 import numpy as np
 from httomolibgpu import cupywrapper