Most Recent changes to the visualization

docs/architecture.md

@@ -76,7 +76,7 @@ Declared parameters drive the autogenerated form (via TissUUmaps plugin system).
 
 ### Rendering
 
-- **SVG overlay:** uses OpenSeadragon’s SVG overlay (`overlayUtils._d3nodes`) to draw polygons and helper outlines.
+- **Canvas overlay (new):** geometry is fetched once per tile/expansion-parameter signature (via `include_geometry=true`), cached on the client, and redrawn onto a canvas overlay. Subsequent overlay switches reuse cached polygons/outlines and only fetch per-label styles/values (`include_geometry=false`), eliminating the heavy SVG DOM rebuilds.
 - **Tile overview:** HTML canvas minimap (~320 px square) with gradient styling; clicking selects and centers tiles, so an extra on-slide grid is unnecessary.
 - **Viewport utilities:** helper functions convert pixel coordinates to viewport space (accounting for image flip).
 
@@ -95,12 +95,18 @@ Declared parameters drive the autogenerated form (via TissUUmaps plugin system).
 | `P2_CRC_annotated.h5ad` | AnnData with expression + observations | ~4 GB; must fit in RAM. Optional optimizations include using Zarr or downsampling. |
 
 ## Performance Considerations
-
 - **Initial load**: dominated by reading TIFF + `.h5ad`; expect ~20–30 seconds on SSD. Loading is single-threaded (library limitation).
 - **Overlay computation**: per tile, typically < 1 s thanks to caching of expanded labels.
+- **Payload size**: first overlay per tile includes full geometry; subsequent overlays can omit geometry to keep responses small and speed up switching.
 - **Memory footprint**: entire H&E (≈1.2 GB in RAM), sparse labels, AnnData (4 GB), plus caches. Ensure ≥8 GB free RAM during development.
 - **Tile overview**: drawn in canvas to avoid heavy DOM operations; scaled rendering keeps hover/selection lightweight even for thousands of tiles.
 
+## Change Log: Canvas Overlay & Geometry Caching
+
+- **Previous architecture:** every overlay request returned all polygons/outlines and rebuilt an SVG overlay in the browser. Large tiles led to heavy JSON payloads and thousands of `<path>` nodes, slowing interactions and pan/zoom refreshes.
+- **Current architecture:** the backend accepts `include_geometry` (default `true`) and, when enabled, returns a `geometry` block (expanded/raw polygons plus outlines). The frontend caches this geometry per tile/expansion signature and redraws via a canvas overlay. Later overlay switches send `include_geometry=false`, reusing cached shapes and only updating per-label styling/values.
+- **Result:** smaller payloads after the first request, no SVG DOM thrash, and faster overlay redraws on interaction or viewport changes.
+
 ## Extensibility Hooks
 
 - **New overlay types**: add a branch in `_prepare_gene_overlay` / `_prepare_obs_overlay` or create a new handler. Extend the JS rendering branch to draw the new type.

docs/guide.md

@@ -175,3 +175,4 @@ The docs are served at `http://127.0.0.1:8000`. Hit `Ctrl+C` to stop. For a stat
 
 With these steps a new developer can reproduce the environment, understand the code layout, and extend the plugin safely.
 
+