httomolibgpu 4.0__py3-none-any.whl → 5.0__py3-none-any.whl

httomolibgpu/__init__.py

@@ -1,10 +1,12 @@
+from httomolibgpu.misc.utils import data_checker
+
 from httomolibgpu.misc.corr import median_filter, remove_outlier
 from httomolibgpu.misc.denoise import total_variation_ROF, total_variation_PD
 from httomolibgpu.misc.morph import sino_360_to_180, data_resampler
 from httomolibgpu.misc.rescale import rescale_to_int
 from httomolibgpu.prep.alignment import distortion_correction_proj_discorpy
-from httomolibgpu.prep.normalize import normalize
-from httomolibgpu.prep.phase import paganin_filter
+from httomolibgpu.prep.normalize import dark_flat_field_correction, minus_log
+from httomolibgpu.prep.phase import paganin_filter, paganin_filter_savu_legacy
 from httomolibgpu.prep.stripe import (
     remove_stripe_based_sorting,
     remove_stripe_ti,

httomolibgpu/misc/corr.py

@@ -36,8 +36,6 @@ if cupy_run:
 else:
     load_cuda_module = Mock()
 
-from httomolibgpu.misc.supp_func import data_checker
-
 __all__ = [
     "median_filter",
     "remove_outlier",
@@ -82,10 +80,6 @@ def median_filter(
     else:
         raise ValueError("The input array must be a 3D array")
 
-    data = data_checker(
-        data, verbosity=True, method_name="median_filter_or_remove_outlier"
-    )
-
     if kernel_size not in [3, 5, 7, 9, 11, 13]:
         raise ValueError("Please select a correct kernel size: 3, 5, 7, 9, 11, 13")
 

httomolibgpu/misc/denoise.py

@@ -29,8 +29,6 @@ cupy_run = cupywrapper.cupy_run
 
 from unittest.mock import Mock
 
-from httomolibgpu.misc.supp_func import data_checker
-
 if cupy_run:
     from tomobar.regularisersCuPy import ROF_TV_cupy, PD_TV_cupy
 else:
@@ -84,8 +82,6 @@ def total_variation_ROF(
         If the input array is not float32 data type.
     """
 
-    data = data_checker(data, verbosity=True, method_name="total_variation_ROF")
-
     return ROF_TV_cupy(
         data,
         regularisation_parameter,
@@ -139,8 +135,6 @@ def total_variation_PD(
         If the input array is not float32 data type.
     """
 
-    data_checker(data, verbosity=True, method_name="total_variation_PD")
-
     methodTV = 0
     if not isotropic:
         methodTV = 1

httomolibgpu/misc/morph.py

@@ -35,8 +35,6 @@ else:
 
 from typing import Literal
 
-from httomolibgpu.misc.supp_func import data_checker
-
 __all__ = [
     "sino_360_to_180",
     "data_resampler",
@@ -68,8 +66,6 @@ def sino_360_to_180(
     if data.ndim != 3:
         raise ValueError("only 3D data is supported")
 
-    data = data_checker(data, verbosity=True, method_name="sino_360_to_180")
-
     dx, dy, dz = data.shape
 
     overlap = int(np.round(overlap))
@@ -142,8 +138,6 @@ def data_resampler(
         data = cp.expand_dims(data, 1)
         axis = 1
 
-    data = data_checker(data, verbosity=True, method_name="data_resampler")
-
     N, M, Z = cp.shape(data)
 
     if axis == 0:

httomolibgpu/misc/rescale.py

@@ -27,8 +27,6 @@ cp = cupywrapper.cp
 
 from typing import Literal, Optional, Tuple, Union
 
-from httomolibgpu.misc.supp_func import data_checker
-
 
 __all__ = [
     "rescale_to_int",
@@ -80,8 +78,6 @@ def rescale_to_int(
     else:
         output_dtype = np.uint32
 
-    data = data_checker(data, verbosity=True, method_name="rescale_to_int")
-
     # get the min and max integer values of the output type
     output_min = cp.iinfo(output_dtype).min
     output_max = cp.iinfo(output_dtype).max

httomolibgpu/misc/utils.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# ---------------------------------------------------------------------------
+# Copyright 2022 Diamond Light Source Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ---------------------------------------------------------------------------
+# Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
+# Created Date: 02/June/2025
+# ---------------------------------------------------------------------------
+"""Various utilities for data inspection and correction"""
+
+from httomolibgpu import cupywrapper
+from typing import Optional
+
+cp = cupywrapper.cp
+cupy_run = cupywrapper.cupy_run
+
+from unittest.mock import Mock
+
+if cupy_run:
+    from httomolibgpu.cuda_kernels import load_cuda_module
+else:
+    load_cuda_module = Mock()
+
+
+__all__ = [
+    "data_checker",
+]
+
+
+def data_checker(
+    data: cp.ndarray,
+    infsnans_correct: bool = True,
+    zeros_warning: bool = False,
+    data_to_method_name: Optional[str] = None,
+    verbosity: bool = True,
+) -> cp.ndarray:
+    """Function that performs checks on input data to ensure its validity, performs corrections and prints the warnings.
+    Currently it checks for the presence of Infs and NaNs in the data and corrects them.
+
+    Parameters
+    ----------
+    data : cp.ndarray
+        CuPy array either float32 or uint16 data type.
+    infsnans_correct: bool
+        Perform correction of NaNs and Infs if they are present in the data.
+    zeros_warning: bool
+        Count the number of zeros in the data and produce a warning if more half of the data are zeros.
+    verbosity : bool
+        Print the warnings.
+    data_to_method_name : str, optional.
+        Method's name the output of which is tested. This is tailored for printing purposes when the method runs in HTTomo.
+
+    Returns
+    -------
+    cp.ndarray
+        Returns corrected CuPy array.
+    """
+    if data.dtype not in ["uint16", "float32"]:
+        raise ValueError(
+            "The input data of `uint16` and `float32` data types is accepted only."
+        )
+
+    if infsnans_correct:
+        data = __naninfs_check(
+            data, verbosity=verbosity, method_name=data_to_method_name
+        )
+    # TODO
+    # if zeros_warning:
+    # __zeros_check(data, verbosity=verbosity, percentage_threshold = 50, method_name=data_to_method_name)
+
+    return data
+
+
+def __naninfs_check(
+    data: cp.ndarray,
+    verbosity: bool = True,
+    method_name: Optional[str] = None,
+) -> cp.ndarray:
+    """
+    This function finds NaN's, +-Inf's in the input data and then prints the warnings and correct the data if correction is enabled.
+
+    Parameters
+    ----------
+    data : cp.ndarray
+        Input CuPy or Numpy array either float32 or uint16 data type.
+    verbosity : bool
+        If enabled, then the printing of the warning happens when data contains infs or nans
+    method_name : str, optional.
+        Method's name for which the output data is tested.
+
+    Returns
+    -------
+    ndarray
+        Uncorrected or corrected (nans and infs converted to zeros) input array.
+    """
+    present_nans_infs_b = False
+
+    input_type = data.dtype
+    if len(data.shape) == 2:
+        dy, dx = data.shape
+        dz = 1
+    else:
+        dz, dy, dx = data.shape
+
+    present_nans_infs = cp.zeros(shape=(1)).astype(cp.uint8)
+
+    block_x = 128
+    # setting grid/block parameters
+    block_dims = (block_x, 1, 1)
+    grid_x = (dx + block_x - 1) // block_x
+    grid_y = dy
+    grid_z = dz
+    grid_dims = (grid_x, grid_y, grid_z)
+    params = (data, dz, dy, dx, present_nans_infs)
+
+    kernel_args = "remove_nan_inf<{0}>".format(
+        "float" if input_type == "float32" else "unsigned short"
+    )
+
+    module = load_cuda_module("remove_nan_inf", name_expressions=[kernel_args])
+    remove_nan_inf_kernel = module.get_function(kernel_args)
+    remove_nan_inf_kernel(grid_dims, block_dims, params)
+
+    if present_nans_infs[0].get() == 1:
+        present_nans_infs_b = True
+
+    if present_nans_infs_b:
+        if verbosity:
+            print(
+                "Warning! Output data of the \033[31m{}\033[0m method contains Inf's or/and NaN's. Corrected to zeros.".format(
+                    method_name
+                )
+            )
+    return data

httomolibgpu/prep/alignment.py

@@ -35,8 +35,6 @@ else:
 
 from typing import Dict, List, Tuple
 
-from httomolibgpu.misc.supp_func import data_checker
-
 __all__ = [
     "distortion_correction_proj_discorpy",
 ]
@@ -88,10 +86,6 @@ def distortion_correction_proj_discorpy(
     if len(data.shape) == 2:
         data = cp.expand_dims(data, axis=0)
 
-    data = data_checker(
-        data, verbosity=True, method_name="distortion_correction_proj_discorpy"
-    )
-
     # Get info from metadata txt file
     xcenter, ycenter, list_fact = _load_metadata_txt(metadata_path)
 

httomolibgpu/prep/normalize.py

@@ -20,7 +20,6 @@
 # ---------------------------------------------------------------------------
 """Modules for raw projection data normalization"""
 
-import numpy as np
 from httomolibgpu import cupywrapper
 
 cp = cupywrapper.cp
@@ -34,27 +33,21 @@ else:
     mean = Mock()
 
 from numpy import float32
-from typing import Tuple
 
-from httomolibgpu.misc.supp_func import data_checker
 
-__all__ = ["normalize"]
+__all__ = ["dark_flat_field_correction", "minus_log"]
 
 
-def normalize(
+def dark_flat_field_correction(
     data: cp.ndarray,
     flats: cp.ndarray,
     darks: cp.ndarray,
     flats_multiplier: float = 1.0,
     darks_multiplier: float = 1.0,
     cutoff: float = 10.0,
-    minus_log: bool = True,
-    nonnegativity: bool = False,
-    remove_nans: bool = False,
 ) -> cp.ndarray:
     """
     Normalize raw projection data using the flat and dark field projections.
-    This is a raw CUDA kernel implementation with CuPy wrappers.
 
     Parameters
     ----------
@@ -70,17 +63,11 @@ def normalize(
         A multiplier to apply to darks, can work as an intensity compensation constant.
     cutoff : float
         Permitted maximum value for the normalised data.
-    minus_log : bool
-        Apply negative log to the normalised data.
-    nonnegativity : bool
-        Remove negative values in the normalised data.
-    remove_nans : bool
-        Remove NaN and Inf values in the normalised data.
 
-    Returns
+            Returns
     -------
     cp.ndarray
-        Normalised 3D tomographic data as a CuPy array.
+        Normalised by dark/flat fields 3D tomographic data as a CuPy array.
     """
     _check_valid_input_normalise(data, flats, darks)
 
@@ -101,16 +88,6 @@ def normalize(
         }
         float v = (float(data) - float(darks))/denom;
         """
-    if minus_log:
-        kernel += "v = -log(v);\n"
-        kernel_name += "_mlog"
-    if nonnegativity:
-        kernel += "if (v < 0.0f) v = 0.0f;\n"
-        kernel_name += "_nneg"
-    if remove_nans:
-        kernel += "if (isnan(v)) v = 0.0f;\n"
-        kernel += "if (isinf(v)) v = 0.0f;\n"
-        kernel_name += "_remnan"
     kernel += "if (v > cutoff) v = cutoff;\n"
     kernel += "if (v < -cutoff) v = cutoff;\n"
     kernel += "out = v;\n"
@@ -130,6 +107,24 @@ def normalize(
     return out
 
 
+def minus_log(data: cp.ndarray) -> cp.ndarray:
+    """
+    Apply -log(data) operation
+
+    Parameters
+    ----------
+    data : cp.ndarray
+        Data as a CuPy array.
+
+    Returns
+    -------
+    cp.ndarray
+        data after -log(data)
+    """
+
+    return -cp.log(data)
+
+
 def _check_valid_input_normalise(data, flats, darks) -> None:
     """Helper function to check the validity of inputs to normalisation functions"""
     if data.ndim != 3:
@@ -145,7 +140,3 @@ def _check_valid_input_normalise(data, flats, darks) -> None:
         flats = flats[cp.newaxis, :, :]
     if darks.ndim == 2:
         darks = darks[cp.newaxis, :, :]
-
-    data_checker(data, verbosity=True, method_name="normalize_data")
-    data_checker(flats, verbosity=True, method_name="normalize_flats")
-    data_checker(darks, verbosity=True, method_name="normalize_darks")

httomolibgpu/prep/phase.py

@@ -39,10 +39,9 @@ from numpy import float32
 from typing import Tuple
 import math
 
-from httomolibgpu.misc.supp_func import data_checker
-
 __all__ = [
     "paganin_filter",
+    "paganin_filter_savu_legacy",
 ]
 
 
@@ -85,8 +84,6 @@ def paganin_filter(
             " please provide a stack of 2D projections."
         )
 
-    tomo = data_checker(tomo, verbosity=True, method_name="paganin_filter")
-
     dz_orig, dy_orig, dx_orig = tomo.shape
 
     # Perform padding to the power of 2 as FFT is O(n*log(n)) complexity
@@ -233,3 +230,37 @@ def _reciprocal_coord(pixel_size: float, num_grid: int) -> cp.ndarray:
     rc = cp.arange(-n, num_grid, 2, dtype=cp.float32)
     rc *= 2 * math.pi / (n * pixel_size)
     return rc
+
+
+def paganin_filter_savu_legacy(
+    tomo: cp.ndarray,
+    pixel_size: float = 1.28,
+    distance: float = 1.0,
+    energy: float = 53.0,
+    ratio_delta_beta: float = 250,
+) -> cp.ndarray:
+    """
+    Perform single-material phase retrieval from flats/darks corrected tomographic measurements. For more detailed information, see :ref:`phase_contrast_module`.
+    Also see :cite:`Paganin02` and :cite:`paganin2020boosting` for references. The ratio_delta_beta parameter here follows implementation in Savu software.
+    The module will be retired in future in favour of paganin_filter. One can rescale parameter ratio_delta_beta / 4 to achieve the same effect in paganin_filter.
+
+    Parameters
+    ----------
+    tomo : cp.ndarray
+        3D array of f/d corrected tomographic projections.
+    pixel_size : float
+        Detector pixel size (resolution) in micron units.
+    distance : float
+        Propagation distance of the wavefront from sample to detector in metre units.
+    energy : float
+        Beam energy in keV.
+    ratio_delta_beta : float
+        The ratio of delta/beta, where delta is the phase shift and real part of the complex material refractive index and beta is the absorption.
+
+    Returns
+    -------
+    cp.ndarray
+        The 3D array of Paganin phase-filtered projection images.
+    """
+
+    return paganin_filter(tomo, pixel_size, distance, energy, ratio_delta_beta / 4)

httomolibgpu/prep/stripe.py

@@ -43,8 +43,6 @@ else:
 
 from typing import Union
 
-from httomolibgpu.misc.supp_func import data_checker
-
 __all__ = [
     "remove_stripe_based_sorting",
     "remove_stripe_ti",
@@ -83,8 +81,6 @@ def remove_stripe_based_sorting(
 
     """
 
-    data = data_checker(data, verbosity=True, method_name="remove_stripe_based_sorting")
-
     if size is None:
         if data.shape[2] > 2000:
             size = 21
@@ -139,7 +135,6 @@ def remove_stripe_ti(
     ndarray
         3D array of de-striped projections.
     """
-    data = data_checker(data, verbosity=True, method_name="remove_stripe_ti")
 
     _, _, dx_orig = data.shape
     if (dx_orig % 2) != 0:
@@ -216,7 +211,6 @@ def remove_all_stripe(
         Corrected 3D tomographic data as a CuPy or NumPy array.
 
     """
-    data = data_checker(data, verbosity=True, method_name="remove_all_stripe")
 
     matindex = _create_matindex(data.shape[2], data.shape[0])
     for m in range(data.shape[1]):
@@ -392,8 +386,6 @@ def raven_filter(
     if data.dtype != cp.float32:
         raise ValueError("The input data should be float32 data type")
 
-    data = data_checker(data, verbosity=True, method_name="raven_filter")
-
     # Padding of the sinogram
     data = cp.pad(data, ((pad_y, pad_y), (0, 0), (pad_x, pad_x)), mode=pad_method)