[React] VTK 좌표계에서 3개 뷰 동시에 BBox 그리기

3편 / 3편 — 完

VTK 좌표계에서
3개 뷰 동시에 BBox 그리기

Axial 슬라이스의 2D 픽셀 좌표를 어떻게 3D 공간으로 끌어올리고, 다시 Sagittal·Coronal 뷰의 Canvas 픽셀로 떨어트리는지 — VTK 좌표 변환 체인의 전 과정을 코드와 함께 설명합니다.

IJK → World → Display 3D BBox 재구성 뷰별 투영 전략 좌표계 명명 역전 onModified 동기화 DPR 보정

🗂 시리즈: SEG NIfTI에서 BBox JSON으로

1

SEG NIfTI의 문제와 BBox JSON 전환 배경

2

BBox JSON API 설계와 Canvas 오버레이 구현

3

VTK 좌표계에서 3개 뷰 동시에 BBox 그리기 ← 현재

01 · The Challenge

무엇이 어려운가

2편에서 구현한 drawBBoxOverlay는 AxialGridViewer에서만 동작합니다. Canvas 픽셀 좌표와 복셀 인덱스가 1:1로 매핑되기 때문에 변환 없이 바로 쓸 수 있었습니다.

MPR 뷰(Axial/Sagittal/Coronal)는 다릅니다. VTK는 내부적으로 3D 공간을 WebGL로 렌더링한 뒤, 그 결과를 Canvas 픽셀로 복사합니다. 사용자가 줌·팬을 하면 같은 복셀이 다른 Canvas 위치에 그려집니다. 따라서 annotation 좌표를 그 순간의 카메라 상태에 맞게 변환해야 합니다.

여기에 또 하나의 난관이 있습니다. BE가 내려준 annotation은 Axial 슬라이스 기준의 2D 좌표입니다. 이 좌표를 Sagittal, Coronal 뷰에서도 그리려면 2D → 3D → 2D 두 번의 변환이 필요합니다.

📍

Axial 뷰

annotation 원본 좌표(픽셀) → IJK 변환 → World → Display. 현재 슬라이스와 일치하는 annotation만 그립니다.

📐

Sagittal 뷰

annotation에서 3D BBox를 재구성 → 현재 I가 BBox I 범위에 속하면 J×K 투영 사각형을 그립니다.

📏

Coronal 뷰

annotation에서 3D BBox를 재구성 → 현재 J가 BBox J 범위에 속하면 I×K 투영 사각형을 그립니다.

02 · Naming Trap

먼저 반드시 짚고 가야 할 것 — 명명 역전

이 프로젝트에서 가장 많은 버그를 만든 원인은 코드의 복잡함이 아니라 렌더러 내부 명칭과 UI 라벨의 불일치입니다. 처음 접하면 반드시 혼란스럽습니다.

🚨 코드에서 renderers.coronal은 사용자에게 Axial(축방향)로 보이는 뷰입니다. renderers.axial은 Coronal(관상면)으로 보입니다. 이 역전을 모르고 코드를 작성하면 올바른 뷰에 올바른 박스가 그려지지 않습니다. BBoxOverlay 전체에서 이 매핑을 일관되게 지켜야 합니다.

03 · Coordinate Chain

좌표 변환 체인 — IJK → World → Display → Canvas

BBoxOverlay에서 annotation 좌표가 Canvas 픽셀로 변환되기까지 4단계를 거칩니다.

① 픽셀 좌표 → IJK

BE가 내려준 graphic_data의 [px, py]는 Axial 슬라이스의 픽셀 좌표입니다. Axial(coronal 렌더러)에서는 K축이 고정되므로 px=i, py=j, k=sliceK로 직접 매핑됩니다.

// ① 픽셀 좌표 → IJK
// Axial(coronal 렌더러): I×J 평면, K 고정
const pixelToIJK = (
  px: number, py: number, sliceK: number
): [number, number, number] => {
  return [px, py, sliceK];  // [i, j, k]
};

