Engine

단일 캔버스 렌더 루프 + 오버레이 드로잉

타일/포인트는 WebGL2에서 합성하고, ROI 인터랙션은 독립 Overlay Canvas에서 처리합니다. 성능과 UX를 분리해 안정적으로 유지하는 구조입니다.

런타임 구성

React
 └─ WsiViewerCanvas
    ├─ WebGL Canvas (WsiTileRenderer: pan/zoom/rotate)
    │  ├─ Tile pass (bitmap quads)
    │  └─ Point pass (palette indexed ring points)
    └─ DrawLayer Canvas (pointer capture, ROI preview/labels)

타일 파이프라인

tier 선택: `rawTier = maxTierZoom + log2(zoom)`.

visible tile 계산: viewport와 tile grid 교차 범위를 계산.

캐시 우선 렌더: 기존 캐시 타일(특히 이전 tier) 먼저 draw.

타일 전용 색상 보정: brightness/contrast/saturation uniform은 tile fragment shader에만 적용됩니다.

신규 타일 비동기 요청: 요청 완료 시 texture 업로드 후 다음 frame에서 반영.

LRU trim: `maxCacheTiles` 초과 시 오래된 texture 정리.

fallback 타일을 먼저 렌더하기 때문에 줌 변경 직후 검은 화면이 아닌 점진적 채움이 유지됩니다.

안정성/복구 (WS-7)

컨텍스트 손실 대응: webglcontextlost에서 프레임 루프/드래그/타일 스케줄러를 즉시 정지합니다.

복구 재초기화: webglcontextrestored 시 셰이더/버퍼/텍스처를 재생성합니다.

포인트 자동 복원: 마지막 point buffer/palette를 CPU 스냅샷에서 자동 재업로드합니다.

네트워크 degrade: retry/backoff + fallback tier 렌더로 타일 실패 중에도 화면 연속성을 유지합니다.

호스트 콜백: onContextLost, onContextRestored, onTileError로 장애 신호를 외부 앱에 전달합니다.

포인트 파이프라인

외부 파싱: 포인트 로딩/디코딩(zstd+MVT 등)은 호출자 책임.

입력 계약: Float32Array positions + Uint16Array paletteIndices를 기본으로 받고, 선택적으로 fillModes/drawIndices를 수신합니다.

업로드: positions/paletteIndices를 GPU 버퍼로 전송.

셰이더 렌더: fillModes 기반 ring/solid 모드로 palette 색상을 렌더합니다.

ROI clip: 필요 시 clipMode에 따라 polygon 내부 포인트만 필터링.

ROI 통계: computeRoiPointGroups / onRoiPointGroups로 ROI별 term 집계.

ROI 가속 모드

`sync`

메인 스레드에서 즉시 polygon 필터링. 디버깅/기준 측정용.

`worker`

전용 worker 스레드에서 ROI 필터링. UI 프리즈를 줄이는 현재 권장 기본값.

`hybrid-webgpu`

실험 경로. WebGPU bbox prefilter + polygon 정밀 판정 후 drawIndices 브리지로 인덱스 기반 포인트 렌더를 수행합니다.

관측

onStats/onClipStats와 내장 debugOverlay로 런타임 지표를 수집하고 회귀를 빠르게 추적합니다.

드로잉 파이프라인

카메라 입력: pan + wheel zoom + Ctrl/Cmd + drag 회전(rotationDeg).

Pointer capture: draw 활성 시 입력을 DrawLayer가 독점.

미리보기: freehand/rectangle/circular preview 또는 brush cursor+stroke.

완료: tool별 좌표를 닫힌 ring으로 변환 후 `onDrawComplete` emit(intent: "roi" | "patch" | "brush").

Region 상호작용: cursor 모드 hit-test 대상은 contour + 라벨 영역이며 내부 fill은 제외됩니다.

영속 표시: `persistedRegions`로 outline와 label을 계속 렌더.

WebGPU 확장 방향 (연산 전용)

ROI Culling

bbox prefilter compute를 시작점으로 polygon 정밀 판정을 결합합니다.

LOD Aggregation

저배율에서 cell density 집계를 compute pass로 사전 생성.

Term Histogram

ROI 단위 term count/positivity 통계를 GPU에서 병렬 계산.

Interop

연산 결과를 WebGL 업로드 가능한 packed buffer로 반환.

현재 WebGPU 경로는 실험적입니다. 실데이터 벤치마크가 확인되기 전까지는 운영 기본값을 worker로 유지하는 것을 권장합니다.

오픈소스 문서 원칙

동작 우선: 각 모드의 기본값/폴백/실패 동작을 명시합니다.

버전 동기화: 문서와 src/index.ts export 변경을 같은 PR에서 처리합니다.

측정 근거: 성능 주장은 onStats/onClipStats 수치로 재현 가능해야 합니다.

이중언어 동등성: EN/KO 문서는 기능 단위로 동일 정보를 유지합니다.