Merge branch 'develop' of https://github.com/TissueImageAnalytics/tiatoolbox into address-review-comments

Author: measty

.github/workflows/python-package.yml

@@ -30,7 +30,7 @@ jobs:
         sudo apt update
         sudo apt-get install -y libopenjp2-7 libopenjp2-tools
         python -m pip install --upgrade pip
-        python -m pip install ruff==0.11.13 pytest pytest-cov pytest-runner
+        python -m pip install ruff==0.12.7 pytest pytest-cov pytest-runner
         pip install -r requirements/requirements.txt
     - name: Cache tiatoolbox static assets
       uses: actions/cache@v3

.pre-commit-config.yaml

@@ -60,7 +60,7 @@ repos:
       - id: rst-inline-touching-normal # Detect mistake of inline code touching normal text in rst.
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.11.13
+    rev: v0.12.7
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

benchmarks/annotation_store_alloc.py

@@ -141,6 +141,7 @@ def __exit__(self: memray, *args: object) -> None:
 
 import numpy as np
 import psutil
+from shapely import affinity
 from shapely.geometry import Polygon
 from tqdm import tqdm
 
@@ -188,8 +189,6 @@ def cell_polygon(
         round_coords (bool): Round coordinates to integers. Defaults to False.
 
     """
-    from shapely import affinity
-
     rand_state = np.random.default_rng().__getstate__()
     rng = np.random.default_rng(seed)
     if repeat_first:

docs/images/dual_win_reg.png

@@ -119,6 +119,55 @@ A filter can be applied to annotations using the filter box. For example, enteri
 
 The main slide view can be made fullscreen by clicking the fullscreen icon in the small toolbar to the immediate right of the main window. This toolbar also provides a button to save the current view as a .png file.
 
+Visualising Image Registration/Transformation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: images/dual_win_reg.png
+    :width: 100%
+    :align: center
+    :alt: dual window example
+
+
+TIAToolbox provides a powerful registration visualization feature that enables intuitive alignment and comparison of histopathology images—such as H&E and IHC-stained slides—without requiring full whole-slide registration. This is particularly useful for quickly inspecting the accuracy of precomputed registration results.
+
+To use this feature, you must supply a precomputed registration matrix (e.g., .mha or .npy file) generated from an affine or deformable registration process. This matrix is used to align the images visually.
+
+Dual Window Mode:
+"""""""""""""""""
+
+This mode allows side-by-side comparison of registered images.
+
+**Steps:**
+
+* Open **Dual Window Mode** and load the images.
+
+* In one window, open the H&E (source) image.
+
+* In the other window, open the IHC (target) image.
+
+* Load the registration file (e.g., an .mha or .npy file) as an overlay on the source image.
+
+Overlay Mode:
+"""""""""""""
+
+This mode overlays the registered image directly on top of the source image for visual inspection.
+
+
+**Steps:**
+
+* Open the H&E (source) image.
+
+* Overlay the IHC (target) image on the source image.
+
+* Load the registration file (e.g., an .mha or .npy file) as an overlay on the source image.
+
+.. note::
+   Always load the **target image first** when using overlays. If not, the system may incorrectly assume both images are the same, leading to inaccurate transformations. Incorrect ordering may result in misaligned overlays or misleading visualizations.
+
+
+The **order** of source and target images must remain consistent with how the registration matrix was computed. This is as most registration algorithms require the dimensions of both the source and target images to perform the registration transformation. The above examples assume that the H&E image is registered to the IHC images, but if instead you have registered the IHC to the H&E image then please change the order of image loading accordingly.
+
+
 .. _data_format:
 
 3. Data Format Conventions and File Structure

docs/visualization.rst

@@ -14,7 +14,7 @@
 def git_branch_name() -> str:
     """Get the current branch name."""
     return (
-        subprocess.check_output(  # noqa: S603
+        subprocess.check_output(
             ["/usr/bin/git", "rev-parse", "--abbrev-ref", "HEAD"],
         )
         .decode()
@@ -45,7 +45,7 @@ def git_previous_commit_modified_paths() -> set[Path]:
     """Get a set of file paths modified in the previous commit."""
     return {
         Path(p)
-        for p in subprocess.check_output(  # noqa: S603
+        for p in subprocess.check_output(
             ["/usr/bin/git", "diff", "--name-only", "HEAD~"],
         )
         .decode()

pre-commit/notebook_urls.py

@@ -115,7 +115,7 @@ def parse_setup_py(file_path: Path) -> dict[str, Requirement]:
             pkg_resources.Requirement.
     """
     mock_setup = {}
-    import setuptools
+    import setuptools  # noqa: PLC0415
 
     setuptools.setup = lambda **kw: mock_setup.update(kw)
     spec = importlib.util.spec_from_file_location("setup", str(file_path))

pre-commit/requirements_consistency.py

@@ -10,7 +10,7 @@ pytest>=7.2.0
 pytest-cov>=4.0.0
 pytest-runner>=6.0
 pytest-xdist[psutil]
-ruff==0.11.13  # This will be updated by pre-commit bot to latest version
+ruff==0.12.7  # This will be updated by pre-commit bot to latest version
 toml>=0.10.2
 twine>=4.0.1
 wheel>=0.37.1

requirements/requirements_dev.txt

@@ -589,9 +589,9 @@ def chdir() -> Callable:
 
     """
     try:
-        from contextlib import chdir
+        from contextlib import chdir  # noqa: PLC0415
     except ImportError:
-        from contextlib import AbstractContextManager
+        from contextlib import AbstractContextManager  # noqa: PLC0415
 
         class chdir(AbstractContextManager):  # noqa: N801
             """Non thread-safe context manager to change the current working directory.

tests/conftest.py

@@ -11,19 +11,19 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-import bokeh.models as bkmodels
 import matplotlib.pyplot as plt
 import numpy as np
 import pytest
 import requests
-from bokeh.application import Application
-from bokeh.application.handlers import FunctionHandler
-from bokeh.events import ButtonClick, DoubleTap, MenuItemClick
 from flask_cors import CORS
 from matplotlib import colormaps
 from PIL import Image
 from scipy.ndimage import label
 
+import bokeh.models as bkmodels
+from bokeh.application import Application
+from bokeh.application.handlers import FunctionHandler
+from bokeh.events import ButtonClick, DoubleTap, MenuItemClick
 from tiatoolbox.data import _fetch_remote_sample
 from tiatoolbox.visualization.bokeh_app import main
 from tiatoolbox.visualization.tileserver import TileServer
@@ -125,6 +125,11 @@ def annotation_path(data_path: dict[str, Path]) -> dict[str, object]:
         "annotation_dat_svs_1",
         data_path["base_path"] / "overlays",
     )
+    data_path["affine_trans"] = (
+        data_path["base_path"] / "overlays" / (data_path["slide1"].stem + ".npy")
+    )
+    # save eye as test identity transform
+    np.save(data_path["affine_trans"], np.eye(3))
     data_path["config"] = _fetch_remote_sample(
         "config_2",
         data_path["base_path"] / "overlays",
@@ -246,6 +251,31 @@ def test_remove_dual_window(doc: Document, data_path: pytest.TempPathFactory) ->
     assert main.UI["vstate"].slide_path == data_path["slide1"]
 
 
+def test_add_slide_layer(doc: Document, data_path: pytest.TempPathFactory) -> None:
+    """Test adding a non-annotation slide layer."""
+    slide_select = doc.get_model_by_name("slide_select0")
+    slide_select.value = [data_path["slide1"].name]
+
+    layer_drop = doc.get_model_by_name("layer_drop0")
+    slide_layer_path = str(data_path["slide1"])
+
+    click = MenuItemClick(layer_drop, slide_layer_path)
+    layer_drop._trigger_event(click)
+
+    assert len(layer_drop.menu) == 6
+
+
+def test_transform_overlay(doc: Document, data_path: pytest.TempPathFactory) -> None:
+    """Test adding a transform overlay."""
+    layer_drop = doc.get_model_by_name("layer_drop0")
+    affine_layer_path = str(data_path["affine_trans"])  # sample .npy file
+
+    click = MenuItemClick(layer_drop, affine_layer_path)
+    layer_drop._trigger_event(click)
+
+    assert len(layer_drop.menu) == 6
+
+
 def test_add_annotation_layer(doc: Document, data_path: pytest.TempPathFactory) -> None:
     """Test adding annotation layers."""
     # test loading a geojson file.
@@ -263,7 +293,7 @@ def test_add_annotation_layer(doc: Document, data_path: pytest.TempPathFactory)
     # test loading an annotation store
     slide_select.value = [data_path["slide1"].name]
     layer_drop = doc.get_model_by_name("layer_drop0")
-    assert len(layer_drop.menu) == 5
+    assert len(layer_drop.menu) == 6
     n_renderers = len(doc.get_model_by_name("slide_windows").children[0].renderers)
     # trigger an event to select the annotation .db file
     click = MenuItemClick(layer_drop, str(data_path["annotations"]))