celldetective 1.4.2__py3-none-any.whl → 1.5.0b1__py3-none-any.whl

celldetective/utils/mask_cleaning.py

@@ -0,0 +1,348 @@
+import concurrent.futures
+import threading
+
+import numpy as np
+import pandas as pd
+from skimage.measure import regionprops_table, label
+from skimage.transform import resize
+from tqdm import tqdm
+
+from celldetective.utils.image_loaders import load_frames
+from scipy.ndimage import binary_fill_holes
+from scipy.ndimage import find_objects
+
+
+def fill_label_holes(lbl_img, **kwargs):
+    """Fill small holes in label image.
+    from https://github.com/stardist/stardist/blob/main/stardist/utils.py
+    """
+
+    # TODO: refactor 'fill_label_holes' and 'edt_prob' to share code
+    def grow(sl, interior):
+        return tuple(
+            slice(s.start - int(w[0]), s.stop + int(w[1])) for s, w in zip(sl, interior)
+        )
+
+    def shrink(interior):
+        return tuple(slice(int(w[0]), (-1 if w[1] else None)) for w in interior)
+
+    objects = find_objects(lbl_img)
+    lbl_img_filled = np.zeros_like(lbl_img)
+    for i, sl in enumerate(objects, 1):
+        if sl is None:
+            continue
+        interior = [(s.start > 0, s.stop < sz) for s, sz in zip(sl, lbl_img.shape)]
+        shrink_slice = shrink(interior)
+        grown_mask = lbl_img[grow(sl, interior)] == i
+        mask_filled = binary_fill_holes(grown_mask, **kwargs)[shrink_slice]
+        lbl_img_filled[sl][mask_filled] = i
+    if lbl_img.min() < 0:
+        # preserve (and fill holes in) negative labels ('find_objects' ignores these)
+        lbl_neg_filled = -fill_label_holes(-np.minimum(lbl_img, 0))
+        mask = lbl_neg_filled < 0
+        lbl_img_filled[mask] = lbl_neg_filled[mask]
+    return lbl_img_filled
+
+
+def _check_label_dims(lbl, file=None, template=None):
+
+    if file is not None:
+        template = load_frames(0, file, scale=1, normalize_input=False)
+    elif template is not None:
+        template = template
+    else:
+        return lbl
+
+    if lbl.shape != template.shape[:2]:
+        lbl = resize(lbl, template.shape[:2], order=0)
+    return lbl
+
+
+def auto_correct_masks(
+    masks, bbox_factor: float = 1.75, min_area: int = 9, fill_labels: bool = False
+):
+    """
+    Correct segmentation masks to ensure consistency and remove anomalies.
+
+    This function processes a labeled mask image to correct anomalies and reassign labels.
+    It performs the following operations:
+
+    1. Corrects negative mask values by taking their absolute values.
+    2. Identifies and corrects segmented objects with a bounding box area that is disproportionately
+       larger than the actual object area. This indicates potential segmentation errors where separate objects
+       share the same label.
+    3. Removes small objects that are considered noise (default threshold is an area of less than 9 pixels).
+    4. Reorders the labels so they are consecutive from 1 up to the number of remaining objects (to avoid encoding errors).
+
+    Parameters
+    ----------
+    masks : np.ndarray
+            A 2D array representing the segmented mask image with labeled regions. Each unique value
+            in the array represents a different object or cell.
+    bbox_factor : float, optional
+            A factor on cell area that is compared directly to the bounding box area of the cell, to detect remote cells
+            sharing a same label value. The default is `1.75`.
+    min_area : int, optional
+            Discard cells that have an area smaller than this minimum area (px²). The default is `9` (3x3 pixels).
+    fill_labels : bool, optional
+            Fill holes within cell masks automatically. The default is `False`.
+
+    Returns
+    -------
+    clean_labels : np.ndarray
+            A corrected version of the input mask, with anomalies corrected, small objects removed,
+            and labels reordered to be consecutive integers.
+
+    Notes
+    -----
+    - This function is useful for post-processing segmentation outputs to ensure high-quality
+      object detection, particularly in applications such as cell segmentation in microscopy images.
+    - The function assumes that the input masks contain integer labels and that the background
+      is represented by 0.
+
+    Examples
+    --------
+    >>> masks = np.array([[0, 0, 1, 1], [0, 2, 2, 1], [0, 2, 0, 0]])
+    >>> corrected_masks = auto_correct_masks(masks)
+    >>> corrected_masks
+    array([[0, 0, 1, 1],
+               [0, 2, 2, 1],
+               [0, 2, 0, 0]])
+    """
+
+    assert masks.ndim == 2, "`masks` should be a 2D numpy array..."
+
+    # Avoid negative mask values
+    masks[masks < 0] = np.abs(masks[masks < 0])
+
+    props = pd.DataFrame(
+        regionprops_table(masks, properties=("label", "area", "area_bbox"))
+    )
+    max_lbl = props["label"].max()
+    corrected_lbl = masks.copy()  # .astype(int)
+
+    for cell in props["label"].unique():
+
+        bbox_area = props.loc[props["label"] == cell, "area_bbox"].values
+        area = props.loc[props["label"] == cell, "area"].values
+
+        if bbox_area > bbox_factor * area:  # condition for anomaly
+
+            lbl = masks == cell
+            lbl = lbl.astype(int)
+
+            relabelled = label(lbl, connectivity=2)
+            relabelled += max_lbl
+            relabelled[np.where(lbl == 0)] = 0
+
+            corrected_lbl[np.where(relabelled != 0)] = relabelled[
+                np.where(relabelled != 0)
+            ]
+
+        max_lbl = np.amax(corrected_lbl)
+
+    # Second routine to eliminate objects too small
+    props2 = pd.DataFrame(
+        regionprops_table(corrected_lbl, properties=("label", "area", "area_bbox"))
+    )
+    for cell in props2["label"].unique():
+        area = props2.loc[props2["label"] == cell, "area"].values
+        lbl = corrected_lbl == cell
+        if area < min_area:
+            corrected_lbl[lbl] = 0
+
+    # Additionnal routine to reorder labels from 1 to number of cells
+    label_ids = np.unique(corrected_lbl)[1:]
+    clean_labels = corrected_lbl.copy()
+
+    for k, lbl in enumerate(label_ids):
+        clean_labels[corrected_lbl == lbl] = k + 1
+
+    clean_labels = clean_labels.astype(int)
+
+    if fill_labels:
+        clean_labels = fill_label_holes(clean_labels)
+
+    return clean_labels
+
+
+def relabel_segmentation(
+    labels,
+    df,
+    exclude_nans=True,
+    column_labels={
+        "track": "TRACK_ID",
+        "frame": "FRAME",
+        "y": "POSITION_Y",
+        "x": "POSITION_X",
+        "label": "class_id",
+    },
+    threads=1,
+    progress_callback=None,
+):
+    """
+    Relabel the segmentation labels with the tracking IDs from the tracks.
+
+    The function reassigns the mask value for each cell with the associated `TRACK_ID`, if it exists
+    in the trajectory table (`df`). If no track uses the cell mask, a new track with a single point
+    is generated on the fly (max of `TRACK_ID` values + i, for i=0 to N such cells). It supports
+    multithreaded processing for faster execution on large datasets.
+
+    Parameters
+    ----------
+    labels : np.ndarray
+            A (TYX) array where each frame contains a 2D segmentation mask. Each unique
+            non-zero integer represents a labeled object.
+    df : pandas.DataFrame
+            A DataFrame containing tracking information with columns
+            specified in `column_labels`. Must include at least frame, track ID, and object ID.
+    exclude_nans : bool, optional
+            Whether to exclude rows in `df` with NaN values in the column specified by
+            `column_labels['label']`. Default is `True`.
+    column_labels : dict, optional
+            A dictionary specifying the column names in `df`. Default is:
+            - `'track'`: Track ID column name (`"TRACK_ID"`)
+            - `'frame'`: Frame column name (`"FRAME"`)
+            - `'y'`: Y-coordinate column name (`"POSITION_Y"`)
+            - `'x'`: X-coordinate column name (`"POSITION_X"`)
+            - `'label'`: Object ID column name (`"class_id"`)
+    threads : int, optional
+            Number of threads to use for multithreaded processing. Default is `1`.
+
+    Returns
+    -------
+    np.ndarray
+            A new (TYX) array with the same shape as `labels`, where objects are relabeled
+            according to their tracking identity in `df`.
+
+    Notes
+    -----
+    - For frames where labeled objects in `labels` do not match any entries in the `df`,
+      new track IDs are generated for the unmatched labels.
+    - The relabeling process maintains synchronization across threads using a shared
+      counter for generating unique track IDs.
+
+    Examples
+    --------
+    Relabel segmentation using tracking data:
+
+    >>> labels = np.random.randint(0, 5, (10, 100, 100))
+    >>> df = pd.DataFrame({
+    ...     "TRACK_ID": [1, 2, 1, 2],
+    ...     "FRAME": [0, 0, 1, 1],
+    ...     "class_id": [1, 2, 1, 2],
+    ... })
+    >>> new_labels = relabel_segmentation(labels, df, threads=2)
+    Done.
+
+    Use custom column labels and exclude rows with NaNs:
+
+    >>> column_labels = {
+    ...     'track': "track_id",
+    ...     'frame': "time",
+    ...     'label': "object_id"
+    ... }
+    >>> new_labels = relabel_segmentation(labels, df, column_labels=column_labels, exclude_nans=True)
+    Done.
+
+    """
+
+    n_threads = threads
+    df = df.sort_values(by=[column_labels["track"], column_labels["frame"]])
+    if exclude_nans:
+        df = df.dropna(subset=column_labels["label"])
+
+    new_labels = np.zeros_like(labels)
+    shared_data = {"s": 0}
+
+    # Progress tracking
+    shared_progress = {"val": 0, "lock": threading.Lock()}
+    total_frames = len(df[column_labels["frame"]].dropna().unique())
+
+    def rewrite_labels(indices):
+
+        all_track_ids = df[column_labels["track"]].dropna().unique()
+
+        # Check for cancellation
+        if progress_callback:
+            with shared_progress["lock"]:
+                if shared_progress.get("cancelled", False):
+                    return
+
+        disable_tqdm = progress_callback is not None
+
+        for t in tqdm(indices, disable=disable_tqdm):
+
+            # Cancellation check inside loop
+            if progress_callback:
+                with shared_progress["lock"]:
+                    if shared_progress.get("cancelled", False):
+                        return
+
+                    shared_progress["val"] += 1
+                    p = int((shared_progress["val"] / total_frames) * 100)
+
+                if not progress_callback(p):
+                    with shared_progress["lock"]:
+                        shared_progress["cancelled"] = True
+                    return
+
+            f = int(t)
+            cells = df.loc[
+                df[column_labels["frame"]] == f,
+                [column_labels["track"], column_labels["label"]],
+            ].to_numpy()
+            tracks_at_t = list(cells[:, 0])
+            identities = list(cells[:, 1])
+
+            labels_at_t = list(np.unique(labels[f]))
+            if 0 in labels_at_t:
+                labels_at_t.remove(0)
+            labels_not_in_df = [lbl for lbl in labels_at_t if lbl not in identities]
+            for lbl in labels_not_in_df:
+                with threading.Lock():  # Synchronize access to `shared_data["s"]`
+                    track_id = max(all_track_ids) + shared_data["s"]
+                    shared_data["s"] += 1
+                tracks_at_t.append(track_id)
+                identities.append(lbl)
+
+            # exclude NaN
+            tracks_at_t = np.array(tracks_at_t)
+            identities = np.array(identities)
+
+            tracks_at_t = tracks_at_t[identities == identities]
+            identities = identities[identities == identities]
+
+            for k in range(len(identities)):
+
+                # need routine to check values from labels not in class_id of this frame and add new track id
+
+                loc_i, loc_j = np.where(labels[f] == identities[k])
+                track_id = tracks_at_t[k]
+
+                if track_id == track_id:
+                    new_labels[f, loc_i, loc_j] = round(track_id)
+
+    # Multithreading
+    indices = list(df[column_labels["frame"]].dropna().unique())
+    chunks = np.array_split(indices, n_threads)
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=threads) as executor:
+
+        results = executor.map(
+            rewrite_labels, chunks
+        )  # list(map(lambda x: executor.submit(self.parallel_job, x), chunks))
+        try:
+            for i, return_value in enumerate(results):
+                # print(f"Thread {i} output check: ", return_value)
+                pass
+        except Exception as e:
+            print("Exception: ", e)
+
+    if shared_progress.get("cancelled", False):
+        print("Relabeling cancelled.")
+        return None
+
+    print("\nDone.")
+
+    return new_labels

