🆕 Add Reading Slide-level info & Simple Plugins for Visualization Tool

docs/visualization.rst

@@ -265,6 +265,11 @@ Additional features can be added to nodes by adding extra keys to the dictionary
 
 It will be possible to color the nodes by these features in the interface, and the top 10 will appear in a tooltip when hovering over a node (you will have to turn on the hovertool in the small toolbar to the right of the main window to enable this, it is disabled by default).
 
+Slide Level Information
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have slide-level predictions, ground truth labels, or other metadata you wish to be able to see associated with slides in the interface, this can be provided as a .csv formatted table placed in the slides folder, with "Image File" as the first column. The other columns can be anything you like. When loading a slide in the UI, if the slide name appears in the "Image File" column of the provided .csv, any other entries in that row will be displayed in the interface below the main view window when the slide is selected.
+
 .. _examples:
 
 4. Annotation Store Examples
@@ -460,7 +465,7 @@ and the ability to toggle on or off specific UI elements:
 
 ::
 
-    "UI_elements_1": {              # controls which UI elements are visible
+    "ui_elements_1": {              # controls which UI elements are visible
         "slide_select": 1,          # slide select box
         "layer_drop": 1,            # overlay select drop down
         "slide_row": 1,             # slide alpha toggle and slider
@@ -475,7 +480,7 @@ and the ability to toggle on or off specific UI elements:
 
 ::
 
-    "UI_elements_2": {              # controls visible UI elements on second tab in UI
+    "ui_elements_2": {              # controls visible UI elements on second tab in UI
         "opt_buttons": 1,           # UI elements providing a few options including if annotations should be filled/outline only
         "pt_size_spinner": 1,       # control for point size and graph node size
         "edge_size_spinner": 1,     # control for edge thickness

tests/conftest.py

@@ -622,6 +622,7 @@ def data_path(tmp_path_factory: pytest.TempPathFactory) -> dict[str, object]:
     """Set up a temporary data directory for testing visualization UI."""
     tmp_path = tmp_path_factory.mktemp("data")
     (tmp_path / "slides").mkdir()
+    (tmp_path / "slides" / "CMU-1_files").mkdir()
     (tmp_path / "overlays").mkdir()
     return {"base_path": tmp_path}
 

tests/test_app_bokeh.py

@@ -101,6 +101,10 @@ def annotation_path(data_path: dict[str, Path]) -> dict[str, object]:
         "patch-extraction-vf",
         data_path["base_path"] / "slides",
     )
+    data_path["meta"] = _fetch_remote_sample(
+        "test_meta",
+        data_path["base_path"] / "slides",
+    )
     data_path["annotations"] = _fetch_remote_sample(
         "annotation_store_svs_1",
         data_path["base_path"] / "overlays",
@@ -134,6 +138,14 @@ def annotation_path(data_path: dict[str, Path]) -> dict[str, object]:
         "config_2",
         data_path["base_path"] / "overlays",
     )
+    data_path["plugin_img"] = _fetch_remote_sample(
+        "stainnorm-source",
+        data_path["base_path"] / "slides" / "CMU-1_files",
+    )
+    data_path["plugin_csv"] = _fetch_remote_sample(
+        "test_csv",
+        data_path["base_path"] / "slides" / "CMU-1_files",
+    )
     return data_path
 
 
@@ -186,8 +198,8 @@ def test_get_level_by_extent() -> None:
 
 def test_roots(doc: Document) -> None:
     """Test that the document has the correct number of roots."""
-    # should be 4 roots: main window, controls, slide_info, popup table
-    assert len(doc.roots) == 4
+    # should be 5 roots: main window, controls, slide_info, popup, extra_layout
+    assert len(doc.roots) == 5
 
 
 def test_config_loaded(data_path: pytest.TempPathFactory) -> None:
@@ -215,6 +227,11 @@ def test_slide_select(doc: Document, data_path: pytest.TempPathFactory) -> None:
     slide_select.value = ["CMU-1.ndpi"]
     assert main.UI["vstate"].slide_path == data_path["slide2"]
 
+    # check the slide metadata is loaded from csv
+    desc = doc.get_model_by_name("description")
+    assert "valA" in desc.text
+    assert "valB" not in desc.text
+
     # check selecting nothing has no effect
     slide_select.value = []
     assert main.UI["vstate"].slide_path == data_path["slide2"]

tests/test_json_config_bokeh.py

@@ -7,6 +7,7 @@
 from threading import Thread
 from typing import TYPE_CHECKING
 
+import pandas as pd
 import pytest
 import requests
 from bokeh.client.session import ClientSession, pull_session
@@ -29,6 +30,15 @@ def annotation_path(data_path: dict[str, Path]) -> dict[str, Path]:
         "ndpi-1",
         data_path["base_path"] / "slides",
     )
+    data_path["meta"] = _fetch_remote_sample(
+        "test_meta",
+        data_path["base_path"] / "slides",
+    )
+    meta_df = pd.read_csv(data_path["meta"])
+    # change 'Image File' column name to 'Wrong Name'
+    meta_df = meta_df.rename(columns={"Image File": "Wrong Name"})
+    # save so we can test behaviour if required column isn't there
+    meta_df.to_csv(data_path["meta"], index=False)
     data_path["annotations"] = _fetch_remote_sample(
         "annotation_store_svs_1",
         data_path["base_path"] / "overlays",
@@ -82,6 +92,10 @@ def test_slides_available(bk_session: ClientSession) -> None:
     slide_select.value = ["CMU-1.ndpi"]
     assert len(layer_drop.menu) == 2
 
+    # check the metadata wasnt found as the column name was wrong
+    desc = doc.get_model_by_name("description")
+    assert "Metadata:" not in desc.text
+
     bk_session.document.clear()
     assert len(bk_session.document.roots) == 0
     bk_session.close()

tiatoolbox/cli/visualize.py

@@ -77,6 +77,14 @@ def run_bokeh(img_input: list[str], port: int, *, noshow: bool) -> None:
     This option must be used in conjunction with --slides.
     The --base-path option should not be used in this case.""",
 )
+@click.option(
+    "--plugin",
+    multiple=True,
+    help=r"""Path to a file to define an extra layout containing extra
+    resources such as graphs below each slide. Some pre-built plugins are
+    available in the tiatoolbox\visualization\templates folder. Can pass
+    multiple instances of this option to add multiple ui additions.""",
+)
 @click.option(
     "--port",
     type=int,
@@ -88,6 +96,7 @@ def visualize(
     base_path: str,
     slides: str,
     overlays: str,
+    plugin: list[str],
     port: int,
     *,
     noshow: bool,
@@ -101,6 +110,7 @@ def visualize(
         base_path (str): Path to base directory containing images to be displayed.
         slides (str): Path to directory containing slides to be displayed.
         overlays (str): Path to directory containing overlays to be displayed.
+        plugin (list): Paths to files containing ui plugins.
         port (int): Port to launch the visualization tool on.
         noshow (bool): Do not launch in browser (mainly intended for testing).
 
@@ -109,7 +119,7 @@ def visualize(
     if base_path is None and (slides is None or overlays is None):
         msg = "Must specify either base-path or both slides and overlays."
         raise ValueError(msg)
-    img_input = [base_path, slides, overlays]
+    img_input = [base_path, slides, overlays, *list(plugin)]
     img_input = [p for p in img_input if p is not None]
     # check that the input paths exist
     for input_path in img_input:

tiatoolbox/data/remote_samples.yaml

@@ -143,6 +143,10 @@ files:
     url: [*testdata, "annotation/test1_config.json"]
   config_2:
     url: [*testdata, "annotation/test2_config.json"]
+  test_meta:
+    url: [*testdata, "annotation/test_meta.csv"]
+  test_csv:
+    url: [*testdata, "annotation/metrics_10.csv"]
   patch_annotations:
     url: [*testdata, "annotation/sample_wsi_patch_preds.db"]
   nuclick-output: