⬆️ Upgrade Zarr to v3+ Compatibility

[measty]

✅ Summary

• Enables compatibility with Zarr v3+
• Simplifies error handling across Zarr versions
• Removes deprecated storage backends and APIs
• Lays groundwork for full Zarr v3 migration

This PR updates TIAToolbox to support Zarr v3+, addressing breaking changes introduced in Zarr ≥ 3.0 and aligning internal APIs, storage handling, and error handling accordingly.

---

Zarr v3 removed zarr.errors.FSPathExistNotDir. In Zarr ≥ 3.0, equivalent failure modes now raise standard Python exceptions (e.g. FileNotFoundError).

To avoid fragile version-specific logic:

• Removed checks for specific Zarr exception types
• Replaced them with generic exception handling that works consistently across Zarr versions

---

🔧 Key changes

Dependency updates

• 🆙 Upgrade to:
  • zarr >= 3.0.8
  • tifffile >= 2025.5.21

Zarr API & storage migration

• Refactor zarr.core.Array → zarr.Array
• Replace zarr.DirectoryStore with zarr.storage.LocalStore
• Remove ngff.sqlitestore (Zarr v3 no longer supports zarr.SQLiteStore)
• Replace canvas_zarr.store.path with canvas_zarr.store.root
• Ensure Zarr paths explicitly use string keys (key / str(i) instead of key / i)

Dask & array handling

• Remove unsupported object_codec usage in dask.to_zarr
• Update zarr.resize calls to use tuple inputs
• Replace output.items() with output.members()

---

⚠️ Known limitations & follow‑ups

Zarr v3 removes or significantly changes several APIs still used by TIAToolbox, including:

• zarr.LRUStoreCache
• zarr.DirectoryStore
• zarr.SQLiteStore

While this PR resolves immediate incompatibilities and enables Zarr v3 usage, additional refactoring will be required to fully replace or redesign components that depend on these removed features.

In addition, full compatibility with tifffile depends on upstream Zarr v3 support, and some workflows may remain limited until that stabilises.

📖 For a detailed overview of breaking changes, see the official Zarr v3 migration guide:
https://zarr.readthedocs.io/en/latest/user-guide/v3_migration.html

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.87%. Comparing base (3ca1599) to head (8e4dca6).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #904   +/-   ##
========================================
  Coverage    99.87%   99.87%           
========================================
  Files           85       85           
  Lines        11572    11623   +51     
  Branches      1513     1524   +11     
========================================
+ Hits         11557    11608   +51     
- Misses           8        9    +1     
+ Partials         7        6    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[shaneahmed]

Zarr v3 is not compatible with tifffile cgohlke/tifffile#282 czbiohub-sf/iohub#292

[shaneahmed]

Zarr 3 is supported by tifffile. However, zarr 3 only supports Python 3.11+.

[Copilot]

Pull request overview

This PR updates TIAToolbox to be compatible with Zarr v3 by migrating deprecated Zarr v2 APIs, adjusting store handling (LocalStore/FsspecStore, group iteration), and updating dependency requirements and tests accordingly.

Changes:

• Upgrade dependencies to zarr>=3.0.8 and tifffile>=2025.5.21, and refactor Zarr usage to Zarr v3 APIs (stores, group/array types, iteration, resize signatures).
• Update WSI readers (TIFF/NGFF/fsspec-json) to work with Zarr v3 storage and caching patterns.
• Adjust model engines and tests to avoid Zarr v2-only features (e.g., object codecs, SQLiteStore) and accommodate Zarr v3 group key semantics.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tiatoolbox/wsicore/wsireader.py	Refactors Zarr/NGFF detection and readers for Zarr v3, introduces CacheStore usage, URL handling, and updates group iteration.
tiatoolbox/wsicore/__init__.py	Adds WSIReaderParams to exports and extends it with storage_options.
tiatoolbox/utils/transforms.py	Minor typing adjustments for NumPy dtype handling and local variable annotations.
tiatoolbox/utils/misc.py	Updates shapely typing, migrates Zarr types (zarr.Array/zarr.Group), updates Zarr creation API, and adds pad_contours helper for Zarr v3.
tiatoolbox/utils/metrics.py	Adds explicit NumPy typing for unpaired coordinate outputs.
tiatoolbox/utils/image.py	Adds explicit ndarray annotations for intermediate variables.
tiatoolbox/tools/pyramid.py	Adds a mypy ignore for defusedxml.defuse_stdlib() attribute typing.
tiatoolbox/tools/patchextraction.py	Refactors meshgrid helper into a static method with improved typing.
tiatoolbox/tools/graph.py	Normalizes cKDTree.query outputs into NumPy arrays.
tiatoolbox/models/engine/semantic_segmentor.py	Updates Zarr store root usage and Zarr v3 resize signature / LocalStore.
tiatoolbox/models/engine/nucleus_detector.py	Removes object_codec usage in to_zarr call.
tiatoolbox/models/engine/multi_task_segmentor.py	Adapts output handling to Zarr v3 group semantics and adds Zarr cleanup helper logic.
tiatoolbox/models/engine/engine_abc.py	Removes object codec logic for Zarr writing; always rechunks before saving.
tiatoolbox/models/architecture/micronet.py	Ensures empty outputs use non-object dtypes for Zarr v3 compatibility.
tiatoolbox/models/architecture/hovernetplus.py	Ensures empty outputs use non-object dtypes for Zarr v3 compatibility.
tiatoolbox/models/architecture/hovernet.py	Avoids object dtypes in outputs and pads inhomogeneous arrays for Zarr v3 saving.
tests/test_wsireader.py	Updates/introduces tests for Zarr v3 metadata and adds an xfail S3 NGFF test plus additional coverage branches.
tests/test_utils.py	Adds tests for pad_contours and create_smart_array chunk handling.
tests/models/test_models_abc.py	Changes pretrained-model download test to be unconditionally skipped.
tests/models/test_arch_micronet.py	Updates Zarr group indexing to string keys.
tests/engines/test_semantic_segmentor.py	Updates iteration to use members() for Zarr v3 groups.
tests/engines/test_nucleus_detection_engine.py	Updates Zarr group indexing to string keys.
tests/engines/test_multi_task_segmentor.py	Updates assertions and indexing for Zarr v3 storage and contour handling.
requirements/requirements.txt	Bumps tifffile and zarr minimum versions for v3 compatibility.
.github/workflows/mypy-type-check.yml	Relaxes mypy import handling with --follow-imports=skip --ignore-missing-imports.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shaneahmed]

I have tested the engines locally and they work well. I have also addressed Co-Pilots comments.