v0.17.0

v0.17.0

Highlights

• Refactored public API — __init__.py files for all sub-packages now export explicit, stable public symbols; internal helpers are prefixed with _ and no longer part of the public surface.
• Circular-import fix — resolved a startup ImportError caused by a circular dependency between utils.misc and metadata_tools.czi_metadata; the import is now deferred inside md2dataframe.
• calc_scaling zarr fix — zarr arrays are now wrapped in a dask view before reduction so min/max are computed chunk-by-chunk without loading the full array into memory, and without relying on zarr version-specific methods.
• Bug fixes in misc.py — corrected type hint (da.array → da.Array), added zarr.Array to the union, suppressed Pylance false-positives.
• Updated demo notebooks and scripts to use the revised API.

Added

• Explicit __all__ exports in src/czitools/metadata_tools/__init__.py, read_tools/__init__.py, utils/__init__.py, and visu_tools/__init__.py
• src/czitools/__init__.py — re-exports visu_tools helpers and napari_helpers at the top level

Changed

• src/czitools/utils/misc.py
  • calc_scaling: fixed data type hint to Union[np.ndarray, da.Array, zarr.Array]; zarr branch now uses da.from_zarr + da.compute for chunk-wise reduction
  • md2dataframe: circular import of CziMetadata / _obj2dict moved to a deferred local import; top-level import replaced with a TYPE_CHECKING guard
  • Added Google-style docstring to md2dataframe
• src/czitools/metadata_tools/czi_metadata.py — internal helpers renamed with _ prefix; reduced duplication
• src/czitools/read_tools/read_tools.py — internal helpers renamed with _ prefix
• src/czitools/utils/planetable.py — minor refactor and clarified docstrings
• src/czitools/visu_tools/vis_tools.py — CI fix for optional import guard
• Demo notebooks refreshed (metadata, pixel-data, NDV, surface); removed outdated save_with_ZSTD_compression.ipynb
• Demo scripts updated to use the new public API

Fixed

• ImportError: cannot import name 'CziAddMetaData' from partially initialized module on package startup (circular import)
• AttributeError: 'Array' object has no attribute 'min' in calc_scaling when a zarr.Array is passed (version-dependent API)
• KeyError in test suite caused by stale internal function references after rename

v0.16.0

v0.16.0

Highlights

• Dropped Python 3.11 support — czifile >= 2026 requires Python 3.12+; minimum is now Python 3.12.
• Removed all old-czifile API compatibility shims; code now targets the CziDirectoryEntryDV API exclusively.
• Improved and expanded MkDocs documentation (install, usage, API reference pages).
• Removed aicspylibczi dependency; all pixel reading now uses pylibCZIrw and czifile exclusively.
• Fixed Pylance type-checking issues across metadata, read, and utility modules.
• Added automated GitHub Actions workflow for building and publishing docs to GitHub Pages.
• Added module-level docstrings to all public modules for cleaner API reference output.

Added

• .github/workflows/docs.yml — CI workflow that deploys MkDocs docs via mike to GitHub Pages on push to main and on version tags
• docs/install.md — full installation guide (PyPI, editable, conda, dependency tables)
• docs/usage.md — usage guide covering metadata, pixel reading, Napari helpers, NDV integration and Colab notebooks
• src/czitools/utils/threading_helpers.py — thread-safe helpers for Napari integration
• src/czitools/utils/napari_helpers.py — get_recommended_read_params and related helpers
• .github/copilot-instructions.md — Copilot coding guidelines for the repository

Changed

