isoview 0.1.0__py3-none-any.whl

isoview/__init__.py

@@ -0,0 +1,36 @@
+"""Isoview: multi-view light sheet microscopy processing pipeline."""
+
+from .config import ProcessingConfig
+from .pipeline import IsoviewProcessor, process_dataset, process_timepoint
+from .fusion import multi_fuse, fuse_views, blend_views
+from .transforms import (
+    estimate_channel_transform,
+    estimate_camera_transform,
+    apply_channel_transform,
+    apply_camera_transform,
+    gradient_descent_optimize,
+)
+from . import temporal
+from . import viz
+from .io import read_volume, detect_timepoints
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ProcessingConfig",
+    "IsoviewProcessor",
+    "process_dataset",
+    "process_timepoint",
+    "multi_fuse",
+    "fuse_views",
+    "blend_views",
+    "estimate_channel_transform",
+    "estimate_camera_transform",
+    "apply_channel_transform",
+    "apply_camera_transform",
+    "gradient_descent_optimize",
+    "temporal",
+    "viz",
+    "read_volume",
+    "detect_timepoints",
+]

isoview/array.py

@@ -0,0 +1,11 @@
+"""IsoviewArray - re-exported from mbo_utilities for backwards compatibility."""
+
+try:
+    from mbo_utilities.arrays.isoview import IsoviewArray
+except ImportError:
+    raise ImportError(
+        "IsoviewArray requires mbo_utilities. Install with: "
+        "pip install mbo_utilities[isoview]"
+    )
+
+__all__ = ["IsoviewArray"]

isoview/config.py

