httomolibgpu 3.1.1__tar.gz → 5.0__tar.gz

{httomolibgpu-3.1.1/httomolibgpu.egg-info → httomolibgpu-5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httomolibgpu
-Version: 3.1.1
+Version: 5.0
 Summary: Commonly used tomography data processing methods at DLS.
 Author-email: Daniil Kazantsev <daniil.kazantsev@diamond.ac.uk>, Yousef Moazzam <yousef.moazzam@diamond.ac.uk>, Naman Gera <naman.gera@diamond.ac.uk>
 License: BSD-3-Clause

{httomolibgpu-3.1.1 → httomolibgpu-5.0}/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_tomopy
+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-3.1.1 → httomolibgpu-5.0}/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-3.1.1 → httomolibgpu-5.0}/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-3.1.1 → httomolibgpu-5.0}/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-3.1.1 → httomolibgpu-5.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-5.0/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-3.1.1 → httomolibgpu-5.0}/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-3.1.1 → httomolibgpu-5.0}/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-3.1.1 → httomolibgpu-5.0}/httomolibgpu/prep/phase.py

@@ -18,7 +18,7 @@
 # Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
 # Created Date: 01 November 2022
 # ---------------------------------------------------------------------------
-"""Modules for phase retrieval and phase-contrast enhancement"""
+"""Modules for phase retrieval and phase-contrast enhancement. For more detailed information, see :ref:`phase_contrast_module`."""
 
 import numpy as np
 from httomolibgpu import cupywrapper
@@ -39,38 +39,38 @@ from numpy import float32
 from typing import Tuple
 import math
 
-from httomolibgpu.misc.supp_func import data_checker
-
 __all__ = [
-    "paganin_filter_tomopy",
+    "paganin_filter",
+    "paganin_filter_savu_legacy",
 ]
 
 
