sigima 0.0.1.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

sigima/proc/image/noise.py

@@ -0,0 +1,107 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Noise addition computation module.
+----------------------------------
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y...
+
+# Note:
+# ----
+# - All `guidata.dataset.DataSet` parameter classes must also be imported in the
+#   `sigima.params` module.
+# - All functions decorated by `computation_function` must be imported in the upper
+#   level `sigima.proc.image` module.
+
+from __future__ import annotations
+
+import guidata.dataset as gds
+
+from sigima.objects.base import (
+    NormalDistributionParam,
+    PoissonDistributionParam,
+    UniformDistributionParam,
+)
+from sigima.objects.image import (
+    ImageObj,
+    NormalDistribution2DParam,
+    PoissonDistribution2DParam,
+    UniformDistribution2DParam,
+    create_image_from_param,
+)
+from sigima.proc.base import dst_1_to_1
+from sigima.proc.decorator import computation_function
+from sigima.proc.image.arithmetic import addition
+
+
+@computation_function()
+def add_gaussian_noise(src: ImageObj, p: NormalDistributionParam) -> ImageObj:
+    """Add Gaussian (normal) noise to the input image.
+
+    Args:
+        src: Source image.
+        p: Parameters.
+
+    Returns:
+        Result image object.
+    """
+    param = NormalDistribution2DParam()  # Do not confuse with NormalDistributionParam
+    gds.update_dataset(param, p)
+    assert src.data is not None
+    shape = src.data.shape
+    param.height = shape[0]
+    param.width = shape[1]
+    param.dtype = src.data.dtype
+    noise = create_image_from_param(param)
+    dst = dst_1_to_1(src, "add_gaussian_noise", f"mu={p.mu},sigma={p.sigma}")
+    dst.data = addition([dst, noise]).data
+    return dst
+
+
+@computation_function()
+def add_poisson_noise(src: ImageObj, p: PoissonDistributionParam) -> ImageObj:
+    """Add Poisson noise to the input image.
+
+    Args:
+        src: Source image.
+        p: Parameters.
+
+    Returns:
+        Result image object.
+    """
+    param = PoissonDistribution2DParam()  # Do not confuse with PoissonDistributionParam
+    gds.update_dataset(param, p)
+    assert src.data is not None
+    shape = src.data.shape
+    param.height = shape[0]
+    param.width = shape[1]
+    param.dtype = src.data.dtype
+    noise = create_image_from_param(param)
+    dst = dst_1_to_1(src, "add_poisson_noise", f"lam={p.lam}")
+    dst.data = addition([dst, noise]).data
+    return dst
+
+
+@computation_function()
+def add_uniform_noise(src: ImageObj, p: UniformDistributionParam) -> ImageObj:
+    """Add uniform noise to the input image.
+
+    Args:
+        src: Source image.
+        p: Parameters.
+
+    Returns:
+        Result image object.
+    """
+    param = UniformDistribution2DParam()  # Do not confuse with UniformDistributionParam
+    gds.update_dataset(param, p)
+    assert src.data is not None
+    shape = src.data.shape
+    param.height = shape[0]
+    param.width = shape[1]
+    param.dtype = src.data.dtype
+    noise = create_image_from_param(param)
+    dst = dst_1_to_1(src, "add_uniform_noise", f"low={p.vmin}, high={p.vmax}")
+    dst.data = addition([dst, noise]).data
+    return dst

sigima/proc/image/preprocessing.py

