napari-tmidas 0.2.1__py3-none-any.whl → 0.2.4__py3-none-any.whl

napari_tmidas/processing_functions/basic.py

@@ -3,45 +3,439 @@
 Basic image processing functions
 """
 import concurrent.futures
+import inspect
 import os
 import traceback
+import warnings
 
-import dask.array as da
 import numpy as np
-import tifffile
 
 from napari_tmidas._registry import BatchProcessingRegistry
 
+# Lazy imports for optional heavy dependencies
+try:
+    import dask.array as da
+
+    _HAS_DASK = True
+except ImportError:
+    da = None
+    _HAS_DASK = False
+
+try:
+    import tifffile
+
+    _HAS_TIFFFILE = True
+except ImportError:
+    tifffile = None
+    _HAS_TIFFFILE = False
+
+
+def _to_array(data: np.ndarray) -> np.ndarray:
+    arr = np.asarray(data)
+    if arr.ndim == 0:
+        raise ValueError("Label images must have at least one dimension")
+    return arr
+
+
+def _nonzero_bounds(arr: np.ndarray) -> list[tuple[int, int]]:
+    if not np.any(arr):
+        return [(0, size) for size in arr.shape]
+
+    bounds: list[tuple[int, int]] = []
+    dims = range(arr.ndim)
+    for axis in dims:
+        reduction_axes = tuple(i for i in dims if i != axis)
+        axis_any = np.any(arr, axis=reduction_axes)
+        nonzero_idx = np.flatnonzero(axis_any)
+        if nonzero_idx.size == 0:
+            bounds.append((0, arr.shape[axis]))
+        else:
+            bounds.append((int(nonzero_idx[0]), int(nonzero_idx[-1]) + 1))
+    return bounds
+
+
+def _match_ndim(reference: np.ndarray, candidate: np.ndarray) -> np.ndarray:
+    result = np.asarray(candidate)
+    if result.ndim > reference.ndim:
+        axes = [idx for idx, size in enumerate(result.shape) if size == 1]
+        while axes and result.ndim > reference.ndim:
+            result = np.squeeze(result, axis=axes.pop())
+    if result.ndim > reference.ndim:
+        raise ValueError(
+            "Unable to align label images with differing numbers of non-singleton dimensions"
+        )
+    while result.ndim < reference.ndim:
+        result = result[np.newaxis, ...]
+    return result
+
+
+def _align_candidate(
+    reference: np.ndarray, candidate: np.ndarray
+) -> np.ndarray:
+    candidate = _match_ndim(reference, candidate)
+    if candidate.shape == reference.shape:
+        return candidate
+
+    aligned = np.zeros_like(reference)
+    if not np.any(candidate):
+        return aligned
+
+    ref_bounds = _nonzero_bounds(reference)
+    cand_bounds = _nonzero_bounds(candidate)
+
+    shifts: list[int] = []
+    for axis in range(reference.ndim):
+        ref_min, ref_max = ref_bounds[axis]
+        cand_min, cand_max = cand_bounds[axis]
+        ref_center = (ref_min + ref_max) / 2.0
+        cand_center = (cand_min + cand_max) / 2.0
+        shifts.append(int(round(ref_center - cand_center)))
+
+    target_slices: list[slice] = []
+    source_slices: list[slice] = []
+    for axis, shift in enumerate(shifts):
+        ref_len = reference.shape[axis]
+        cand_len = candidate.shape[axis]
+        ref_start = max(0, shift)
+        cand_start = max(0, -shift)
+        length = min(ref_len - ref_start, cand_len - cand_start)
+        if length <= 0:
+            return aligned
+        target_slices.append(slice(ref_start, ref_start + length))
+        source_slices.append(slice(cand_start, cand_start + length))
+
+    aligned[tuple(target_slices)] = candidate[tuple(source_slices)]
+    return aligned
+
 
 @BatchProcessingRegistry.register(
     name="Labels to Binary",
     suffix="_binary",
-    description="Convert multi-label images to binary masks (all non-zero labels become 1)",
+    description="Convert a label image to a binary mask (255 for non-zero, 0 otherwise)",
+    parameters={},
 )
 def labels_to_binary(image: np.ndarray) -> np.ndarray:
+    arr = _to_array(image)
+    result = np.zeros(arr.shape, dtype=np.uint8)
+    np.copyto(result, 255, where=arr != 0)
+    return result
+
+
+@BatchProcessingRegistry.register(
+    name="Invert Binary Labels",
+    suffix="_inverted",
+    description="Invert a binary label image (non-zero becomes 0, zero becomes 255)",
+    parameters={},
+)
+def invert_binary_labels(image: np.ndarray) -> np.ndarray:
+    arr = _to_array(image)
+    result = np.zeros(arr.shape, dtype=np.uint8)
+    np.copyto(result, 255, where=arr == 0)
+    return result
+
+
+@BatchProcessingRegistry.register(
+    name="Filter Label by ID",
+    suffix="_filtered",
+    description="Keep only the specified label ID, set all other labels to background (0)",
+    parameters={
+        "label_id": {
+            "type": int,
+            "default": 1,
+            "min": 1,
+            "description": "Label ID to keep (all others become background)",
+        }
+    },
+)
+def filter_label_by_id(image: np.ndarray, label_id: int = 1) -> np.ndarray:
     """