-##-------------------------------------------------------------##
-# Adaptation of retrieve_phase (Paganin filter) from TomoPy
-def paganin_filter_tomopy(
+# This implementation originated from the TomoPy version. It has been modified to conform
+# different unit standards and also control of the filter driven by 'delta/beta' ratio
+# as opposed to 'alpha' in the TomoPy's implementation.
+def paganin_filter(
     tomo: cp.ndarray,
-    pixel_size: float = 1e-4,
-    dist: float = 50.0,
+    pixel_size: float = 1.28,
+    distance: float = 1.0,
     energy: float = 53.0,
-    alpha: float = 1e-3,
+    ratio_delta_beta: float = 250,
 ) -> cp.ndarray:
     """
-    Perform single-material phase retrieval from flats/darks corrected tomographic measurements. See
-    :cite:`Paganin02` for a reference.
+    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.
 
     Parameters
     ----------
     tomo : cp.ndarray
         3D array of f/d corrected tomographic projections.
-    pixel_size : float, optional
-        Detector pixel size in cm.
-    dist : float, optional
-        Propagation distance of the wavefront in cm.
-    energy : float, optional
-        Energy of incident wave in keV.
-    alpha : float, optional
-        Regularization parameter, the ratio of delta/beta. Smaller values lead to less noise and more blur.
+    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
     -------
@@ -84,8 +84,6 @@ def paganin_filter_tomopy(
             " please provide a stack of 2D projections."
         )
 
-    tomo = data_checker(tomo, verbosity=True, method_name="paganin_filter_tomopy")
-
     dz_orig, dy_orig, dx_orig = tomo.shape
 
     # Perform padding to the power of 2 as FFT is O(n*log(n)) complexity
@@ -98,11 +96,18 @@ def paganin_filter_tomopy(
     padded_tomo = cp.asarray(padded_tomo, dtype=cp.complex64)
     fft_tomo = fft2(padded_tomo, axes=(-2, -1), overwrite_x=True)
 
-    # Compute the reciprocal grid.
-    w2 = _reciprocal_grid(pixel_size, (dy, dx))
+    # calculate alpha constant
+    alpha = _calculate_alpha(energy, distance / 1e-6, ratio_delta_beta)
+
+    # Compute the reciprocal grid
+    indx = _reciprocal_coord(pixel_size, dy)
+    indy = _reciprocal_coord(pixel_size, dx)
+
+    # Build Lorentzian-type filter
+    phase_filter = fftshift(
+        1.0 / (1.0 + alpha * (cp.add.outer(cp.square(indx), cp.square(indy))))
+    )
 
-    # Build filter in the Fourier space.
-    phase_filter = fftshift(_paganin_filter_factor2(energy, dist, alpha, w2))
     phase_filter = phase_filter / phase_filter.max()  # normalisation
 
     # Filter projections
@@ -132,6 +137,12 @@ def paganin_filter_tomopy(
     return _log_kernel(tomo)
 
 
+def _calculate_alpha(energy, distance_micron, ratio_delta_beta):
+    return (
+        _wavelength_micron(energy) * distance_micron / (4 * math.pi)
+    ) * ratio_delta_beta
+
+
 def _shift_bit_length(x: int) -> int:
     return 1 << (x - 1).bit_length()
 
@@ -192,60 +203,64 @@ def _pad_projections_to_second_power(
     return padded_tomo, tuple(pad_list)
 
 
-def _paganin_filter_factor2(energy, dist, alpha, w2):
-    # Alpha represents the ratio of delta/beta.
-    return 1 / (_wavelength(energy) * dist * w2 / (4 * math.pi) + alpha)
-
-
-def _wavelength(energy: float) -> float:
-    SPEED_OF_LIGHT = 299792458e2  # [cm/s]
+def _wavelength_micron(energy: float) -> float:
+    SPEED_OF_LIGHT = 299792458e2 * 10000.0  # [microns/s]
     PLANCK_CONSTANT = 6.58211928e-19  # [keV*s]
     return 2 * math.pi * PLANCK_CONSTANT * SPEED_OF_LIGHT / energy
 
 
-def _reciprocal_grid(pixel_size: float, shape_proj: tuple) -> cp.ndarray:
+def _reciprocal_coord(pixel_size: float, num_grid: int) -> cp.ndarray:
     """
-    Calculate reciprocal grid.
+    Calculate reciprocal grid coordinates for a given pixel size
+    and discretization.
 
     Parameters
     ----------
     pixel_size : float
-        Detector pixel size in cm.
-    shape_proj : tuple
-        Shape of the reciprocal grid along x and y axes.
+        Detector pixel size in microns.
+    num_grid : int
+        Size of the reciprocal grid.
 
     Returns
     -------
     ndarray
         Grid coordinates.
     """
-    # Sampling in reciprocal space.
-    indx = _reciprocal_coord(pixel_size, shape_proj[0])
-    indy = _reciprocal_coord(pixel_size, shape_proj[1])
-    indx_sq = cp.square(indx)
-    indy_sq = cp.square(indy)
-
-    return cp.add.outer(indx_sq, indy_sq)
+    n = num_grid - 1
+    rc = cp.arange(-n, num_grid, 2, dtype=cp.float32)
+    rc *= 2 * math.pi / (n * pixel_size)
+    return rc
 
 
-def _reciprocal_coord(pixel_size: float, num_grid: int) -> cp.ndarray:
+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:
     """
-    Calculate reciprocal grid coordinates for a given pixel size
-    and discretization.
+    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 in cm.
-    num_grid : int
-        Size of the reciprocal grid.
+        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
     -------
-    ndarray
-        Grid coordinates.
+    cp.ndarray
+        The 3D array of Paganin phase-filtered projection images.
     """
-    n = num_grid - 1
-    rc = cp.arange(-n, num_grid, 2, dtype=cp.float32)
-    rc *= 2 * math.pi / (n * pixel_size)
-    return rc
+
+    return paganin_filter(tomo, pixel_size, distance, energy, ratio_delta_beta / 4)

{httomolibgpu-3.1.1 → httomolibgpu-5.0}/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)