🆕 Define MultiTaskSegmentor and NucleusInstanceSegmentor

[shaneahmed]

Summary

1. A new MultiTaskSegmentor engine supporting multi‑head models (e.g., HoVerNet and HoVerNetPlus) for both patch and WSI inference.
2. A new NucleusInstanceSegmentor, implemented as a thin, backward‑compatible wrapper on top of MultiTaskSegmentor, providing a simplified API for nucleus instance segmentation.
   • The class issues a deprecation warning and will be removed in a future release.
3. A fully updated CLI exposing:
   • multitask-segmentor
   • Updated nucleus-instance-segment (now powered by the MultiTask engine)
4. Architecture updates unify task outputs across HoVerNet & HoVerNetPlus.
5. EngineABC enhancements, including new Zarr‑saving utilities and stricter validation.

These updates significantly modernize the inference engine, unify multi‑task workflows, and prepare TIAToolbox for future segmentation models.

---

Key Changes

1) MultiTaskSegmentor

• Full multi‑task inference engine:
  • Patch‑mode and WSI‑mode
  • Horizontal and vertical stitching
  • Memory‑aware Zarr spillover
  • Output as dict, .zarr, or AnnotationStore
• Post‑processing organized per‑task ("task_type", "predictions", "info_dict").
• Supports per‑task return_predictions.
• Tile‑mode inference with instance de‑duplication for large WSIs.

2) NucleusInstanceSegmentor (inherits MultiTaskSegmentor)

• Drop‑in replacement for nucleus‑only instance segmentation.
• Reimplemented on top of the MultiTask engine.
• Emits a deprecation warning, encouraging migration to MultiTaskSegmentor.
• Compatible with patch/WSI workflows.
• CLI preserved:

  tiatoolbox nucleus-instance-segment ...

3) CLI Updates

• New multitask-segmentor command.
• Updated nucleus-instance-segment:
  • Uses IOSegmentorConfig
  • Supports new options: input/output resolutions, memory threshold, stride, patch shapes, predictions/ probabilities, masks, YAML config
• Adds boolean list parser (parse_bool_list) for --return-predictions.

4) Model Architecture: HoVerNet & HoVerNetPlus

• postproc now returns task dictionaries, not positional arrays.
• Added explicit .tasks and .class_dict.
• All instance fields standardized:
  • contour → contours
  • HoVerNetPlus layer predictions now include "box".
• Supports Dask for large‑array outputs.

5) EngineABC Improvements

• run() now requires save_dir when output_type = zarr|annotationstore.
• Adds _get_tasks_for_saving_zarr for:
  • Namespaced task saving
  • Object codec handling
  • Multi-array Zarr writes
• Safer dictionary construction.

6) Dependency Updates

• Dask requirement bumped to >=2026.1.2.

---

Breaking / Behavioral Changes

• postproc output changed to structured task dictionaries.
• contour consistently renamed to contours.
• EngineABC.run() raises on missing save_dir when using Zarr or AnnotationStore.
• NucleusInstanceSegmentor is now deprecated (internally uses MultiTaskSegmentor).

---

Usage Examples

Patch Mode

mt = MultiTaskSegmentor(model="hovernetplus-oed", device="cuda")
out = mt.run(
    images=patches,
    patch_mode=True,
    output_type="dict",
    return_probabilities=True,
    return_labels=False,
)

WSI Mode (Zarr Output)

from pathlib import Path

mt = MultiTaskSegmentor(model="hovernetplus-oed", batch_size=64)
out = mt.run(
    images=[slide],
    patch_mode=False,
    output_type="zarr",
    save_dir=Path("out/"),
    return_predictions=(False, True),  # per-task flags
)

WSI + AnnotationStore

from pathlib import Path

mt = MultiTaskSegmentor(model="hovernetplus-oed")
out = mt.run(
    images=[slide],
    patch_mode=False,
    output_type="annotationstore",
    save_dir=Path("ann/"),
    return_probabilities=True,
)

CLI

tiatoolbox multitask-segmentor \
  --img-input slides/ \
  --output-path results/ \
  --model hovernetplus-oed \
  --output-type annotationstore \
  --return-predictions False,True

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.13%. Comparing base (d6ef926) to head (7c62b3d).

Additional details and impacted files

@@                    Coverage Diff                     @@
##           dev-define-engines-abc     #981      +/-   ##
==========================================================
+ Coverage                   95.33%   99.13%   +3.80%     
==========================================================
  Files                          79       80       +1     
  Lines                       10001    10304     +303     
  Branches                     1290     1355      +65     
==========================================================
+ Hits                         9534    10215     +681     
+ Misses                        431       60     -371     
+ Partials                       36       29       -7     

☔ 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.

[Copilot]

Pull request overview

This PR introduces a comprehensive MultiTaskSegmentor engine for TIAToolbox that handles multi-head segmentation models (HoVerNet/HoVerNetPlus) with both patch and WSI inference capabilities. The implementation adds memory-aware processing with automatic Zarr spillover for large slides and refactors model post-processing into a unified, task-centric structure.

Changes:

• Adds new MultiTaskSegmentor engine with patch/WSI modes, memory-aware Zarr caching, and support for dict/zarr/annotationstore outputs
• Introduces CLI command tiatoolbox multitask-segmentor for terminal-based multi-task model execution
• Refactors HoVerNet/HoVerNetPlus postprocessing to return task-centric dictionaries and renames contour → contours
• Updates EngineABC to support Zarr task grouping and adds save_dir validation for zarr/annotationstore outputs
• Adds create_smart_array utility for memory-aware NumPy/Zarr allocation

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tiatoolbox/models/engine/multi_task_segmentor.py	New multi-task segmentation engine with comprehensive inference, post-processing, and saving capabilities
tiatoolbox/models/engine/engine_abc.py	Enhanced base engine with Zarr task grouping, save_dir validation, and dask config changes
tiatoolbox/models/architecture/hovernet.py	Updated postproc to return task dictionaries, renamed contour→contours, added dask support
tiatoolbox/models/architecture/hovernetplus.py	Extended hovernet changes with layer segmentation task and bounding boxes
tiatoolbox/cli/multitask_segmentor.py	New CLI command for multi-task segmentation
tiatoolbox/cli/common.py	Added parse_bool_list callback and cli_return_predictions for tuple[bool] parsing
tiatoolbox/cli/init.py	Registered new multitask-segmentor CLI command
tiatoolbox/utils/misc.py	Added create_smart_array for memory-aware array allocation with psutil
tests/*	Comprehensive test coverage for new functionality

---

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

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 7 comments.

---

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