② IJK → World (mm)

VTK ImageData의 spacing(복셀 간격)과 origin(원점)을 이용해 물리적 mm 좌표로 변환합니다.

// ② IJK → World (mm 단위)
// World = origin + IJK * spacing
const ijkToWorld = (
  ijk: [number, number, number],
  imageData: VtkImageData,
): [number, number, number] => {
  const [si, sj, sk] = imageData.getSpacing();
  const [oi, oj, ok] = imageData.getOrigin();
  return [
    oi + ijk[0] * si,
    oj + ijk[1] * sj,
    ok + ijk[2] * sk,
  ];
};

③ World → Display (VTK 픽셀)

VTK의 vtkCoordinate를 이용해 World 좌표를 현재 뷰포트의 Display 픽셀로 변환합니다. 이 변환은 카메라의 줌·팬 상태를 자동으로 반영합니다.

// ③ World → Display (VTK 내부 픽셀 좌표)
// vtkCoordinate가 카메라 행렬을 자동 반영
const worldToDisplay = (
  world: [number, number, number],
  renderer: VtkRendererInstance,
  renderWindow: VtkRenderWindow,
): [number, number] => {
  const coord = vtkCoordinate.newInstance();
  coord.setCoordinateSystemToWorld();
  coord.setValue(...world);

  const [dx, dy] = coord.getComputedDisplayValue(renderer);
  coord.delete();  // VTK 메모리 명시 해제

  // VTK Display Y축은 하단 기준 → 상단 기준으로 반전
  const [, winH] = renderWindow.getSize();
  return [dx, winH - dy];
};

④ Display → Canvas (DPR 보정)

고해상도(Retina) 화면에서는 브라우저의 devicePixelRatio(DPR)가 1 이상입니다. VTK Display 좌표는 물리 픽셀 기준이므로 CSS 픽셀로 나누어 Canvas에 그려야 합니다.

// ④ Display → Canvas CSS 픽셀 (DPR 보정)
const dpr = window.devicePixelRatio || 1;
const canvasX = displayX / dpr;
const canvasY = displayY / dpr;

// Canvas는 CSS 픽셀 기준으로 strokeRect / moveTo 호출
ctx.strokeRect(canvasX, canvasY, width / dpr, height / dpr);

⚠️ DPR 보정을 빠뜨리면 Retina 디스플레이에서 bbox가 절반 크기로 그려지거나 위치가 어긋납니다. devicePixelRatio는 창 이동이나 외부 모니터 연결 시 변경되므로, drawOverlay() 호출 시점에 매번 새로 읽어야 합니다.

04 · 3D BBox Reconstruction

Sagittal·Coronal 뷰를 위한 3D BBox 재구성

Axial 뷰는 annotation 원본 좌표를 그대로 사용하면 됩니다. 하지만 Sagittal·Coronal에서는 병변이 몇 번 슬라이스부터 몇 번 슬라이스까지 걸쳐 있는지와, 가로세로 얼마나 큰지를 알아야 합니다. 이 정보를 모든 슬라이스의 annotation에서 누적해 3D 바운딩 박스(aneurysm_id별 min/max IJK)를 계산합니다.

components/BBoxOverlay.tsx — buildAneurysmBBoxes()

interface AneurysmBBox {
  iMin: number; iMax: number;  // I축 (가로) 범위
  jMin: number; jMax: number;  // J축 (세로) 범위
  kMin: number; kMax: number;  // K축 (슬라이스) 범위
  color: string;
}

/**
 * 전체 annotation에서 aneurysm_id별 3D BBox를 계산한다.
 * 모든 슬라이스의 graphic_data를 누적해 min/max를 구한다.
 */
