Merge pull request #111 from sebi06/improve_stability

Fix threading issues with aicspylibczi on Linux + Napari

Author: sebi06

README.md

@@ -9,6 +9,61 @@
 
 This repository provides a collection of tools to simplify reading CZI (Carl Zeiss Image) pixel and metadata in Python. It is available as a [Python Package on PyPi](https://pypi.org/project/czitools/)
 
+## ⚠️ Important: Using czitools with Napari on Linux
+
+## ⚠️ Important: Using czitools with Napari on Linux
+
+If you use **Napari** on **Linux** and need `get_planetable()` or `read_tiles()`:
+
+📖 **[Linux + Napari + Planetable Guide](docs/LINUX_NAPARI_PLANETABLE.md)** ⭐ **READ THIS**
+
+**The Solution: Sequential Execution Pattern**
+
+Extract planetable **BEFORE** starting Napari to avoid threading conflicts:
+
+```python
+# Step 1: Get planetable FIRST (before Napari)
+from czitools.utils.planetable import get_planetable
+df, _ = get_planetable("file.czi")
+
+# Step 2: Load image (thread-safe)
+from czitools.read_tools import read_tools
+array, _ = read_tools.read_6darray("file.czi", use_dask=True)
+
+# Step 3: NOW start Napari (safe - no conflicts!)
+import napari
+viewer = napari.Viewer()
+viewer.add_image(array)
+napari.run()
+```
+
+✅ **Full planetable functionality on Linux**  
+✅ **No crashes**  
+✅ **No performance loss**
+
+**Alternative: Safe Mode** (simpler, but no planetable/tiles):
+
+```python
+import os
+os.environ["CZITOOLS_DISABLE_AICSPYLIBCZI"] = "1"
+
+from czitools.read_tools import read_tools
+# Use read_6darray() instead of read_tiles()
+array, mdata = read_tools.read_6darray("file.czi", use_dask=True)
+```
+
+**Why?** `aicspylibczi` has threading conflicts with PyQt on Linux.  
+**Solution:** Extract planetable before PyQt event loop starts (sequential execution).
+
+📄 **Documentation:**
+- [Linux + Napari + Planetable Guide](docs/LINUX_NAPARI_PLANETABLE.md) - Complete examples
+- [Threading Considerations](docs/threading_considerations.md) - Technical details
+- [Quick Fix Guide](docs/NAPARI_FIX.md) - Emergency fixes
+
+---
+
+See [demo/scripts/napari_with_process_isolation.py](demo/scripts/napari_with_process_isolation.py) for complete examples and [docs/threading_considerations.md](docs/threading_considerations.md) for detailed information.
+
 ## Installation
 
 To install czitools (core functionality) use:

demo/scripts/napari_plugin_example.py

@@ -0,0 +1,173 @@
+"""
+Example: Platform-aware CZI loading for napari-czitools plugin.
+
+This module shows how to handle Linux threading issues when czitools
+is used as part of a Napari plugin.
+"""
+
+import platform
+from pathlib import Path
+from typing import Optional, Tuple
+import pandas as pd
+import numpy as np
+from czitools.read_tools import read_tools
+from czitools.utils.planetable import get_planetable
+from czitools.metadata_tools.czi_metadata import CziMetadata
+
+
+class NapariCziLoader:
+    """
+    Platform-aware CZI loader for Napari plugins.
+
+    Handles threading issues on Linux automatically.
+    """
+
+    def __init__(self, enable_planetable_on_linux: bool = False):
+        """
+        Initialize loader.
+
+        Args:
+            enable_planetable_on_linux: If True, attempt planetable extraction
+                on Linux (may crash). If False, skip planetable on Linux.
+        """
+        self.enable_planetable_on_linux = enable_planetable_on_linux
+        self.is_linux = platform.system() == "Linux"
+
+    def load_czi(
+        self, filepath: Path, extract_planetable: bool = True
+    ) -> Tuple[np.ndarray, CziMetadata, Optional[pd.DataFrame]]:
+        """
+        Load CZI file with platform-aware handling.
+
+        Args:
+            filepath: Path to CZI file
+            extract_planetable: Whether to attempt planetable extraction
+
+        Returns:
+            Tuple of (array, metadata, planetable_df)
+            planetable_df may be None on Linux or if extraction fails
+        """
+        print(f"Loading CZI: {filepath}")
+
+        # Always load image data (thread-safe)
+        array, metadata = read_tools.read_6darray(filepath, use_dask=True, use_xarray=True, chunk_zyx=True)
+        print(f"✅ Image loaded: {array.shape}")
+
+        # Handle planetable based on platform
+        planetable_df = None
+
+        if extract_planetable:
+            if self.is_linux and not self.enable_planetable_on_linux:
+                # Skip on Linux by default
+                print("ℹ️  Planetable extraction disabled on Linux (threading safety)")
+                print("   To enable: set enable_planetable_on_linux=True")
+                print("   Warning: May cause crashes with Napari on Linux")
+            else:
+                # Try extraction
+                planetable_df = self._extract_planetable_safe(filepath)
+
+        return array, metadata, planetable_df
+
+    def _extract_planetable_safe(self, filepath: Path) -> Optional[pd.DataFrame]:
+        """
+        Safely attempt planetable extraction with error handling.
+
+        Args:
+            filepath: Path to CZI file
+
+        Returns:
+            DataFrame or None if extraction fails
+        """
+        if self.is_linux:
+            print("⚠️  WARNING: Attempting planetable extraction on Linux")
+            print("   This may cause Napari to crash due to threading conflicts")
+            print("   If crashes occur, set CZITOOLS_DISABLE_AICSPYLIBCZI=1")
+
+        try:
+            df, _ = get_planetable(filepath, norm_time=True)
+            print(f"✅ Planetable extracted: {len(df)} rows")
+            return df
+
+        except RuntimeError as e:
+            if "CZITOOLS_DISABLE_AICSPYLIBCZI" in str(e):
+                print("ℹ️  Planetable disabled (safe mode active)")
+            else:
+                print(f"❌ Planetable extraction failed: {e}")
+            return None
+
+        except Exception as e:
+            print(f"❌ Planetable extraction error: {e}")
+            if self.is_linux:
+                print("   This may be a threading conflict on Linux")
+                print("   Restart Napari with: export CZITOOLS_DISABLE_AICSPYLIBCZI=1")
+            return None
+
+
+# Example usage in a napari plugin widget
+def example_napari_plugin_widget():
+    """
+    Example of how to use NapariCziLoader in a napari plugin.
+    """
+    from magicgui import magic_factory
+    from napari.types import LayerDataTuple
+
+    @magic_factory(
+        call_button="Load CZI",
+        filepath={"mode": "r", "filter": "*.czi"},
+        enable_planetable={"label": "Extract Planetable (may crash on Linux)"},
+    )
+    def load_czi_widget(filepath: Path, enable_planetable: bool = False) -> LayerDataTuple:
+        """
+        Napari widget to load CZI files.
+
+        Args:
+            filepath: CZI file to load
+            enable_planetable: Extract planetable (risky on Linux)
+
+        Returns:
+            Layer data tuple for Napari
+        """
+        # Create loader with platform awareness
+        loader = NapariCziLoader(enable_planetable_on_linux=enable_planetable)
+
+        # Load CZI
+        array, metadata, planetable_df = loader.load_czi(filepath, extract_planetable=enable_planetable)
+
+        # Prepare metadata for Napari
+        layer_metadata = {
+            "czi_metadata": metadata.info,
+            "planetable": planetable_df.to_dict() if planetable_df is not None else None,
+        }
+
+        # Show planetable summary if available
+        if planetable_df is not None:
+            print(f"\n📊 Planetable Summary:")
+            print(f"   Total planes: {len(planetable_df)}")
+            if "Time[s]" in planetable_df.columns:
+                print(f"   Time range: {planetable_df['Time[s]'].min():.2f} - {planetable_df['Time[s]'].max():.2f} s")
+
+        # Return layer data tuple
+        return (array, {"name": filepath.name, "metadata": layer_metadata}, "image")
+
+    return load_czi_widget
+
+
+# Example: Manual usage
+if __name__ == "__main__":
+    from pathlib import Path
+
+    # Create loader
+    loader = NapariCziLoader(enable_planetable_on_linux=False)  # Safe default for Linux
+
+    # Load CZI
+    filepath = Path("data/CellDivision_T3_Z5_CH2_X240_Y170.czi")
+    array, metadata, planetable_df = loader.load_czi(filepath)
+
+    print(f"\n✅ Loaded successfully:")
+    print(f"   Shape: {array.shape}")
+    print(f"   Planetable: {'Available' if planetable_df is not None else 'Not extracted'}")
+
+    # If running in Napari, could display now:
+    # import napari
+    # viewer = napari.current_viewer()
+    # viewer.add_image(array, name=filepath.name)

demo/scripts/napari_safe_loading.py

@@ -0,0 +1,95 @@
+"""
+Safe CZI Loading for Napari on Linux
+
+This script demonstrates how to safely load CZI files with Napari on Linux
+to avoid crashes related to aicspylibczi threading issues.
+
+Author: sebi06
+"""
+
+import os
+
+# CRITICAL: Set this BEFORE importing czitools or napari
+# This prevents aicspylibczi from being used, avoiding threading conflicts
+os.environ["CZITOOLS_DISABLE_AICSPYLIBCZI"] = "1"
+
+from pathlib import Path
+from czitools.read_tools import read_tools
+from czitools.utils import misc
+import napari
+
+# Define base directory for test data
+basedir = Path(__file__).resolve().parents[2] / "data"
+os.chdir(basedir)
+
+# Select a CZI file
+filepath = misc.openfile(
+    directory=str(basedir),
+    title="Open CZI Image File",
+    ftypename="CZI Files",
+    extension="*.czi",
+)
+
+if filepath is None:
+    print("No file selected. Exiting.")
+    exit()
+
+print(f"Loading: {filepath}")
+print("\n⚠️  Using thread-safe mode (aicspylibczi disabled)")
+print("This is the recommended approach for Napari on Linux\n")
+
+# Read CZI with thread-safe settings
+# This uses ONLY pylibCZIrw which is confirmed thread-safe
+array6d, mdata = read_tools.read_6darray(
+    filepath,
+    use_dask=True,  # Lazy loading - efficient for large files
+    use_xarray=True,  # Labeled dimensions - easy to work with
+    chunk_zyx=True,  # Optimize chunking for performance
+)
+
+print(f"Image dimensions: {array6d.dims}")
+print(f"Image shape: {array6d.shape}")
+print(f"Number of channels: {mdata.image.SizeC}")
+print(f"Pixel type: {mdata.pixeltypes}")
+
+# Create Napari viewer
+viewer = napari.Viewer()
+
+# Add each channel to Napari
+for ch in range(mdata.image.SizeC):
+    # Extract channel
+    channel_data = array6d.sel(C=ch)
+
+    # Get channel name if available
+    channel_name = (
+        mdata.channelinfo.names[ch]
+        if mdata.channelinfo.names and ch < len(mdata.channelinfo.names)
+        else f"Channel {ch}"
+    )
+
+    # Get scaling information
+    scale = [1.0]  # For Scene dimension if present
+    if mdata.image.SizeT and mdata.image.SizeT > 1:
+        scale.append(1.0)  # Time dimension
+    scale.extend(
+        [
+            mdata.scale.Z if mdata.scale.Z else 1.0,
+            mdata.scale.Y if mdata.scale.Y else 1.0,
+            mdata.scale.X if mdata.scale.X else 1.0,
+        ]
+    )
+
+    # Add to viewer
+    viewer.add_image(
+        channel_data,
+        name=channel_name,
+        scale=scale,
+        colormap="gray" if not mdata.isRGB.get(ch, False) else "viridis",
+        blending="additive",
+    )
+
+print("\n✅ CZI loaded successfully in thread-safe mode!")
+print("No aicspylibczi was used - only pylibCZIrw (thread-safe)\n")
+
+# Run Napari
+napari.run()

demo/scripts/napari_with_planetable_linux.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+Safe pattern for using get_planetable() with Napari on Linux.
+
+The key: Extract planetable BEFORE starting Napari's event loop.
+This avoids threading conflicts between aicspylibczi and PyQt.
+"""
+
+from pathlib import Path
+from czitools.utils.planetable import get_planetable
+from czitools.read_tools import read_tools
+
+# Step 1: Extract planetable FIRST (before Napari)
+print("Extracting planetable...")
+czi_file = Path("data/CellDivision_T3_Z5_CH2_X240_Y170.czi")
+
+# Get planetable - aicspylibczi runs here, before Napari
+df_planetable, csv_path = get_planetable(czi_file, norm_time=True, save_table=False)
+
+print(f"✅ Planetable extracted: {len(df_planetable)} rows")
+print(f"   Columns: {list(df_planetable.columns)}")
+
+# Step 2: Load image data (thread-safe, uses only pylibCZIrw)
+print("\nLoading image data...")
+array, metadata = read_tools.read_6darray(czi_file, use_dask=True, use_xarray=True, chunk_zyx=True)
+
+print(f"✅ Image loaded: {array.shape}")
+
+# Step 3: NOW start Napari (planetable already extracted)
+print("\nStarting Napari...")
+import napari
+
+viewer = napari.Viewer()
+
+# Add image
+viewer.add_image(array, name="CZI Image", metadata={"czi_metadata": metadata.info})
+
+# Use planetable data for visualization
+# Example: Color timepoints differently based on planetable timestamps
+if "Time[s]" in df_planetable.columns:
+    time_info = df_planetable.groupby("T")["Time[s]"].first()
+    print(f"\n📊 Time points from planetable:")
+    for t, time_s in time_info.items():
+        print(f"   T={t}: {time_s:.2f} seconds")
+
+# Example: Show planetable as table in console
+print(f"\n📊 Planetable preview:")
+print(df_planetable.head(10))
+
+print("\n✅ Safe to use Napari now - planetable extracted before event loop started")
+print("   Close Napari viewer to exit.")
+
+napari.run()