-    Convert multi-label images to binary masks.
+    Filter a label image to keep only the specified label ID.
+    All other label IDs are set to background (0).
+
+    Parameters
+    ----------
+    image : np.ndarray
+        Input label image
+    label_id : int
+        The label ID to keep (default: 1)
+
+    Returns
+    -------
+    np.ndarray
+        Filtered label image with only the specified label ID preserved
+    """
+    arr = _to_array(image)
+    result = np.where(arr == label_id, arr, 0).astype(arr.dtype)
+    return result
 
-    This function takes a label image (where different regions have different label values)
-    and converts it to a binary mask (where all labeled regions have a value of 1 and
-    background has a value of 0).
 
-    Parameters:
-    -----------
-    image : numpy.ndarray
-        Input label image array
+@BatchProcessingRegistry.register(
+    name="Mirror Labels",
+    suffix="_mirrored",
+    description="Mirror labels at their largest slice area along an axis, keeping original image shape",
+    parameters={
+        "axis": {
+            "type": int,
+            "default": 0,
+            "description": "Axis along which to mirror the labels",
+        }
+    },
+)
+def mirror_labels(image: np.ndarray, axis: int = 0) -> np.ndarray:
+    arr = _to_array(image)
+    if arr.ndim == 0:
+        raise ValueError("Cannot mirror a scalar")
+    if not isinstance(axis, int):
+        raise TypeError("axis must be an integer")
+    if axis >= arr.ndim or axis < -arr.ndim:
+        raise ValueError(
+            f"Axis {axis} is out of bounds for an image with {arr.ndim} dimensions"
+        )
 
-    Returns:
-    --------
+    axis = axis % arr.ndim
+
+    # Find the slice with the largest area (most non-zero pixels)
+    reduction_axes = tuple(i for i in range(arr.ndim) if i != axis)
+    slice_areas = np.sum(arr != 0, axis=reduction_axes, dtype=np.int64)
+
+    if slice_areas.size == 0 or np.max(slice_areas) == 0:
+        # No labels to mirror, return copy
+        return arr.copy()
+
+    # Find the index of the slice with maximum area
+    max_area_idx = int(np.argmax(slice_areas))
+
+    # Create result array (same shape as input)
+    result = np.zeros_like(arr)
+
+    # Get max label value for offset
+    max_label = int(np.max(arr)) if arr.size else 0
+
+    # Mirror labels from the max_area_idx position
+    for i in range(arr.shape[axis]):
+        # Calculate the mirrored position relative to max_area_idx
+        mirrored_i = 2 * max_area_idx - i
+
+        # Create slicers for current position i and mirrored position
+        slicer_i = [slice(None)] * arr.ndim
+        slicer_i[axis] = i
+        slicer_i = tuple(slicer_i)
+
+        # If mirrored position is within bounds, copy and offset the labels
+        if 0 <= mirrored_i < arr.shape[axis]:
+            slicer_mirrored = [slice(None)] * arr.ndim
+            slicer_mirrored[axis] = mirrored_i
+            slicer_mirrored = tuple(slicer_mirrored)
+
+            # Copy mirrored slice with offset labels
+            mirrored_slice = arr[slicer_mirrored]
+            result[slicer_i] = np.where(
+                mirrored_slice != 0, mirrored_slice + max_label, 0
+            )
+
+    return result.astype(arr.dtype, copy=False)
+
+
+@BatchProcessingRegistry.register(
+    name="Intersect Label Images",
+    suffix="_intersected",
+    description="Compute the voxel-wise intersection of paired label images identified by suffix",
+    parameters={
+        "primary_suffix": {
+            "type": str,
+            "default": "_a.tif",
+            "description": "Suffix (including extension) of the primary label image",
+        },
+        "secondary_suffix": {
+            "type": str,
+            "default": "_b.tif",
+            "description": "Suffix (including extension) of the paired label image",
+        },
+    },
+)
+def intersect_label_images(
+    image: np.ndarray,
+    primary_suffix: str = "_a.tif",
+    secondary_suffix: str = "_b.tif",
+) -> np.ndarray:
+    """Return the intersection of two paired label images.
+
+    The function expects two label files that share a base name but differ by suffix.
+    When overlap occurs, the label IDs from the primary image are retained anywhere both
+    volumes contain non-zero voxels. Each pair is processed exactly once by treating the
+    file with ``primary_suffix`` as the active entry point; secondary label files are
+    skipped and left unchanged.
+    """
+
+    if not primary_suffix or not secondary_suffix:
+        raise ValueError(
+            "Both primary_suffix and secondary_suffix must be provided"
+        )
+
+    def _load_label_file(path: str) -> np.ndarray:
+        ext = os.path.splitext(path)[1].lower()
+        if ext == ".npy":
+            return np.load(path)
+        if _HAS_TIFFFILE and ext in {".tif", ".tiff", ".ome.tif", ".ome.tiff"}:
+            return tifffile.imread(path)
+
+        try:
+            from skimage.io import imread
+        except (
+            ImportError
+        ) as exc:  # pragma: no cover - optional dependency path
+            raise ImportError(
+                "Install 'tifffile' or 'scikit-image' to load paired label images"
+            ) from exc
+
+        return imread(path)
+
+    current_file = None
+    for frame_info in inspect.stack():
+        frame_locals = frame_info.frame.f_locals
+        if "filepath" in frame_locals:
+            current_file = frame_locals["filepath"]
+            break
+
+    if current_file is None:
+        raise ValueError(
+            "Could not determine current file path for paired label lookup"
+        )
+
+    current_file = os.fspath(current_file)
+    folder_path = os.path.dirname(current_file)
+    filename = os.path.basename(current_file)
+
+    if filename.endswith(primary_suffix):
+        base_name = filename[: -len(primary_suffix)]
+        paired_suffix = secondary_suffix
+    elif filename.endswith(secondary_suffix):
+        warnings.warn(
+            (
+                f"Skipping secondary label image '{filename}'; only files ending with "
+                f"'{primary_suffix}' are processed by the 'Intersect Label Images' function."
+            ),
+            stacklevel=2,
+        )
+        return None
+    else:
+        raise ValueError(
+            f"Filename '{filename}' does not end with either '{primary_suffix}' or '{secondary_suffix}'"
+        )
+
+    paired_name = base_name + paired_suffix
+    paired_path = os.path.abspath(os.path.join(folder_path, paired_name))
+
+    if not os.path.exists(paired_path):
+        raise FileNotFoundError(f"Paired label image not found: {paired_path}")
+
+    current_array = _to_array(image)
+    paired_array = _to_array(_load_label_file(paired_path))
+
+    paired_aligned = _align_candidate(current_array, paired_array)
+
+    overlap_mask = (current_array != 0) & (paired_aligned != 0)
+    if not np.any(overlap_mask):
+        result_dtype = np.promote_types(
+            current_array.dtype, paired_aligned.dtype
+        )
+        return np.zeros(current_array.shape, dtype=result_dtype)
+
+    result_dtype = np.promote_types(current_array.dtype, paired_aligned.dtype)
+    result = np.zeros(current_array.shape, dtype=result_dtype)
+    np.copyto(
+        result,
+        current_array.astype(result_dtype, copy=False),
+        where=overlap_mask,
+    )
+
+    return result
+
+
+@BatchProcessingRegistry.register(
+    name="Keep Slice Range by Area",
+    suffix="_area_range",
+    description="Zero out label content outside the min/max area slice range (preserves image shape for alignment)",
+    parameters={
+        "axis": {
+            "type": int,
+            "default": 0,
+            "description": "Axis index representing the slice dimension (negative values count from the end)",
+        }
+    },
+)
+def keep_slice_range_by_area(image: np.ndarray, axis: int = 0) -> np.ndarray:
+    """Keep label content only between the minimum-area and maximum-area slices (inclusive).
+
+    The per-slice area is measured as the number of non-zero pixels in the slice. When all slices
+    share the same area, the original volume is returned unchanged. This function preserves the
+    original image dimensions but zeros out label content outside the detected range, ensuring
+    alignment with corresponding image data is maintained.
+
+    Parameters
+    ----------
+    image:
+        3D (or higher dimensional) label image as a NumPy array.
+    axis:
+        Axis index corresponding to the slice dimension that should be evaluated.
+
+    Returns
+    -------
     numpy.ndarray