• pyproject.toml — requires-python bumped to >=3.12,<3.14; removed Python 3.11 classifier
• tox.ini — removed py311 from envlist and gh-actions mapping
• .github/workflows/test_and_deploy.yml, test_and_deploy_testpypi.yml — removed "3.11" from test matrix
• docs/install.md — updated requirements table (Python 3.12, 3.13)
• src/czitools/utils/misc.py — simplified _de_dim_start/size/chars, _de_scene_idx, _de_mosaic_idx; dropped all dimension_entries fallback paths
• src/czitools/read_tools/read_tools.py — read_tiles() uses de.dims, de.is_pyramid, de.stored_shape directly; removed old-API branches
• src/czitools/utils/planetable.py — sb.metadata() treated as XML string only; removed _getsbinfo_from_dict and dict-metadata code path
• src/czitools/metadata_tools/czi_metadata.py — is_pyramid accessed directly on directory entry
• mkdocs.yml
  • switched docstring_style to google (matching actual docstring format)
  • enabled parameter_headings, separate_signature, show_symbol_type_heading and other mkdocstrings options for richer API reference output
  • fixed social link (was pointing to pyapp-kit instead of sebi06)
• README.md — shortened; detailed installation and usage sections replaced with links to the new docs pages
• src/czitools/utils/logging_tools.py — added missing type annotations (int, str | None, bool, -> logging.Logger)
• src/czitools/utils/napari_tools.py — added missing type annotations on all public functions
• All public modules — added module-level docstrings for mkdocstrings API reference

Removed

• Python 3.11 support (dropped; czifile >= 2026 requires Python 3.12)
• Old-czifile API compatibility code (dimension_entries loops, getattr guards, dict metadata fallback)
• _getsbinfo_from_dict helper in planetable.py
• aicspylibczi dependency (all functionality replaced by pylibCZIrw)
• Legacy napari demo scripts moved to _archive/

v0.15.0

v0.15.0

Highlights

• Enhanced read_stacks(...) with explicit metadata return and improved stacking/chunk behavior.
• Added clearer typed scene-reading wrappers for stable return contracts.
• Aligned tests with current APIs and improved zoom/lazy-read coverage.
• Updated README and Copilot instructions for API consistency.
• Refreshed NDV demo notebook/script workflows and added a bioio-vs-czitools dask comparison script.

Added

• src/czitools/read_tools/read_tools.py
  • read_stacks_list(...)
  • read_stacks_stacked(...)
• demo/scripts/read_bioio_dask_compare.py
• RELEASE_NOTES/v0.15.0.md

Changed

• src/czitools/read_tools/read_tools.py
  • read_stacks(...) now returns (result, dims, num_stacks, mdata)
  • improved scene stacking and chunk-policy handling
  • improved metadata propagation for stack outputs
• Tests
  • src/czitools/_tests/test_read_stacks.py
  • src/czitools/_tests/test_read_scenes.py
  • updated for current read_stacks(...) and read_6darray(..., use_dask=True) usage
• Documentation
  • README.md updated for current read_stacks(...) signature
  • .github/copilot-instructions.md updated to reflect current read tools APIs
• Demos
  • updated demo/notebooks/read_czi_pixeldata_ndv.ipynb
  • updated demo/scripts/use_ndv.py

Removed

• demo/scripts/read_lazy_demo.py
• diagnose_czi.py

Validation

• conda run -n omezarr python -m pytest src/czitools/_tests/test_read_stacks.py src/czitools/_tests/test_read_scenes.py -q
• 71 passed, 2 warnings

Release v0.14.0

v0.14.0

Highlights

• Added NDV utility helpers for LUT and scale generation from CZI metadata.
• Added typed stack-reading wrappers for clearer API contracts.
• Improved Napari display helpers for channel-label handling and list-of-stacks display.
• Improved robustness of URL metadata tests against transient SSL/network issues.
• Updated docs and demos to reflect new stack and viewer workflows.

Added

• src/czitools/utils/ndv_tools.py
  • normalize_luts(...)
  • create_luts_ndv(...)
  • create_scales_ndv(...)
• src/czitools/read_tools/read_tools.py
  • read_stacks_list(...)
  • read_stacks_stacked(...)
• Tests
  • src/czitools/_tests/test_ndv_tools.py

Changed

