Reference

공개 API 레퍼런스

아래 표는 `src/index.ts`에서 export된 항목 기준입니다. 타입/시그니처가 변경되면 이 문서도 함께 업데이트하세요.

`WsiViewerCanvas` Props

이름	타입	설명
`source`	`WsiImageSource \| null`	렌더 대상 이미지 메타데이터.
`authToken`	`string`	필요한 요청에 Authorization 헤더 토큰을 주입합니다.
`viewState`	`Partial<WsiViewState>`	외부 제어 줌/오프셋/회전(`rotationDeg`) 상태.
`onViewStateChange`	`(next) => void`	카메라 상태 변경 콜백.
`imageColorSettings`	`WsiImageColorSettings \| null`	타일 전용 밝기/대비/채도 입력(`[-100, 100]`). point/ROI/draw overlay에는 적용되지 않습니다.
`onStats`	`(stats: WsiRenderStats) => void`	프레임 관측 이벤트. 타일/포인트 통계와 queue/failure/cache hit/miss, frame 시간 포함.
`onTileError`	`(event) => void`	타일 로드 실패 콜백(타일 정보, 오류 객체, 재시도 횟수).
`onContextLost`	`() => void`	WebGL 컨텍스트 손실 시 호출되며 렌더 루프가 일시 정지됩니다.
`onContextRestored`	`() => void`	컨텍스트 복구 후 GPU 상태 재구성 완료 시 호출됩니다.
`debugOverlay`	`boolean`	내장 런타임 디버그 HUD 표시. 기본값 `false`.
`debugOverlayStyle`	`CSSProperties`	내장 디버그 HUD 스타일 오버라이드.
`fitNonce`	`number`	값이 바뀌면 fit-to-image 재실행.
`rotationResetNonce`	`number`	값이 바뀌면 회전을 0도로 리셋.
`ctrlDragRotate`	`boolean`	`Ctrl/Cmd + drag` 회전 허용. 기본값 `true`.
`minZoom`	`number`	최소 줌 override. 미지정 시 `fitZoom * 0.5`. wheel/double-click/`setViewState`/`fitToImage` 경로 모두 적용.
`maxZoom`	`number`	최대 줌 override. 미지정 시 `fitZoom * 8`.
`viewTransition`	`{ duration?: number; easing?: (t) => number }`	기본 카메라 전환 애니메이션. duration은 `0..2000ms`로 clamp됩니다.
`zoomSnaps`	`number[]`	배율 스냅 단계 목록(예: `[1.25, 2.5, 5, 10, 20, 40]`). 내부적으로 `source.mpp` 기준 zoom 값으로 정규화됩니다.
`zoomSnapFitAsMin`	`boolean`	true면 snap-out 시 fit zoom을 하한으로 취급합니다.
`pointData`	`WsiPointData \| null`	포인트 위치 + 팔레트 인덱스 버퍼(`ids`로 hit-test 지원).
`pointPalette`	`Uint8Array \| null`	RGBA palette texture 데이터.
`pointSizeByZoom`	`Record<number, number>`	continuous zoom 기준 point 크기(px) stop. stop 사이는 선형 보간.
`pointStrokeScale`	`number`	point ring 두께 스케일.
`pointInnerFillOpacity`	`number`	point 내부 채움 불투명도 (`0..1`).
`roiRegions`	`WsiRegion[]`	영속 ROI 목록(라벨 포함).
`roiPolygons`	`DrawCoordinate[][]`	간소화 ROI 입력.
`clipPointsToRois`	`boolean`	ROI 외부 포인트 제거.
`clipMode`	`"sync" \| "worker" \| "hybrid-webgpu"`	ROI clip 실행 모드. 기본값 `"worker"`.
`onClipStats`	`(event) => void`	clip 실행 통계 콜백(mode, duration, input/output, WebGPU 사용 여부, draw 브리지 여부 `bridgedToDraw`).
`onRoiPointGroups`	`(stats) => void`	현재 포인트/ROI 기준 ROI별 term count 콜백.
`roiPaletteIndexToTermId`	`ReadonlyMap<number,string> \| string[]`	ROI term count 집계용 paletteIndex→termId 매핑.
`interactionLock`	`boolean`	캔버스 pan/zoom 잠금.
`drawTool`	`"cursor" \| "freehand" \| "rectangle" \| "circular" \| "brush" \| StampDrawTool`	활성 draw 툴. `stamp-rectangle-4096px`는 patch intent, brush는 `intent: "brush"`를 emit합니다.
`stampOptions`	`{ rectangleAreaMm2?: number; circleAreaMm2?: number; rectanglePixelSize?: number }`	외부에서 stamp 크기 제어. 기본값은 면적 stamp 2mm², 고정 사각형 4096px.
`brushOptions`	`BrushOptions`	brush 반경/디테일/스무딩/커서 옵션. 반경은 HTML/CSS px 기준으로 화면에서 줌 불변입니다.
`drawFillColor`	`string`	freehand/rectangle/circular draw preview fill 색상. 기본값 `transparent`.
`patchRegions`	`WsiRegion[]`	ROI 상호작용과 분리된 patch 전용 영속 polygon 목록.
`patchStrokeStyle`	`Partial<RegionStrokeStyle>`	patch 전용 stroke override(기본: cyan 점선).
`regionStrokeStyle`	`Partial<RegionStrokeStyle>`	ROI stroke 스타일 override.
`regionStrokeHoverStyle`	`Partial<RegionStrokeStyle>`	ROI hover 시 stroke 스타일 override.
`regionStrokeActiveStyle`	`Partial<RegionStrokeStyle>`	ROI active 시 stroke 스타일 override (shadow 포함).
`resolveRegionStrokeStyle`	`(context) => Partial<RegionStrokeStyle>`	region/state별 동적 stroke 스타일 resolver.
`resolveRegionLabelStyle`	`(context) => Partial<RegionLabelStyle>`	region/zoom별 동적 라벨 스타일 resolver(`offsetY` 등).
`overlayShapes`	`DrawOverlayShape[]`	DrawLayer 커스텀 오버레이 도형(폴리곤 stroke + 반전 마스크 지원).
`customLayers`	`WsiCustomLayer[]`	world/screen 변환기를 받는 커스텀 React 오버레이 레이어 슬롯.
`regionLabelStyle`	`Partial<RegionLabelStyle>`	영속 region 라벨 스타일 override.
`regionLabelAnchor`	`"top-center" \| "centroid"`	라벨 배치/히트 영역에 쓰이는 anchor 모드.
`drawAreaTooltip`	`DrawAreaTooltipOptions`	freehand/rectangle/circular draw 중 실시간 mm² tooltip.
`autoLiftRegionLabelAtMaxZoom`	`boolean`	`maxZoom` 도달 시 라벨을 20px 위로 애니메이션 이동하고, 이탈 시 복귀.
`clampRegionLabelToViewport`	`boolean`	region 라벨을 뷰포트 경계 안으로 clamp합니다.
`onPointerWorldMove`	`(event) => void`	월드 좌표 포인터 스트림 콜백.
`onPointHover`	`(event) => void`	cursor 모드에서 nearest point hover 이벤트. 미히트 시 `index/id`는 `null`.
`onPointClick`	`(event) => void`	cursor 모드에서 nearest point 클릭 이벤트(버튼 정보 포함).
`getCellByCoordinatesRef`	`MutableRefObject<(coord) => PointHitEvent \| null>`	월드 좌표 기반 point hit-test 함수를 imperative ref로 노출.
`onRegionHover`	`(event) => void`	cursor 모드 region hover 이벤트.
`onRegionClick`	`(event) => void`	cursor 모드 region 클릭 이벤트.
`activeRegionId`	`string \| number \| null`	controlled active region id. 생략하면 uncontrolled 모드로 동작.
`onActiveRegionChange`	`(regionId) => void`	active region 변경 이벤트. 기본 동작은 같은 region 재클릭 시 토글 해제, 빈 공간 클릭 시 해제입니다.
`onDrawComplete`	`(result) => void`	도형 완료 콜백. payload에 `intent: "roi" \| "patch" \| "brush"` 포함.
`onPatchComplete`	`(result) => void`	`stamp-rectangle-4096px` 완료 시 patch 전용 콜백.
`overviewMapConfig`	`OverviewMapConfig`	Overview map 표시/옵션/스타일.
`className`	`string`	루트 컨테이너 className.
`style`	`CSSProperties`	루트 컨테이너 style.

