napari-tmidas 0.2.2__py3-none-any.whl → 0.2.5__py3-none-any.whl

napari_tmidas/processing_functions/skimage_filters.py

@@ -16,59 +16,255 @@ except ImportError:
         "scikit-image not available, some processing functions will be disabled"
     )
 
-import contextlib
-import os
 
-import pandas as pd
+# Lazy imports for optional heavy dependencies
+try:
+    import pandas as pd
+
+    _HAS_PANDAS = True
+except ImportError:
+    pd = None
+    _HAS_PANDAS = False
 
-from napari_tmidas._file_selector import ProcessingWorker
 from napari_tmidas._registry import BatchProcessingRegistry
 
 if SKIMAGE_AVAILABLE:
 
-    # Equalize histogram
+    # CLAHE (Contrast Limited Adaptive Histogram Equalization)
     @BatchProcessingRegistry.register(
-        name="Equalize Histogram",
-        suffix="_equalized",
-        description="Equalize histogram of image",
+        name="CLAHE (Adaptive Histogram Equalization)",
+        suffix="_clahe",
+        description="Apply Contrast Limited Adaptive Histogram Equalization (CLAHE) to enhance local contrast, especially useful for dark images with weak bright features",
+        parameters={
+            "clip_limit": {
+                "type": float,
+                "default": 0.01,
+                "description": "Clipping limit for contrast (0.01 = 1%). Higher values give more contrast but may amplify noise. Range: 0.001-0.1",
+            },
+            "kernel_size": {
+                "type": int,
+                "default": 0,
+                "description": "Size of the local region (0 = auto-calculate based on image size). For small features use smaller values (e.g., 32), for large features use larger values (e.g., 128)",
+            },
+        },
     )
     def equalize_histogram(
-        image: np.ndarray, clip_limit: float = 0.01
+        image: np.ndarray, clip_limit: float = 0.01, kernel_size: int = 0
     ) -> np.ndarray:
         """
-        Equalize histogram of image
+        Apply CLAHE (Contrast Limited Adaptive Histogram Equalization) to enhance local contrast.
+
+        This is much better than standard histogram equalization for dark images with
+        weak bright features like membranes, as it works locally and prevents over-brightening
+        of background regions.
+
+        Parameters
+        ----------
+        image : np.ndarray
+            Input image
+        clip_limit : float
+            Clipping limit for contrast limiting (normalized to 0-1 range, e.g., 0.01 = 1%)
+            Higher values give more contrast but may amplify noise
+        kernel_size : int
+            Size of the contextual regions (0 = auto-calculate based on image size)
+
+        Returns
+        -------
+        np.ndarray
+            CLAHE-enhanced image with same dtype as input
         """
