✨ Extend Annotation to Support Init from WKB (#639)

I have created this as a proof of concept in regard to my comments on #632.

This PR extends the `Annotation` class to enable the creation from either a set of coordinates and a geometry type (int) for direct decoding of the WKB OR from a shapely geometry object. The shapely geometry is created lazily, and vice versa; the coordinates can be accessed lazily if the Annotation was created from a Shapely object.

# Summary

1. Enables init of `Annotation` from WKB bytes instead of from Shapely geometry object. This can shorten the path from database WKB -> Shapely -> Numpy Array for applications which just need the raw coordinates and not any Shapely/geos methods.
1. Move `decode_wkb` to an Annotation static method. This could potentially be optimized with numba or similar in future.
1. Lazily create a Shapely geometry object, WKB, or raw numpy coordinates as needed. This can avoid converting WKB to shapely and then to coordinates and go directly from WKB to coordinates.
1. Add tests.
1. Update code relying on `as_wkb`.
1. Bug fixes including fixing exceptions on appending unsupported geometry and generation of coordinates from WKB in `decode_wkb`.
2. Ensures the coordinates generates from Shapely and from `decode_wkb` via `Annotation.coords` are in the same format as each other. I.e. 1x2 array for points, nx2 array for lines, list of nx2 arrays for poylgons and lists for the multi forms.

---------

Co-authored-by: measty <[email protected]>
Co-authored-by: Shan E Ahmed Raza <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 4 people

tests/test_annotation_stores.py

@@ -257,21 +257,17 @@ def sub_tile_level_count(self):
 
 
 def test_unknown_geometry(
-    fill_store,
-    tmp_path: Path,
+    fill_store,  # noqa: ARG001
     caplog: pytest.LogCaptureFixture,
 ) -> None:
     """Test warning when unknown geometries cannot be rendered."""
-    array = np.ones((1024, 1024))
-    wsi = wsireader.VirtualWSIReader(array)
-    _, store = fill_store(SQLiteStore, tmp_path / "test.db")
-    store.append(
-        Annotation(geometry=MultiPoint([(5.0, 5.0), (10.0, 10.0)]), properties={}),
-    )
-    store.commit()
     renderer = AnnotationRenderer(max_scale=8, edge_thickness=0)
-    tg = AnnotationTileGenerator(wsi.info, store, renderer, tile_size=256)
-    tg.get_tile(0, 0, 0)
+    renderer.render_by_type(
+        tile=np.zeros((256, 256, 3), dtype=np.uint8),
+        annotation=Annotation(MultiPoint([(5.0, 5.0), (10.0, 10.0)])),
+        top_left=(0, 0),
+        scale=1,
+    )
     assert "Unknown geometry" in caplog.text
 
 
@@ -431,16 +427,16 @@ def test_unfilled_polys(fill_store, tmp_path: Path) -> None:
     assert np.sum(tile_filled) > 2 * np.sum(tile_outline)
 
 
-def test_multipolygon_render(cell_grid, tmp_path: Path) -> None:
+def test_multipolygon_render(cell_grid) -> None:
     """Test multipolygon rendering."""
-    array = np.ones((1024, 1024))
-    wsi = wsireader.VirtualWSIReader(array, mpp=(1, 1))
-    store = SQLiteStore(tmp_path / "test.db")
-    # add a multi-polygon
-    store.append(Annotation(MultiPolygon(cell_grid), {"color": (1, 0, 0)}))
     renderer = AnnotationRenderer(score_prop="color", edge_thickness=0)
-    tg = AnnotationTileGenerator(wsi.info, store, renderer, tile_size=256)
-    tile = np.array(tg.get_tile(1, 0, 0))
+    tile = np.zeros((1024, 1024, 3), dtype=np.uint8)
+    renderer.render_multipoly(
+        tile=tile,
+        annotation=Annotation(MultiPolygon(cell_grid), {"color": (1, 0, 0)}),
+        top_left=(0, 0),
+        scale=1,
+    )
     _, num = label(np.array(tile)[:, :, 0])
     assert num == 25  # expect 25 red objects
 

tests/test_annotation_tilerendering.py

@@ -0,0 +1,40 @@
+"""Tests for the enumerated types used by TIAToolbox."""
+import pytest
+
+from tiatoolbox.enums import GeometryType
+
+
+def test_geometrytype_missing() -> None:
+    """Test that GeometryType.MISSING is returned when given None."""
+    with pytest.raises(ValueError, match="not a valid GeometryType"):
+        GeometryType(None)
+
+
+def test_geometrytype_point_from_string() -> None:
+    """Init GeometryType.POINT from string."""
+    assert GeometryType("Point") == GeometryType.POINT
+
+
+def test_geometrytype_linestring_from_string() -> None:
+    """Init GeometryType.LINE_STRING from string."""
+    assert GeometryType("LineString") == GeometryType.LINE_STRING
+
+
+def test_geometrytype_polygon_from_string() -> None:
+    """Init GeometryType.POLYGON from string."""
+    assert GeometryType("Polygon") == GeometryType.POLYGON
+
+
+def test_geometrytype_multipoint_from_string() -> None:
+    """Init GeometryType.MULTI_POINT from string."""
+    assert GeometryType("MultiPoint") == GeometryType.MULTI_POINT
+
+
+def test_geometrytype_multilinestring_from_string() -> None:
+    """Init GeometryType.MULTI_LINE_STRING from string."""
+    assert GeometryType("MultiLineString") == GeometryType.MULTI_LINE_STRING
+
+
+def test_geometrytype_multipolygon_from_string() -> None:
+    """Init GeometryType.MULTI_POLYGON from string."""
+    assert GeometryType("MultiPolygon") == GeometryType.MULTI_POLYGON

tests/test_enums.py

@@ -17,8 +17,9 @@
     Polygon,
 )
 