cursor 모드의 region hit-test는 contour + 라벨 영역만 대상으로 하며, 내부 fill 영역은 의도적으로 제외됩니다.

타일 색상 보정 정규화: brightness / 200, contrast / 100, saturation / 100. 타일 셰이더에만 적용됩니다.

`DrawLayer` / 도형 유틸

Export	설명
`DrawLayer`	독립 오버레이 캔버스 컴포넌트.
`closeRing(coords)`	첫점/끝점을 닫아 polygon ring 생성.
`createRectangle(start, end)`	사각형 폐곡선 좌표 생성.
`createCircle(start, end)`	원형 다각형 좌표 생성.
`DrawResult`	`{ tool, intent, coordinates, bbox, areaPx }` (`intent`는 `"roi"`, `"patch"`, `"brush"`)
`PatchDrawResult`	`stamp-rectangle-4096px` 전용 patch 결과 타입.
`DrawRegion`	`{ id?, coordinates, label? }`
`DrawIntent`	draw 완료 intent 유니온(`"roi" \| "patch" \| "brush"`).
`DrawOverlayShape`	`{ id?, coordinates, closed?, fill?, stroke?, strokeStyle?, invertedFill?, visible? }` 형태의 오버레이 입력. `coordinates`는 `DrawCoordinate[]`, `DrawCoordinate[][]`, `DrawCoordinate[][][]`(single ring/multi-ring/multi-polygon)을 받습니다.
`DrawOverlayInvertedFillStyle`	`{ fillColor: string }` 폴리곤 바깥 영역을 채우는 반전 마스크 색상 스타일.
`BrushOptions`	brush 반경/디테일/스무딩/커서 옵션. `radius`는 HTML/CSS px 기준(화면 고정)이며 결과 좌표는 줌에 맞게 world로 변환됩니다.
`RegionStyleContext`	`resolveRegionStrokeStyle`에 전달되는 상태 payload(`default`/`hover`/`active`).
`RegionLabelStyleContext`	라벨 resolver context(`region`, `regionId`, `regionIndex`, `zoom`).
`RegionLabelStyleResolver`	`resolveRegionLabelStyle`에서 사용하는 동적 라벨 스타일 resolver.
`StampOptions`	면적(mm²) + 고정 픽셀 사각형 옵션.
`RegionStrokeStyle`	색상/두께/점선/캡/조인 + shadow(색상/블러/오프셋) 제어.
`RegionLabelStyle`	폰트/배경/패딩/오프셋/라운드 제어.
`DrawAreaTooltipOptions`	실시간 면적 tooltip 옵션(`enabled`, `format`, `style`, `cursorOffset`).
`DrawAreaTooltipStyle`	draw 중 tooltip 글꼴/배경/패딩 스타일.