function buildAneurysmBBoxes(
  annotations: BBoxAnnotationItem[]
): Map<number, AneurysmBBox> {

  const bboxMap = new Map<number, AneurysmBBox>();

  for (const ann of annotations) {
    const { aneurysm_id, instance_number: k, graphic_data, color } = ann;

    const xs = graphic_data.map(p => p[0]);  // I 좌표
    const ys = graphic_data.map(p => p[1]);  // J 좌표

    const prev = bboxMap.get(aneurysm_id);

    bboxMap.set(aneurysm_id, {
      iMin:  prev ? Math.min(prev.iMin, ...xs) : Math.min(...xs),
      iMax:  prev ? Math.max(prev.iMax, ...xs) : Math.max(...xs),
      jMin:  prev ? Math.min(prev.jMin, ...ys) : Math.min(...ys),
      jMax:  prev ? Math.max(prev.jMax, ...ys) : Math.max(...ys),
      kMin:  prev ? Math.min(prev.kMin, k)    : k,
      kMax:  prev ? Math.max(prev.kMax, k)    : k,
      color,
    });
  }

  return bboxMap;  // aneurysm_id → 3D BBox
}

05 · Per-View Strategy

뷰별 렌더링 전략 — drawOverlay 구현

세 뷰 각각의 렌더링 로직을 살펴봅니다. 핵심은 어떤 IJK 점을 World로 변환하고, 어떤 두 점이 사각형의 두 꼭짓점이 되는가입니다.

components/BBoxOverlay.tsx — drawOverlay() 핵심 로직

function drawOverlay() {
  if (!annotations || !imageData || !sliceIndices) return;

  // 3D BBox 사전 계산 (annotation 전체 순회, 1회)
  const bboxMap = buildAneurysmBBoxes(annotations);

  // ── Axial 뷰 (coronal 렌더러) ────────────────────────────────
  // 현재 K 슬라이스에 해당하는 annotation 원본 좌표 사용
  drawForRenderer('coronal', (ctx, renderer, rw) => {
    const k = sliceIndices.k;
    const sliceAnns = annotations.filter(a => a.instance_number === k);

    for (const ann of sliceAnns) {
      const xs = ann.graphic_data.map(p => p[0]);
      const ys = ann.graphic_data.map(p => p[1]);
      // 두 꼭짓점: (iMin, jMin, k) and (iMax, jMax, k)
      const [x1, y1] = iJKToCanvas([Math.min(...xs), Math.min(...ys), k], renderer, rw);
      const [x2, y2] = iJKToCanvas([Math.max(...xs), Math.max(...ys), k], renderer, rw);
      ctx.strokeStyle = ann.color;
      ctx.strokeRect(x1, y1, x2 - x1, y2 - y1);
    }
  });

  // ── Sagittal 뷰 (sagittal 렌더러) ────────────────────────────
  // 현재 sliceI가 3D BBox의 I 범위에 포함되면 J×K 사각형
  drawForRenderer('sagittal', (ctx, renderer, rw) => {
    const i = sliceIndices.i;

    bboxMap.forEach((bbox) => {
      if (i < bbox.iMin || i > bbox.iMax) return;  // 범위 밖

      // Sagittal(I축 고정): 가로=K, 세로=J
      // 좌상단 (i, jMin, kMin) → 우하단 (i, jMax, kMax)
      const [x1, y1] = iJKToCanvas([i, bbox.jMin, bbox.kMin], renderer, rw);
      const [x2, y2] = iJKToCanvas([i, bbox.jMax, bbox.kMax], renderer, rw);
      ctx.strokeStyle = bbox.color;
      ctx.strokeRect(
        Math.min(x1, x2), Math.min(y1, y2),
        Math.abs(x2 - x1), Math.abs(y2 - y1),
      );
    });
  });

  // ── Coronal 뷰 (axial 렌더러) ────────────────────────────────
  // 현재 sliceJ가 3D BBox의 J 범위에 포함되면 I×K 사각형
  drawForRenderer('axial', (ctx, renderer, rw) => {
    const j = sliceIndices.j;

    bboxMap.forEach((bbox) => {
      if (j < bbox.jMin || j > bbox.jMax) return;  // 범위 밖

      // Coronal(J축 고정): 가로=I, 세로=K
      // 좌상단 (iMin, j, kMin) → 우하단 (iMax, j, kMax)
      const [x1, y1] = iJKToCanvas([bbox.iMin, j, bbox.kMin], renderer, rw);
      const [x2, y2] = iJKToCanvas([bbox.iMax, j, bbox.kMax], renderer, rw);
      ctx.strokeStyle = bbox.color;
      ctx.strokeRect(
        Math.min(x1, x2), Math.min(y1, y2),
        Math.abs(x2 - x1), Math.abs(y2 - y1),
      );
    });
  });
}

