open-plant 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+- `HeatmapLayer`: hotspot/density overlay for `WsiViewer` composition API.
+  - `HeatmapPointData` typed input (`count`, `positions`, optional `weights`).
+  - `scaleMode: "screen" | "fixed-zoom"` with optional `fixedZoom`.
+  - ROI clip support via `clipToRegions`.
+  - Visibility, opacity, gradient, blur/radius, z-index, render stats callback, and `maxRenderedPoints` CPU draw cap.
+
+### Docs
+- Updated README and EN/KO API/architecture docs for `HeatmapLayer`.
+- Example app now demonstrates hotspot toggle + fixed-zoom lock behavior.
+
 ## [1.4.0] - 2026-03-16
 
 ### Added

package/README.md

@@ -153,6 +153,7 @@ draw mode에 진입하면 `setPointerCapture`로 입력을 독점해 팬(드래
 | **포인트 크기 커스터마이즈** | `pointSizeByZoom` 객체로 zoom별 셀(px) 크기 지정 + 내부 선형 보간 |
 | **포인트 내부 채움 제어** | `pointInnerFillOpacity`로 ring 내부 채움 강도 제어 |
 | **포인트 렌더 모드 제어** | `pointData.fillModes`로 ring/solid 렌더링 제어 |
+| **Heatmap overlay** | `HeatmapLayer`로 hotspot density overlay 렌더링. `screen` / `fixed-zoom` 커널 모드, ROI clip, visibility toggle, typed point+weight 입력 |
 | **모바일 타겟 성능** | iPhone 15급 환경에서 수백만 cell 워크로드를 전제로 pan/zoom 응답성을 유지하도록 설계 |
 | **드로잉 / ROI 도구** | Freehand · Rectangle · Circular · Brush + Stamp(사각형/원, mm² 지정) |
 | **고정 픽셀 스탬프** | `stamp-rectangle-4096px` + `stampOptions.rectanglePixelSize` |
@@ -224,6 +225,8 @@ src/
 └── react/
     ├── wsi-viewer.tsx           # WsiTileRenderer + ViewerContext (권장 엔트리)
     ├── viewer-context.ts        # rendererRef, worldToScreen, 오버레이 등록
+    ├── heatmap-layer.tsx        # hotspot / density heatmap layer orchestration
+    ├── heatmap-webgl.ts         # offscreen WebGL2 accumulation + colorize pass
     ├── point-layer.tsx          # 포인트 데이터·클리핑·히트 테스트
     ├── region-layer.tsx         # ROI Canvas2D
     ├── drawing-layer.tsx        # 드로잉 툴 진입 시 오버레이
@@ -269,6 +272,7 @@ src/
 ```tsx
 import {
   DrawingLayer,
+  HeatmapLayer,
   OverviewMap,
   OverlayLayer,
   PatchLayer,
@@ -280,6 +284,16 @@ import {
 
 <WsiViewer source={source} viewState={vs} onViewStateChange={setVs} authToken={token} zoomSnaps={[...]} zoomSnapFitAsMin>
   <PointLayer data={pointData} palette={palette} sizeByZoom={sizes} clipEnabled clipToRegions={rois} clipMode="worker" />
+  <HeatmapLayer
+    data={heatmapData}
+    visible
+    opacity={0.82}
+    radius={4}
+    blur={2}
+    scaleMode="fixed-zoom"
+    fixedZoom={source.maxTierZoom + Math.log2(Math.max(1e-6, vs.zoom))}
+    clipToRegions={rois}
+  />
   <RegionLayer regions={rois} ... />
   <DrawingLayer tool={drawTool} ... />
   <PatchLayer regions={patches} ... />
@@ -294,6 +308,7 @@ import {
 | 컴포넌트 | 역할 |
 |---|---|
 | **PointLayer** | `WsiPointData` + 팔레트, zoom별 크기, ROI 클리핑(`clipMode`: `sync` / `worker` / `hybrid-webgpu`). `ref` → `queryAt(coord)` imperative hit |
+| **HeatmapLayer** | `HeatmapPointData` 기반 hotspot/density 오버레이. `screen` / `fixed-zoom` 커널, optional `weights`, ROI clip, `onStats` |
 | **RegionLayer** | ROI contour/라벨 Canvas2D, hover/active, hit-test |
 | **DrawingLayer** | 드로잉 모드 진입·휠 줌 전달 등; 내부에서 **DrawLayer** 사용 |
 | **DrawLayer** | 실제 freehand/rect/circle/brush/stamp 구현 |
@@ -302,7 +317,26 @@ import {
 
 ### `useViewerContext()`
 
-`rendererRef`, `rendererSerial`, `source`, `worldToScreen`, `registerDrawOverlay`, `overviewInvalidateRef`, interaction lock 등 — 커스텀 오버레이·미니맵에서 사용합니다.
+`rendererRef`, `rendererSerial`, `source`, `worldToScreen`, `registerDrawCallback`, `overviewInvalidateRef`, interaction lock 등 — 커스텀 오버레이·미니맵에서 사용합니다.
+
+### `<HeatmapLayer>`
+
+현재 구현은 offscreen WebGL2 누적/컬러라이즈 후 공유 오버레이 캔버스에 합성하는 레이어입니다. `screen` 모드는 현재 화면 기준으로 level/정규화/커널을 선택하고, `fixed-zoom` 모드는 **continuous zoom** 기준(`source.maxTierZoom + log2(viewState.zoom)`)으로 잠근 시점의 heatmap state를 유지합니다. WebGL2 초기화에 실패하면 레이어는 warning을 남기고 렌더를 건너뜁니다.
+
+| Prop | Type | Notes |
+|---|---|---|
+| `data` | `HeatmapPointData \| null` | `count`, `positions`, optional `weights` |
+| `visible` | `boolean` | 독립 토글 |
+| `opacity` | `number` | `0..1` |
+| `radius` / `blur` | `number` | 커널 크기 (CSS px) |
+| `gradient` | `readonly string[]` | 색상 stop 배열 |
+| `backgroundColor` | `string \| null` | 기본 `null` |
+| `scaleMode` | `"screen" \| "fixed-zoom"` | 최소 지원 모드 |
+| `fixedZoom` | `number` | `scaleMode="fixed-zoom"`일 때의 continuous zoom 기준값 |
+| `clipToRegions` | `WsiRegion[]` | ROI 내부로 mask + point filter |
+| `maxRenderedPoints` | `number` | visible bin budget. 기본 `24000` |
+| `zIndex` | `number` | 오버레이 draw priority |
+| `onStats` | `(stats) => void` | point count / render time 등 |
 
 ### `<DrawLayer>` (단독 사용)
 
@@ -343,7 +377,7 @@ import {
 
 | Export | 설명 |
 |---|---|
-| `WsiViewer`, `PointLayer`, `RegionLayer`, `DrawingLayer`, `DrawLayer`, `PatchLayer`, `OverlayLayer`, `OverviewMap`, `TileViewerCanvas` | React |
+| `WsiViewer`, `PointLayer`, `HeatmapLayer`, `RegionLayer`, `DrawingLayer`, `DrawLayer`, `PatchLayer`, `OverlayLayer`, `OverviewMap`, `TileViewerCanvas` | React |
 | `useViewerContext` | 컨텍스트 (`rendererRef`, `worldToScreen`, …) |
 | `WsiTileRenderer`, `M1TileRenderer`, `TileScheduler` | 코어 렌더러·타일 큐 |
 | `normalizeImageInfo`, `toTileUrl`, `toRoiGeometry`, `parseWkt` | 이미지/ROI/WKT |