`TileViewerCanvas` Props

이름	타입	설명
`imageWidth`	`number`	원본 너비(px).
`imageHeight`	`number`	원본 높이(px).
`tiles`	`TileDefinition[]`	M1 타일 정의 리스트.
`viewState`	`Partial<ViewState>`	초기/외부 시점 제어.

핵심 타입

interface WsiImageSource {
  id: string;
  name: string;
  width: number;
  height: number;
  mpp?: number;
  tileSize: number;
  maxTierZoom: number;
  tilePath: string;
  tileBaseUrl: string;
  terms: WsiTerm[];
  tileUrlBuilder?: (tier: number, x: number, y: number) => string;
}

interface WsiPointData {
  count: number;
  positions: Float32Array; // [x0,y0,x1,y1,...]
  paletteIndices: Uint16Array;
  fillModes?: Uint8Array; // point 채움 모드(0: ring, 1: solid)
  ids?: Uint32Array; // hit-test/cell 액션용 선택 ID
  drawIndices?: Uint32Array; // 선택 인덱스 브리지(선택적)
}

interface WsiViewState {
  zoom: number;
  offsetX: number;
  offsetY: number;
  rotationDeg: number;
}

interface WsiRenderStats {
  tier: number;
  visible: number;
  rendered: number;
  fallback: number;
  points: number;
  cache: number;
  inflight: number;
  queued?: number;
  retries?: number;
  failed?: number;
  aborted?: number;
  cacheHits?: number;
  cacheMisses?: number;
  drawCalls?: number;
  frameMs?: number;
}