@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+"""
+Image preprocessing functions.
+
+This module consolidates preprocessing functions that were previously scattered
+across different modules (exposure, geometry, fourier). All functions in this
+module operate on high-level ImageObj objects and use parameter classes from
+the sigima.proc framework.
+"""
+
+from __future__ import annotations
+
+import guidata.dataset as gds
+import numpy as np
+
+import sigima.enums
+import sigima.tools.image
+from sigima.config import _
+from sigima.enums import PadLocation2D
+from sigima.objects.image import ImageObj
+from sigima.proc.base import dst_1_to_1
+from sigima.proc.decorator import computation_function
+
+__all__ = [
+    "BinningParam",
+    "ZeroPadding2DParam",
+    "binning",
+    "zero_padding",
+]
+
+
+class BinningParam(gds.DataSet):
+    """Binning parameters."""
+
+    sx = gds.IntItem(
+        _("Cluster size (X)"),
+        default=2,
+        min=2,
+        help=_("Number of adjacent pixels to be combined together along X-axis."),
+    )
+    sy = gds.IntItem(
+        _("Cluster size (Y)"),
+        default=2,
+        min=2,
+        help=_("Number of adjacent pixels to be combined together along Y-axis."),
+    )
+    operation = gds.ChoiceItem(
+        _("Operation"),
+        sigima.enums.BinningOperation,
+        default=sigima.enums.BinningOperation.SUM,
+    )
+    dtypes = ["dtype"] + ImageObj.get_valid_dtypenames()
+    dtype_str = gds.ChoiceItem(
+        _("Data type"),
+        list(zip(dtypes, dtypes)),
+        help=_("Output image data type."),
+    )
+    change_pixel_size = gds.BoolItem(
+        _("Change pixel size"),
+        default=True,
+        help=_(
+            "If checked, pixel size is updated according to binning factors. "
+            "Users who prefer to work with pixel coordinates may want to uncheck this."
+        ),
+    )
+
+
+@computation_function()
+def binning(src: ImageObj, p: BinningParam) -> ImageObj:
+    """Binning: image pixel binning (or aggregation).
+
+    Depending on the algorithm, the input image may be cropped to fit an integer
+    number of blocks.
+
+    Args:
+        src: source image
+        p: parameters
+
+    Returns:
+        Output image
+
+    Raises:
+        ValueError: if source image has non-uniform coordinates
+    """
+    if not src.is_uniform_coords:
+        raise ValueError("Binning only works with images having uniform coordinates")
+    # Create destination image
+    dst = dst_1_to_1(
+        src,
+        "binning",
+        f"{p.sx}x{p.sy},{p.operation},change_pixel_size={p.change_pixel_size}",
+    )
+    dst.data = sigima.tools.image.binning(
+        src.data,
+        sx=p.sx,
+        sy=p.sy,
+        operation=p.operation,
+        dtype=None if p.dtype_str == "dtype" else p.dtype_str,
+    )
+    if p.change_pixel_size:
+        if not np.isnan(src.dx) and not np.isnan(src.dy):
+            # Update coordinates with new pixel spacing
+            new_dx = src.dx * p.sx
+            new_dy = src.dy * p.sy
+            dst.set_uniform_coords(new_dx, new_dy, src.x0, src.y0)
+    return dst
+
+
+class ZeroPadding2DParam(gds.DataSet):
+    """Zero padding parameters for 2D images"""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.__obj: ImageObj | None = None
+
+    def update_from_obj(self, obj: ImageObj) -> None:
+        """Update parameters from image"""
+        self.__obj = obj
+        self.choice_callback(None, self.strategy)
+
+    def choice_callback(self, item, value):  # pylint: disable=unused-argument
+        """Callback to update padding values"""
+        if self.__obj is None:
+            return
+        rows, cols = self.__obj.data.shape
+        if value == "next_pow2":
+            self.rows = 2 ** int(np.ceil(np.log2(rows))) - rows
+            self.cols = 2 ** int(np.ceil(np.log2(cols))) - cols
+        elif value == "multiple_of_64":
+            self.rows = (64 - rows % 64) if rows % 64 != 0 else 0
+            self.cols = (64 - cols % 64) if cols % 64 != 0 else 0
+
+    strategies = ("next_pow2", "multiple_of_64", "custom")
+    _prop = gds.GetAttrProp("strategy")
+    strategy = gds.ChoiceItem(
+        _("Padding strategy"), zip(strategies, strategies), default=strategies[-1]
+    ).set_prop("display", store=_prop, callback=choice_callback)
+
+    _func_prop = gds.FuncProp(_prop, lambda x: x == "custom")
+    rows = gds.IntItem(_("Rows to add"), min=0, default=0).set_prop(
+        "display", active=_func_prop
+    )
+    cols = gds.IntItem(_("Columns to add"), min=0, default=0).set_prop(
+        "display", active=_func_prop
+    )
+    position = gds.ChoiceItem(
+        _("Padding position"), PadLocation2D, default=PadLocation2D.BOTTOM_RIGHT
+    )
+
+
+@computation_function()
+def zero_padding(
+    src: ImageObj,
+    p: ZeroPadding2DParam | None = None,
+) -> ImageObj:
+    """Zero-padding: add zeros to image borders.
+
+    Args:
+        src: input image object
+        p: parameters
+
+    Returns:
+        Output image object
+    """
+    if p is None:
+        p = ZeroPadding2DParam.create()
+
+    if p.strategy == "custom":
+        suffix = f"rows={p.rows}, cols={p.cols}"
+    else:
+        suffix = f"strategy={p.strategy}"
+    suffix += f", position={p.position}"
+
+    dst = dst_1_to_1(src, "zero_padding", suffix)
+    result = sigima.tools.image.zero_padding(
+        src.data,
+        rows=p.rows,
+        cols=p.cols,
+        position=p.position,
+    )
+    dst.data = result
+    return dst