• read_stacks(...) typing and ergonomics improved while keeping adaptive, backward-compatible behavior.
• src/czitools/utils/napari_tools.py
  • robust channel selection for numeric and string C labels
  • support for showing list outputs with heterogeneous scene shapes via display_xarray_list_in_napari(...)
• src/czitools/_tests/test_url_metadata.py
  • prefers direct raw.githubusercontent.com URL
  • retries candidate URLs and skips on transient SSL/network failures
• Documentation
  • README.md updated with read_stacks return behavior and typed wrapper guidance
  • Napari helper usage documented for single-array and list-of-stacks cases
• Demos
  • updated demo/scripts/read_mdstack.py
  • updated demo/scripts/use_ndv.py
  • updated demo/scripts/use_read_tools.py
  • updated demo/notebooks/read_czi_pixeldata_ndv.ipynb

Validation

• Full suite in omezarr environment:
  • conda run -n omezarr pytest -q
  • 299 passed, 15 warnings

v0.13.2 - Fix Threading Issues with aicspylibczi on Linux + Napari

Release Notes - v0.13.2

Release Date: January 26, 2026

🔴 Critical Fix: Linux + Napari Threading Issues

This release addresses critical threading crashes when using czitools with Napari on Linux systems.

Problem Resolved

aicspylibczi library caused crashes when used concurrently with Napari (PyQt) on Linux, affecting:

• CZI file loading in Napari plugins
• Planetable extraction in GUI applications
• Mosaic tile reading with concurrent operations

Root Cause

• aicspylibczi is NOT thread-safe and conflicts with PyQt event loop on Linux
• pylibCZIrw is thread-safe but cannot read individual subblocks/tiles

✅ New Features

1. Safe Mode (Primary Solution) ⭐

Environment variable control to disable problematic library:

import os
os.environ["CZITOOLS_DISABLE_AICSPYLIBCZI"] = "1"

from czitools.read_tools import read_tools
array, metadata = read_tools.read_6darray("file.czi", use_dask=True)

Benefits:

• 100% stable with Napari on Linux
• No threading conflicts
• No performance loss (dask lazy loading)
• Recommended for all Napari users on Linux

2. Thread Locks (Backward Compatibility)

Global RLock protection added to:

• read_tiles() function
• get_planetable() function

Note: May still experience issues with Napari on Linux. Safe mode is recommended.

3. Platform Detection & Warnings

Automatic Linux detection with user warnings:

from czitools.utils.napari_helpers import warn_if_unsafe_for_napari
warn_if_unsafe_for_napari()

4. New Helper Utilities

src/czitools/utils/napari_helpers.py (NEW):

• enable_napari_safe_mode() - Enable safe mode programmatically
• is_napari_safe_mode() - Check safe mode status
• check_napari_compatibility() - Verify environment safety
• get_recommended_read_params() - Get optimal parameters
• warn_if_unsafe_for_napari() - Warning for unsafe conditions

src/czitools/utils/threading_helpers.py (NEW):

• with_aics_lock(func) - Decorator for thread-safe operations
• is_napari_safe() - Check safe mode status
• warn_if_unsafe_for_napari() - Linux platform warnings

📝 Changes

Modified Files

• src/czitools/read_tools/read_tools.py - Added safe mode + thread locks
• src/czitools/utils/planetable.py - Added safe mode + thread locks
• src/czitools/metadata_tools/czi_metadata.py - Safe mode support
• README.md - Added prominent warning section
• setup.cfg - Updated version to 0.13.2
• tox.ini - Updated test configuration

New Files

• src/czitools/utils/threading_helpers.py - Thread-safety utilities
• src/czitools/utils/napari_helpers.py - Napari integration helpers
• src/czitools/_tests/test_napari_safe_mode.py - Test suite (7 tests)

Documentation

• docs/threading_considerations.md - Comprehensive threading guide
• docs/NAPARI_FIX.md - Quick-fix guide
• docs/FINAL_SOLUTION.md - Complete solution documentation
• docs/IMPLEMENTATION_SUMMARY.md - Technical details
• docs/LINUX_NAPARI_PLANETABLE.md - Linux-specific guide