celldetective/utils/mask_transforms.py

@@ -0,0 +1,5 @@
+from scipy.ndimage import zoom
+
+
+def _rescale_labels(lbl, scale_model=1):
+    return zoom(lbl, [1.0 / scale_model, 1.0 / scale_model], order=0)

celldetective/utils/masks.py

@@ -0,0 +1,184 @@
+from typing import Union, List, Tuple
+
+import numpy as np
+from scipy import ndimage
+from scipy.ndimage.morphology import distance_transform_edt
+from skimage.morphology import disk
+from celldetective.log_manager import get_logger
+
+logger = get_logger(__name__)
+
+
+def contour_of_instance_segmentation(label, distance, sdf=None, voronoi_map=None):
+    """
+
+    Generate an instance mask containing the contour of the segmented objects.
+
+    This updated version uses a Signed Distance Field (SDF) and Voronoi tessellation approach
+    Generic enough to handle Inner contours, Outer contours, and arbitrary "stripes" (annuli).
+
+    Parameters
+    ----------
+    label : ndarray
+            The instance segmentation labels.
+    distance : int, float, list, tuple, or str
+            The distance specification.
+            - Scalar > 0: Inner contour (Erosion) from boundary to 'distance' pixels inside. Range [0, distance].
+            - Scalar < 0: Outer contour (Dilation) from 'distance' pixels outside to boundary. Range [distance, 0].
+            - Tuple/List (a, b): Explicit range in SDF space.
+               - Positive values are inside the object.
+               - Negative values are outside methods.
+               - Example: (5, 10) -> Inner ring 5 to 10px deep.
+               - Example: (-10, -5) -> Outer ring 5 to 10px away.
+            - String "rad1-rad2": Interpretation for Batch Measurements (Outer Rings).
+               - Interpreted as an annular region OUTSIDE the object.
+               - "5-10" -> Range [-10, -5] in SDF space (5 to 10px away).
+    sdf : ndarray, optional
+            Pre-computed Signed Distance Field (dist_in - dist_out).
+            If provided, avoids recomputing EDT.
+    voronoi_map : ndarray, optional
+            Pre-computed Voronoi map of instance labels.
+            Required if sdf is provided and outer contours are needed.
+
+    Returns
+    -------
+    border_label : ndarray
+            An instance mask containing the contour of the segmented objects.
+            Outer contours preserve instance identity via Voronoi propagation.
+
+    """
+    from scipy.ndimage import distance_transform_edt
+
+    # helper to parse string "rad1-rad2"
+    if isinstance(distance, str):
+        try:
+            # Check for stringified tuple "(a, b)"
+            distance = distance.strip()
+            if distance.startswith("(") and distance.endswith(")"):
+                import ast
+
+                val_tuple = ast.literal_eval(distance)
+                if isinstance(val_tuple, (list, tuple)) and len(val_tuple) == 2:
+                    min_r = val_tuple[0]
+                    max_r = val_tuple[1]
+                else:
+                    raise ValueError("Tuple string must have 2 elements")
+            else:
+                try:
+                    val = float(distance)
+                    # It's a scalar string like "5" or "-5"
+                    if val >= 0:
+                        min_r = 0
+                        max_r = val
+                    else:
+                        min_r = val
+                        max_r = 0
+                except ValueError:
+                    # It's a range string "5-10"
+                    parts = distance.split("-")
+                    # Assumption: "A-B" where A, B positive radii for OUTER annulus.
+                    r1 = float(parts[0])
+                    r2 = float(parts[1])
+                    min_r = -max(r1, r2)
+                    max_r = -min(r1, r2)
+
+        except Exception:
+            logger.warning(
+                f"Could not parse contour string '{distance}'. returning empty."
+            )
+            return np.zeros_like(label)
+
+    elif isinstance(distance, (list, tuple)):
+        min_r = distance[0]
+        max_r = distance[1]
+
+    elif isinstance(distance, (int, float)):
+        if distance >= 0:
+            min_r = 0
+            max_r = distance
+        else:
+            min_r = distance
+            max_r = 0
+    else:
+        return np.zeros_like(label)
+
+    if sdf is None or voronoi_map is None:
+        # Compute SDF maps
+        # We need SDF = dist_in - dist_out
+        # inside > 0, outside < 0
+
+        # 1. Dist In (Inside object)
+        dist_in = distance_transform_edt(label > 0)
+
+        # 2. Dist Out (Outside object) + Voronoi
+        dist_out, indices = distance_transform_edt(label == 0, return_indices=True)
+
+        # Voronoi Map
+        voronoi_map = label[indices[0], indices[1]]
+
+        # Composite SDF
+        sdf = dist_in - dist_out
+
+    # Create Mask
+    mask = (sdf >= min_r) & (sdf <= max_r)
+
+    # Result
+    border_label = voronoi_map * mask
+
+    return border_label
+
+
+def create_patch_mask(h, w, center=None, radius=None):
+    """
+
+    Create a circular patch mask of given dimensions.
+    Adapted from alkasm on https://stackoverflow.com/questions/44865023/how-can-i-create-a-circular-mask-for-a-numpy-array
+
+    Parameters
+    ----------
+    h : int
+            Height of the mask. Prefer odd value.
+    w : int
+            Width of the mask. Prefer odd value.
+    center : tuple, optional
+            Coordinates of the center of the patch. If not provided, the middle of the image is used.
+    radius : int or float or list, optional
+            Radius of the circular patch. If not provided, the smallest distance between the center and image walls is used.
+            If a list is provided, it should contain two elements representing the inner and outer radii of a circular annular patch.
+
+    Returns
+    -------
+    numpy.ndarray
+            Boolean mask where True values represent pixels within the circular patch or annular patch, and False values represent pixels outside.
+
+    Notes
+    -----
+    The function creates a circular patch mask of the given dimensions by determining which pixels fall within the circular patch or annular patch.
+    The circular patch or annular patch is centered at the specified coordinates or at the middle of the image if coordinates are not provided.
+    The radius of the circular patch or annular patch is determined by the provided radius parameter or by the minimum distance between the center and image walls.
+    If an annular patch is desired, the radius parameter should be a list containing the inner and outer radii respectively.
+
+    Examples
+    --------
+    >>> mask = create_patch_mask(100, 100, center=(50, 50), radius=30)
+    >>> print(mask)
+
+    """
+
+    if center is None:  # use the middle of the image
+        center = (int(w / 2), int(h / 2))
+    if radius is None:  # use the smallest distance between the center and image walls
+        radius = min(center[0], center[1], w - center[0], h - center[1])
+
+    Y, X = np.ogrid[:h, :w]
+    dist_from_center = np.sqrt((X - center[0]) ** 2 + (Y - center[1]) ** 2)
+
+    if isinstance(radius, int) or isinstance(radius, float):
+        mask = dist_from_center <= radius
+    elif isinstance(radius, list):
+        mask = (dist_from_center <= radius[1]) * (dist_from_center >= radius[0])
+    else:
+        print("Please provide a proper format for the radius")
+        return None
+
+    return mask