🔖 Release 2.0.0 (#1031)

## TIAToolbox v2.0.0 (2026-03-11)

### ✨ Major Updates and Feature Improvements

#### ⚙️ Engine Redesign (PR #578)
TIAToolbox 2.0.0 introduces a completely re-engineered inference engine designed for significant performance, scalability, and memory-efficiency improvements.

#### Key Enhancements
- A modern processing stack built on **Dask** (parallel/distributed execution) and **Zarr** (chunked, out-of-core storage)
- **Standardised output formats** across all engines:
  - Python `dict`
  - **Zarr**
  - **AnnotationStore** (SQLite-backed)
  - **QuPath JSON**
- Cleaner runtime behavior with reduced warning noise and a unified progress bar
- More predictable memory usage through chunked streaming
- Broader test coverage across engine components

### 🗺️ Improved QuPath Support
Enhancements include:

- Better handling of **GeoJSON**
- Support for **multipoint geometries** (#841)
- Improved semantic output helpers:
  - `dict_to_store_semantic_segmentor` (#926)
  - OME-TIFF probability overlays (#929)

### 🔬 New Nucleus Detection Engine
A dedicated nucleus detection pipeline has been added, built on the redesigned engine for improved accuracy and efficient large-scale processing.

#### 🧠 KongNet Model Family
TIAToolbox 2.0.0 introduces **KongNet**, a high-performance architecture that achieved top results across multiple international challenges:

- 🥇 **1st place: MONKEY Challenge (overall detection)**
- 🥇 **1st place: MIDOG (mitosis detection)**
- ⭐ Top-tier performance on **PUMA**

Multiple pretrained variants are available (CoNIC, PanNuke, MONKEY, PUMA, MIDOG), each with standardised IO configurations.

### 🧬 Expanded Foundation Model Support
Additional foundation models are now supported (#906), broadening the range of high-capacity architectures available for feature extraction and downstream tasks.

### 🖼️ SAM Segmentation in TIAViz
TIAViz now integrates Meta’s Segment Anything Model (SAM), enabling:

- Interactive segmentation
- Rapid region extraction
- Exploratory annotation workflows

Simplified SAM usage (#968) streamlines its integration into analysis pipelines.

### 🧩 Enhanced WSIReader & Metadata Handling
Major improvements include:

- More robust cross-vendor **metadata extraction** (#1001)
- **Multichannel image support** (PR #825) for immunofluorescence and non-RGB modalities
- Simplified Windows installation using `openslide-bin` (no manual DLL steps)
- macOS Tileserver fix (#976)
- Improved DICOM reading (#934)

### ☁️ New Cloud-Native Reader: FsspecJSONWSIReader (PR #897)
A new reader supporting **fsspec-compatible filesystems**, enabling seamless access to WSIs stored on:

- S3
- GCS
- Azure
- HPC clusters
- Any fsspec-supported backend

This enables cloud-native and distributed data workflows.
Contributed by @aacic

### 🤗 Pretrained Models Migrated to Hugging Face
All pretrained models and sample assets have been migrated (#945, #983), improving:

- Download reliability
- Versioning and reproducibility
- Caching and CI integration
- Licensing clarity per model family

### 🛡️ Security, Compatibility & Tooling

#### 🔐 Security & Dependency Updates
- Dependency upgrades
- Internal security improvements
- Explicit workflow permissions added (#1021, #1023)

#### 🐍 Python Version Support
- **Dropped:** Python **3.9**
- **Added:** Python **3.13**
- **Supported:** Python 3.10–3.13
- Updated CUDA wheel source to **cu126**

#### 🛠️ Developer Tooling & CI/CD
- Expanded **mypy** type-checking coverage (#912, #931, #935, #951)
- Updated pre-commit hooks and general formatting
- CI uses **CPU-only PyTorch** for faster, more reliable builds (#974, #979)
- Updated pip install workflow (#1013)
- Added new **Python 3.13 Docker images** (#1014, #1019)

### 🧹 Bug Fixes & Stability Improvements
- Fixed multi-GPU behaviour with `torch.compile` (#923)
- Fixed DICOM reading issue (#934)
- Fixed annotation contour handling with holes (#956)
- Fixed consecutive annotation load bug (#927)
- Fixed SCCNN model issues (#970)
- Fixed MapDe `dist_filter` shape issue (#914)
- Improved notebook reliability on Colab (#1026–#1030)
- macOS TileServer issues resolved (#976)

### 🧭 Migration Guide for Users

#### 🔄 Updating from 1.x to 2.0.0

#### Update calls: replace `.predict()` with `.run()`
```python
# Old
results = segmentor.predict(imgs=[...], ioconfig=config)

# New
results = segmentor.run(images=[...], ioconfig=config)
```

#### Use `patch_mode`: replace `mode="patch"` with `patch_mode=True` and `mode="tile"` or "wsi" with `patch_mode=False`
```python
# Old
results = segmentor.predict(imgs=[...], mode="patch", ioconfig=config)

# New
results = segmentor.run(images=[...], patch_mode=True, ioconfig=config)
```

```python
# Old
results = segmentor.predict(imgs=[...], mode="wsi", ioconfig=config)

# New
results = segmentor.run(images=[...], patch_mode=False, ioconfig=config)

```

#### Use the new I/O configs
```python
from tiatoolbox.models.engine.io_config import IOSegmentorConfig

config = IOSegmentorConfig(
    patch_input_shape=(256, 256),
    stride_shape=(240, 240),
    input_resolutions=[{"resolution": 0.25, "units": "mpp"}],
    save_resolution={"units": "baseline", "resolution": 1.0}
)
```

#### Specify the output format
```python
results = segmentor.run(
    images=[...],
    ioconfig=ioconfig,
    output_type="zarr",  # or "dict", "annotationstore", "qupath"
    save_dir="outputs/"
)
```

#### Update imports
- `tiatoolbox.typing` → `tiatoolbox.type_hints`

#### Install requirements
- Python **3.10+** required
- On Windows: install OpenSlide via `pip install openslide-bin`

**Full Changelog:** v1.6.0...v2.0.0

---------

Signed-off-by: Shan E Ahmed Raza <13048456+shaneahmed@users.noreply.github.com>
Co-authored-by: measty <20169086+measty@users.noreply.github.com>
Co-authored-by: Jiaqi-Lv <60471431+Jiaqi-Lv@users.noreply.github.com>
Co-authored-by: adamshephard <39619155+adamshephard@users.noreply.github.com>
Co-authored-by: Mostafa Jahanifar <74412979+mostafajahanifar@users.noreply.github.com>
Co-authored-by: John Pocock <John-P@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Yijie Zhu <120978607+YijieZhu15@users.noreply.github.com>
Co-authored-by: Aleksandar Acic <32873451+aacic@users.noreply.github.com>
Co-authored-by: Abdol A <u2271662@live.warwick.ac.uk>
Co-authored-by: Abishek <abishekraj6797@gmail.com>
Co-authored-by: behnazelhaminia <30952176+behnazelhaminia@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Adam Shephard <adam.shephard@warwick.ac.uk>
Co-authored-by: gozdeg <gozdegunesli@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Co-authored-by: mbasheer04 <78800844+mbasheer04@users.noreply.github.com>
Co-authored-by: vqdang <24943262+vqdang@users.noreply.github.com>

Author: 18 people

.github/workflows/conda-env-create.yml

@@ -2,6 +2,9 @@
 
 name: Solve Conda Environment
 
+permissions:
+  contents: read
+
 on:
   push:
     paths: [ "requirements/requirements*.yml", "conda-env-create.yml", "requirement*.txt"]
@@ -33,7 +36,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Copy requirements files
         shell: bash
         run: |
@@ -48,3 +51,4 @@ jobs:
         run: |
           micromamba info
           micromamba list
+          python -c "import torch, numpy; print(torch.__version__, numpy.__version__)"

.github/workflows/docker-publish.yml

@@ -6,7 +6,7 @@ env:
   REGISTRY: ghcr.io
   IMAGE_NAME: TissueImageAnalytics/tiatoolbox
   image: ghcr.io/tissueimageanalytics/tiatoolbox
-  TOOLBOX_VER: 1.6.0
+  TOOLBOX_VER: 2.0.0
 
 jobs:
   build-and-push-image:
@@ -15,10 +15,6 @@ jobs:
       fail-fast: true
       matrix:
         include:
-          - dockerfile: ./docker/3.9/Debian/Dockerfile
-            mtag: py3.9-debian
-          - dockerfile: ./docker/3.9/Ubuntu/Dockerfile
-            mtag: py3.9-ubuntu
           - dockerfile: ./docker/3.10/Debian/Dockerfile
             mtag: py3.10-debian
           - dockerfile: ./docker/3.10/Ubuntu/Dockerfile
@@ -31,7 +27,11 @@ jobs:
             mtag: py3.12-debian
           - dockerfile: ./docker/3.12/Ubuntu/Dockerfile
             mtag: py3.12-ubuntu
-          - dockerfile: ./docker/3.12/Ubuntu/Dockerfile
+          - dockerfile: ./docker/3.13/Ubuntu/Dockerfile
+            mtag: py3.13-debian
+          - dockerfile: ./docker/3.13/Ubuntu/Dockerfile
+            mtag: py3.13-ubuntu
+          - dockerfile: ./docker/3.13/Ubuntu/Dockerfile
             mtag: latest
     permissions:
       contents: read

.github/workflows/mypy-type-check.yml

@@ -1,6 +1,8 @@
 # This workflow will perform code type checking using mypy
 
 name: mypy type checking
+permissions:
+  contents: read
 
 on:
   push:
@@ -16,7 +18,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
 
@@ -33,17 +35,25 @@ jobs:
         sudo apt update
         sudo apt-get install -y libopenslide-dev openslide-tools libopenjp2-7 libopenjp2-tools
         python -m pip install --upgrade pip
+        pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
         pip install -r requirements/requirements_dev.txt
 
     - name: Perform type checking
       run: |
         mypy --install-types --non-interactive --follow-imports=skip \
           tiatoolbox/__init__.py \
           tiatoolbox/__main__.py \
-          tiatoolbox/typing.py \
+          tiatoolbox/type_hints.py \
           tiatoolbox/tiatoolbox.py \
           tiatoolbox/utils \
           tiatoolbox/tools \
           tiatoolbox/data \
           tiatoolbox/annotation \
-          tiatoolbox/cli/common.py
+          tiatoolbox/cli/common.py \
+          tiatoolbox/models/__init__.py \
+          tiatoolbox/models/models_abc.py \
+          tiatoolbox/models/architecture/__init__.py \
+          tiatoolbox/models/architecture/utils.py \
+          tiatoolbox/wsicore/__init__.py \
+          tiatoolbox/wsicore/wsimeta.py \
+          tiatoolbox/wsicore/metadata/

.github/workflows/pip-install.yml

@@ -1,89 +1,193 @@
-# This workflow will install the package as is on the github default branch using pip
-
 name: pip Install
 
 on:
-    push:
-        paths: [ "requirements*.yml", "conda-env-create.yml", "requirements/requirement*.txt", "setup*py", "setup*cfg", "pytproject*toml", "MANIFEST*in"]
+  push:
+    paths:
+      - "requirements*.yml"
+      - "conda-env-create.yml"
+      - "requirements/requirement*.txt"
+      - "setup*py"
+      - "setup*cfg"
+      - "pyproject*toml"
+      - "MANIFEST*in"
+      - ".github/workflows/pip-install.yml"
+  pull_request:
+    paths:
+      - "requirements*.yml"
+      - "conda-env-create.yml"
+      - "requirements/requirement*.txt"
+      - "setup*py"
+      - "setup*cfg"
+      - "pyproject*toml"
+      - "MANIFEST*in"
+      - ".github/workflows/pip-install.yml"
+
+permissions:
+  contents: read
 
 jobs:
   build:
     runs-on: ${{ matrix.os }}
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         os: [ubuntu-24.04, windows-latest, macos-latest]
+
+    # Force UTF-8 everywhere (Windows is the one that really needs it)
+    env:
+      PYTHONUTF8: "1"
+      PYTHONIOENCODING: "utf-8"
+
     steps:
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: 🐧 Install OpenSlide & OpenJPEG
-      if: runner.os == 'Linux'
-      run: |
-        sudo apt update
-        sudo apt-get install -y libopenslide-dev openslide-tools libopenjp2-7 libopenjp2-tools
-        python -m pip install --upgrade pip
-    - name: 🍎 Install OpenSlide & OpenJPEG
-      if: runner.os == 'macOS'
-      run: |
-        brew install openslide openjpeg
-        python -m pip install --upgrade pip
-    - name: 🪟 Install OpenJPEG
-      if: runner.os == 'Windows'
-      run: |
-        # Install OpenJPEG
-        git clone https://github.com/uclouvain/openjpeg.git
-        cd openjpeg
-        mkdir build
-        cd build
-        cmake -G "MinGW Makefiles" .. -DCMAKE_BUILD_TYPE=Release
-        ls
-        make -j4
-        make install
-        make clean
-    - name: 🪟 Install OpenSlide
-      if: runner.os == 'Windows'
-      run: |
-        choco install wget --no-progress
-        wget https://github.com/openslide/openslide-winbuild/releases/download/v20220811/openslide-win64-20220811.zip
-        7z x openslide-win64-20220811.zip
-        ls openslide-win64-20220811
-        # Add to PATH
-        echo "$(realpath ./openslide-win64-20220811/bin)" >> $GITHUB_PATH
-        echo "$(realpath ./openslide-win64-20220811/lib)" >> $GITHUB_PATH
-        # Install
-        mkdir "C:\Program Files\openslide"
-        Copy-Item -Path ".\openslide-win64-20220811\*" -Destination "C:\Program Files\openslide" -Recurse
-        ls "C:/Program Files/openslide"
-    - name: 🪟 Install SQLite Shell
-      if: runner.os == 'Windows'
-      run: choco install sqlite.shell --no-progress
-    - name: SQLite Version Information
-      run: |
-        sqlite3 --version
-        sqlite3 ":memory:" -list ".output stdout" "pragma compile_options" ".exit"
-    - name: OpenSlide Version Information
-      if: runner.os == 'Linux'
-      run: openslide-quickhash1sum --version
-    - name: OpenJPEG Version Information
-      continue-on-error: true  # This -h option has exit code 1 for some reason
-      run: opj_dump -h
-    - name: pip Install From GitHub Repo on Linux and macOS
-      if: runner.os != 'Windows'
-      run: python -m pip install git+https://github.com/TissueImageAnalytics/tiatoolbox@${GITHUB_REF_NAME}
-    - name: pip Install From GitHub on Windows
-      if: runner.os == 'Windows'
-      run: python -m pip install git+https://github.com/TissueImageAnalytics/tiatoolbox@$env:GITHUB_REF_NAME
-    - name: Test TIAToolbox Import
-      shell: python
-      run: |
-        import os
-        if hasattr(os, "add_dll_directory"):
-          # Required for Python>=3.8 on Windows
-          with os.add_dll_directory(r"D:\a\tiatoolbox\tiatoolbox\openslide-win64-20220811\bin"):
-            import tiatoolbox
-        else:
-          os.environ["PATH"] = r"D:\a\tiatoolbox\tiatoolbox\openslide-win64-20220811\bin;"
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Miniconda
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          channels: conda-forge
+          channel-priority: strict
+          auto-update-conda: true
+
+      # -------------------------------
+      # Create environment (Linux/macOS)
+      # -------------------------------
+      - name: Create conda environment (Linux/macOS)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          conda create -y -n test-env python=${{ matrix.python-version }}
+          conda activate test-env
+          conda install -y openjpeg sqlite
+          python -m pip install --upgrade pip setuptools wheel
+
+      # -------------------------------
+      # Create environment (Windows)
+      # -------------------------------
+      - name: Create conda environment (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          conda create -y -n test-env python=${{ matrix.python-version }}
+          conda activate test-env
+          conda install -y openjpeg sqlite
+          python -m pip install --upgrade pip setuptools wheel
+
+      # -------------------------------
+      # Verify SQLite
+      # -------------------------------
+      - name: Verify SQLite (Linux/macOS)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          conda activate test-env
+          sqlite3 --version
+          sqlite3 ":memory:" -list ".output stdout" "pragma compile_options" ".exit"
+
+      - name: Verify SQLite (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          conda activate test-env
+          sqlite3 --version
+          sqlite3 ":memory:" -list ".output stdout" "pragma compile_options" ".exit"
+
+      # -------------------------------
+      # Verify OpenJPEG
+      # -------------------------------
+      - name: Verify OpenJPEG (Linux/macOS)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          conda activate test-env
+          opj_dump -h || true  # -h exits with code 1 in some builds
+
+      - name: Verify OpenJPEG (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          conda activate test-env
+          opj_dump -h || true  # -h exits with code 1 in some builds
+
+      # -------------------------------
+      # Install PyTorch (CPU-only)
+      # -------------------------------
+      - name: Install CPU-only PyTorch (Linux/macOS)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          conda activate test-env
+          pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install CPU-only PyTorch (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          conda activate test-env
+          pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+
+      # -------------------------------
+      # (Windows only) make console UTF-8 (extra safety)
+      # -------------------------------
+      - name: Ensure UTF-8 console (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          chcp 65001 > $null
+          [Console]::InputEncoding  = [System.Text.Encoding]::UTF8
+          [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+      # -------------------------------
+      # Install tiatoolbox from this commit
+      # -------------------------------
+      - name: Install tiatoolbox (Linux/macOS)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          conda activate test-env
+          pip install git+https://github.com/TissueImageAnalytics/tiatoolbox@${GITHUB_SHA}
+
+      - name: Install tiatoolbox (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          conda activate test-env
+          pip install git+https://github.com/TissueImageAnalytics/tiatoolbox@$env:GITHUB_SHA
+
+      # -------------------------------
+      # Test Imports
+      # -------------------------------
+      - name: Test Imports (Linux/macOS)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          conda activate test-env
+          python - << 'EOF'
+          import tiatoolbox
+          print("tiatoolbox:", tiatoolbox.__version__)
+          import openslide
+          print("openslide:", openslide.__version__)
+          import torch
+          print("torch:", torch.__version__)
+          EOF
+
+      - name: Test Imports (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          conda activate test-env
+          @"
           import tiatoolbox
+          print("tiatoolbox:", tiatoolbox.__version__)
+          import openslide
+          print("openslide:", openslide.__version__)
+          import torch
+          print("torch:", torch.__version__)
+          "@ | python -