+        # Store original dtype to convert back later
+        original_dtype = image.dtype
+
+        # Auto-calculate kernel size if not specified
+        if kernel_size <= 0:
+            # Use 1/8 of the smaller dimension, but cap between 16 and 128
+            min_dim = min(
+                image.shape[-2:]
+            )  # Last 2 dimensions are spatial (Y, X)
+            kernel_size = max(16, min(128, min_dim // 8))
+
+        # Ensure kernel_size is odd
+        if kernel_size % 2 == 0:
+            kernel_size += 1
+
+        # Apply CLAHE using scikit-image's equalize_adapthist
+        # Note: clip_limit in equalize_adapthist is already normalized (0-1 range)
+        # This returns float64 in range [0, 1]
+        result = skimage.exposure.equalize_adapthist(
+            image, kernel_size=kernel_size, clip_limit=clip_limit
+        )
 
-        return skimage.exposure.equalize_hist(image)
+        # Convert back to original dtype to preserve compatibility
+        if np.issubdtype(original_dtype, np.integer):
+            # For integer types, scale back to original range
+            iinfo = np.iinfo(original_dtype)
+            result = (result * (iinfo.max - iinfo.min) + iinfo.min).astype(
+                original_dtype
+            )
+        else:
+            # For float types, keep as is but match dtype
+            result = result.astype(original_dtype)
+
+        return result
 
     # simple otsu thresholding
     @BatchProcessingRegistry.register(
         name="Otsu Thresholding (semantic)",
         suffix="_otsu_semantic",
-        description="Threshold image using Otsu's method to obtain a binary image",
+        description="Threshold image using Otsu's method to obtain a binary image. Supports dimension_order hint (TYX, ZYX, etc.) to process frame-by-frame or slice-by-slice.",
     )
-    def otsu_thresholding(image: np.ndarray) -> np.ndarray:
-        """
-        Threshold image using Otsu's method
+    def otsu_thresholding(
+        image: np.ndarray, dimension_order: str = "Auto"
+    ) -> np.ndarray:
         """
+        Threshold image using Otsu's method.
 
+        Args:
+            image: Input image (YX, TYX, ZYX, CYX, TCYX, TZYX, etc.)
+            dimension_order: Dimension interpretation hint (Auto, YX, TYX, ZYX, CYX, TCYX, etc.)
+                            If TYX/ZYX/TCYX/TZYX: processes each frame/slice independently
+                            If CYX: processes each channel independently
+                            If YX or Auto: processes as single 2D image
+
+        Returns:
+            Binary image with same shape as input (255=foreground, 0=background)
+        """
         image = skimage.img_as_ubyte(image)  # convert to 8-bit
-        thresh = skimage.filters.threshold_otsu(image)
-        return (image > thresh).astype(np.uint32)
+
+        # Handle different dimension orders
+        if dimension_order in ["TYX", "ZYX", "TCYX", "TZYX", "ZCYX", "TZCYX"]:
+            # Process frame-by-frame or slice-by-slice
+            result = np.zeros_like(image, dtype=np.uint8)
+
+            # Determine which axes to iterate over
+            if len(image.shape) == 3:  # TYX or ZYX
+                for i in range(image.shape[0]):
+                    thresh = skimage.filters.threshold_otsu(image[i])
+                    result[i] = np.where(image[i] > thresh, 255, 0).astype(
+                        np.uint8
+                    )
+            elif len(image.shape) == 4:  # TCYX, TZYX, ZCYX
+                for i in range(image.shape[0]):
+                    for j in range(image.shape[1]):
+                        thresh = skimage.filters.threshold_otsu(image[i, j])
+                        result[i, j] = np.where(
+                            image[i, j] > thresh, 255, 0
+                        ).astype(np.uint8)
+            elif len(image.shape) == 5:  # TZCYX
+                for i in range(image.shape[0]):
+                    for j in range(image.shape[1]):
+                        for k in range(image.shape[2]):
+                            thresh = skimage.filters.threshold_otsu(
+                                image[i, j, k]
+                            )
+                            result[i, j, k] = np.where(
+                                image[i, j, k] > thresh, 255, 0
+                            ).astype(np.uint8)
+            else:
+                # Fallback for unexpected shapes
+                thresh = skimage.filters.threshold_otsu(image)
+                result = np.where(image > thresh, 255, 0).astype(np.uint8)
+
+            return result
+        elif dimension_order == "CYX":
+            # Process each channel independently
+            if len(image.shape) >= 3:
+                result = np.zeros_like(image, dtype=np.uint8)
+                for i in range(image.shape[0]):
+                    thresh = skimage.filters.threshold_otsu(image[i])
+                    result[i] = np.where(image[i] > thresh, 255, 0).astype(
+                        np.uint8
+                    )
+                return result
+            else:
+                # Fallback if not actually multi-channel
+                thresh = skimage.filters.threshold_otsu(image)
+                return np.where(image > thresh, 255, 0).astype(np.uint8)
+        else:
+            # YX or Auto: process as single image
+            thresh = skimage.filters.threshold_otsu(image)
+            return np.where(image > thresh, 255, 0).astype(np.uint8)
 
     # instance segmentation
     @BatchProcessingRegistry.register(
         name="Otsu Thresholding (instance)",
         suffix="_otsu_labels",
-        description="Threshold image using Otsu's method to obtain a multi-label image",
+        description="Threshold image using Otsu's method to obtain a multi-label image. Supports dimension_order hint (TYX, ZYX, etc.) to process frame-by-frame or slice-by-slice.",
     )
-    def otsu_thresholding_instance(image: np.ndarray) -> np.ndarray:
+    def otsu_thresholding_instance(
+        image: np.ndarray, dimension_order: str = "Auto"
+    ) -> np.ndarray:
         """
-        Threshold image using Otsu's method
+        Threshold image using Otsu's method to create instance labels.
+
+        Args:
+            image: Input image (YX, TYX, ZYX, CYX, TCYX, TZYX, etc.)
+            dimension_order: Dimension interpretation hint (Auto, YX, TYX, ZYX, CYX, TCYX, etc.)
+                            If TYX/ZYX/TCYX/TZYX: processes each frame/slice independently
+                            If CYX: processes each channel independently
+                            If YX or Auto: processes as single 2D image
+
+        Returns:
+            Label image with same shape as input (0=background, 1,2,3...=objects)
         """
         image = skimage.img_as_ubyte(image)  # convert to 8-bit
-        thresh = skimage.filters.threshold_otsu(image)
-        return skimage.measure.label(image > thresh).astype(np.uint32)
+
+        # Handle different dimension orders
+        if dimension_order in ["TYX", "ZYX", "TCYX", "TZYX", "ZCYX", "TZCYX"]:
+            # Process frame-by-frame or slice-by-slice
+            result = np.zeros_like(image, dtype=np.uint32)
+
+            # Determine which axes to iterate over
+            if len(image.shape) == 3:  # TYX or ZYX
+                for i in range(image.shape[0]):
+                    thresh = skimage.filters.threshold_otsu(image[i])
+                    result[i] = skimage.measure.label(
+                        image[i] > thresh
+                    ).astype(np.uint32)
+            elif len(image.shape) == 4:  # TCYX, TZYX, ZCYX
+                for i in range(image.shape[0]):
+                    for j in range(image.shape[1]):
+                        thresh = skimage.filters.threshold_otsu(image[i, j])
+                        result[i, j] = skimage.measure.label(
+                            image[i, j] > thresh
+                        ).astype(np.uint32)
+            elif len(image.shape) == 5:  # TZCYX
+                for i in range(image.shape[0]):
+                    for j in range(image.shape[1]):
+                        for k in range(image.shape[2]):
+                            thresh = skimage.filters.threshold_otsu(
+                                image[i, j, k]
+                            )
+                            result[i, j, k] = skimage.measure.label(
+                                image[i, j, k] > thresh
+                            ).astype(np.uint32)
+            else:
+                # Fallback for unexpected shapes
+                thresh = skimage.filters.threshold_otsu(image)
+                result = skimage.measure.label(image > thresh).astype(
+                    np.uint32
+                )
+
+            return result
+        elif dimension_order == "CYX":
+            # Process each channel independently
+            if len(image.shape) >= 3:
+                result = np.zeros_like(image, dtype=np.uint32)
+                for i in range(image.shape[0]):
+                    thresh = skimage.filters.threshold_otsu(image[i])
+                    result[i] = skimage.measure.label(
+                        image[i] > thresh
+                    ).astype(np.uint32)
+                return result
+            else:
+                # Fallback if not actually multi-channel
+                thresh = skimage.filters.threshold_otsu(image)
+                return skimage.measure.label(image > thresh).astype(np.uint32)
+        else:
+            # YX or Auto: process as single image
+            thresh = skimage.filters.threshold_otsu(image)
+            return skimage.measure.label(image > thresh).astype(np.uint32)
 
     # simple thresholding
     @BatchProcessingRegistry.register(
@@ -93,7 +289,9 @@ if SKIMAGE_AVAILABLE:
         """
         # convert to 8-bit
         image = skimage.img_as_ubyte(image)
-        return image > threshold
+        # Return 255 for values above threshold, 0 for values below
+        # This ensures the binary image is visible when viewed as a regular image
+        return np.where(image > threshold, 255, 0).astype(np.uint8)
 
     # remove small objects
     @BatchProcessingRegistry.register(
@@ -212,199 +410,26 @@ if SKIMAGE_AVAILABLE:
 
         return result.astype(np.uint32)
 
-    @BatchProcessingRegistry.register(
-        name="Extract Region Properties",
-        suffix="_props",  # Changed to indicate this is for CSV output only
-        description="Extract properties of labeled regions and save as CSV (no image output)",
-        parameters={
-            "properties": {
-                "type": str,
-                "default": "area,bbox,centroid,eccentricity,euler_number,perimeter",
-                "description": "Comma-separated list of properties to extract (e.g., area,perimeter,centroid)",
-            },
-            "intensity_image": {
-                "type": bool,
-                "default": False,
-                "description": "Use input as intensity image for intensity-based measurements",
-            },
-            "min_area": {
-                "type": int,
-                "default": 0,
-                "min": 0,
-                "max": 100000,
-                "description": "Minimum area to include in results (pixels)",
-            },
-        },
-    )
-    def extract_region_properties(
-        image: np.ndarray,
-        properties: str = "area,bbox,centroid,eccentricity,euler_number,perimeter",
-        intensity_image: bool = False,
-        min_area: int = 0,
-    ) -> np.ndarray:
-        """
-        Extract properties of labeled regions in an image and save results as CSV.
-
-        This function analyzes all labeled regions in a label image and computes
-        various region properties like area, perimeter, centroid, etc. The results
-        are saved as a CSV file. The input image is returned unchanged.
-
-        Parameters:
-        -----------
-        image : numpy.ndarray
-            Input label image (instance segmentation)
-        properties : str
-            Comma-separated list of properties to extract
-            See scikit-image documentation for all available properties:
-            https://scikit-image.org/docs/stable/api/skimage.measure.html#skimage.measure.regionprops
-        intensity_image : bool
-            Whether to use the input image as intensity image for intensity-based measurements
-        min_area : int
-            Minimum area (in pixels) for regions to include in results
-
-        Returns:
-        --------
-        numpy.ndarray
-            The original image (unchanged)
-        """
-        # Check if we have a proper label image
-        if image.ndim < 2 or np.max(image) == 0:
-            print(
-                "Input must be a valid label image with at least one labeled region"
-            )
-            return image
-
-        # Convert image to proper format for regionprops
-        label_image = image.astype(np.int32)
-
-        # Parse the properties list
-        prop_list = [prop.strip() for prop in properties.split(",")]
-
-        # Get region properties
-        if intensity_image:
-            # Use the same image as both label and intensity image # this is wrong
-            regions = skimage.measure.regionprops(
-                label_image, intensity_image=image
-            )
-        else:
-            regions = skimage.measure.regionprops(label_image)
-
-        # Collect property data
-        data = []
-        for region in regions:
-            # Skip regions that are too small
-            if region.area < min_area:
-                continue
-
-            # Get all requested properties
-            region_data = {"label": region.label}
-            for prop in prop_list:
-                try:
-                    value = getattr(region, prop)
-
-                    # Handle different types of properties
-                    if isinstance(value, tuple) or (
-                        isinstance(value, np.ndarray) and value.ndim > 0
-                    ):
-                        # For tuple/array properties like centroid, bbox, etc.
-                        if isinstance(value, tuple):
-                            value = np.array(value)
-
-                        # For each element in the tuple/array
-                        for i, val in enumerate(value):
-                            region_data[f"{prop}_{i}"] = val
-                    else:
-                        # For scalar properties like area, perimeter, etc.
-                        region_data[prop] = value
-                except AttributeError:
-                    print(f"Property '{prop}' not found, skipping")
-                    continue
-
-            data.append(region_data)
-
-        # Create a DataFrame
-        df = pd.DataFrame(data)
+    # Note: Old "Extract Region Properties" function removed
+    # Use "Extract Regionprops to CSV" from regionprops_analysis.py instead
+    # which properly handles multi-dimensional data (T, C, Z dimensions)
+    # and creates a single CSV for all images in a folder
 
-        # Store the DataFrame as an attribute of the function
-        extract_region_properties.csv_data = df
-        extract_region_properties.save_csv = True
-        extract_region_properties.no_image_output = (
-            True  # Indicate no image output needed
+else:
+    # Export stub functions that raise ImportError when called
+    def invert_image(*args, **kwargs):
+        raise ImportError(
+            "scikit-image is not available. Please install scikit-image to use this function."
         )
 
-        print(f"Extracted properties for {len(data)} regions")
-        return image
-
-    # Monkey patch to handle saving CSV files without creating a new image file
-    try:
-        # Check if ProcessingWorker is imported and available
-        original_process_file = ProcessingWorker.process_file
-
-        # Create a new version that handles saving CSV
-        def process_file_with_csv_export(self, filepath):
-            """Modified process_file function that saves CSV after processing."""
-            result = original_process_file(self, filepath)
-
-            # Check if there's a result and if we should save CSV
-            if isinstance(result, dict) and "processed_file" in result:
-                output_path = result["processed_file"]
-
-                # Check if the processing function had CSV data
-                if (
-                    hasattr(self.processing_func, "save_csv")
-                    and self.processing_func.save_csv
-                    and hasattr(self.processing_func, "csv_data")
-                ):
-
-                    # Get the CSV data
-                    df = self.processing_func.csv_data
-
-                    # For functions that don't need an image output, use the original filepath
-                    # as the base for the CSV filename
-                    if (
-                        hasattr(self.processing_func, "no_image_output")
-                        and self.processing_func.no_image_output
-                    ):
-                        # Use the original filepath without creating a new image file
-                        base_path = os.path.splitext(filepath)[0]
-                        csv_path = f"{base_path}_regionprops.csv"
-
-                        # Don't save a duplicate image file
-                        if (
-                            os.path.exists(output_path)
-                            and output_path != filepath
-                        ):
-                            contextlib.suppress(OSError)
-                    else:
-                        # Create CSV filename from the output image path
-                        csv_path = (
-                            os.path.splitext(output_path)[0]
-                            + "_regionprops.csv"
-                        )
-
-                    # Save the CSV file
-                    df.to_csv(csv_path, index=False)
-                    print(f"Saved region properties to {csv_path}")
-
-                    # Add the CSV file to the result
-                    result["secondary_files"] = [csv_path]
-
-                    # If we don't need an image output, update the result to just point to the CSV
-                    if (
-                        hasattr(self.processing_func, "no_image_output")
-                        and self.processing_func.no_image_output
-                    ):
-                        result["processed_file"] = csv_path
-
-            return result
-
-        # Apply the monkey patch
-        ProcessingWorker.process_file = process_file_with_csv_export
+    def equalize_histogram(*args, **kwargs):
+        raise ImportError(
+            "scikit-image is not available. Please install scikit-image to use this function."
+        )
 
-    except (NameError, AttributeError) as e:
-        print(f"Warning: Could not apply CSV export patch: {e}")
-        print(
-            "Region properties will be extracted but CSV files may not be saved"
+    def otsu_thresholding(*args, **kwargs):
+        raise ImportError(
+            "scikit-image is not available. Please install scikit-image to use this function."
         )
 
 
@@ -455,3 +480,190 @@ def convert_to_uint8(image: np.ndarray) -> np.ndarray:
 
     # Convert the rescaled image to uint8
     return skimage.img_as_ubyte(img_rescaled)
+
+
+# ============================================================================
+# Bright Region Extraction Functions
+# ============================================================================
+
+if SKIMAGE_AVAILABLE:
+
+    @BatchProcessingRegistry.register(
+        name="Percentile Threshold (Keep Brightest)",
+        suffix="_percentile",
+        description="Keep only pixels above a brightness percentile, zero out the rest",
+        parameters={
+            "percentile": {
+                "type": float,
+                "default": 90.0,
+                "min": 0.0,
+                "max": 100.0,
+                "description": "Keep pixels brighter than this percentile (0-100)",
+            },
+            "output_type": {
+                "type": str,
+                "default": "original",
+                "options": ["original", "binary"],
+                "description": "Output original values or binary mask",
+            },
+        },
+    )
+    def percentile_threshold(
+        image: np.ndarray,
+        percentile: float = 90.0,
+        output_type: str = "original",
+    ) -> np.ndarray:
+        """
+        Keep only pixels above a certain brightness percentile.
+
+        This function calculates the specified percentile of pixel intensities
+        and keeps only pixels brighter than that threshold. Darker pixels are
+        set to zero.
+
+        Parameters:
+        -----------
+        image : numpy.ndarray
+            Input image array
+        percentile : float
+            Percentile threshold (0-100). Higher values keep fewer, brighter pixels.
+        output_type : str
+            'original' returns the original pixel values for pixels above threshold,
+            'binary' returns a binary mask (255 for above threshold, 0 otherwise)
+
+        Returns:
+        --------
+        numpy.ndarray
+            Image with only bright regions preserved
+        """
+        # Calculate the percentile threshold
+        threshold = np.percentile(image, percentile)
+
+        if output_type == "binary":
+            # Return binary mask
+            return np.where(image > threshold, 255, 0).astype(np.uint8)
+        else:
+            # Return original values above threshold, zero elsewhere
+            result = image.copy()
+            result[image <= threshold] = 0
+            return result
+
+    @BatchProcessingRegistry.register(
+        name="Rolling Ball Background Subtraction",
+        suffix="_rollingball",
+        description="Remove uneven background using rolling ball algorithm (like ImageJ)",
+        parameters={
+            "radius": {
+                "type": int,
+                "default": 50,
+                "min": 5,
+                "max": 200,
+                "description": "Radius of rolling ball (larger = remove broader background)",
+            }
+        },
+    )
+    def rolling_ball_background(
+        image: np.ndarray, radius: int = 50
+    ) -> np.ndarray:
+        """
+        Remove background using rolling ball algorithm.
+
+        This algorithm estimates and removes uneven background by simulating
+        a ball rolling under the image surface. It's particularly effective
+        for fluorescence microscopy images with uneven illumination.
+
+        Parameters:
+        -----------
+        image : numpy.ndarray
+            Input image array
+        radius : int
+            Radius of the rolling ball. Should be larger than the largest
+            feature you want to keep. Larger values remove broader background
+            variations.
+
+        Returns:
+        --------
+        numpy.ndarray
+            Background-subtracted image with bright features preserved
+        """
+        from skimage.restoration import rolling_ball
+
+        # Estimate background
+        background = rolling_ball(image, radius=radius)
+
+        # Subtract background and clip to valid range
+        result = image.astype(np.float32) - background
+        result = np.clip(result, 0, None)
+
+        # Convert back to original dtype range if needed
+        if image.dtype == np.uint8:
+            result = np.clip(result, 0, 255).astype(np.uint8)
+        elif image.dtype == np.uint16:
+            result = np.clip(result, 0, 65535).astype(np.uint16)
+
+        return result
+
+    @BatchProcessingRegistry.register(
+        name="Adaptive Threshold (Bright Bias)",
+        suffix="_adaptive_bright",
+        description="Adaptive thresholding biased to keep bright regions",
+        parameters={
+            "block_size": {
+                "type": int,
+                "default": 35,
+                "min": 3,
+                "max": 201,
+                "description": "Size of local neighborhood (must be odd)",
+            },
+            "offset": {
+                "type": float,
+                "default": -10.0,
+                "min": -128.0,
+                "max": 128.0,
+                "description": "Constant subtracted from mean (negative = keep more bright pixels)",
+            },
+        },
+    )
+    def adaptive_threshold_bright(
+        image: np.ndarray, block_size: int = 35, offset: float = -10.0
+    ) -> np.ndarray:
+        """
+        Apply adaptive thresholding with bias toward bright regions.
+
+        Unlike global thresholding, adaptive thresholding calculates a threshold
+        for each pixel based on its local neighborhood. The negative offset
+        biases the threshold to keep more bright pixels.
+
+        Parameters:
+        -----------
+        image : numpy.ndarray
+            Input image array
+        block_size : int
+            Size of the local neighborhood for threshold calculation. Must be odd.
+            Larger values consider broader neighborhoods.
+        offset : float
+            Value subtracted from the local mean. Negative values (like -10)
+            lower the threshold, keeping more bright pixels.
+
+        Returns:
+        --------
+        numpy.ndarray
+            Binary image (255 for bright regions, 0 elsewhere)
+        """
+        # Ensure block_size is odd
+        if block_size % 2 == 0:
+            block_size += 1
+
+        # Convert to uint8 if needed
+        if image.dtype != np.uint8:
+            image = skimage.img_as_ubyte(image)
+
+        # Apply adaptive thresholding
+        threshold = skimage.filters.threshold_local(
+            image, block_size=block_size, offset=offset
+        )
+
+        # Create binary mask
+        binary = image > threshold
+
+        # Return as uint8 (255/0)
+        return (binary * 255).astype(np.uint8)