🔑 iJKToCanvas는 ②③④를 한 번에 수행하는 헬퍼입니다 — IJK → World(ijkToWorld) → Display(worldToDisplay) → Canvas(÷DPR). 이 함수가 카메라 상태를 자동 반영하므로 줌·팬 후에도 박스가 정확히 그려집니다.

뷰별 투영 좌표 요약

뷰 (렌더러명)	고정 축	BBox 두 꼭짓점 IJK	표현 평면
Axial (coronal)	K = sliceK	(iMin, jMin, k) ~ (iMax, jMax, k)	I(가로) × J(세로)
Sagittal (sagittal)	I = sliceI	(i, jMin, kMin) ~ (i, jMax, kMax)	K(가로) × J(세로)
Coronal (axial)	J = sliceJ	(iMin, j, kMin) ~ (iMax, j, kMax)	I(가로) × K(세로)

06 · Camera Sync

줌·팬·리사이즈 동기화 — onModified 구독

bbox가 처음 그려진 뒤 사용자가 줌·팬하면 VTK WebGL 렌더링은 업데이트되지만 Canvas 오버레이는 그대로입니다. renderWindow.onModified()를 구독해 VTK 뷰가 바뀔 때마다 Canvas를 재그립니다.

1

컴포넌트 마운트 시 — Canvas 생성 & 구독 시작

containerRef 안에 position: absolute의 투명 Canvas를 생성합니다. VTK Canvas와 완전히 겹치도록 크기를 맞춥니다. renderWindow.onModified()로 VTK 렌더 이벤트를 구독합니다.

2

사용자 줌·팬 → VTK onModified 발생

카메라 변환 행렬이 바뀔 때마다 drawOverlay()가 호출됩니다. 이 함수 내에서 worldToDisplay가 현재 카메라 기준으로 Display 좌표를 다시 계산하므로 bbox가 올바른 위치에 그려집니다.

3

sliceIndices 변경 시 — useEffect로 재그리기

슬라이스를 스크롤할 때는 VTK onModified가 발생하지 않을 수 있습니다. useEffect([sliceIndices])에서 drawOverlay()를 추가로 호출해 슬라이스 이동도 반영합니다.

4

컴포넌트 언마운트 시 — 구독 해제 & Canvas 제거

sub.unsubscribe()로 VTK 이벤트 구독을 해제하고, Canvas DOM을 제거합니다. 메모리 누수 방지.

// BBoxOverlay.tsx — 전체 Effect 구조
useEffect(() => {
  const rw = fullScreenRendererRef.current?.getRenderWindow();
  if (!rw || !annotations || annotations.length === 0) return;

  // 1. Canvas 생성 및 배치
  const canvas = document.createElement('canvas');
  canvas.style.cssText = 'position:absolute;top:0;left:0;pointer-events:none;';
  containerRef.current?.appendChild(canvas);

  // 2. Canvas 크기 — VTK renderWindow 물리 픽셀 기준
  const [w, h] = rw.getSize();
  const dpr = window.devicePixelRatio || 1;
  canvas.width  = w;
  canvas.height = h;
  canvas.style.width  = `${w / dpr}px`;
  canvas.style.height = `${h / dpr}px`;

  // 3. VTK onModified 구독 → 줌/팬/리사이즈 시 재그리기
  const sub = rw.onModified(() => drawOverlay(canvas));

  drawOverlay(canvas);  // 초기 그리기

  return () => {
    sub.unsubscribe();
    canvas.remove();
  };
}, [fullScreenRendererRef, annotations]);

