gliders 0.1.0__py3-none-any.whl

gliders/__init__.py

@@ -0,0 +1,2 @@
+from .pipeline import clean_image
+# __all__ = ["get_clean_image_and_segment"]

gliders/artifacts.py

@@ -0,0 +1,349 @@
+import numpy as np
+from .utils import interpolate_image, grow_mask, add_noise_to_region, sigma_clipping, shrink_mask, get_profile_gradient, get_profile_from_border
+from photutils.segmentation import SourceCatalog, detect_sources
+
+
+def detect_and_clean_artifacts(image, config = None, img_bkg_lvl = None, pix_scale = 1, main_source_pos = None,
+                               skip_flagged_artifacts = False, verbose = False,  show_plots = False):
+    """
+    Detect and optionally remove overexposure artifacts from an image.
+
+    Artifact candidates are first identified using
+    :func:`detect_artifacts`, which searches for bright structures with
+    characteristic intensity profiles. Detected artifacts are then
+    classified as either safe or unsafe according to their size and
+    proximity to the target source through
+    :func:`get_artifact_flag`.
+
+    If artifacts are detected and cleaning is allowed, the affected
+    regions are replaced using :func:`clean_artifacts`, including an
+    additional mask to account for bleeding around the artifact.
+
+    Parameters
+    ----------
+    image : ndarray
+        Input image to be inspected and cleaned.
+
+    config : object, optional
+        Configuration object containing the artifact-detection and
+        cleaning parameters. If None, the default cleaning configuration
+        is loaded from ``cleaning_configs``.
+
+    img_bkg_lvl : float, optional
+        Background level of the image. If None, it is estimated using
+        sigma clipping.
+
+    pix_scale : float, optional
+        Pixel scale of the image. Used when cleaning artifacts. Default is 1.
+
+    main_source_pos : tuple(float, float) or None, optional
+        Pixel coordinates (x, y) of the primary target source. Used to
+        determine whether a detected artifact lies within the protected
+        central region of the image. If None, the image center is used.
+
+    skip_flagged_artifacts : bool, optional
+        If True, artifacts classified as unsafe are not cleaned and the
+        original image is returned unchanged. This can be useful to
+        preserve images where an artifact significantly affects the
+        target source. Default is False.
+
+    show_plots : bool, optional
+        If True, display diagnostic plots showing the original image,
+        cleaned image, detected artifact mask, and final cleaning mask.
+        Default is False.
+
+    Returns
+    -------
+    clean_image : ndarray
+        The cleaned image. If no artifacts are detected, or if cleaning
+        is skipped, this will be identical to the input image.
+
+    cleaning_mask : ndarray of bool
+        Boolean mask identifying pixels affected by the artifact
+        cleaning process. This includes both the detected artifact
+        pixels and any additional bleeding region considered during
+        cleaning.
+
+    unsafe_artifact_flag : bool
+        True if a detected artifact overlaps the protected central
+        region and exceeds the configured relative size threshold.
+        False otherwise.
+
+    Notes
+    -----
+    The behavior of the detector and cleaner is controlled by the
+    following configuration parameters:
+
+    - ``npixels_artifact``
+    - ``artifact_delta_slope_threshold``
+    - ``artifact_segment_slack``
+    - ``artifact_candidate_ratio``
+    - ``artifact_rel_size_thresh``
+    - ``artifact_safe_region_radius``
+    - ``artifact_bleeding_factor``
+
+    When ``skip_flagged_artifacts=True``, images containing unsafe
+    artifacts are not modified, although the artifact mask and flag are
+    still returned.
+    """
+
+    if config is None:
+        from .cleaning_configs import configs
+        config = configs["default"]
+    if img_bkg_lvl is None:
+        img_bkg_lvl, _ = sigma_clipping(image)
+
+    artifact_segmap = detect_artifacts(image, npixels_artifact=config.npixels_artifact,
+                                     delta_slope_threshold=config.artifact_delta_slope_threshold,
+                                     segment_slack=config.artifact_segment_slack,
+                                     hi_pass_threshold=img_bkg_lvl * config.artifact_candidate_ratio)
+
+    if artifact_segmap is None:
+        if verbose:
+            print("No overexposure artifacts were detected in the image.")
+        cleaning_mask = np.zeros_like(image, dtype=bool)
+        return image, cleaning_mask, False
+
+    artifact_mask = artifact_segmap.make_source_mask()
+    unsafe_artifact_flag = get_artifact_flag(artifact_mask, main_source_pos, config.artifact_rel_size_thresh, config.artifact_safe_region_radius, show_plots = show_plots)
+
+    if artifact_mask.any() and not (skip_flagged_artifacts and unsafe_artifact_flag):
+        clean_image, cleaning_mask = clean_artifacts(image, artifact_segmap, config.artifact_bleeding_factor,
+                                                     config.artifact_interpolation_radius, pix_scale)
+    else:
+        clean_image = image
+        cleaning_mask = artifact_mask
+
+    if show_plots:
+        import matplotlib.pyplot as plt
+        fig, ax = plt.subplots(2,2)
+        ax[0,0].imshow(image, norm = "log", origin = "lower")
+        ax[0,0].set_title('Input image')
+        ax[0,1].imshow(clean_image, norm = "log", origin = "lower")
+        ax[0,1].set_title('Treated image')
+        ax[1,0].imshow(artifact_mask, origin = "lower")
+        ax[1,0].set_title('Detected artifacts')
+        ax[1,1].imshow(cleaning_mask, origin = "lower")
+        ax[1,1].set_title('Detected artifacts + bleeding')
+        plt.tight_layout()
+        plt.show()
+
+    return clean_image, cleaning_mask, unsafe_artifact_flag
+
+def clean_artifacts(image, artifact_segmap = None, bleeding_factor = 1.0, interpolation_radius = 1, pix_scale = 1):
+
+    """Remove artifacts based on interpolation over segmented artifacts.
+
+    Parameters
+    ----------
+    image : np.ndarray
+        Input image.
+    artifact_segmap : segmentation map, optional
+        Artifact segmentation map. If None, the image is returned unchanged.
+    bleeding_factor : float
+        Multiplier controlling how far the artifact mask is expanded.
+    interpolation_radius : float
+        Radius of the circle containing the pixels to be considered in the interpolation.
+    pix_scale : float
+        Scale factor of the noise pixels added.
+
+    Returns
+    -------
+    image : np.ndarray
+        Cleaned image.
+    full_cleaning_mask : np.ndarray or None
+        Mask of pixels modified by the cleaning procedure.
+    """
+
+    if artifact_segmap is None or (len(artifact_segmap.segments) < 1):
+        return image, np.zeros(image.shape, dtype=bool)
+
+    if bleeding_factor < 0:
+        raise ValueError("bleeding_factor must be non-negative")
+
+    if interpolation_radius < 1:
+        raise ValueError("interpolation_radius must be equal or greater than 1")
+    all_artifacts_mask = artifact_segmap.make_source_mask()
+    full_cleaning_mask = all_artifacts_mask.copy()
+    for artifact in artifact_segmap.segments:
+        artifact_mask = artifact_segmap.data == artifact.label
+        artifact_area = artifact_mask.sum()
+        bleeding_decay = 2 * artifact_area**(1/3) # Rounded from empiric formula based on DESI Legacy images.
+        bleeding_radius = round(bleeding_factor * bleeding_decay)
+        # Expanding detection mask to cover artifact bleeding
+        cleaning_mask = grow_mask(artifact_mask, pixels=bleeding_radius)
+        full_cleaning_mask |= cleaning_mask
+
+    image = interpolate_image(image, full_cleaning_mask, interpolation_radius, method="inpaint")
+    _, img_bkg_lvl_std = sigma_clipping(image)
+    image = add_noise_to_region(image, full_cleaning_mask, noise_center=0, noise_std=img_bkg_lvl_std, scale=pix_scale)
+    return image, full_cleaning_mask
+
+def detect_artifacts(image, npixels_artifact=100, delta_slope_threshold = 2.7, segment_slack = 5, hi_pass_threshold = 1):
+    """
+    Detect candidate overexposure artifacts based on their radial intensity profile.
+
+    The algorithm first identifies bright connected regions above a fixed
+    intensity threshold. For each candidate region, a series of concentric
+    layers is constructed around the detected segment and the mean pixel value
+    within each layer is measured. The resulting radial profile is analyzed
+    through its gradient and second-order variations (delta slopes).
+
+    Regions showing an abrupt change in profile slope are classified as
+    artifacts.
+
+    Parameters
+    ----------
+    image : ndarray
+        2D image to analyze.
+
+    npixels_artifact : int, optional
+        Minimum number of connected pixels required for a region to be
+        considered as an artifact candidate.
+
+    delta_slope_threshold : float, optional
+        Minimum peak value in the profile delta-slope sequence required to
+        classify a candidate as an artifact. Larger values make the detection
+        more conservative.
+
+    segment_slack : int, optional
+        Number of pixels by which each candidate segment is expanded when
+        computing the surrounding radial profile. Also sets the number of
+        profile layers evaluated.
+
+    hi_pass_threshold : float, optional
+        Pixel intensity threshold used to generate the initial binary mask of
+        artifact candidates.
+
+    Returns
+    -------
+    ndarray of bool
+        Segmentation map of all detected artifacts.
+
+    Notes
+    -----
+    Artifact identification relies on the assumption that overexposed features
+    often exhibit sharp transitions in their radial intensity profile, unlike
+    typical astronomical sources whose profiles vary more smoothly.
+    """
+
+    hi_pass_mask = image > hi_pass_threshold
+    artifacts_segmap = detect_sources(hi_pass_mask, 0.5, npixels_artifact, connectivity=8)
+    if artifacts_segmap is None:
+        return artifacts_segmap
+
+    candidate_artifacts_mask = artifacts_segmap.data > 0
+
+    labels_to_remove = []
+    artifacts_cat = SourceCatalog(candidate_artifacts_mask, artifacts_segmap)
+
+    for artifact in artifacts_cat:
+        segment_mask = artifact.segment.astype(bool)
+
+        pad_top = min(segment_slack, artifact.bbox.iymin)
+        pad_bottom = min(segment_slack, image.shape[0] - artifact.bbox.iymax)
+        pad_left = min(segment_slack, artifact.bbox.ixmin)
+        pad_right = min(segment_slack, image.shape[1] - artifact.bbox.ixmax)
+        segment_mask_padded = np.pad(segment_mask, ((pad_top, pad_bottom), (pad_left, pad_right)),
+                                     mode="constant", constant_values=False)
+
+        segment_cutout = image[max(0, artifact.bbox.iymin - segment_slack):min(image.shape[0],
+                                                                               artifact.bbox.iymax + segment_slack),
+                         max(0, artifact.bbox.ixmin - segment_slack):min(image.shape[1],
+                                                                         artifact.bbox.ixmax + segment_slack)]
+
+        mean_profile = get_profile_from_border(segment_cutout, segment_mask_padded, segment_slack)
+
+        if len(mean_profile) < 3:
+            labels_to_remove.append(artifact.label)
+            continue
+        _, profile_delta_slopes = get_profile_gradient(mean_profile)
+        max_delta_slope = np.max(profile_delta_slopes)
+        is_artifact = max_delta_slope >= delta_slope_threshold
+        if not is_artifact:
+            labels_to_remove.append(artifact.label)
+    artifacts_segmap.remove_labels(labels_to_remove)
+
+    return artifacts_segmap
+
+def get_artifact_flag(artifact_mask, main_source_pos = None, relative_size_thresh = 0.005, safe_region_radius = 0.25, show_plots = False):
+    """
+        Determine whether a detected artifact should be considered critical.
+
+        An artifact is flagged when both of the following conditions are met:
+
+        1. At least one artifact pixel lies inside a central circular region
+           of the image.
+        2. The total artifact area exceeds a minimum fraction of the area
+           of that central region.
+
+        The central region is defined as a circle centered on
+        ``main_source_pos``. If no valid source position is provided, the
+        image center is used instead. The circle radius is computed as
+        ``safe_region_radius * min(image_shape)``.
+
+        Parameters
+        ----------
+        artifact_mask : ndarray of bool
+            Boolean mask containing the detected artifact pixels.
+            True values indicate artifact locations.
+
+        main_source_pos : tuple(float, float) or None, optional
+            Pixel coordinates (x, y) of the target source. If None or if
+            the coordinates are not finite, the geometric center of the
+            image is used.
+
+        relative_size_thresh : float, optional
+            Minimum ratio between the total artifact area and the area of
+            the central circular region required to trigger the flag.
+            Default is 0.005.
+
+        safe_region_radius : float, optional
+            Radius of the central circular region expressed as a fraction of
+            the smallest image dimension. Values are clipped to the interval
+            [0, 1]. Default is 0.25.
+
+        show_plots : bool, optional
+            If True and a critical artifact is detected, display a diagnostic
+            plot showing the artifact mask and the central region. Default is
+            False.
+
+        Returns
+        -------
+        bool
+            True if the artifact overlaps the central region and is larger
+            than the specified relative size threshold. False otherwise.
+
+        Notes
+        -----
+        The artifact size is computed using the total number of pixels in
+        ``artifact_mask`` and is not restricted to the portion lying within
+        the central region.
+        """
+    ny, nx = artifact_mask.shape
+    if (main_source_pos is None or not np.all(np.isfinite(main_source_pos))):
+        center = (nx // 2, ny // 2)
+    else:
+        center = main_source_pos
+    safe_reg_prop_radius = np.clip(safe_region_radius, 0, 1)
+    radius = int(round(min((ny, nx)) * safe_reg_prop_radius))
+    # Create a mask for the central circular region
+    y, x = np.ogrid[:ny, :nx]
+    circle_mask = ((x - center[0]) ** 2 + (y - center[1]) ** 2 <= radius ** 2)
+
+    artifact_size = np.sum(artifact_mask)
+    inner_region_size = np.sum(circle_mask)
+    if inner_region_size == 0:
+        return False
+    big_artifact = (artifact_size / inner_region_size >= relative_size_thresh)
+    artifact_inside_region = np.any(artifact_mask & circle_mask)
+    artifact_flag = artifact_inside_region and big_artifact
+
+    if show_plots and artifact_flag:
+        import matplotlib.pyplot as plt
+        plt.imshow(artifact_mask.astype(int) + circle_mask.astype(int), origin = "lower")
+        plt.title("Artifact not-safe region")
+        plt.show()
+
+    return artifact_flag
+

gliders/background_suppressor.py

@@ -0,0 +1,268 @@
+import matplotlib.pyplot as plt
+import numpy as np
+from scipy.stats import norm
+from scipy.signal import convolve2d
+from .utils import sigma_clipping, normalize_data
+from astropy.convolution import Gaussian2DKernel
+
+def suppress_background(image, method ="simple", kernel = None, logit_alpha = 1.0):
+    """
+    Suppress background-dominated pixels in an image using a noise-based
+    probability model.
+
+    The function assumes that image noise follows an approximately normal
+    distribution. A noise probability map is first computed from the image
+    intensity distribution and then refined using one of several methods.
+    The resulting probability map is applied as a weighting function,
+    enhancing statistically significant structures while attenuating pixels
+    consistent with the background noise.
+
+    Parameters
+    ----------
+    image : ndarray
+        Input image.
+
+    method : {'simple', 'logit', 'layers'}, optional
+        Method used to generate the probability map.
+
+        * ``'simple'``: spatial smoothing of the noise probability map.
+        * ``'logit'``: smoothing in logit space followed by a logistic
+          transformation.
+        * ``'layers'``: iterative probability refinement using an
+          additional intensity-weighted layer.
+
+        Default is ``'simple'``.
+
+    kernel : ndarray, optional
+        Convolution kernel used for local probability aggregation. If
+        ``None``, a ``Gaussian2DKernel(2.0)`` is used.
+
+    logit_alpha : float, optional
+        Scaling factor applied to the logistic transform when
+        ``method='logit'``. Larger values increase the contrast between
+        low- and high-probability regions.
+
+    Returns
+    -------
+    ndarray
+        Background-suppressed image rescaled to approximately match the
+        original image intensity range.
+
+    Notes
+    -----
+    For better performance it is recommended that the image background
+    is already flattened (background subtraction).
+
+    See Also
+    --------
+    get_p_simple
+    get_p_logit
+    get_p_layers
+    apply_p_map
+    """
+
+    if kernel is None:
+        kernel = Gaussian2DKernel(2.0) # Larger kernels yield higher noise level, but more symmetric noise distribution
+
+    image_noise_lvl, image_noise_std = sigma_clipping(image, robust=False)
+
+    # Probability of obtaining x or lower:
+    noise_p_map = norm.cdf(image, loc=image_noise_lvl, scale=image_noise_std)  # sf = 1 - cdf = survival function
+
+    if method == "logit":
+        p_map = _get_p_logit(noise_p_map, kernel, alpha = logit_alpha)
+    elif method == "layers":
+        p_map = _get_p_layers(image, noise_p_map, kernel)
+    else: #simple
+        p_map = _get_p_simple(noise_p_map, kernel)
+
+    bkg_reduced_image_leveled = _apply_p_map(image, p_map)
+
+    return bkg_reduced_image_leveled
+
+def _get_p_simple(p_map, kernel):
+    """
+    Convolve probability map (p_map) with the input kernel.
+    """
+
+    p_out = convolve2d(p_map, kernel, mode='same', boundary='symm')
+    return p_out
+
+def _get_p_logit(p_map, kernel, alpha = 1.0):
+    """
+    Transform probability map (p_map) into logits, convolve with the supplied
+    kernel, and transform back into a probability map.
+
+    alpha is the scaling factor applied to the aggregated logits before converting
+    back to probabilities. Values greater than one amplify local contrast,
+    while values less than one reduce it.
+
+    Notes
+    -----
+    Pixels with probability equal to one are clipped slightly below one
+    before the logit transformation to avoid numerical singularities.
+    """
+
+    p_map[p_map >= 1] = 1-1e-9
+    logit = np.log(p_map / (1 - p_map))
+    L = convolve2d(logit, kernel, mode='same', boundary='symm')  # weighted sum of logit
+    p_out = 1.0 / (1.0 + np.exp(-alpha * L))
+    return p_out
+
+def _get_p_layers(image, p_map, kernel):
+    """
+    Generate a probability map using a two-layer probability refinement
+    scheme.
+
+    An initial probability map (p_map) is first convolved with the provided kernel.
+    The image is then weighted by this smoothed map, and a second probability map is
+    estimated from the resulting intensity distribution. The final output
+    is obtained by combining the two probability layers.
+    """
+
+    p_map_cnv = convolve2d(p_map, kernel, mode='same', boundary='symm')
+    image_p_map_cnv = image * p_map_cnv
+    image_p_map_cnv_noise = sigma_clipping(image_p_map_cnv, robust=False)
+    p_map_new_layer = norm.cdf(image_p_map_cnv, loc=image_p_map_cnv_noise[0], scale=image_p_map_cnv_noise[1])
+    p_map_new_layer_cnv = convolve2d(p_map_new_layer, kernel, mode='same', boundary='symm')
+    p_out = p_map_cnv * p_map_new_layer_cnv
+    return p_out
+
+def _apply_p_map(image, p_map):
+    """
+    Apply a probability map (p_map) to an image and rescale according to their maxima.
+    """
+
+    image_p_map = image * p_map
+    image_p_map_leveled = image_p_map * image.max() / image_p_map.max()
+    return image_p_map_leveled
+
+def show_all_methods(image, kernel = None, normalize = True, cmap = "plasma", display_norm = "log", image_bias = 0.001, show_distributions = False):
+    """
+    Visualization of the different background-suppression methods available in the
+    package.
+
+    This utility function computes the probability maps and background-reduced
+    images obtained with the ``simple``, ``logit``, and ``layers`` methods,
+    and displays the results either as images or as intensity distributions.
+    It is primarily intended for visual inspection, debugging, and parameter
+    tuning.
+
+    Parameters
+    ----------
+    image : ndarray
+        Input image.
+
+    kernel : ndarray, optional
+        Convolution kernel used to smooth the probability maps. If ``None``,
+        a ``Gaussian2DKernel(2.0)`` is used.
+
+    normalize : bool, optional
+        If ``True``, all displayed images are normalized using
+        ``normalize_data`` before visualization. Default is ``True``.
+
+    cmap : str, optional
+        Matplotlib colormap used for image display. Default is ``"plasma"``.
+
+    display_norm : str, optional
+        Normalization used for image visualization and histogram scaling.
+        Typical values are ``"log"`` and ``"linear"``. Default is ``"log"``.
+
+    image_bias : float, optional
+        Small positive value added to displayed images to avoid issues with
+        logarithmic visualization and zero-valued pixels. Default is
+        ``0.001``.
+
+    show_distributions : bool, optional
+        If ``True``, display intensity histograms of the original and
+        processed images instead of image panels. Default is ``False``.
+
+    Returns
+    -------
+    None
+        The function generates matplotlib figures but does not return any
+        value.
+
+    See Also
+    --------
+    suppress_background
+    get_p_simple
+    get_p_logit
+    get_p_layers
+    apply_p_map
+    normalize_data
+    sigma_clipping
+    """
+
+    if kernel is None:
+        kernel = Gaussian2DKernel(2.0)
+    image_noise_lvl, image_noise_std = sigma_clipping(image, robust=False)
+    p_map = norm.cdf(image, loc=image_noise_lvl, scale=image_noise_std)  # sf = 1 - cdf = survival function
+
+    p_simple = _get_p_simple(p_map, kernel)
+    p_logit = _get_p_logit(p_map, kernel)
+    p_layers = _get_p_layers(image, p_map, kernel)
+
+    bkg_reduced_image_simple = _apply_p_map(image, p_simple)
+    bkg_reduced_image_logit = _apply_p_map(image, p_logit)
+    bkg_reduced_image_layers = _apply_p_map(image, p_layers)
+
+    images = {
+        'im_original': image,
+        'im_simple': bkg_reduced_image_simple,
+        'im_logit': bkg_reduced_image_logit,
+        'im_layers': bkg_reduced_image_layers,
+    }
+
+    if normalize:
+        for key in images:
+            images[key] = normalize_data(images[key]) + image_bias
+
+    if show_distributions:
+
+        image_hist = images['im_original'].flatten()
+        bins = np.logspace(np.log10(np.min(image_hist[image_hist>0])),np.log10(np.max(image_hist)),100)
+        for key in images:
+            log_y = False
+            if display_norm == "log":
+                log_y = True
+            plt.hist(images[key].flatten(), bins = bins, alpha = 0.8, log = log_y, histtype='step', label = key, linewidth = 3, density = False)
+        plt.xscale(display_norm)
+        plt.legend()
+        plt.show()
+
+    else:
+
+        if not normalize:
+            for key in images:
+                images[key] += image_bias
+
+        figs, ax = plt.subplots(2, 4, layout="tight")
+
+        ax[1, 0].imshow(p_map, origin="lower")
+        ax[1, 0].set_title("raw p_map")
+        ax[0, 0].imshow(images["im_original"], origin="lower", norm=display_norm, cmap=cmap)
+        ax[0, 0].set_title("original")
+
+        ax[1, 1].imshow(p_simple, origin="lower")
+        ax[1, 1].set_title("simple")
+        ax[0, 1].imshow(images["im_simple"], origin="lower", norm=display_norm, cmap=cmap)
+        ax[0, 1].set_title("simple")
+
+        ax[1, 2].imshow(p_logit, origin="lower")
+        ax[1, 2].set_title("logit")
+        ax[0, 2].imshow(images["im_logit"], origin="lower", norm=display_norm, cmap=cmap)
+        ax[0, 2].set_title("logit")
+
+        ax[1, 3].imshow(p_layers, origin="lower")
+        ax[1, 3].set_title("layers")
+        ax[0, 3].imshow(images["im_layers"], origin="lower", norm=display_norm, cmap=cmap)
+        ax[0, 3].set_title("layers")
+
+        plt.show()
+
+
+if __name__ == "__main__":
+    quit()
+
+