@@ -0,0 +1,213 @@
+"""Configuration for isoview processing pipeline."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+
+@dataclass
+class ProcessingConfig:
+    """Configuration for IsoView image processing pipeline."""
+
+    # paths
+    input_dir: Path
+    output_dir: Optional[Path] = None
+    projection_dir: Optional[Path] = None
+
+    # specimen and timepoint selection
+    specimen: int = 0
+    timepoints: Optional[list[int]] = None  # None = auto-detect all
+    cameras: list[int] = field(default_factory=lambda: [0, 1, 2, 3])
+    channels: list[int] = field(default_factory=lambda: [0, 1])
+
+    # roi cropping (none means auto-detect from xml)
+    crop_left: Optional[list[int]] = None
+    crop_top: Optional[list[int]] = None
+    crop_width: Optional[list[int]] = None
+    crop_height: Optional[list[int]] = None
+    crop_front: Optional[list[int]] = None
+    crop_depth: Optional[list[int]] = None
+
+    # file formats
+    output_format: str = "zarr"  # klb, tiff, or zarr
+    zarr_compression: Optional[str] = "blosc-zstd"  # blosc-zstd, blosc-lz4, blosc-lz4hc, gzip, bzip2, or None (default: blosc-zstd for best compression)
+    zarr_compression_level: int = 9  # 1-9, default to maximum compression
+    zarr_chunks: Optional[tuple[int, int, int]] = None  # (z, y, x) chunk size for zarr, None = auto
+    zarr_shards: Optional[tuple[int, int, int]] = None  # (z, y, x) shard size for zarr, None = auto (10 frames/shard for z>=20)
+    zarr_consolidate: bool = True  # consolidate projections and masks into single OME-Zarr file (only for zarr output)
+
+    # pixel correction
+    median_kernel: Optional[tuple[int, int]] = (3, 3)
+
+    # background estimation
+    background_percentile: float = 5.0
+    mask_percentile: float = 1.0
+    subsample_factor: int = 100
+
+    # segmentation
+    # segment_mode: 0=no masking, 1=segment+mask, 2=masks only, 3=apply global mask
+    segment_mode: int = 1
+    gauss_kernel: int = 5
+    gauss_sigma: float = 2.0
+    segment_threshold: float = 0.4
+    splitting: int = 10  # for memory-efficient gaussian filtering
+    global_mask_dir: Optional[Path] = None  # for segment_mode=3
+
+    # transformations
+    rotation: int = 0  # 0: none, 1: 90° cw, -1: 90° ccw
+    flip_horizontal: bool = False
+    flip_vertical: bool = False
+
+    # microscope parameters
+    pixel_spacing_z: float = 0.40625
+    detection_objective_mag: float = 16.0
+    pixel_spacing_camera: float = 6.5
+
+    # channel dependencies (for multi-channel segmentation)
+    reference_channels: Optional[list[list[int]]] = None
+    dependent_channels: Optional[list[list[int]]] = None
+
+    # camera-channel mapping (isoview hardware: CM0,1→CHN01; CM2,3→CHN00)
+    camera_channel_map: Optional[dict[int, int]] = None
+
+    # camera pairs for flipping (second camera in each pair gets flipped)
+    camera_pairs: Optional[list[tuple[int, int]]] = None  # [(0, 1), (2, 3)]
+
+    # fusion parameters (for multiFuse pipeline)
+    fusion_enable: bool = False
+    fusion_type: str = "adaptive_blending"  # adaptive_blending, geometric, wavelet, average
+    fusion_blending_range: tuple[int, int] = (20, 20)  # (channel_range, camera_range)
+    fusion_camera_pairs: Optional[list[tuple[int, int]]] = None  # [(cam0, cam1), ...]
+    fusion_channel_pairs: Optional[list[tuple[int, int]]] = None  # [(ch0, ch1), ...]
+    fusion_4view_only: bool = False  # skip camera fusion, use existing camera-fused files for 4-view
+    fusion_flip_h: bool = False  # flip second camera horizontally (for camera fusion)
+    fusion_flip_v: bool = False  # flip second camera vertically (for camera fusion)
+    fusion_channel_flip_h: bool = True  # flip second channel horizontally (for 4-view/channel fusion)
+    fusion_channel_flip_v: bool = True  # flip second channel vertically (for 4-view/channel fusion)
+    fusion_left_flags: tuple[int, int] = (2, 1)  # light sheet direction per camera (1=ref, 2=transformed)
+    fusion_front_flag: int = 1  # which camera has quality in front (1=ref, 2=transformed)
+    fusion_search_offsets_x: tuple[int, int, int] = (-50, 50, 10)  # (start, stop, step)
+    fusion_search_offsets_y: tuple[int, int, int] = (-50, 50, 10)
+    fusion_optimizer: str = "gradient_descent"  # gradient_descent (MATLAB fminuncFA), nelder_mead, bfgs
+
+    # axial scaling for channel fusion (z_spacing / xy_spacing)
+    # used for anisotropic rotation in XZ plane
+    axial_scaling: float = 1.0
+
+    # temporal parameter processing
+    fusion_temporal_smoothing: bool = False  # enable rloess smoothing across timepoints
+    fusion_smoothing_window: int = 100  # rloess smoothing window size
+    fusion_temporal_interpolation: bool = False  # interpolate params for missing timepoints
+    fusion_offset_averaging_range: int = 10  # median/mean window for spatial offsets
+    fusion_angle_averaging_range: int = 10  # median/mean window for rotation angles
+    fusion_intensity_averaging_range: int = 5  # median/mean window for intensity correction
+    fusion_averaging: str = "median"  # median or mean for lookup table
+    fusion_static: bool = False  # use static (time-averaged) parameters instead of time-dependent
+    fusion_generate_lookup_table: bool = False  # generate and save lookup tables
+
+    # mask processing
+    fusion_mask_fusion_mode: int = 1  # 0: overlap only, 1: combine full masks
+    fusion_mask_padding: int = 0  # 0: disable, 1: center coord, 2: smooth padding
+    fusion_mask_padding_radius: int = 50  # disk radius for smooth padding mode
+    fusion_mask_min_object_size: float = 0  # bwareaopen fraction, 0 to disable
+    fusion_mask_percentile: float = 1.0  # percentile for minimum calculation
+    fusion_mask_subsample: int = 100  # subsampling for percentile computation
+
+    # processing modes
+    fusion_slab_size_channels: int = 5  # adaptive slab size for channel correlation, 0 for slice mode
+    fusion_slab_size_cameras: int = 3  # adaptive slab size for camera correlation, 0 for slice mode
+    fusion_intensity_slab_size_channels: int = 10  # slab size for channel intensity correction
+    fusion_intensity_slab_size_cameras: int = 5  # slab size for camera intensity correction
+
+    # filtering options
+    fusion_median_filter_range: int = 100  # median filter range, 0 to disable
+    fusion_precise_gauss: bool = True  # True for double precision, False for uint16 (faster)
+    fusion_gauss_kernel: int = 3  # gauss filter kernel size, 0 to disable
+    fusion_gauss_sigma: float = 1.0  # gauss filter sigma
+    fusion_subsample_slices: int = 1  # slice subsampling for percentile computation
+    fusion_subsample_stacks: int = 100  # stack subsampling for percentile computation
+
+    # diagnostic output
+    save_diagnostics: bool = True  # save diagnostic PNG images during processing
+    diagnostics_dir: Optional[Path] = None  # directory for diagnostic images, None = output_dir/diagnostics
+
+    def __post_init__(self):
+        """Initialize derived attributes."""
+        self.input_dir = Path(self.input_dir)
+
+        # auto-detect timepoints if not specified
+        if self.timepoints is None:
+            from .io import detect_timepoints
+            self.timepoints = detect_timepoints(self.input_dir, self.specimen)
+
+        if self.output_dir is None:
+            self.output_dir = self.input_dir.parent / f"{self.input_dir.name}.corrected"
+        else:
+            self.output_dir = Path(self.output_dir)
+
+        if self.projection_dir is None:
+            self.projection_dir = self.output_dir.parent / f"{self.input_dir.name}.projections"
+        else:
+            self.projection_dir = Path(self.projection_dir)
+
+        # pixel spacing calculations
+        pixel_xy = self.pixel_spacing_camera / self.detection_objective_mag
+        # Order: [z, y, x, t, c] for OME-Zarr compliance
+        self.pixel_spacing = np.array([self.pixel_spacing_z, pixel_xy, pixel_xy, 1.0, 1.0])
+        self.scaling = self.pixel_spacing_z / pixel_xy
+
+        # compute axial scaling for channel fusion if not explicitly set
+        if self.axial_scaling == 1.0:
+            self.axial_scaling = self.scaling
+
+        # global mask directory
+        if self.global_mask_dir is None:
+            self.global_mask_dir = self.input_dir.parent / f"{self.input_dir.name}.globalMask"
+        else:
+            self.global_mask_dir = Path(self.global_mask_dir)
+
+        # sync segment with segment_mode for backwards compat
+        if self.segment_mode == 0:
+            self.segment = False
+        elif self.segment_mode in (1, 2):
+            self.segment = True
+
+        # default camera-channel mapping for standard isoview hardware
+        if self.camera_channel_map is None:
+            self.camera_channel_map = {0: 1, 1: 1, 2: 0, 3: 0}
+
+        # default camera pairs for standard isoview hardware
+        if self.camera_pairs is None:
+            self.camera_pairs = [(0, 1), (2, 3)]
+
+        # validate camera pairs if flipping is enabled
+        if self.flip_horizontal or self.flip_vertical:
+            self._validate_camera_pairs()
+
+    def _validate_camera_pairs(self) -> None:
+        """Validate that all cameras belong to a pair when flipping is enabled."""
+        paired_cameras = set()
+        for cam0, cam1 in self.camera_pairs:
+            paired_cameras.add(cam0)
+            paired_cameras.add(cam1)
+
+        for camera in self.cameras:
+            if camera not in paired_cameras:
+                raise ValueError(
+                    f"camera {camera} is not in any pair but flipping is enabled. "
+                    f"camera_pairs={self.camera_pairs}, cameras={self.cameras}"
+                )
+
+    def is_second_in_pair(self, camera: int) -> bool:
+        """Check if camera is the second in its pair (should be flipped)."""
+        for cam0, cam1 in self.camera_pairs:
+            if camera == cam1:
+                return True
+        return False
+
+    @property
+    def extension(self) -> str:
+        """File extension for output format."""
+        return f".{self.output_format}"

isoview/corrections.py

@@ -0,0 +1,135 @@
+"""Pixel and intensity corrections for microscopy data."""
+
+import numpy as np
+from scipy.ndimage import median_filter
+
+
+def percentile_interp(data: np.ndarray, percentile: float) -> float:
+    """Compute percentile using (i+0.5)/n interpolation.
+
+    Args:
+        data: 1d array of values (will be sorted internally)
+        percentile: percentile to compute (0-100)
+
+    Returns:
+        percentile value
+    """
+    if len(data) == 0:
+        return 0.0
+
+    sorted_data = np.sort(data)
+    n = len(sorted_data)
+
+    p_rank = 100.0 * (np.arange(n) + 0.5) / n
+
+    # interpolate, clamp to min/max outside range
+    return float(np.interp(percentile, p_rank, sorted_data,
+                           left=sorted_data[0], right=sorted_data[-1]))
+
+
+def correct_dead_pixels(
+    volume: np.ndarray,
+    background_value: float,
+    kernel: tuple[int, int],
+    verbose: bool = False,
+) -> np.ndarray:
+    """Detect and correct insensitive pixels using median filtering.
+
+    Args:
+        volume: 3d image stack (z, y, x)
+        background_value: camera background intensity
+        kernel: median filter kernel size (y, x)
+        verbose: print detection statistics
+
+    Returns:
+        corrected volume
+    """
+    # detect dead pixels via deviation projection
+    deviation_proj = np.std(volume.astype(np.float32), axis=0)
+    deviation_filtered = median_filter(deviation_proj, size=kernel, mode="reflect")
+    deviation_dist = np.abs(deviation_proj - deviation_filtered)
+    deviation_thresh = _determine_threshold(np.sort(deviation_dist.ravel()))
+    deviation_mask = deviation_dist > deviation_thresh
+
+    # detect via mean projection
+    mean_proj = np.mean(volume, axis=0) - background_value
+    mean_filtered = median_filter(mean_proj, size=kernel, mode="reflect")
+    mean_dist = np.abs((mean_proj - mean_filtered) / (mean_filtered + 1e-10))
+    mean_thresh = _determine_threshold(np.sort(mean_dist.ravel()))
+    mean_mask = mean_dist > mean_thresh
+
+    # combine masks
+    dead_pixel_mask = deviation_mask | mean_mask
+
+    if verbose:
+        n_dead = dead_pixel_mask.sum()
+        pct = 100 * n_dead / dead_pixel_mask.size
+        print(f"detected {n_dead} dead pixels ({pct:.1f}%)")
+
+    # correct each frame
+    corrected = volume.copy()
+    for z in range(volume.shape[0]):
+        frame = corrected[z]
+        filtered = median_filter(frame, size=kernel, mode="reflect")
+        frame[dead_pixel_mask] = filtered[dead_pixel_mask]
+        corrected[z] = frame
+
+    return corrected
+
+
+def _determine_threshold(sorted_array: np.ndarray, max_samples: int = 50000) -> float:
+    """Determine threshold using maximum distance from linear fit.
+
+    matches matlab's determineThreshold: uses round() for subsampling and
+    1-based indexing for the x coordinate.
+
+    Args:
+        sorted_array: sorted 1d array
+        max_samples: subsample if array is larger
+
+    Returns:
+        threshold value
+    """
+    n = len(sorted_array)
+
+    # subsample if too large (matlab uses round, not floor)
+    if n > max_samples:
+        step = round(n / max_samples)
+        sorted_array = sorted_array[::step]
+        n = len(sorted_array)
+
+    # matlab uses 1-based indexing: X = (1:elements)'
+    x = np.arange(1, n + 1)
+
+    # find maximum distance from line connecting first and last points
+    p1 = np.array([1, sorted_array[0]])
+    p2 = np.array([n, sorted_array[-1]])
+    vec = p2 - p1
+
+    points = np.column_stack([x, sorted_array])
+    h = np.dot(points - p1, vec) / (np.linalg.norm(vec) ** 2)
+    proj = p1 + h[:, np.newaxis] * vec
+    distances = np.linalg.norm(points - proj, axis=1)
+
+    max_idx = np.argmax(distances)
+    return sorted_array[max_idx]
+
+
+def estimate_background(
+    volume: np.ndarray,
+    percentile: float = 5.0,
+    subsample: int = 100,
+) -> float:
+    """Estimate background intensity from subsampled volume.
+
+    Args:
+        volume: 3d image stack
+        percentile: percentile for background estimation
+        subsample: subsampling factor
+
+    Returns:
+        background intensity value
+    """
+    subsampled = volume.ravel()[::subsample]
+    subsampled = subsampled[subsampled > 0]
+    return percentile_interp(subsampled, percentile)