+from tiatoolbox.annotation.storage import Annotation
+from tiatoolbox.enums import GeometryType
 from tiatoolbox.utils.visualization import (
-    AnnotationRenderer,
     overlay_prediction_contours,
     overlay_prediction_mask,
     overlay_probability_map,
@@ -27,7 +28,7 @@
 from tiatoolbox.wsicore.wsireader import WSIReader
 
 
-def test_overlay_prediction_mask(sample_wsi_dict) -> None:
+def test_overlay_prediction_mask(sample_wsi_dict: dict) -> None:
     """Test for overlaying merged patch prediction of wsi."""
     mini_wsi_svs = Path(sample_wsi_dict["wsi2_4k_4k_svs"])
     mini_wsi_pred = Path(sample_wsi_dict["wsi2_4k_4k_pred"])
@@ -127,7 +128,7 @@ def test_overlay_prediction_mask(sample_wsi_dict) -> None:
     _ = overlay_prediction_mask(thumb_float, merged, min_val=0.5, return_ax=False)
 
 
-def test_overlay_probability_map(sample_wsi_dict) -> None:
+def test_overlay_probability_map(sample_wsi_dict: dict) -> None:
     """Test functional run for overlaying merged patch prediction of wsi."""
     mini_wsi_svs = Path(sample_wsi_dict["wsi2_4k_4k_svs"])
     reader = WSIReader.open(mini_wsi_svs)
@@ -216,8 +217,9 @@ def test_overlay_instance_prediction() -> None:
         type_colours=type_colours,
         line_thickness=1,
     )
+    ref_value = -12
     assert np.sum(canvas[..., 0].astype(np.int32) - inst_map) == 0
-    assert np.sum(canvas[..., 1].astype(np.int32) - inst_map) == -12
+    assert np.sum(canvas[..., 1].astype(np.int32) - inst_map) == ref_value
     assert np.sum(canvas[..., 2].astype(np.int32) - inst_map) == 0
     canvas = overlay_prediction_contours(
         canvas,
@@ -276,8 +278,6 @@ def test_plot_graph() -> None:
 
 def test_decode_wkb() -> None:
     """Test decoding of WKB geometries."""
-    renderer = AnnotationRenderer()
-
     # Create some Shapely geometries of supported types
     point = Point(0, 0)
     line = LineString([(0, 0), (1, 1), (2, 0)])
@@ -289,9 +289,18 @@ def test_decode_wkb() -> None:
     polygon_wkb = polygon.wkb
 
     # Decode the WKB geometries
-    point_contours = renderer.decode_wkb(point_wkb, 1).reshape(-1, 2)
-    line_contours = renderer.decode_wkb(line_wkb, 2).reshape(-1, 2)
-    polygon_contours = renderer.decode_wkb(polygon_wkb, 3).reshape(-1, 2)
+    point_contours = Annotation.decode_wkb(
+        point_wkb,
+        GeometryType.POINT,
+    )
+    line_contours = Annotation.decode_wkb(
+        line_wkb,
+        GeometryType.LINE_STRING,
+    )
+    polygon_contours = Annotation.decode_wkb(
+        polygon_wkb,
+        GeometryType.POLYGON,
+    )
 
     # Check that the decoded contours are as expected
     assert np.all(point_contours == np.array([[0, 0]]))
@@ -314,9 +323,9 @@ def test_decode_wkb() -> None:
     multiline_wkb = multiline.wkb
     multipolygon_wkb = multipolygon.wkb
 
-    multipoint_contours = renderer.decode_wkb(multipoint_wkb, 4).reshape(3, -1, 2)
-    multiline_contours = renderer.decode_wkb(multiline_wkb, 5).reshape(2, -1, 2)
-    multipolygon_contours = renderer.decode_wkb(multipolygon_wkb, 6).reshape(2, -1, 2)
+    multipoint_contours = Annotation.decode_wkb(multipoint_wkb, 4)
+    multiline_contours = Annotation.decode_wkb(multiline_wkb, 5)
+    multipolygon_contours = Annotation.decode_wkb(multipolygon_wkb, 6)
 
     assert np.all(multipoint_contours == np.array([[[0, 0]], [[1, 1]], [[2, 0]]]))
     assert np.all(
@@ -335,4 +344,4 @@ def test_decode_wkb() -> None:
 
     # test unknown geometry type
     with pytest.raises(ValueError, match=r"Unknown geometry type"):
-        renderer.decode_wkb(multipolygon_wkb, 7)
+        Annotation.decode_wkb(multipolygon_wkb, 7)