-        Binary mask with 1 for all non-zero labels and 0 for background
+        Volume with the same shape as input, but with label content zeroed outside the
+        minimum and maximum area slice range (inclusive).
     """
-    # Make a copy of the input image to avoid modifying the original
-    binary_mask = image.copy()
 
-    binary_mask = (binary_mask > 0).astype(np.uint32)
+    if image.ndim < 3:
+        raise ValueError(
+            "Slice range trimming requires an array with at least 3 dimensions"
+        )
+    if not isinstance(axis, int):
+        raise TypeError("axis must be provided as an integer")
+    if axis >= image.ndim or axis < -image.ndim:
+        raise ValueError(
+            f"Axis {axis} is out of bounds for an image with {image.ndim} dimensions"
+        )
+
+    axis = axis % image.ndim
+
+    if image.shape[axis] == 0:
+        raise ValueError(
+            "Cannot determine slice range on an axis with zero length"
+        )
+
+    reduction_axes = tuple(i for i in range(image.ndim) if i != axis)
+    # Count non-zero pixels per slice to determine occupied area per slice
+    slice_areas = np.sum(image != 0, axis=reduction_axes, dtype=np.int64)
+
+    if slice_areas.size == 0:
+        return image.copy()
+
+    if slice_areas.min() == slice_areas.max():
+        return image.copy()
+
+    min_idx = int(np.argmin(slice_areas))
+    max_idx = int(np.argmax(slice_areas))
+
+    start = min(min_idx, max_idx)
+    end = max(min_idx, max_idx)
 
-    return binary_mask
+    # Create a copy of the full image to preserve shape
+    result = image.copy()
+
+    # Zero out slices before the start
+    if start > 0:
+        before_slicer = [slice(None)] * image.ndim
+        before_slicer[axis] = slice(0, start)
+        result[tuple(before_slicer)] = 0
+
+    # Zero out slices after the end
+    if end < image.shape[axis] - 1:
+        after_slicer = [slice(None)] * image.ndim
+        after_slicer[axis] = slice(end + 1, None)
+        result[tuple(after_slicer)] = 0
+
+    return result
 
 
 @BatchProcessingRegistry.register(
@@ -168,7 +562,7 @@ def max_z_projection_tzyx(image: np.ndarray) -> np.ndarray:
 
 @BatchProcessingRegistry.register(
     name="Split Color Channels",
-    suffix="_split_color_channels",
+    suffix="_split",
     description="Splits the color channels of the image",
     parameters={
         "num_channels": {
@@ -313,6 +707,9 @@ def split_channels(
     # Process output format
     result_channels = []
     for i, channel_img in enumerate(channels):
+        # Remove the channel dimension (which now has size 1 after split)
+        channel_img = np.squeeze(channel_img, axis=channel_axis)
+
         # Get original axes without channel
         axes_without_channel = axes.copy()
         del axes_without_channel[channel_axis]
@@ -368,6 +765,140 @@ def split_channels(
     return np.stack(result_channels, axis=0)
 
 
+@BatchProcessingRegistry.register(
+    name="Merge Color Channels",
+    suffix="_merged_colors",
+    description="Merges separate channel images from a folder into a single multi-channel image",
+    parameters={
+        "channel_substring": {
+            "type": str,
+            "default": "_channel_",
+            "description": "Substring before channel number",
+        },
+    },
+)
+def merge_channels(
+    image: np.ndarray,
+    channel_substring: str = "_channel_",
+) -> np.ndarray:
+    """
+    Merge multiple single-channel images from a folder into one multi-channel image.
+
+    Identifies channel files by finding a substring followed by a 1-2 digit number.
+    Adds channels as the last dimension regardless of input dimensionality.
+
+    Args:
+        image: Current image being processed
+        channel_substring: Substring that appears before channel number in filenames
+
+    Returns:
+        Multi-channel image with channels as last dimension
+    """
+    # Get file context from batch processing
+    import inspect
+    import re
+
+    from skimage.io import imread
+
+    current_file = None
+
+    for frame_info in inspect.stack():
+        frame_locals = frame_info.frame.f_locals
+        if "filepath" in frame_locals:
+            current_file = frame_locals["filepath"]
+            break
+
+    if current_file is None:
+        raise ValueError("Could not determine current file path")
+
+    folder_path = os.path.dirname(current_file)
+    filename = os.path.basename(current_file)
+
+    # Create regex pattern to find channel substring followed by 1-2 digits
+    pattern = re.compile(rf"({re.escape(channel_substring)})(\d{{1,2}})")
+    match = pattern.search(filename)
+
+    if not match:
+        print(
+            f"⚠️  No channel pattern '{channel_substring}[number]' found in filename"
+        )
+        return image
+
+    # Extract base name and channel number
+    channel_num = int(match.group(2))
+    base_name = filename[: match.start()] + filename[match.end() :]
+
+    print(f"\n📐 Current image shape: {image.shape}")
+    print(f"✅ Found channel {channel_num} in file: {filename}")
+
+    # Find all related channel files
+    all_files = os.listdir(folder_path)
+    channel_files = {}
+
+    for file in all_files:
+        file_match = pattern.search(file)
+        if file_match:
+            # Check if base name matches (excluding channel part)
+            file_base = file[: file_match.start()] + file[file_match.end() :]
+            if file_base == base_name:
+                ch_num = int(file_match.group(2))
+                channel_files[ch_num] = os.path.join(folder_path, file)
+
+    # Sort by channel number
+    sorted_channels = sorted(channel_files.keys())
+    num_channels = len(sorted_channels)
+
+    if num_channels < 2:
+        print(
+            f"⚠️  Only found {num_channels} channel(s). Need at least 2 for merging."
+        )
+        return image
+
+    # Determine which channel acts as the primary trigger for merging
+    primary_channel = sorted_channels[0]
+
+    if channel_num != primary_channel:
+        print(
+            f"ℹ️  Channel {channel_num} is not the primary channel ({primary_channel}); skipping merge for this file."
+        )
+        return image
+
+    print(f"📊 Found {num_channels} channels: {sorted_channels}")
+
+    # Load all channels in order
+    # First channel is the current image
+    channels = []
+    for ch_num in sorted_channels:
+        if ch_num == channel_num:
+            # Use the already loaded image for current channel
+            channels.append(image)
+        else:
+            # Load other channel files
+            channel_path = channel_files[ch_num]
+            channel_data = imread(channel_path)
+
+            if channel_data.shape != image.shape:
+                raise ValueError(
+                    f"Channel {ch_num} has different shape: {channel_data.shape} vs {image.shape}"
+                )
+
+            channels.append(channel_data)
+
+        print(
+            f"   Channel {ch_num}: {os.path.basename(channel_files[ch_num])}"
+        )
+
+    # Stack channels as last dimension
+    merged = np.stack(channels, axis=-1)
+
+    print(
+        f"✨ Merged shape: {merged.shape} (channels added as last dimension)"
+    )
+
+    # Return merged array so downstream steps receive the combined channels
+    return merged
+
+
 @BatchProcessingRegistry.register(
     name="RGB to Labels",
     suffix="_labels",
@@ -542,7 +1073,13 @@ def split_tzyx_stack(
 # Monkey patch ProcessingWorker.process_file to handle parallel TZYX splitting
 try:
     # Import tifffile here to ensure it's available for the monkey patch
-    import tifffile
+    if not _HAS_TIFFFILE:
+        try:
+            import tifffile
+
+            _HAS_TIFFFILE = True
+        except ImportError:
+            pass  # tifffile not available, skip monkey patch
 
     from napari_tmidas._file_selector import ProcessingWorker