Examples

• demo/scripts/napari_safe_loading.py - Working example
• demo/scripts/napari_with_planetable_linux.py - Linux planetable example
• demo/scripts/napari_plugin_example.py - Plugin integration
• demo/scripts/napari_with_process_isolation.py - Process isolation pattern

🚀 Recommended Usage

For Linux + Napari Users:

import os
os.environ["CZITOOLS_DISABLE_AICSPYLIBCZI"] = "1"

from czitools.read_tools import read_tools
import napari

array, metadata = read_tools.read_6darray("file.czi", use_dask=True)
viewer = napari.Viewer()
viewer.add_image(array)

For Windows/macOS:

No changes needed - works as before.

For Planetable Extraction:

Use sequential pattern (extract before Napari):

from czitools.utils.planetable import get_planetable

# Extract planetable BEFORE starting Napari
df, _ = get_planetable("file.czi")

# THEN start Napari
import napari
viewer = napari.Viewer()

🔄 Backward Compatibility

• ✅ No breaking changes for Windows/macOS users
• ✅ Existing code works without modifications
• ✅ Safe mode is opt-in via environment variable
• ✅ Thread locks provide basic protection by default

⚠️ Behavioral Changes

When CZITOOLS_DISABLE_AICSPYLIBCZI=1 is set:

• read_tiles() raises RuntimeError (use read_6darray() instead)
• get_planetable() returns empty DataFrame (extract before Napari)
• CziMetadata.attachment_info returns None
• All other functionality remains unchanged

📊 Statistics

• Total Changes: 19 files
• Insertions: +2,542 lines
• Deletions: -396 lines
• New Tests: 7 (all passing)
• New Documentation: 5 files
• New Examples: 4 scripts

🧪 Testing

All tests passing:

pytest src/czitools/_tests/test_napari_safe_mode.py -v

Test Coverage:

• Safe mode enable/disable
• Environment variable detection
• Thread lock functionality
• read_tiles behavior in safe mode
• get_planetable behavior in safe mode
• read_6darray compatibility
• Platform detection

📚 Documentation

Comprehensive documentation available:

• Threading Considerations
• Napari Quick Fix
• Final Solution
• Linux Guide

🎯 Migration Guide

If you use read_6darray():

✅ No changes needed! Works perfectly in all modes.

If you use read_tiles() or get_planetable() with Napari on Linux:

Enable safe mode and switch to read_6darray():

os.environ["CZITOOLS_DISABLE_AICSPYLIBCZI"] = "1"
array, metadata = read_tools.read_6darray("file.czi")  # Use this instead

If you need planetables with Napari:

Use sequential pattern:

# 1. Extract planetable BEFORE Napari
df, _ = get_planetable("file.czi")

# 2. THEN start Napari
import napari
viewer = napari.Viewer()

🙏 Acknowledgments

Thanks to all users who reported threading issues on Linux systems and helped identify the root cause.

🔗 Related

• Pull Request: #111 - Fix threading issues with aicspylibczi on Linux + Napari
• Branch: improve_stability

---

For detailed technical information, see the Implementation Summary.

Release v0.12.0

This release introduces significant improvements to the CZI reading capabilities, including a new read_scenes() function, URL support for lazy loading, and comprehensive test coverage.

New Features

read_scenes() Function

• Read all 2D planes from CZI files grouped by scene
• Lazy loading with use_dask=True
• xarray support with labeled dimensions
• Scene stacking for consistent shapes

URL Support for Lazy Loading

• get_pyczi_readertype() utility function
• Direct URL reading without full metadata load

Improved read_6darray_lazy()

• Added use_xarray parameter
• Fixed attribute errors
• URL-based reading support

read_6darray() Improvements

• Fixed type hints
• Simplified logic
• Better logging

Test Coverage

• 33 new tests for read_scenes() and read_6darray_lazy()
• Tests for get_pyczi_readertype()

Breaking Changes

None - backwards compatible"