🆕 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.11%. Comparing base (15df5e1) to head (e1862eb).

Additional details and impacted files

@@                    Coverage Diff                     @@
##           dev-define-engines-abc     #981      +/-   ##
==========================================================
+ Coverage                   95.50%   99.11%   +3.60%     
==========================================================
  Files                          80       81       +1     
  Lines                       10361    10701     +340     
  Branches                     1360     1424      +64     
==========================================================
+ Hits                         9895    10606     +711     
+ Misses                        429       62     -367     
+ Partials                       37       33       -4     

☔ 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

Copilot reviewed 32 out of 33 changed files in this pull request and generated 10 comments.

---

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

[Jiaqi-Lv]

Looks Good.