NEW: Feature CLI For Nucleus Instance Segmentation (#194)

- Add cli for nucleus instance segmentation
  - Add tests for cli and remove tests if cli is covering these.
- Fix link for pretrained models in semantic segmentation
- Rearrange add commands in cli
- Replace `get_wsireader` with `WSIReader.open` as `get_wsireader` is being depreciated.
- Update installation instructions for pygeos.
- Fix OOM errors using garbage collection `gc.collect()`.

Co-authored by: @shaneahmed

Author: shaneahmed

docs/installation.rst

@@ -29,12 +29,19 @@ Windows
 1. Download OpenSlide binaries from `this page <https://openslide.org/download/>`_. Extract the folder and add `bin` and `lib` subdirectories to
 Windows `system path <https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)>`_.
 
-2. Install OpenJPEG. The easiest way is to install OpenJpeg is through conda
+2. Install
+TIAToolbox.
+
+.. code-block:: console
+
+    $ pip install tiatoolbox
+
+3. Install OpenJPEG. The easiest way is to install OpenJpeg is through conda
 using
 
 .. code-block:: console
 
-    C:\> conda install -c conda-forge openjpeg>=2.3.0
+    C:\> conda install -c conda-forge openjpeg pygeos
 
 Linux (Ubuntu)
 ^^^^^^^^^^^^^^

tests/models/test_nucleus_instance_segmentor.py

@@ -27,20 +27,24 @@
 import numpy as np
 import pytest
 import torch
+import yaml
+from click.testing import CliRunner
 
+from tiatoolbox import cli
 from tiatoolbox.models import (
     IOSegmentorConfig,
     NucleusInstanceSegmentor,
     SemanticSegmentor,
 )
+from tiatoolbox.models.architecture import fetch_pretrained_weights
 from tiatoolbox.models.engine.nucleus_instance_segmentor import (
     _process_tile_predictions,
 )
 from tiatoolbox.utils.metrics import f1_detection
 from tiatoolbox.utils.misc import imwrite
-from tiatoolbox.wsicore.wsireader import get_wsireader
+from tiatoolbox.wsicore.wsireader import WSIReader
 
-BATCH_SIZE = 2
+BATCH_SIZE = 1
 ON_TRAVIS = True
 ON_GPU = not ON_TRAVIS and torch.cuda.is_available()
 
@@ -57,11 +61,8 @@ def _crash_func(x):
     raise ValueError("Propataion Crash.")
 
 
-# ----------------------------------------------------
-
-
-def test_get_tile_info():
-    """Test for getting tile info."""
+def helper_tile_info():
+    """Helper function for tile information."""
     predictor = NucleusInstanceSegmentor(model="A")
     # ! assuming the tiles organized as follows (coming out from
     # ! PatchExtractor). If this is broken, need to check back
@@ -76,7 +77,6 @@ def test_get_tile_info():
     # ---------------------
     # | 12 | 13 | 14 | 15 |
     # ---------------------
-
     # ! assume flag index ordering: left right top bottom
     ioconfig = IOSegmentorConfig(
         input_resolutions=[{"units": "mpp", "resolution": 0.25}],
@@ -91,8 +91,17 @@ def test_get_tile_info():
         patch_input_shape=[4, 4],
         patch_output_shape=[4, 4],
     )
-    info = predictor._get_tile_info([16, 16], ioconfig)
-    boxes, flag = info[0]  # index 0 should be full grid, removal
+
+    return predictor._get_tile_info([16, 16], ioconfig)
+
+
+# ----------------------------------------------------
+
+
+def test_get_tile_info():
+    """Test for getting tile info."""
+    info = helper_tile_info()
+    _, flag = info[0]  # index 0 should be full grid, removal
     # removal flag at top edges
     assert (
         np.sum(
@@ -124,7 +133,10 @@ def test_get_tile_info():
         == 0
     ), "Fail Right"
 
-    # test for vertical boundary boxes
+
+def test_vertical_boundary_boxes():
+    """Test for vertical boundary boxes."""
+    info = helper_tile_info()
     _boxes = np.array(
         [
             [3, 0, 5, 4],
@@ -161,7 +173,10 @@ def test_get_tile_info():
     assert np.sum(_boxes - boxes) == 0, "Wrong Vertical Bounds"
     assert np.sum(flag - _flag) == 0, "Fail Vertical Flag"
 
-    # test for horizontal boundary boxes
+
+def test_horizontal_boundary_boxes():
+    """Test for horizontal boundary boxes."""
+    info = helper_tile_info()
     _boxes = np.array(
         [
             [0, 3, 4, 5],
@@ -198,7 +213,10 @@ def test_get_tile_info():
     assert np.sum(_boxes - boxes) == 0, "Wrong Horizontal Bounds"
     assert np.sum(flag - _flag) == 0, "Fail Horizontal Flag"
 
-    # test for cross-section boundary boxes
+
+def test_cross_section_boundary_boxes():
+    """Test for cross-section boundary boxes."""
+    info = helper_tile_info()
     _boxes = np.array(
         [
             [2, 2, 6, 6],
@@ -233,8 +251,11 @@ def test_get_tile_info():
 def test_crash_segmentor(remote_sample, tmp_path):
     """Test engine crash when given malformed input."""
     root_save_dir = pathlib.Path(tmp_path)
-    sample_wsi_svs = pathlib.Path(remote_sample("wsi2_4k_4k_svs"))
-    sample_wsi_msk = pathlib.Path(remote_sample("wsi2_4k_4k_msk"))
+    sample_wsi_svs = pathlib.Path(remote_sample("svs-1-small"))
+    sample_wsi_msk = remote_sample("small_svs_tissue_mask")
+    sample_wsi_msk = np.load(sample_wsi_msk).astype(np.uint8)
+    imwrite(f"{tmp_path}/small_svs_tissue_mask.jpg", sample_wsi_msk)
+    sample_wsi_msk = tmp_path.joinpath("small_svs_tissue_mask.jpg")
 
     save_dir = f"{root_save_dir}/instance/"
 
@@ -278,48 +299,16 @@ def test_crash_segmentor(remote_sample, tmp_path):
 def test_functionality_travis(remote_sample, tmp_path):
     """Functionality test for nuclei instance segmentor."""
     root_save_dir = pathlib.Path(tmp_path)
-    save_dir = pathlib.Path(f"{tmp_path}/output")
-    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_1k_1k_svs"))
+    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_512_512_svs"))
 
     resolution = 2.0
 
-    reader = get_wsireader(mini_wsi_svs)
+    reader = WSIReader.open(mini_wsi_svs)
     thumb = reader.slide_thumbnail(resolution=resolution, units="mpp")
     mini_wsi_jpg = f"{tmp_path}/mini_svs.jpg"
     imwrite(mini_wsi_jpg, thumb)
 
-    # resolution for travis testing, not the correct ones
-    ioconfig = IOSegmentorConfig(
-        input_resolutions=[{"units": "mpp", "resolution": resolution}],
-        output_resolutions=[
-            {"units": "mpp", "resolution": resolution},
-            {"units": "mpp", "resolution": resolution},
-            {"units": "mpp", "resolution": resolution},
-        ],
-        margin=128,
-        tile_shape=[512, 512],
-        patch_input_shape=[256, 256],
-        patch_output_shape=[164, 164],
-        stride_shape=[164, 164],
-    )
-
     save_dir = f"{root_save_dir}/instance/"
-    # * test run on tile, run without worker first
-    _rm_dir(save_dir)
-    inst_segmentor = NucleusInstanceSegmentor(
-        batch_size=1,
-        num_loader_workers=0,
-        num_postproc_workers=0,
-        pretrained_model="hovernet_fast-pannuke",
-    )
-    inst_segmentor.predict(
-        [mini_wsi_jpg],
-        mode="tile",
-        ioconfig=ioconfig,
-        on_gpu=ON_GPU,
-        crash_on_exception=True,
-        save_dir=save_dir,
-    )
 
     # * test run on wsi, test run with worker
     # resolution for travis testing, not the correct ones
@@ -337,6 +326,7 @@ def test_functionality_travis(remote_sample, tmp_path):
     )
 
     _rm_dir(save_dir)
+
     inst_segmentor = NucleusInstanceSegmentor(
         batch_size=1,
         num_loader_workers=0,
@@ -359,7 +349,7 @@ def test_functionality_travis(remote_sample, tmp_path):
 def test_functionality_merge_tile_predictions_travis(remote_sample, tmp_path):
     """Functional tests for merging tile predictions."""
     save_dir = pathlib.Path(f"{tmp_path}/output")
-    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_1k_1k_svs"))
+    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_512_512_svs"))
 
     resolution = 0.5
     ioconfig = IOSegmentorConfig(
@@ -439,6 +429,7 @@ def test_functionality_merge_tile_predictions_travis(remote_sample, tmp_path):
         )
 
     # test exception flag
+    tile_flag = [0, 0, 0, 0]
     with pytest.raises(ValueError, match=r".*Unknown tile mode.*"):
         _process_tile_predictions(
             ioconfig=ioconfig,
@@ -525,3 +516,97 @@ def test_functionality_local(remote_sample, tmp_path):
     score = f1_detection(inst_coords_b, inst_coords_a, radius=1.0)
     assert score > 0.9, "Heavy loss of precision!"
     _rm_dir(tmp_path)
+
+
+def test_cli_nucleus_instance_segment_ioconfig(remote_sample, tmp_path):
+    """Test for nucleus segmentation with IOconfig."""
+    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_512_512_svs"))
+    output_path = tmp_path / "output"
+
+    resolution = 2.0
+
+    reader = WSIReader.open(mini_wsi_svs)
+    thumb = reader.slide_thumbnail(resolution=resolution, units="mpp")
+    mini_wsi_jpg = f"{tmp_path}/mini_svs.jpg"
+    imwrite(mini_wsi_jpg, thumb)
+
+    fetch_pretrained_weights(
+        "hovernet_fast-pannuke", str(tmp_path.joinpath("hovernet_fast-pannuke.pth"))
+    )
+
+    # resolution for travis testing, not the correct ones
+    config = {
+        "input_resolutions": [{"units": "mpp", "resolution": resolution}],
+        "output_resolutions": [
+            {"units": "mpp", "resolution": resolution},
+            {"units": "mpp", "resolution": resolution},
+            {"units": "mpp", "resolution": resolution},
+        ],
+        "margin": 128,
+        "tile_shape": [512, 512],
+        "patch_input_shape": [256, 256],
+        "patch_output_shape": [164, 164],
+        "stride_shape": [164, 164],
+        "save_resolution": {"units": "mpp", "resolution": 8.0},
+    }
+
+    with open(tmp_path.joinpath("config.yaml"), "w") as fptr:
+        yaml.dump(config, fptr)
+
+    runner = CliRunner()
+    nucleus_instance_segment_result = runner.invoke(
+        cli.main,
+        [
+            "nucleus-instance-segment",
+            "--img-input",
+            str(mini_wsi_jpg),
+            "--pretrained-weights",
+            str(tmp_path.joinpath("hovernet_fast-pannuke.pth")),
+            "--num-loader-workers",
+            str(0),
+            "--num-postproc-workers",
+            str(0),
+            "--mode",
+            "tile",
+            "--output-path",
+            str(output_path),
+            "--yaml-config-path",
+            tmp_path.joinpath("config.yaml"),
+        ],
+    )
+
+    assert nucleus_instance_segment_result.exit_code == 0
+    assert output_path.joinpath("0.dat").exists()
+    assert output_path.joinpath("file_map.dat").exists()
+    assert output_path.joinpath("results.json").exists()
+    _rm_dir(tmp_path)
+
+
+def test_cli_nucleus_instance_segment(remote_sample, tmp_path):
+    """Test for nucleus segmentation."""
+    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_512_512_svs"))
+    output_path = tmp_path / "output"
+
+    runner = CliRunner()
+    nucleus_instance_segment_result = runner.invoke(
+        cli.main,
+        [
+            "nucleus-instance-segment",
+            "--img-input",
+            str(mini_wsi_svs),
+            "--mode",
+            "wsi",
+            "--num-loader-workers",
+            str(0),
+            "--num-postproc-workers",
+            str(0),
+            "--output-path",
+            str(output_path),
+        ],
+    )
+
+    assert nucleus_instance_segment_result.exit_code == 0
+    assert output_path.joinpath("0.dat").exists()
+    assert output_path.joinpath("file_map.dat").exists()
+    assert output_path.joinpath("results.json").exists()
+    _rm_dir(tmp_path)

tests/models/test_semantic_segmentation.py

@@ -24,6 +24,8 @@
 import pathlib
 import shutil
 
+# ! The garbage collector
+import gc
 import numpy as np
 import pytest
 import torch
@@ -77,8 +79,7 @@ def __init__(self):
 
     def forward(self, img):
         """Define how to use layer."""
-        output = self.conv(img)
-        return output
+        return self.conv(img)
 
     @staticmethod
     def infer_batch(model, batch_data, on_gpu):
@@ -136,22 +137,23 @@ def test_segmentor_ioconfig():
         patch_output_shape=[1024, 1024],
         stride_shape=[512, 512],
     )
+
     # error when uniform resolution units are not uniform
     with pytest.raises(ValueError, match=r".*Invalid resolution units.*"):
         xconfig = copy.deepcopy(default_config)
         xconfig["input_resolutions"] = [
             {"units": "mpp", "resolution": 0.25},
             {"units": "power", "resolution": 0.50},
         ]
-        ioconfig = IOSegmentorConfig(**xconfig)
+        _ = IOSegmentorConfig(**xconfig)
     # error when uniform resolution units are not supported
     with pytest.raises(ValueError, match=r".*Invalid resolution units.*"):
         xconfig = copy.deepcopy(default_config)
         xconfig["input_resolutions"] = [
             {"units": "alpha", "resolution": 0.25},
             {"units": "alpha", "resolution": 0.50},
         ]
-        ioconfig = IOSegmentorConfig(**xconfig)
+        _ = IOSegmentorConfig(**xconfig)
 
     ioconfig = IOSegmentorConfig(
         input_resolutions=[
@@ -209,7 +211,8 @@ def test_segmentor_ioconfig():
 
 def test_functional_wsi_stream_dataset(remote_sample):
     """Functional test for WSIStreamDataset."""
-    mini_wsi_svs = pathlib.Path(remote_sample("wsi2_4k_4k_svs"))
+    gc.collect()  # Force clean up everything on hold
+    mini_wsi_svs = pathlib.Path(remote_sample("wsi4_512_512_svs"))
 
     ioconfig = IOSegmentorConfig(
         input_resolutions=[

tiatoolbox/cli/__init__.py

@@ -25,6 +25,7 @@
 import click
 
 from tiatoolbox import __version__
+from tiatoolbox.cli.nucleus_instance_segment import nucleus_instance_segment
 from tiatoolbox.cli.patch_predictor import patch_predictor
 from tiatoolbox.cli.read_bounds import read_bounds
 from tiatoolbox.cli.save_tiles import save_tiles
@@ -52,15 +53,15 @@ def main():
     return 0
 
 
-main.add_command(slide_info)
+main.add_command(nucleus_instance_segment)
+main.add_command(patch_predictor)
 main.add_command(read_bounds)
-main.add_command(slide_thumbnail)
 main.add_command(save_tiles)
+main.add_command(semantic_segment)
+main.add_command(slide_info)
+main.add_command(slide_thumbnail)
 main.add_command(tissue_mask)
-main.add_command(patch_predictor)
 main.add_command(stain_norm)
-main.add_command(semantic_segment)
-
 
 if __name__ == "__main__":
     sys.exit(main())  # pragma: no cover