isoview 0.1.0__py3-none-any.whl

isoview/io.py

@@ -0,0 +1,942 @@
+"""I/O operations for microscopy data."""
+
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import pyklb
+import tifffile
+import xmltodict
+
+
+CAMERA_PIXEL_SIZE = 6.5
+
+def read_volume(path: Path, dimensions: Optional[tuple[int, int, int]] = None) -> np.ndarray:
+    """Read 3D volume from file (klb, tiff, zarr, or stack).
+
+    Args:
+        path: file path
+        dimensions: (width, height, depth) required for .stack files (MATLAB convention)
+    """
+    path = Path(path)
+
+    if path.suffix == ".klb":
+        volume = pyklb.readfull(str(path))
+    elif path.suffix == ".zarr":
+        try:
+            import zarr
+        except ImportError as e:
+            raise ImportError(
+                "zarr required for .zarr format. "
+                "Install with: uv pip install 'isoview[parallel]'"
+            ) from e
+
+        # open zarr array (supports both ome-zarr and plain zarr)
+        store = zarr.storage.LocalStore(str(path))
+        root = zarr.open_group(store=store, mode="r")
+
+        # for ome-zarr, data is in resolution level "0"
+        if "0" in root:
+            arr = root["0"]
+        else:
+            # plain zarr array at root
+            arr = zarr.open_array(store=store, mode="r")
+
+        volume = arr[:]
+    elif path.suffix in (".tif", ".tiff"):
+        volume = tifffile.imread(path)
+    elif path.suffix == ".stack":
+        # get height and width from xml, calculate depth from file size
+        if dimensions is None:
+            xml_path = _find_xml_for_stack(path)
+            if xml_path:
+                metadata = read_xml_metadata(xml_path)
+                if "dimensions" in metadata:
+                    dims = metadata["dimensions"]
+                    if dims.ndim > 1:
+                        dims = dims[0]
+                    dimensions = tuple(dims)
+
+        if dimensions is None:
+            raise ValueError(f"dimensions required for .stack file: {path}")
+
+        # calculate actual depth from file size
+        # dimensions from XML are [width, height, depth] (MATLAB convention)
+        width, height, _ = dimensions
+        file_size = path.stat().st_size
+        total_pixels = file_size // 2  # uint16 = 2 bytes
+        depth = total_pixels // (height * width)
+
+        # read binary stack (uint16, bsq format, little-endian)
+        # bsq stores band-sequential: each z-slice stored row by row (y then x)
+        volume = np.fromfile(path, dtype=np.uint16)
+        volume = volume.reshape((depth, height, width))  # (z, y, x)
+    else:
+        raise ValueError(f"unsupported format: {path.suffix}")
+
+    return volume
+
+
+def _find_xml_for_stack(stack_path: Path) -> Optional[Path]:
+    """Find associated XML metadata file for a stack file."""
+    # try same directory with channel xml
+    parent = stack_path.parent
+    xml_files = list(parent.glob("*.xml"))
+    if xml_files:
+        return xml_files[0]
+
+    # try parent directories
+    for _ in range(2):
+        parent = parent.parent
+        xml_files = list(parent.glob("*.xml"))
+        if xml_files:
+            return xml_files[0]
+
+    return None
+
+
+def write_volume(
+    volume: np.ndarray,
+    path: Path,
+    pixel_spacing: Optional[np.ndarray] = None,
+    compression: Optional[str] = "blosc-zstd",
+    compression_level: int = 5,
+    chunks: Optional[tuple[int, int, int]] = None,
+    shards: Optional[tuple[int, int, int]] = None,
+    metadata: Optional[dict] = None,
+    camera_subpath: Optional[str] = None,
+    camera_metadata: Optional[dict] = None,
+) -> None:
+    """Write 3D volume to file (klb, tiff, or zarr).
+
+    Args:
+        volume: 3D array (z, y, x)
+        path: output file path
+        pixel_spacing: physical spacing in micrometers [z, y, x]
+        compression: compression type for zarr
+            - 'blosc-zstd': Blosc with Zstandard
+            - 'blosc-lz4': Blosc with LZ4
+            - 'blosc-lz4hc': Blosc with LZ4HC
+            - 'gzip': Standard gzip compression
+            - None: No compression (fastest I/O, largest files)
+        compression_level: compression level (0-9, higher = more compression)
+        chunks: inner chunk shape for zarr (z, y, x)
+            - With sharding: size of individually accessible sub-chunks
+            - Without sharding: standard chunk size
+            - Default with sharding: (1, full_y, full_x) - one frame per chunk
+            - Default without sharding: (10, 128, 128)
+        shards: outer chunk/shard shape for zarr (z, y, x)
+            - Enables Zarr v3 sharding to reduce file count
+            - Groups multiple chunks into single storage objects
+            - Recommended: (10, full_y, full_x) - 10 frames per shard file
+            - None: disables sharding (default)
+        metadata: common microscope metadata dictionary (written to root)
+        camera_subpath: optional camera subgroup path (e.g., "camera_0") for multi-camera consolidated zarr
+        camera_metadata: optional camera-specific metadata (written to camera subgroup)
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if path.suffix == ".zarr":
+        try:
+            import zarr
+            from zarr.codecs import BloscCodec, GzipCodec, BZ2
+        except ImportError as e:
+            raise ImportError(
+                "zarr required for .zarr format. "
+                "Install with: uv pip install 'isoview[parallel]'"
+            ) from e
+
+        # auto-calculate chunks and shards if not provided
+        if chunks is None:
+            if shards is not None:
+                # with sharding: use full-frame inner chunks for optimal planar access
+                chunks = (1, volume.shape[1], volume.shape[2])
+            else:
+                # without sharding: use smaller chunks
+                chunks = (
+                    min(10, volume.shape[0]),
+                    min(128, volume.shape[1]),
+                    min(128, volume.shape[2]),
+                )
+
+        # auto-enable sharding for large z-stacks if not explicitly disabled
+        if shards is None and volume.shape[0] >= 20:
+            # enable sharding: 10 frames per shard file, full FOV
+            shards = (10, volume.shape[1], volume.shape[2])
+            # ensure chunks is full-frame for sharded access
+            if chunks != (1, volume.shape[1], volume.shape[2]):
+                chunks = (1, volume.shape[1], volume.shape[2])
+
+        # build compressor list (zarr v3 uses compressors parameter, not codecs)
+        compressors = []
+
+        if compression == "blosc-zstd":
+            compressors.append(
+                BloscCodec(
+                    cname="zstd",
+                    clevel=compression_level,
+                    shuffle="bitshuffle",  # excellent for uint16
+                )
+            )
+        elif compression == "blosc-lz4":
+            compressors.append(
+                BloscCodec(
+                    cname="lz4",
+                    clevel=compression_level,
+                    shuffle="shuffle",
+                )
+            )
+        elif compression == "blosc-lz4hc":
+            compressors.append(
+                BloscCodec(
+                    cname="lz4hc",
+                    clevel=compression_level,
+                    shuffle="bitshuffle",
+                )
+            )
+        elif compression == "gzip":
+            compressors.append(GzipCodec(level=compression_level))
+        elif compression == "bzip2":
+            compressors.append(BZ2(level=compression_level))
+        elif compression is not None:
+            raise ValueError(
+                f"unsupported compression: {compression}. "
+                f"use 'blosc-zstd', 'blosc-lz4', 'blosc-lz4hc', 'gzip', 'bzip2', or None"
+            )
+
+        # create zarr store
+        store = zarr.storage.LocalStore(str(path))
+
+        # determine array path based on camera_subpath
+        if camera_subpath:
+            array_path = f"{camera_subpath}/0"
+        else:
+            array_path = "0"
+
+        # create array with optional sharding (use zarr.create_array for v3)
+        if shards is not None:
+            # validate that chunks evenly divide shards
+            for i, (shard_dim, chunk_dim) in enumerate(zip(shards, chunks)):
+                if shard_dim % chunk_dim != 0:
+                    raise ValueError(
+                        f"shard dimension {shard_dim} must be evenly divisible by "
+                        f"chunk dimension {chunk_dim} at axis {i}"
+                    )
+
+            # high-level API with sharding
+            arr = zarr.create_array(
+                store=store,
+                name=array_path,
+                shape=volume.shape,
+                shards=shards,  # outer chunks (shard size)
+                chunks=chunks,  # inner chunks (sub-chunk size)
+                dtype=volume.dtype,
+                compressors=compressors if compressors else None,
+                zarr_format=3,
+                overwrite=True,
+            )
+        else:
+            # standard zarr without sharding
+            arr = zarr.create_array(
+                store=store,
+                name=array_path,
+                shape=volume.shape,
+                chunks=chunks,
+                dtype=volume.dtype,
+                compressors=compressors if compressors else None,
+                zarr_format=3,
+                overwrite=True,
+            )
+
+        # write data
+        arr[:] = volume
+
+        # open group to add metadata
+        root = zarr.open_group(store=store, mode="r+")
+
+        # add ome-zarr metadata
+        if pixel_spacing is not None:
+            z_spacing, y_spacing, x_spacing = pixel_spacing[:3]
+        else:
+            z_spacing = y_spacing = x_spacing = 1.0
+
+        # Build multiscales metadata
+        multiscales_meta = {
+            "version": "0.5",
+            "axes": [
+                {"name": "z", "type": "space", "unit": "micrometer"},
+                {"name": "y", "type": "space", "unit": "micrometer"},
+                {"name": "x", "type": "space", "unit": "micrometer"},
+            ],
+            "datasets": [
+                {
+                    "path": "0",
+                    "coordinateTransformations": [
+                        {
+                            "type": "scale",
+                            "scale": [
+                                float(z_spacing),
+                                float(y_spacing),
+                                float(x_spacing),
+                            ],
+                        }
+                    ],
+                }
+            ],
+        }
+
+        # Add name from metadata if available
+        if metadata and "data_header" in metadata:
+            multiscales_meta["name"] = str(metadata["data_header"])
+
+        # Add metadata to appropriate group
+        if camera_subpath:
+            # Multi-camera mode: add multiscales to camera subgroup
+            camera_group = root[camera_subpath]
+            camera_group.attrs["multiscales"] = [multiscales_meta]
+
+            # Add common microscope metadata to root (once, shared across cameras)
+            # Only write if not already present
+            if metadata and "data_header" not in root.attrs:
+                for key, value in metadata.items():
+                    if isinstance(value, np.ndarray):
+                        root.attrs[key] = value.tolist()
+                    elif isinstance(value, (np.integer, np.floating)):
+                        root.attrs[key] = value.item()
+                    else:
+                        root.attrs[key] = value
+
+            # Add camera-specific metadata to camera subgroup
+            if camera_metadata:
+                for key, value in camera_metadata.items():
+                    if isinstance(value, np.ndarray):
+                        camera_group.attrs[key] = value.tolist()
+                    elif isinstance(value, (np.integer, np.floating)):
+                        camera_group.attrs[key] = value.item()
+                    else:
+                        camera_group.attrs[key] = value
+        else:
+            # Single-camera mode: add to root
+            root.attrs["multiscales"] = [multiscales_meta]
+
+            # Add microscope metadata directly to root attrs
+            if metadata:
+                # Convert numpy arrays to lists for JSON serialization
+                for key, value in metadata.items():
+                    if isinstance(value, np.ndarray):
+                        root.attrs[key] = value.tolist()
+                    elif isinstance(value, (np.integer, np.floating)):
+                        root.attrs[key] = value.item()
+                    else:
+                        root.attrs[key] = value
+
+    elif path.suffix == ".klb":
+        if pixel_spacing is not None:
+            spacing = [1.0, 1.0] + list(pixel_spacing[:3])
+        else:
+            spacing = [1.0, 1.0, 1.0, 1.0, 1.0]
+        pyklb.writefull(volume, str(path), pixelspacing_tczyx=spacing)
+
+    elif path.suffix in (".tif", ".tiff"):
+        metadata = {}
+        if pixel_spacing is not None:
+            # tiff resolution is pixels per unit, spacing is unit per pixel
+            metadata["resolution"] = (1.0 / pixel_spacing[0], 1.0 / pixel_spacing[1])
+            metadata["unit"] = "um"
+        tifffile.imwrite(path, volume, metadata=metadata)
+
+    else:
+        raise ValueError(f"unsupported format: {path.suffix}")
+
+
+def write_to_consolidated_zarr(
+    base_path: Path,
+    subpath: str,
+    volume: np.ndarray,
+    pixel_spacing: Optional[np.ndarray] = None,
+    compression: Optional[str] = "blosc-zstd",
+    compression_level: int = 9,
+    chunks: Optional[tuple[int, int, int]] = None,
+    shards: Optional[tuple[int, int, int]] = None,
+    label_metadata: Optional[dict] = None,
+    camera_subpath: Optional[str] = None,
+) -> None:
+    """Write array to a consolidated OME-Zarr structure.
+
+    Args:
+        base_path: Base Zarr group path (e.g., .../data_TM000000_SPM00.zarr)
+        subpath: Relative path within the Zarr group (e.g., "projections/xy", "labels/segmentation")
+        volume: Array data to write
+        pixel_spacing: Physical spacing in micrometers [z, y, x]
+        compression: Compression type
+        compression_level: Compression level (0-9)
+        chunks: Chunk shape
+        shards: Shard shape
+        label_metadata: Optional metadata for label images (colors, properties)
+        camera_subpath: Optional camera subgroup (e.g., "camera_0") for multi-camera structure
+    """
+    try:
+        import zarr
+        from zarr.codecs import BloscCodec, GzipCodec, BZ2
+    except ImportError as e:
+        raise ImportError(
+            "zarr required for consolidated output. "
+            "Install with: uv pip install 'isoview[parallel]'"
+        ) from e
+
+    # Open or create the base group
+    store = zarr.storage.LocalStore(str(base_path))
+    root = zarr.open_group(store=store, mode="a")
+
+    # Navigate to camera subgroup if specified
+    if camera_subpath:
+        if camera_subpath not in root:
+            root.create_group(camera_subpath)
+        base_group = root[camera_subpath]
+    else:
+        base_group = root
+
+    # Create subgroup structure
+    parts = subpath.split("/")
+    current_group = base_group
+    for part in parts[:-1]:
+        if part not in current_group:
+            current_group = current_group.create_group(part)
+        else:
+            current_group = current_group[part]
+
+    # Prepare compression codecs
+    compressors = []
+    if compression == "blosc-zstd":
+        compressors.append(
+            BloscCodec(cname="zstd", clevel=compression_level, shuffle="bitshuffle")
+        )
+    elif compression == "blosc-lz4":
+        compressors.append(
+            BloscCodec(cname="lz4", clevel=compression_level, shuffle="shuffle")
+        )
+    elif compression == "blosc-lz4hc":
+        compressors.append(
+            BloscCodec(cname="lz4hc", clevel=compression_level, shuffle="bitshuffle")
+        )
+    elif compression == "gzip":
+        compressors.append(GzipCodec(level=compression_level))
+    elif compression == "bzip2":
+        compressors.append(BZ2(level=compression_level))
+
+    # Auto-calculate chunks/shards
+    if chunks is None:
+        if shards is not None:
+            chunks = (1, volume.shape[1], volume.shape[2])
+        else:
+            chunks = (
+                min(10, volume.shape[0]),
+                min(128, volume.shape[1]),
+                min(128, volume.shape[2]),
+            )
+
+    if shards is None and volume.shape[0] >= 20:
+        shards = (10, volume.shape[1], volume.shape[2])
+        if chunks != (1, volume.shape[1], volume.shape[2]):
+            chunks = (1, volume.shape[1], volume.shape[2])
+
+    # Create array
+    array_name = parts[-1]
+
+    # Build full path from root
+    path_parts = []
+    if camera_subpath:
+        path_parts.append(camera_subpath)
+    path_parts.extend(parts[:-1])
+    path_parts.append(array_name)
+    path_parts.append("0")
+    full_array_path = "/".join(path_parts)
+
+    if shards is not None:
+        arr = zarr.create_array(
+            store=store,
+            name=full_array_path,
+            shape=volume.shape,
+            shards=shards,
+            chunks=chunks,
+            dtype=volume.dtype,
+            compressors=compressors if compressors else None,
+            zarr_format=3,
+            overwrite=True,
+        )
+    else:
+        arr = zarr.create_array(
+            store=store,
+            name=full_array_path,
+            shape=volume.shape,
+            chunks=chunks,
+            dtype=volume.dtype,
+            compressors=compressors if compressors else None,
+            zarr_format=3,
+            overwrite=True,
+        )
+
+    # Write data
+    arr[:] = volume
+
+    # Add metadata to the array's parent group
+    if array_name not in current_group:
+        array_group = current_group.create_group(array_name)
+    else:
+        array_group = current_group[array_name]
+
+    # Add multiscales metadata (for images and projections, not labels)
+    if pixel_spacing is not None:
+        z_spacing, y_spacing, x_spacing = pixel_spacing[:3]
+    else:
+        z_spacing = y_spacing = x_spacing = 1.0
+
+    # Don't add multiscales for labels (they use image-label instead)
+    if not label_metadata:
+        array_group.attrs["multiscales"] = [
+            {
+                "version": "0.5",
+                "axes": [
+                    {"name": "z", "type": "space", "unit": "micrometer"},
+                    {"name": "y", "type": "space", "unit": "micrometer"},
+                    {"name": "x", "type": "space", "unit": "micrometer"},
+                ],
+                "datasets": [
+                    {
+                        "path": "0",
+                        "coordinateTransformations": [
+                            {"type": "scale", "scale": [float(z_spacing), float(y_spacing), float(x_spacing)]}
+                        ],
+                    }
+                ],
+            }
+        ]
+
+    # Add label metadata if provided
+    if label_metadata:
+        array_group.attrs["image-label"] = label_metadata
+
+
+def setup_consolidated_zarr(
+    base_path: Path,
+    metadata: Optional[dict] = None,
+    camera_subpath: Optional[str] = None,
+) -> None:
+    """Initialize a consolidated OME-Zarr file with proper structure.
+
+    Creates the base group with metadata and prepares for labels/projections.
+
+    Args:
+        base_path: Path to the .zarr file
+        metadata: Microscope metadata dictionary
+        camera_subpath: Optional camera subgroup (e.g., "camera_0") for multi-camera structure
+    """
+    try:
+        import zarr
+    except ImportError as e:
+        raise ImportError(
+            "zarr required for consolidated output. "
+            "Install with: uv pip install 'isoview[parallel]'"
+        ) from e
+
+    store = zarr.storage.LocalStore(str(base_path))
+    root = zarr.open_group(store=store, mode="a")
+
+    # Navigate to camera subgroup if specified
+    if camera_subpath:
+        if camera_subpath not in root:
+            root.create_group(camera_subpath)
+        base_group = root[camera_subpath]
+    else:
+        base_group = root
+
+    # Create labels group
+    if "labels" not in base_group:
+        labels_group = base_group.create_group("labels")
+        labels_group.attrs["labels"] = []  # Will be populated as labels are added
+
+    # Create projections group (custom, not part of OME-Zarr spec but useful)
+    if "projections" not in base_group:
+        base_group.create_group("projections")
+
+    # Add microscope metadata to root (shared across cameras, only write once)
+    if metadata and "data_header" not in root.attrs:
+        for key, value in metadata.items():
+            if isinstance(value, np.ndarray):
+                root.attrs[key] = value.tolist()
+            elif isinstance(value, (np.integer, np.floating)):
+                root.attrs[key] = value.item()
+            else:
+                root.attrs[key] = value
+
+
+def add_label_to_registry(
+    base_path: Path,
+    label_name: str,
+    camera_subpath: Optional[str] = None,
+) -> None:
+    """Add a label to the labels registry in OME-Zarr.
+
+    Args:
+        base_path: Path to the .zarr file
+        label_name: Name of the label (e.g., "segmentation", "xz_mask")
+        camera_subpath: Optional camera subgroup (e.g., "camera_0") for multi-camera structure
+    """
+    try:
+        import zarr
+    except ImportError:
+        return
+
+    store = zarr.storage.LocalStore(str(base_path))
+    root = zarr.open_group(store=store, mode="a")
+
+    # Navigate to camera subgroup if specified
+    if camera_subpath:
+        if camera_subpath in root:
+            base_group = root[camera_subpath]
+        else:
+            return
+    else:
+        base_group = root
+
+    if "labels" in base_group:
+        labels_group = base_group["labels"]
+        current_labels = list(labels_group.attrs.get("labels", []))
+        if label_name not in current_labels:
+            current_labels.append(label_name)
+            labels_group.attrs["labels"] = current_labels
+
+
+def read_all_xml_metadata(input_dir: Path, specimen: int) -> tuple[dict, dict]:
+    """Read and merge metadata from all XML files for a specimen.
+
+    Args:
+        input_dir: Root directory containing specimen data
+        specimen: Specimen number
+
+    Returns:
+        Tuple of (common_metadata, per_camera_metadata) where:
+        - common_metadata: Metadata that's the same across all cameras
+        - per_camera_metadata: Dict mapping camera index to camera-specific metadata
+    """
+    # Find all XML files for this specimen
+    xml_files = []
+
+    # Check SPM00/ch*.xml pattern
+    spm_dir = input_dir / f"SPM{specimen:02d}"
+    if spm_dir.exists():
+        xml_files.extend(sorted(spm_dir.glob("ch*.xml")))
+
+    # Fallback: check root level
+    if not xml_files:
+        xml_files.extend(sorted(input_dir.glob(f"*spec{specimen:02d}*.xml")))
+
+    if not xml_files:
+        return {}, {}
+
+    # Read all XML files
+    all_metadata = []
+    for xml_file in xml_files:
+        try:
+            meta = read_xml_metadata(xml_file)
+            all_metadata.append(meta)
+        except Exception as e:
+            print(f"Warning: Failed to read {xml_file}: {e}")
+            continue
+
+    if not all_metadata:
+        return {}, {}
+
+    # Separate common and per-camera metadata
+    common_metadata = {}
+    per_camera_metadata = {}
+
+    # Get all keys from all metadata dicts
+    all_keys = set()
+    for meta in all_metadata:
+        all_keys.update(meta.keys())
+
+    # Helper function to check if values are equal
+    def values_equal(v1, v2):
+        if isinstance(v1, np.ndarray) and isinstance(v2, np.ndarray):
+            return v1.shape == v2.shape and np.allclose(v1, v2)
+        return v1 == v2
+
+    for key in all_keys:
+        # Collect values for this key across all cameras
+        values = [meta.get(key) for meta in all_metadata if key in meta]
+
+        if not values:
+            continue
+
+        # Check if all values are the same
+        all_same = all(values_equal(values[0], v) for v in values[1:])
+
+        if all_same:
+            # Same across all cameras - add to common metadata
+            common_metadata[key] = values[0]
+        else:
+            # Different across cameras - add to per-camera metadata
+            for i, meta in enumerate(all_metadata):
+                if key in meta:
+                    if i not in per_camera_metadata:
+                        per_camera_metadata[i] = {}
+                    per_camera_metadata[i][key] = meta[key]
+
+    return common_metadata, per_camera_metadata
+
+
+def read_xml_metadata(xml_path: Path) -> dict:
+    """Parse microscope metadata from xml file.
+
+    Returns dictionary with both raw and calculated metadata fields.
+    """
+    with open(xml_path, "r") as f:
+        data = xmltodict.parse(f.read())
+
+    metadata = {}
+
+    # handle push_config format
+    config = data.get("push_config", {})
+    info_list = config.get("info", [])
+    if not isinstance(info_list, list):
+        info_list = [info_list]
+
+    # parse all info elements
+    for info in info_list:
+        # original fields to keep
+        if "@data_header" in info:
+            metadata["data_header"] = info["@data_header"]
+        if "@specimen_name" in info:
+            metadata["specimen_name"] = info["@specimen_name"]
+        if "@timestamp" in info:
+            metadata["timestamp"] = info["@timestamp"]
+        if "@time_point" in info:
+            metadata["time_point"] = int(info["@time_point"])
+        if "@specimen_XYZT" in info:
+            metadata["specimen_XYZT"] = info["@specimen_XYZT"]
+        if "@angle" in info:
+            metadata["angle"] = float(info["@angle"])
+        if "@camera_index" in info:
+            metadata["camera_index"] = info["@camera_index"]
+        if "@camera_type" in info:
+            metadata["camera_type"] = info["@camera_type"]
+        if "@camera_roi" in info:
+            metadata["camera_roi"] = info["@camera_roi"]
+        if "@wavelength" in info:
+            metadata["wavelength"] = info["@wavelength"]
+        if "@illumination_arms" in info:
+            metadata["illumination_arms"] = info["@illumination_arms"]
+        if "@illumination_filter" in info:
+            metadata["illumination_filter"] = info["@illumination_filter"]
+        if "@exposure_time" in info:
+            exposure_time = float(info["@exposure_time"])
+            metadata["exposure_time"] = exposure_time
+        if "@detection_filter" in info:
+            metadata["detection_filter"] = info["@detection_filter"]
+        if "@dimensions" in info:
+            dims_str = info["@dimensions"]
+            # split by comma for multiple cameras
+            camera_dims = []
+            for cam_dims in dims_str.split(","):
+                dims = [int(x) for x in cam_dims.strip().split("x")]
+                if len(dims) == 3:
+                    camera_dims.append(dims)
+            if camera_dims:
+                metadata["dimensions"] = np.array(camera_dims)
+        if "@z_step" in info:
+            metadata["z_step"] = float(info["@z_step"])
+        if "@detection_objective" in info:
+            metadata["detection_objective"] = info["@detection_objective"]
+            obj_str = info["@detection_objective"].split(",")[0]  # first camera
+            # Extract magnification: look for number followed by 'x'
+            # e.g., "SpecialOptics 16x/0.70" -> 16
+            import re
+            mag_match = re.search(r'(\d+(?:\.\d+)?)x', obj_str, re.IGNORECASE)
+            if mag_match:
+                metadata["objective_mag"] = float(mag_match.group(1))
+
+    # calculate derived fields
+    if "dimensions" in metadata:
+        dims = metadata["dimensions"]
+        if dims.ndim > 1:
+            dims = dims[0]  # use first camera
+        metadata["zplanes"] = int(dims[-1])
+
+    if "exposure_time" in metadata and "zplanes" in metadata:
+        # fps = 1000 / exposure_time_ms
+        metadata["fps"] = 1000.0 / metadata["exposure_time"]
+        # vps = fps / zplanes (volumes per second)
+        metadata["vps"] = metadata["fps"] / metadata["zplanes"]
+
+    # pixel resolution calculation
+    # pixel size of C11440-22C camera = 6.5 um
+    metadata["camera_pixel_size_um"] = CAMERA_PIXEL_SIZE
+
+    if "objective_mag" in metadata:
+        # pixel resolution = camera pixel size / magnification
+        metadata["pixel_resolution_um"] = metadata["camera_pixel_size_um"] / metadata["objective_mag"]
+
+    return metadata
+
+
+def read_background_values(
+    input_dir: Path,
+    percentile: float = 3.0,
+) -> list[float]:
+    """Read background values from Background_*.tif files.
+
+    MATLAB computes backgroundValues by reading ALL Background_*.tif files
+    (sorted by name) and computing prctile(image(:), 3) on each. The values
+    are indexed by loop counter (1-indexed in MATLAB), not by camera number.
+
+    For cameras=[2], MATLAB uses backgroundValues(1) = Background_0.tif.
+
+    Args:
+        input_dir: directory containing Background_*.tif files
+        percentile: percentile for background estimation (default 3.0)
+
+    Returns:
+        list of background values in file sort order
+    """
+    from .corrections import percentile_interp
+
+    background_values = []
+    bg_files = sorted(input_dir.glob("Background_*.tif"))
+
+    for bg_file in bg_files:
+        img = tifffile.imread(bg_file)
+        bg = percentile_interp(img.ravel().astype(np.float64), percentile)
+        background_values.append(bg)
+
+    return background_values
+
+
+def detect_timepoints(input_dir: Path, specimen: int) -> list[int]:
+    """Detect all available timepoints in input directory.
+
+    Args:
+        input_dir: root input directory
+        specimen: specimen number
+
+    Returns:
+        sorted list of timepoint indices
+    """
+    input_dir = Path(input_dir)
+    timepoints = set()
+
+    # check SPM##/TM##### structure
+    spm_dir = input_dir / f"SPM{specimen:02d}"
+    if spm_dir.exists():
+        for tm_dir in spm_dir.glob("TM*"):
+            if tm_dir.is_dir():
+                try:
+                    tp = int(tm_dir.name[2:])
+                    timepoints.add(tp)
+                except ValueError:
+                    continue
+
+    # check TM##### at root level
+    for tm_dir in input_dir.glob("TM*"):
+        if tm_dir.is_dir():
+            try:
+                tp = int(tm_dir.name[2:])
+                timepoints.add(tp)
+            except ValueError:
+                continue
+
+    # check stack files directly (SPC##_TM#####_...)
+    for stack_file in input_dir.glob("SPC*_TM*_*.stack"):
+        name = stack_file.name
+        tm_idx = name.find("_TM")
+        if tm_idx >= 0:
+            try:
+                tp_str = name[tm_idx+3:tm_idx+8]
+                tp = int(tp_str)
+                timepoints.add(tp)
+            except ValueError:
+                continue
+
+    if not timepoints:
+        raise ValueError(f"no timepoints found in {input_dir}")
+
+    return sorted(timepoints)
+
+
+def infer_file_structure(input_dir: Path, specimen: int, channels: list[int]) -> str:
+    """Automatically determine input file structure.
+
+    Returns:
+        'timepoint': organized by SPM##/TM##### folders
+        'channel': organized by channel folders
+    """
+    input_dir = Path(input_dir)
+
+    # check for specimen subdirectory structure
+    spm_dir = input_dir / f"SPM{specimen:02d}"
+    if spm_dir.exists():
+        tm_dirs = list(spm_dir.glob("TM*"))
+        if tm_dirs:
+            return "timepoint"
+
+    # check for timepoint structure at root
+    tm_dirs = list(input_dir.glob("TM*"))
+    if tm_dirs:
+        return "timepoint"
+
+    # check for channel structure
+    ch_files = list(input_dir.glob(f"ch{channels[0]:02d}_spec{specimen:02d}.xml"))
+    if ch_files:
+        return "channel"
+
+    # check for direct stack files
+    stack_files = list(input_dir.glob("*.stack"))
+    if stack_files:
+        return "channel"
+
+    raise ValueError(f"could not determine file structure in {input_dir}")
+
+
+def find_stack_file(
+    input_dir: Path,
+    specimen: int,
+    timepoint: int,
+    camera: int,
+    channel: int,
+    structure: str,
+) -> Path:
+    """Locate stack file based on directory structure."""
+    input_dir = Path(input_dir)
+
+    if structure == "timepoint":
+        # try with SPM subdirectory first
+        spm_pattern = (
+            f"SPM{specimen:02d}/TM{timepoint:05d}/ANG000/"
+            f"SPC{specimen:02d}_TM{timepoint:05d}_ANG000_"
+            f"CM{camera}_CHN{channel:02d}_PH0.stack"
+        )
+        spm_path = input_dir / spm_pattern
+        if spm_path.exists():
+            return spm_path
+
+        # try without SPM subdirectory
+        pattern = (
+            f"TM{timepoint:05d}/ANG000/"
+            f"SPC{specimen:02d}_TM{timepoint:05d}_ANG000_"
+            f"CM{camera}_CHN{channel:02d}_PH0.stack"
+        )
+        stack_path = input_dir / pattern
+        if stack_path.exists():
+            return stack_path
+
+        raise FileNotFoundError(f"stack not found: {spm_path} or {stack_path}")
+    else:  # channel
+        pattern = (
+            f"SPC{specimen:02d}_TM{timepoint:05d}_ANG000_"
+            f"CM{camera}_CHN{channel:02d}_PH0.stack"
+        )
+        stack_path = input_dir / pattern
+        if not stack_path.exists():
+            raise FileNotFoundError(f"stack not found: {stack_path}")
+        return stack_path