✨ NEW: Add Nucleus Detection Engine

docs/pretrained.rst

@@ -326,7 +326,7 @@ The input output configuration is as follows:
         ioconfig = IOPatchPredictorConfig(
             patch_input_shape=(31, 31),
             stride_shape=(8, 8),
-            input_resolutions=[{"resolution": 0.25, "units": "mpp"}]
+            input_resolutions=[{"resolution": 0.5, "units": "mpp"}]
         )
 
 
@@ -342,7 +342,7 @@ The input output configuration is as follows:
         ioconfig = IOPatchPredictorConfig(
             patch_input_shape=(252, 252),
             stride_shape=(150, 150),
-            input_resolutions=[{"resolution": 0.25, "units": "mpp"}]
+            input_resolutions=[{"resolution": 0.5, "units": "mpp"}]
         )
 
 
@@ -366,7 +366,7 @@ The input output configuration is as follows:
         ioconfig = IOPatchPredictorConfig(
             patch_input_shape=(31, 31),
             stride_shape=(8, 8),
-            input_resolutions=[{"resolution": 0.25, "units": "mpp"}]
+            input_resolutions=[{"resolution": 0.5, "units": "mpp"}]
         )
 
 
@@ -382,7 +382,7 @@ The input output configuration is as follows:
         ioconfig = IOPatchPredictorConfig(
             patch_input_shape=(252, 252),
             stride_shape=(150, 150),
-            input_resolutions=[{"resolution": 0.25, "units": "mpp"}]
+            input_resolutions=[{"resolution": 0.5, "units": "mpp"}]
         )
 
 

requirements/requirements.txt

@@ -1,5 +1,5 @@
 # torch installation
---extra-index-url https://download.pytorch.org/whl/cu117; sys_platform != "darwin"
+--extra-index-url https://download.pytorch.org/whl/cu118; sys_platform != "darwin"
 albumentations>=1.3.0
 Click>=8.1.3
 defusedxml>=0.7.1
@@ -25,7 +25,7 @@ shapely>=2.0.0
 SimpleITK>=2.2.1
 sphinx>=5.3.0
 tifffile>=2022.10.10
-torch>=2.0.0
+torch>=1.13.0
 torchvision>=0.14.1
 tqdm>=4.64.1
 umap-learn>=0.5.3

tests/models/test_nucleus_detection_engine.py

@@ -0,0 +1,67 @@
+"""Tests for NucleusDetector."""
+
+import pathlib
+import shutil
+
+import pandas as pd
+import pytest
+
+from tiatoolbox.models.engine.nucleus_detector import (
+    IONucleusDetectorConfig,
+    NucleusDetector,
+)
+from tiatoolbox.utils import env_detection as toolbox_env
+
+ON_GPU = not toolbox_env.running_on_ci() and toolbox_env.has_gpu()
+
+
+def _rm_dir(path):
+    """Helper func to remove directory."""
+    if pathlib.Path(path).exists():
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def check_output(path):
+    """Check NucleusDetector output."""
+    coordinates = pd.read_csv(path)
+    assert coordinates.x[0] == pytest.approx(53, abs=2)
+    assert coordinates.x[1] == pytest.approx(55, abs=2)
+    assert coordinates.y[0] == pytest.approx(107, abs=2)
+    assert coordinates.y[1] == pytest.approx(127, abs=2)
+
+
+def test_nucleus_detector_engine(remote_sample, tmp_path):
+    """Test for nucleus detection engine."""
+    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_512_512_svs"))
+
+    nucleus_detector = NucleusDetector(pretrained_model="mapde-conic")
+    _ = nucleus_detector.predict(
+        [mini_wsi_svs],
+        mode="wsi",
+        save_dir=tmp_path / "output",
+        on_gpu=ON_GPU,
+    )
+
+    check_output(tmp_path / "output" / "0.locations.0.csv")
+
+    _rm_dir(tmp_path / "output")
+
+    ioconfig = IONucleusDetectorConfig(
+        input_resolutions=[{"units": "mpp", "resolution": 0.5}],
+        output_resolutions=[{"units": "mpp", "resolution": 0.5}],
+        save_resolution=None,
+        patch_input_shape=[252, 252],
+        patch_output_shape=[252, 252],
+        stride_shape=[150, 150],
+    )
+
+    nucleus_detector = NucleusDetector(pretrained_model="mapde-conic")
+    _ = nucleus_detector.predict(
+        [mini_wsi_svs],
+        mode="wsi",
+        save_dir=tmp_path / "output",
+        on_gpu=ON_GPU,
+        ioconfig=ioconfig,
+    )
+
+    check_output(tmp_path / "output" / "0.locations.0.csv")

tests/models/test_patch_predictor.py

@@ -548,22 +548,22 @@ def test_io_config_delegation(remote_sample, tmp_path):
     predictor = PatchPredictor(pretrained_model="resnet18-kather100k", batch_size=1)
     predictor.predict(
         [mini_wsi_svs],
-        patch_input_shape=[300, 300],
+        patch_input_shape=(300, 300),
         mode="wsi",
         on_gpu=ON_GPU,
         save_dir=f"{tmp_path}/dump",
     )
