isoview 0.1.0__py3-none-any.whl

isoview/pipeline.py

@@ -0,0 +1,913 @@
+"""Main processing pipeline for isoview microscopy data."""
+
+from pathlib import Path
+from typing import Optional
+import shutil
+import time
+
+import numpy as np
+
+from .config import ProcessingConfig
+from .corrections import correct_dead_pixels, estimate_background, percentile_interp
+from .io import (
+    find_stack_file,
+    infer_file_structure,
+    read_volume,
+    read_all_xml_metadata,
+    read_background_values,
+    write_volume,
+    write_to_consolidated_zarr,
+    setup_consolidated_zarr,
+    add_label_to_registry,
+)
+from .segmentation import create_coordinate_masks, fuse_masks, segment_foreground
+from .transforms import apply_mask, crop_volume, flip_volume, rotate_volume
+
+
+class IsoviewProcessor:
+    """Process multi-view light sheet microscopy data."""
+
+    def __init__(self, config: ProcessingConfig):
+        """Initialize processor with configuration."""
+        self.config = config
+        self.structure = infer_file_structure(
+            config.input_dir, config.specimen, config.channels
+        )
+
+        # Load metadata from all XML files
+        self.metadata, self.per_camera_metadata = read_all_xml_metadata(config.input_dir, config.specimen)
+
+        self.background_values = read_background_values(config.input_dir, percentile=3.0)
+
+        # create output directories
+        self.config.output_dir.mkdir(parents=True, exist_ok=True)
+        self.config.projection_dir.mkdir(parents=True, exist_ok=True)
+
+    def process_timepoint(self, timepoint: int) -> None:
+        """Process single timepoint across all cameras and channels.
+
+        Args:
+            timepoint: timepoint index to process
+        """
+        # create output subdirectory
+        output_subdir = self.config.output_dir / f"TM{timepoint:06d}"
+        output_subdir.mkdir(exist_ok=True)
+
+        # determine channel processing groups
+        if self.config.reference_channels is not None:
+            ref_groups = self.config.reference_channels
+            dep_groups = self.config.dependent_channels or [[] for _ in ref_groups]
+        else:
+            # each channel is independent
+            ref_groups = [[ch] for ch in self.config.channels]
+            dep_groups = [[] for _ in self.config.channels]
+
+        # process each camera
+        for camera in self.config.cameras:
+            self._process_camera(timepoint, camera, output_subdir, ref_groups, dep_groups)
+
+    def _process_camera(
+        self,
+        timepoint: int,
+        camera: int,
+        output_dir: Path,
+        ref_groups: list[list[int]],
+        dep_groups: list[list[int]],
+    ) -> None:
+        """Process single camera for given timepoint."""
+
+        # process each reference group
+        for refs, deps in zip(ref_groups, dep_groups):
+            self._process_channel_group(
+                timepoint, camera, output_dir, refs, deps
+            )
+
+    def _process_channel_group(
+        self,
+        timepoint: int,
+        camera: int,
+        output_dir: Path,
+        ref_channels: list[int],
+        dep_channels: list[int],
+    ) -> None:
+        """Process group of reference and dependent channels."""
+        # load and process reference channels
+        ref_volumes = []
+        ref_masks = []
+
+        for channel in ref_channels:
+            volume = self._load_and_correct(timepoint, camera, channel)
+
+            if self.config.segment:
+                # generate mask
+                mask = segment_foreground(
+                    volume,
+                    self.config.gauss_sigma,
+                    self.config.gauss_kernel,
+                    self.config.segment_threshold,
+                    self.config.mask_percentile,
+                    self.config.scaling,
+                    self.config.splitting,
+                    self.config.subsample_factor,
+                    verbose=True,
+                )
+                ref_masks.append(mask)
+
+                # apply mask
+                volume = apply_mask(volume, mask)
+
+            ref_volumes.append(volume)
+
+            # save reference volume and get path for consolidated mode
+            base_zarr_path = self._save_volume(timepoint, camera, channel, volume, output_dir)
+
+        # fuse masks if multiple references
+        if len(ref_masks) > 1:
+            fused_mask = fuse_masks(ref_masks)
+        elif ref_masks:
+            fused_mask = ref_masks[0]
+        else:
+            fused_mask = None
+
+        # save mask and coordinate masks
+        if fused_mask is not None and self.config.segment:
+            # Determine camera_subpath for consolidated mode
+            camera_subpath = None
+            if self.config.zarr_consolidate and self.config.output_format == "zarr":
+                camera_subpath = f"camera_{camera}"
+            self._save_mask(timepoint, camera, ref_channels[0], fused_mask, output_dir, base_zarr_path, camera_subpath)
+
+        # process dependent channels
+        for channel in dep_channels:
+            volume = self._load_and_correct(timepoint, camera, channel)
+
+            if fused_mask is not None:
+                volume = apply_mask(volume, fused_mask)
+
+            self._save_volume(timepoint, camera, channel, volume, output_dir)
+
+    def _load_and_correct(
+        self,
+        timepoint: int,
+        camera: int,
+        channel: int,
+    ) -> np.ndarray:
+        """Load volume and apply corrections."""
+        # find stack file
+        stack_path = find_stack_file(
+            self.config.input_dir,
+            self.config.specimen,
+            timepoint,
+            camera,
+            channel,
+            self.structure,
+        )
+
+        volume = read_volume(stack_path)
+
+        crop_top = self.config.crop_top[camera] if self.config.crop_top else 0
+        crop_left = self.config.crop_left[camera] if self.config.crop_left else 0
+        crop_height = self.config.crop_height[camera] if self.config.crop_height else None
+        crop_width = self.config.crop_width[camera] if self.config.crop_width else None
+        crop_front = self.config.crop_front[camera] if self.config.crop_front else 0
+        crop_depth = self.config.crop_depth[camera] if self.config.crop_depth else None
+
+        if crop_top or crop_left or crop_front or crop_height or crop_width or crop_depth:
+            volume = crop_volume(
+                volume,
+                top=crop_top,
+                left=crop_left,
+                height=crop_height,
+                width=crop_width,
+                front=crop_front,
+                depth=crop_depth,
+            )
+
+        # apply rotation
+        if self.config.rotation != 0:
+            volume = rotate_volume(volume, self.config.rotation)
+
+        # apply flips to second camera in each pair
+        if self.config.is_second_in_pair(camera):
+            if self.config.flip_horizontal or self.config.flip_vertical:
+                volume = flip_volume(
+                    volume,
+                    self.config.flip_horizontal,
+                    self.config.flip_vertical,
+                )
+
+        if self.config.median_kernel is not None:
+            cam_idx = self.config.cameras.index(camera) if camera in self.config.cameras else 0
+            if cam_idx < len(self.background_values):
+                bg = self.background_values[cam_idx]
+            else:
+                bg = estimate_background(volume, percentile=3.0, subsample=self.config.subsample_factor)
+
+            volume = correct_dead_pixels(
+                volume,
+                bg,
+                self.config.median_kernel,
+            )
+
+        return volume
+
+    def _save_volume(
+        self,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        volume: np.ndarray,
+        output_dir: Path,
+    ) -> Path:
+        """Save processed volume and projection.
+
+        Returns:
+            Path to the main output file (for consolidated mode)
+        """
+        # Determine output path based on consolidate mode
+        if self.config.zarr_consolidate and self.config.output_format == "zarr":
+            # Multi-camera consolidated structure: header.zarr/camera_N/
+            data_header = self.metadata.get("data_header", "data")
+            base_filename = f"{data_header}_TM{timepoint:06d}_SPM{self.config.specimen:02d}.zarr"
+            main_path = output_dir / base_filename
+            camera_subpath = f"camera_{camera}"
+        else:
+            # Traditional single-file structure
+            filename = (
+                f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_"
+                f"CM{camera:02d}_CHN{channel:02d}{self.config.extension}"
+            )
+            main_path = output_dir / filename
+            camera_subpath = None
+
+        # Get camera-specific metadata if available
+        camera_metadata = self.per_camera_metadata.get(camera, {}).copy()
+
+        # Add min intensity to camera metadata
+        camera_metadata["min_intensity"] = float(np.min(volume))
+
+        write_volume(
+            volume,
+            main_path,
+            self.config.pixel_spacing,
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+            chunks=self.config.zarr_chunks,
+            shards=self.config.zarr_shards,
+            metadata=self.metadata,
+            camera_subpath=camera_subpath,
+            camera_metadata=camera_metadata,
+        )
+
+        # Setup consolidated structure if needed
+        if self.config.zarr_consolidate and self.config.output_format == "zarr":
+            setup_consolidated_zarr(main_path, self.metadata, camera_subpath)
+
+        # save xy projection
+        proj = np.max(volume, axis=0)
+
+        if self.config.zarr_consolidate and self.config.output_format == "zarr":
+            # Write projection into the consolidated file
+            write_to_consolidated_zarr(
+                main_path,
+                "projections/xy",
+                proj[np.newaxis, :, :],
+                pixel_spacing=self.config.pixel_spacing,
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                camera_subpath=camera_subpath,
+            )
+        else:
+            # Write as separate file
+            proj_filename = (
+                f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_"
+                f"CM{camera:02d}_CHN{channel:02d}.xyProjection{self.config.extension}"
+            )
+            write_volume(
+                proj[np.newaxis, :, :],
+                self.config.projection_dir / proj_filename,
+                self.config.pixel_spacing,
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                metadata=self.metadata,
+            )
+
+        return main_path
+
+    def _save_mask(
+        self,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        mask: np.ndarray,
+        output_dir: Path,
+        base_zarr_path: Optional[Path] = None,
+        camera_subpath: Optional[str] = None,
+    ) -> None:
+        """Save segmentation mask and coordinate masks.
+
+        Args:
+            timepoint: Timepoint index
+            camera: Camera index
+            channel: Channel index
+            mask: Segmentation mask array
+            output_dir: Output directory
+            base_zarr_path: Path to consolidated Zarr file (if consolidate mode)
+            camera_subpath: Optional camera subgroup path for multi-camera structure
+        """
+        prefix = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+
+        # Generate coordinate masks
+        xz_mask, xy_mask = create_coordinate_masks(mask, self.config.splitting)
+
+        if self.config.zarr_consolidate and self.config.output_format == "zarr" and base_zarr_path:
+            # Write masks into consolidated file
+            # Binary segmentation mask
+            write_to_consolidated_zarr(
+                base_zarr_path,
+                "labels/segmentation",
+                mask,
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                label_metadata={
+                    "version": "0.5",
+                    "colors": [
+                        {"label-value": 0, "rgba": [0, 0, 0, 0]},  # background: transparent
+                        {"label-value": 1, "rgba": [0, 255, 0, 128]},  # foreground: semi-transparent green
+                    ],
+                    "source": {"image": "../../0"},
+                },
+                camera_subpath=camera_subpath,
+            )
+            add_label_to_registry(base_zarr_path, "segmentation", camera_subpath)
+
+            # XZ coordinate mask
+            write_to_consolidated_zarr(
+                base_zarr_path,
+                "labels/xz_coords",
+                xz_mask[np.newaxis, :, :],
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                label_metadata={
+                    "version": "0.5",
+                    "source": {"image": "../../0"},
+                },
+                camera_subpath=camera_subpath,
+            )
+            add_label_to_registry(base_zarr_path, "xz_coords", camera_subpath)
+
+            # XY coordinate mask
+            write_to_consolidated_zarr(
+                base_zarr_path,
+                "labels/xy_coords",
+                xy_mask[np.newaxis, :, :],
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                label_metadata={
+                    "version": "0.5",
+                    "source": {"image": "../../0"},
+                },
+                camera_subpath=camera_subpath,
+            )
+            add_label_to_registry(base_zarr_path, "xy_coords", camera_subpath)
+
+        else:
+            # Write as separate files
+            mask_file = output_dir / f"{prefix}.segmentationMask{self.config.extension}"
+            write_volume(
+                mask,
+                mask_file,
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                metadata=self.metadata,
+            )
+
+            xz_file = output_dir / f"{prefix}.xzMask{self.config.extension}"
+            write_volume(
+                xz_mask[np.newaxis, :, :],
+                xz_file,
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                metadata=self.metadata,
+            )
+
+            xy_file = output_dir / f"{prefix}.xyMask{self.config.extension}"
+            write_volume(
+                xy_mask[np.newaxis, :, :],
+                xy_file,
+                compression=self.config.zarr_compression,
+                compression_level=self.config.zarr_compression_level,
+                chunks=self.config.zarr_chunks,
+                shards=self.config.zarr_shards,
+                metadata=self.metadata,
+            )
+
+    def process_all(self) -> None:
+        """Process all timepoints."""
+        for timepoint in self.config.timepoints:
+            self.process_timepoint(timepoint)
+
+    def process_single_timepoint(self, timepoint: int) -> None:
+        """Process single timepoint.
+
+        Args:
+            timepoint: timepoint index to process
+        """
+        # create output subdirectory
+        output_subdir = self.config.output_dir / f"TM{timepoint:06d}"
+        output_subdir.mkdir(exist_ok=True, parents=True)
+
+        # load global mask if segment_mode == 3
+        global_mask = None
+        if self.config.segment_mode == 3:
+            # search for global mask in any supported format
+            global_mask_path = None
+            for ext in [".klb", ".zarr", ".tif", ".tiff"]:
+                candidate = self.config.global_mask_dir / f"Global.segmentationMask{ext}"
+                if candidate.exists():
+                    global_mask_path = candidate
+                    break
+            if global_mask_path is not None:
+                global_mask = read_volume(global_mask_path)
+            else:
+                raise FileNotFoundError(
+                    f"global mask not found in {self.config.global_mask_dir} "
+                    "(tried .klb, .zarr, .tif, .tiff)"
+                )
+
+        if self.config.reference_channels is not None:
+            ref_groups = self.config.reference_channels
+            dep_groups = self.config.dependent_channels or [[] for _ in ref_groups]
+        else:
+            # each channel is independent reference
+            ref_groups = [[ch] for ch in self.config.channels]
+            dep_groups = [[] for _ in self.config.channels]
+
+        # process each camera
+        for cam_idx, camera in enumerate(self.config.cameras):
+            self._process_single_camera(
+                timepoint, camera, cam_idx, output_subdir,
+                ref_groups, dep_groups, global_mask
+            )
+
+    def _process_single_camera(
+        self,
+        timepoint: int,
+        camera: int,
+        cam_idx: int,
+        output_dir: Path,
+        ref_groups: list[list[int]],
+        dep_groups: list[list[int]],
+        global_mask: Optional[np.ndarray],
+    ) -> None:
+        """Process single camera."""
+        # get the valid channel for this camera from the mapping
+        valid_channel = self.config.camera_channel_map.get(camera)
+
+        # process each reference group, but only if it matches the camera's channel
+        for r_idx, (ref_channels, dep_channels) in enumerate(zip(ref_groups, dep_groups)):
+            # filter ref_channels to only include the valid channel for this camera
+            filtered_refs = [ch for ch in ref_channels if ch == valid_channel]
+            filtered_deps = [ch for ch in dep_channels if ch == valid_channel]
+
+            if not filtered_refs:
+                # no valid channels for this camera in this group
+                continue
+
+            self._process_single_channel_group(
+                timepoint, camera, cam_idx, output_dir,
+                filtered_refs, filtered_deps, global_mask
+            )
+
+    def _process_single_channel_group(
+        self,
+        timepoint: int,
+        camera: int,
+        cam_idx: int,
+        output_dir: Path,
+        ref_channels: list[int],
+        dep_channels: list[int],
+        global_mask: Optional[np.ndarray],
+    ) -> None:
+        """Process channel group."""
+        ref_stacks = []
+        ref_masks = []
+
+        for channel in ref_channels:
+            stack = self._load_and_preprocess(timepoint, camera, cam_idx, channel)
+
+            subsampled = stack.ravel()[::self.config.subsample_factor]
+            subsampled = subsampled[subsampled > 0]
+            min_intensity_stack = percentile_interp(subsampled, self.config.background_percentile)
+
+            # generate segmentation mask if needed
+            if self.config.segment_mode in (1, 2):
+                mask = segment_foreground(
+                    stack,
+                    kernel_sigma=self.config.gauss_sigma,
+                    kernel_size=self.config.gauss_kernel,
+                    threshold=self.config.segment_threshold,
+                    mask_percentile=self.config.mask_percentile,
+                    scaling=self.config.scaling,
+                    splitting=self.config.splitting,
+                    subsample_factor=self.config.subsample_factor,
+                    verbose=True,
+                )
+                ref_masks.append(mask)
+
+                # save min intensity for both mask and stack
+                min_intensity_mask = percentile_interp(
+                    mask.ravel()[::self.config.subsample_factor],
+                    self.config.mask_percentile
+                )
+                min_intensity = np.array([min_intensity_mask, min_intensity_stack])
+            else:
+                min_intensity = min_intensity_stack
+
+            # save min intensity
+            self._save_min_intensity(output_dir, timepoint, camera, channel, min_intensity)
+
+            ref_stacks.append(stack)
+
+        # fuse masks if multiple references
+        if len(ref_masks) > 1 and self.config.segment_mode in (1, 2):
+            fused_mask = fuse_masks(ref_masks)
+        elif ref_masks:
+            fused_mask = ref_masks[0]
+        else:
+            fused_mask = None
+
+        # build master channel list (refs + deps)
+        master_list = list(ref_channels) + list(dep_channels)
+
+        # save segmentation mask
+        if self.config.segment_mode in (1, 2) and fused_mask is not None:
+            self._save_segmentation_mask_file(
+                output_dir, timepoint, camera, master_list[0], fused_mask
+            )
+            # copy to other channels
+            if len(master_list) > 1 and self.config.segment_mode == 1:
+                for other_ch in master_list[1:]:
+                    self._copy_mask_file(output_dir, timepoint, camera, master_list[0], other_ch)
+
+        # skip volume saving if segment_mode == 2 (masks only)
+        if self.config.segment_mode == 2:
+            return
+
+        # apply mask and save reference stacks
+        for stack, channel in zip(ref_stacks, ref_channels):
+            # apply mask
+            if self.config.segment_mode == 1 and fused_mask is not None:
+                stack = apply_mask(stack, fused_mask)
+            elif self.config.segment_mode == 3 and global_mask is not None:
+                stack = apply_mask(stack, global_mask)
+
+            # save volume
+            self._save_volume_file(output_dir, timepoint, camera, channel, stack)
+
+            # save xy projection
+            projection = np.max(stack, axis=0)
+            self._save_projection_file(timepoint, camera, channel, projection)
+
+        # generate and save coordinate masks
+        if self.config.segment_mode == 1 and fused_mask is not None:
+            xz_mask, xy_mask = create_coordinate_masks(fused_mask, self.config.splitting)
+            self._save_coordinate_masks(output_dir, timepoint, camera, master_list[0], xz_mask, xy_mask)
+            # copy to other channels
+            if len(master_list) > 1:
+                for other_ch in master_list[1:]:
+                    self._copy_coord_masks(output_dir, timepoint, camera, master_list[0], other_ch)
+
+        for channel in dep_channels:
+            stack = self._load_and_preprocess(timepoint, camera, cam_idx, channel)
+
+            subsampled = stack.ravel()[::self.config.subsample_factor]
+            subsampled = subsampled[subsampled > 0]
+            min_intensity = percentile_interp(subsampled, self.config.background_percentile)
+            self._save_min_intensity(output_dir, timepoint, camera, channel, min_intensity)
+
+            # apply mask
+            if self.config.segment_mode == 1 and fused_mask is not None:
+                stack = apply_mask(stack, fused_mask)
+            elif self.config.segment_mode == 3 and global_mask is not None:
+                stack = apply_mask(stack, global_mask)
+
+            # save volume
+            self._save_volume_file(output_dir, timepoint, camera, channel, stack)
+
+            # save xy projection
+            projection = np.max(stack, axis=0)
+            self._save_projection_file(timepoint, camera, channel, projection)
+
+    def _load_and_preprocess(
+        self,
+        timepoint: int,
+        camera: int,
+        cam_idx: int,
+        channel: int,
+    ) -> np.ndarray:
+        """Load stack and apply preprocessing (crop, rotate, flip, dead pixel correction)."""
+        # find and read stack
+        stack_path = find_stack_file(
+            self.config.input_dir,
+            self.config.specimen,
+            timepoint,
+            camera,
+            channel,
+            self.structure,
+        )
+        stack = read_volume(stack_path)
+
+        # apply cropping (uses cam_idx to index into per-camera arrays, supports partial params)
+        crop_top = self.config.crop_top[cam_idx] if self.config.crop_top else 0
+        crop_left = self.config.crop_left[cam_idx] if self.config.crop_left else 0
+        crop_height = self.config.crop_height[cam_idx] if self.config.crop_height else None
+        crop_width = self.config.crop_width[cam_idx] if self.config.crop_width else None
+        crop_front = self.config.crop_front[cam_idx] if self.config.crop_front else 0
+        crop_depth = self.config.crop_depth[cam_idx] if self.config.crop_depth else None
+
+        if crop_top or crop_left or crop_front or crop_height or crop_width or crop_depth:
+            stack = crop_volume(
+                stack,
+                top=crop_top,
+                left=crop_left,
+                height=crop_height,
+                width=crop_width,
+                front=crop_front,
+                depth=crop_depth,
+            )
+
+        # apply rotation
+        if self.config.rotation != 0:
+            stack = rotate_volume(stack, self.config.rotation)
+
+        # apply flips to second camera in each pair
+        if self.config.is_second_in_pair(camera):
+            if self.config.flip_horizontal or self.config.flip_vertical:
+                stack = flip_volume(stack, self.config.flip_horizontal, self.config.flip_vertical)
+
+        if self.config.median_kernel is not None:
+            if cam_idx < len(self.background_values):
+                bg = self.background_values[cam_idx]
+            else:
+                bg = estimate_background(stack, percentile=3.0, subsample=self.config.subsample_factor)
+            stack = correct_dead_pixels(stack, bg, self.config.median_kernel)
+
+        return stack
+
+    def _save_min_intensity(
+        self,
+        output_dir: Path,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        min_intensity,
+    ) -> None:
+        """Save min intensity to npz file."""
+        filename = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}.minIntensity.npz"
+        np.savez(output_dir / filename, min_intensity=min_intensity)
+
+    def _save_segmentation_mask_file(
+        self,
+        output_dir: Path,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        mask: np.ndarray,
+    ) -> None:
+        """Save segmentation mask."""
+        prefix = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+        write_volume(
+            mask,
+            output_dir / f"{prefix}.segmentationMask{self.config.extension}",
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+    def _copy_mask_file(
+        self,
+        output_dir: Path,
+        timepoint: int,
+        camera: int,
+        src_channel: int,
+        dst_channel: int,
+    ) -> None:
+        """Copy mask file to another channel."""
+        prefix_src = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{src_channel:02d}"
+        prefix_dst = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{dst_channel:02d}"
+        src = output_dir / f"{prefix_src}.segmentationMask{self.config.extension}"
+        dst = output_dir / f"{prefix_dst}.segmentationMask{self.config.extension}"
+        if src.exists():
+            if src.is_dir():
+                shutil.copytree(src, dst, dirs_exist_ok=True)
+            else:
+                shutil.copy2(src, dst)
+
+    def _save_coordinate_masks(
+        self,
+        output_dir: Path,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        xz_mask: np.ndarray,
+        xy_mask: np.ndarray,
+    ) -> None:
+        """Save xz and xy coordinate masks."""
+        prefix = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+
+        write_volume(
+            xz_mask[np.newaxis, :, :],
+            output_dir / f"{prefix}.xzMask{self.config.extension}",
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+        write_volume(
+            xy_mask[np.newaxis, :, :],
+            output_dir / f"{prefix}.xyMask{self.config.extension}",
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+    def _copy_coord_masks(
+        self,
+        output_dir: Path,
+        timepoint: int,
+        camera: int,
+        src_channel: int,
+        dst_channel: int,
+    ) -> None:
+        """Copy coordinate mask files to another channel."""
+        prefix_src = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{src_channel:02d}"
+        prefix_dst = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{dst_channel:02d}"
+
+        for mask_type in ["xzMask", "xyMask"]:
+            src = output_dir / f"{prefix_src}.{mask_type}{self.config.extension}"
+            dst = output_dir / f"{prefix_dst}.{mask_type}{self.config.extension}"
+            if src.exists():
+                if src.is_dir():
+                    shutil.copytree(src, dst, dirs_exist_ok=True)
+                else:
+                    shutil.copy2(src, dst)
+
+    def _save_volume_file(
+        self,
+        output_dir: Path,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        volume: np.ndarray,
+    ) -> None:
+        """Save processed volume."""
+        prefix = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+        write_volume(
+            volume,
+            output_dir / f"{prefix}{self.config.extension}",
+            pixel_spacing=self.config.pixel_spacing,
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+            chunks=self.config.zarr_chunks,
+            shards=self.config.zarr_shards,
+            metadata=self.metadata,
+        )
+
+    def _save_projection_file(
+        self,
+        timepoint: int,
+        camera: int,
+        channel: int,
+        projection: np.ndarray,
+    ) -> None:
+        """Save xy projection."""
+        self.config.projection_dir.mkdir(parents=True, exist_ok=True)
+        prefix = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+        write_volume(
+            projection[np.newaxis, :, :],
+            self.config.projection_dir / f"{prefix}.xyProjection{self.config.extension}",
+            pixel_spacing=self.config.pixel_spacing,
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+    def run(self) -> None:
+        """Process all timepoints."""
+        n_timepoints = len(self.config.timepoints)
+        print(f"processing {n_timepoints} timepoints: {self.config.timepoints[0]} to {self.config.timepoints[-1]}")
+        print(f"cameras: {self.config.cameras}, channels: {self.config.channels}")
+        print(f"segment_mode: {self.config.segment_mode}, output: {self.config.output_format}")
+        print("-" * 60)
+
+        total_start = time.time()
+        timepoint_times = []
+
+        for i, timepoint in enumerate(self.config.timepoints):
+            tp_start = time.time()
+            print(f"[{i+1}/{n_timepoints}] timepoint {timepoint:04d}\n", end="", flush=True)
+
+            self.process_single_timepoint(timepoint)
+
+            tp_elapsed = time.time() - tp_start
+            timepoint_times.append(tp_elapsed)
+            print(f" - {tp_elapsed:.1f}s")
+
+        total_elapsed = time.time() - total_start
+        avg_time = total_elapsed / n_timepoints if n_timepoints > 0 else 0
+
+        print("-" * 60)
+        print(f"completed {n_timepoints} timepoints in {total_elapsed:.1f}s ({avg_time:.2f}s/timepoint)")
+
+        # generate global mask if segment_mode == 2
+        if self.config.segment_mode == 2:
+            self.generate_global_mask()
+
+    def generate_global_mask(self) -> None:
+        """Generate global segmentation mask from individual timepoint masks."""
+        print("generating global segmentation mask")
+        self.config.global_mask_dir.mkdir(parents=True, exist_ok=True)
+
+        global_mask = None
+        mask_count = 0
+
+        for timepoint in self.config.timepoints:
+            mask_dir = self.config.output_dir / f"TM{timepoint:06d}"
+
+            for camera in self.config.cameras:
+                # determine which channels have masks
+                if self.config.reference_channels is not None:
+                    channels_to_check = [ref[0] for ref in self.config.reference_channels]
+                else:
+                    channels_to_check = self.config.channels
+
+                for channel in channels_to_check:
+                    prefix = f"SPM{self.config.specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+                    mask_path = mask_dir / f"{prefix}.segmentationMask{self.config.extension}"
+
+                    if mask_path.exists():
+                        print(f"reading mask: {mask_path.name}")
+                        mask = read_volume(mask_path)
+
+                        if global_mask is None:
+                            global_mask = mask == 1
+                        else:
+                            global_mask = global_mask | (mask == 1)
+
+                        mask_count += 1
+
+        if global_mask is None:
+            print("no masks found")
+            return
+
+        print(f"total masks read: {mask_count}")
+
+        # save global mask
+        global_mask_uint16 = global_mask.astype(np.uint16)
+        write_volume(
+            global_mask_uint16,
+            self.config.global_mask_dir / f"Global.segmentationMask{self.config.extension}",
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+        # generate and save coordinate masks
+        xz_mask, xy_mask = create_coordinate_masks(global_mask_uint16, self.config.splitting)
+
+        write_volume(
+            xz_mask[np.newaxis, :, :],
+            self.config.global_mask_dir / f"Global.xzMask{self.config.extension}",
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+        write_volume(
+            xy_mask[np.newaxis, :, :],
+            self.config.global_mask_dir / f"Global.xyMask{self.config.extension}",
+            compression=self.config.zarr_compression,
+            compression_level=self.config.zarr_compression_level,
+        )
+
+        print("global mask saved")
+
+
+def process_timepoint(config: ProcessingConfig) -> None:
+    """Process all timepoints in config (matches MATLAB processTimepoint)."""
+    processor = IsoviewProcessor(config)
+    processor.run()
+
+
+def process_dataset(config: ProcessingConfig) -> None:
+    processor = IsoviewProcessor(config)
+    processor.process_all()