// 4. 슬라이스 이동 시 재그리기
useEffect(() => {
  if (canvasRef.current) drawOverlay(canvasRef.current);
}, [sliceIndices]);

07 · Full Flow

BBoxOverlay 전체 동작 흐름

08 · Pitfalls

구현 시 주의할 점

함정	증상	해결
렌더러 명칭 역전	박스가 Axial에 그려야 할 것이 Coronal에 나타남	coronal→Axial, axial→Coronal 매핑 표를 코드 주석으로 명시
VTK Y축 반전 누락	박스가 위아래 뒤집혀 나타남	winH - displayY로 반전. getSize()[1]은 매번 최신 값 사용
DPR 보정 누락	Retina 화면에서 박스가 절반 크기 또는 오프셋 어긋남	Display 좌표 ÷ devicePixelRatio. Canvas CSS 크기도 동일 적용
vtkCoordinate delete 누락	장시간 사용 시 WebGL 메모리 누수	coord.delete() 항상 호출. Object Pool 패턴 적용 권장
drawOverlay 중복 호출	빠른 스크롤 시 불필요한 리렌더 누적	requestAnimationFrame으로 debounce. 이미 pending이면 skip
sliceIndices ref vs state	drawOverlay 클로저가 오래된 인덱스를 참조	drawOverlay 내부에서 sliceIndices를 ref로 읽거나 Effect 의존성 명시

⚡ vtkCoordinate는 생성 비용이 높습니다. buildAneurysmBBoxes로 계산된 꼭짓점 수(병변 수 × 2)는 보통 10~30개 수준이므로 drawOverlay당 생성·삭제가 크게 문제되지 않습니다. 하지만 annotation이 수백 개라면 Object Pool 패턴(최대 4개 재사용)을 적용하세요.

09 · Series Wrap-up

3편 요약 & 시리즈 마무리

주제	핵심 내용
좌표계 명명 역전	coronal 렌더러 = Axial UI / axial 렌더러 = Coronal UI
픽셀 → IJK	Axial: px=i, py=j, k=sliceK 직접 매핑
IJK → World	origin + IJK × spacing (imageData API)
World → Display	vtkCoordinate · Y축 반전 (winH - dy)
Display → Canvas	÷ devicePixelRatio
3D BBox 재구성	buildAneurysmBBoxes — 슬라이스 전체 annotation 누적
Sagittal 투영	iMin≤sliceI≤iMax 체크 → (i,jMin,kMin)~(i,jMax,kMax)
Coronal 투영	jMin≤sliceJ≤jMax 체크 → (iMin,j,kMin)~(iMax,j,kMax)
카메라 동기화	renderWindow.onModified() → drawOverlay() 재호출

🎯 이번 시리즈에서 한 일을 돌아보면 — 제거가 핵심이었습니다. SEG NIfTI fetch, gzip 해제, Web Worker 리샘플, VTK ImageData 생성, GPU 텍스처 업로드. 이 다섯 단계를 모두 없애고 JSON 수 KB로 대체했습니다. 그 결과로 로딩 시간이 줄었고, 메모리 사용량이 줄었고, 코드가 단순해졌으며, 3개 뷰 모두에 박스를 그릴 수 있게 됐습니다. 좋은 성능 최적화의 대부분은 "더 잘하는 것"이 아니라 "하지 않는 것"에서 나옵니다.

🎉 시리즈 완결

SEG NIfTI → BBox JSON 전환 3부작이 완료되었습니다.

1편 · 전환 배경과 병목 분석 → 2편 · API 설계와 Canvas 구현 → 3편 · VTK 좌표 변환과 3뷰 동기화

NIfTI Viewer 프로젝트 · SEG → BBox 전환 시리즈 3편(完) · 2026