sigima/proc/image/restoration.py

@@ -0,0 +1,235 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Restoration computation module
+------------------------------
+
+This module provides image restoration techniques, such as
+denoising, inpainting, and deblurring. These methods aim to recover
+the original quality of images by removing artifacts, noise, or
+distortions.
+"""
+
+# pylint: disable=invalid-name  # Allows short reference names like x, y, ...
+
+# Note:
+# ----
+# - All `guidata.dataset.DataSet` parameter classes must also be imported
+#   in the `sigima.params` module.
+# - All functions decorated by `computation_function` must be imported in the upper
+#   level `sigima.proc.image` module.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import guidata.dataset as gds
+import numpy as np
+import pywt
+from skimage import morphology, restoration
+
+from sigima.config import _
+from sigima.enums import ShrinkageMethod, ThresholdMethod, WaveletMode
+from sigima.objects.image import ImageObj, ROI2DParam
+from sigima.proc.base import dst_1_to_1
+from sigima.proc.decorator import computation_function
+from sigima.proc.image.base import Wrap1to1Func, restore_data_outside_roi
+
+if TYPE_CHECKING:
+    import sigima.params
+
+
+# NOTE: Only parameter classes DEFINED in this module should be included in __all__.
+# Parameter classes imported from other modules (like sigima.proc.base) should NOT
+# be re-exported to avoid Sphinx cross-reference conflicts. The sigima.params module
+# serves as the central API point that imports and re-exports all parameter classes.
+__all__ = [
+    "DenoiseBilateralParam",
+    "DenoiseTVParam",
+    "DenoiseWaveletParam",
+    "denoise_bilateral",
+    "denoise_tophat",
+    "denoise_tv",
+    "denoise_wavelet",
+    "erase",
+]
+
+
+class DenoiseTVParam(gds.DataSet):
+    """Total Variation denoising parameters"""
+
+    weight = gds.FloatItem(
+        _("Denoising weight"),
+        default=0.1,
+        min=0,
+        nonzero=True,
+        help=_(
+            "The greater weight, the more denoising "
+            "(at the expense of fidelity to input)."
+        ),
+    )
+    eps = gds.FloatItem(
+        "Epsilon",
+        default=0.0002,
+        min=0,
+        nonzero=True,
+        help=_(
+            "Relative difference of the value of the cost function that "
+            "determines the stop criterion. The algorithm stops when: "
+            "(E_(n-1) - E_n) < eps * E_0"
+        ),
+    )
+    max_num_iter = gds.IntItem(
+        _("Max. iterations"),
+        default=200,
+        min=0,
+        nonzero=True,
+        help=_("Maximal number of iterations used for the optimization"),
+    )
+
+
+@computation_function()
+def denoise_tv(src: ImageObj, p: DenoiseTVParam) -> ImageObj:
+    """Compute Total Variation denoising
+    with :py:func:`skimage.restoration.denoise_tv_chambolle`
+
+    Args:
+        src: input image object
+        p: parameters
+
+    Returns:
+        Output image object
+    """
+    return Wrap1to1Func(
+        restoration.denoise_tv_chambolle,
+        weight=p.weight,
+        eps=p.eps,
+        max_num_iter=p.max_num_iter,
+        func_name="denoise_tv",
+    )(src)
+
+
+class DenoiseBilateralParam(gds.DataSet):
+    """Bilateral filter denoising parameters"""
+
+    sigma_spatial = gds.FloatItem(
+        "σ<sub>spatial</sub>",
+        default=1.0,
+        min=0,
+        nonzero=True,
+        unit="pixels",
+        help=_(
+            "Standard deviation for range distance. "
+            "A larger value results in averaging of pixels "
+            "with larger spatial differences."
+        ),
+    )
+    mode = gds.ChoiceItem(_("Mode"), WaveletMode, default=WaveletMode.CONSTANT)
+    cval = gds.FloatItem(
+        "cval",
+        default=0.0,
+        help=_(
+            "Used in conjunction with mode 'constant', "
+            "the value outside the image boundaries."
+        ),
+    )
+
+
+@computation_function()
+def denoise_bilateral(src: ImageObj, p: DenoiseBilateralParam) -> ImageObj:
+    """Compute bilateral filter denoising
+    with :py:func:`skimage.restoration.denoise_bilateral`
+
+    Args:
+        src: input image object
+        p: parameters
+
+    Returns:
+        Output image object
+    """
+    return Wrap1to1Func(
+        restoration.denoise_bilateral,
+        sigma_spatial=p.sigma_spatial,
+        mode=p.mode,
+        cval=p.cval,
+    )(src)
+
+
+class DenoiseWaveletParam(gds.DataSet):
+    """Wavelet denoising parameters"""
+
+    wavelets = pywt.wavelist()
+    wavelet = gds.ChoiceItem(
+        _("Wavelet"), list(zip(wavelets, wavelets)), default="sym9"
+    )
+    mode = gds.ChoiceItem(_("Mode"), ThresholdMethod, default=ThresholdMethod.SOFT)
+    method = gds.ChoiceItem(
+        _("Method"), ShrinkageMethod, default=ShrinkageMethod.VISU_SHRINK
+    )
+
+
+@computation_function()
+def denoise_wavelet(src: ImageObj, p: DenoiseWaveletParam) -> ImageObj:
+    """Compute Wavelet denoising
+    with :py:func:`skimage.restoration.denoise_wavelet`
+
+    Args:
+        src: input image object
+        p: parameters
+
+    Returns:
+        Output image object
+    """
+    return Wrap1to1Func(
+        restoration.denoise_wavelet, wavelet=p.wavelet, mode=p.mode, method=p.method
+    )(src)
+
+
+@computation_function()
+def denoise_tophat(src: ImageObj, p: sigima.params.MorphologyParam) -> ImageObj:
+    """Denoise using White Top-Hat
+    with :py:func:`skimage.morphology.white_tophat`
+
+    Args:
+        src: input image object
+        p: parameters
+
+    Returns:
+        Output image object
+    """
+    dst = dst_1_to_1(src, "denoise_tophat", f"radius={p.radius}")
+    dst.data = src.data - morphology.white_tophat(src.data, morphology.disk(p.radius))
+    restore_data_outside_roi(dst, src)
+    return dst
+
+
+@computation_function()
+def erase(src: ImageObj, p: ROI2DParam | list[ROI2DParam]) -> ImageObj:
+    """Erase an area of the image using the mean value of the image.
+
+    .. note::
+
+        The erased area is defined by a region of interest (ROI) parameter set.
+        This ROI must not be mistaken with the ROI of the image object. If the
+        image object has a ROI, it is not used in this processing, except to
+        restore the data outside the ROI (as in all other processing).
+
+    Args:
+        src: input image object
+        p: parameters defining the area to erase (region of interest)
+
+    Returns:
+        Output image object
+    """
+    params = [p] if isinstance(p, ROI2DParam) else p
+    suffix = None
+    if len(params) == 1:
+        suffix = params[0].get_suffix()
+    dst = dst_1_to_1(src, "erase", suffix)
+    for param in params:
+        value = np.nanmean(param.get_data(src))
+        erase_roi = param.to_single_roi(src)
+        mask = erase_roi.to_mask(src)
+        dst.data[~mask] = value
+    restore_data_outside_roi(dst, src)
+    return dst