-    assert predictor._ioconfig.patch_input_shape == [300, 300]
+    assert predictor._ioconfig.patch_input_shape == (300, 300)
     _rm_dir(f"{tmp_path}/dump")
 
     predictor.predict(
         [mini_wsi_svs],
-        stride_shape=[300, 300],
+        stride_shape=(300, 300),
         mode="wsi",
         on_gpu=ON_GPU,
         save_dir=f"{tmp_path}/dump",
     )
-    assert predictor._ioconfig.stride_shape == [300, 300]
+    assert predictor._ioconfig.stride_shape == (300, 300)
     _rm_dir(f"{tmp_path}/dump")
 
     predictor.predict(

tiatoolbox/data/pretrained_model.yaml

@@ -765,7 +765,6 @@ micronet-consep:
                 - {"units": "mpp", "resolution": 0.25}
             output_resolutions:
                 - {"units": "mpp", "resolution": 0.25}
-            margin: 128
             tile_shape: [2048, 2048]
             patch_input_shape: [252, 252]
             patch_output_shape: [252, 252]
@@ -777,66 +776,90 @@ mapde-crchisto:
     architecture:
         class: mapde.MapDe
         kwargs:
-            input_resolutions:
-                - { "units": "mpp", "resolution": 0.25 }
             num_input_channels: 3
             min_distance: 4
             threshold_abs: 250
             num_classes: 1
+    ioconfig:
+        class: semantic_segmentor.IOSegmentorConfig
+        kwargs:
+            input_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
+            output_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
             tile_shape: [ 2048, 2048 ]
             patch_input_shape: [ 252, 252 ]
+            patch_output_shape: [ 252, 252 ]
             stride_shape: [ 150, 150 ]
+            save_resolution: { 'units': 'mpp', 'resolution': 0.5 }
 
 mapde-conic:
     url: https://tiatoolbox.dcs.warwick.ac.uk/models/detection/mapde-conic.pth
     architecture:
         class: mapde.MapDe
         kwargs:
-            input_resolutions:
-                - { "units": "mpp", "resolution": 0.25 }
             num_input_channels: 3
             min_distance: 3
             threshold_abs: 205
             num_classes: 1
+    ioconfig:
+        class: semantic_segmentor.IOSegmentorConfig
+        kwargs:
+            input_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
+            output_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
             tile_shape: [ 2048, 2048 ]
             patch_input_shape: [ 252, 252 ]
+            patch_output_shape: [ 252, 252 ]
             stride_shape: [ 150, 150 ]
+            save_resolution: { 'units': 'mpp', 'resolution': 0.5 }
 
 sccnn-crchisto:
     url: https://tiatoolbox.dcs.warwick.ac.uk/models/detection/sccnn-crchisto.pth
     architecture:
         class: sccnn.SCCNN
         kwargs:
-            input_resolutions:
-                - { "units": "mpp", "resolution": 0.25 }
             num_input_channels: 3
-            out_height: 13
-            out_width: 13
             radius: 12
             min_distance: 6
             threshold_abs: 0.20
+            patch_output_shape: [ 13, 13 ]
+    ioconfig:
+        class: semantic_segmentor.IOSegmentorConfig
+        kwargs:
+            input_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
+            output_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
             tile_shape: [ 2048, 2048 ]
             patch_input_shape: [ 31, 31 ]
             patch_output_shape: [ 13, 13 ]
             stride_shape: [ 8, 8 ]
+            save_resolution: { 'units': 'mpp', 'resolution': 0.5 }
 
 sccnn-conic:
     url: https://tiatoolbox.dcs.warwick.ac.uk/models/detection/sccnn-conic.pth
     architecture:
         class: sccnn.SCCNN
         kwargs:
-            input_resolutions:
-                - { "units": "mpp", "resolution": 0.25 }
             num_input_channels: 3
-            out_height: 13
-            out_width: 13
             radius: 12
             min_distance: 5
             threshold_abs: 0.05
+            patch_output_shape: [ 13, 13 ]
+    ioconfig:
+        class: semantic_segmentor.IOSegmentorConfig
+        kwargs:
+            input_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
+            output_resolutions:
+                - { "units": "mpp", "resolution": 0.5 }
             tile_shape: [ 2048, 2048 ]
             patch_input_shape: [ 31, 31 ]
             patch_output_shape: [ 13, 13 ]
             stride_shape: [ 8, 8 ]
+            save_resolution: { 'units': 'mpp', 'resolution': 0.5 }
 
 nuclick_original-pannuke:
     url: https://tiatoolbox.dcs.warwick.ac.uk/models/seg/nuclick_original-pannuke.pth

tiatoolbox/models/engine/__init__.py

@@ -1,5 +1,6 @@
 """Engines to run models implemented in tiatoolbox."""
 from tiatoolbox.models.engine import (
+    nucleus_detector,
     nucleus_instance_segmentor,
     patch_predictor,
     semantic_segmentor,