API 안정성 정책 (WS-10)

SemVer: patch = 버그 수정, minor = 하위호환 기능 추가, major = 브레이킹 변경.

Deprecation 수명주기: 대체 API를 먼저 제공하고 문서에서 deprecated 표시 후 최소 두 번의 minor 릴리스 동안 호환을 유지하며, 제거는 다음 major에서만 수행합니다.

Migration 계약: 브레이킹 변경에는 before/after 예시와 체크리스트를 반드시 동반합니다.

Known limitations: 실제 브라우저 상호작용(pan/zoom/draw) E2E 자동화는 아직 CI에서 완전 커버되지 않습니다.

실제 업그레이드 절차와 before/after 예시는 마이그레이션 가이드를 확인하세요.

유틸 함수

함수	설명
`normalizeImageInfo(raw, tileBaseUrl)`	백엔드 응답 + 타일 베이스 URL을 `WsiImageSource`로 변환.
`toTileUrl(source, tier, x, y)`	IMS 타일 URL 생성.
`buildTermPalette(terms)`	termId → palette index 매핑 + RGBA 팔레트 생성.
`filterPointDataByPolygons(data, polygons)`	ROI 다각형 기반 포인트 필터링.
`filterPointDataByPolygonsInWorker(data, polygons)`	ROI 필터를 워커 스레드에서 실행합니다.
`terminateRoiClipWorker()`	공유 ROI clip worker 인스턴스를 종료합니다(teardown/테스트에서 유용).
`filterPointIndicesByPolygons(data, polygons)`	polygon 내부 원본 point 인덱스를 반환해 patch JSON export 파이프라인을 구성합니다.
`filterPointIndicesByPolygonsInWorker(data, polygons)`	point 인덱스 반환의 워커 버전(+duration 메타).
`filterPointDataByPolygonsHybrid(data, polygons, options?)`	실험적 하이브리드 경로(WebGPU bbox prefilter + polygon 정밀 판정). `{ bridgeToDraw: true }`를 주면 전체 버퍼 + `drawIndices` 브리지를 반환합니다.
`computeRoiPointGroups(pointData, regions, options)`	TypedArray 포인트 버퍼로 ROI별 term count(`roiPointGroups`)를 계산합니다.
`getWebGpuCapabilities()`	런타임에서 WebGPU 지원/어댑터/기능 정보를 조회합니다.
`prefilterPointsByBoundsWebGpu(positions, count, bounds)`	ROI bounding box 기준 점 분류를 WebGPU compute로 수행합니다(실험적).
`calcScaleResolution(imageMpp, imageZoom, currentZoom)`	현재 줌 기준 μm/스크린픽셀 해상도 계산.
`calcScaleLength(imageMpp, imageZoom, currentZoom)`	100px 스케일바 길이를 μm/mm 문자열로 포맷.
`toBearerToken(token)`	`Bearer ...` 정규화.

mpp란? mpp는 네이티브 피라미드 레벨(maxTierZoom)에서의 microns per pixel(픽셀당 마이크론)입니다. 스탬프 물리 크기(mm²)는 이 값으로 환산됩니다. mpp가 없으면 1μm/px 가정으로 계산되어 물리 크기는 근사치가 됩니다.