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

2편 / 3편

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

BE가 내려주는 JSON 구조를 어떻게 설계했는지, FE에서 그 데이터를 받아 AxialGridViewer와 BBoxOverlay에서 어떻게 Canvas로 그리는지 구현 코드 중심으로 설명합니다.

BBoxAnnotationItem fetchAxialBBox drawBBoxOverlay useNiftiLoader 변경 Canvas 2D BBoxOverlay 컴포넌트

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

1

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

2

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

3

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

01 · API Design

BBox JSON — 무엇을 어떻게 담았나

가장 먼저 결정해야 할 것은 BE가 FE에 무엇을 내려줄 것인가였습니다. SEG NIfTI에서 우리가 실제로 필요한 정보만 추려보면 세 가지입니다.

🗂️

어느 슬라이스에

병변이 등장하는 슬라이스 번호(instance_number). 현재 슬라이스와 비교해 그릴지 말지를 결정합니다.

📐

어느 위치에

bbox라면 좌상단·우하단 좌표, contour라면 폴리라인 좌표 배열. Canvas strokeRect / beginPath로 바로 쓸 수 있는 형태.

🎨

어떤 색으로

aneurysm_id별 고유 색상. 같은 병변이 여러 슬라이스에 걸쳐 있어도 동일한 색으로 추적할 수 있습니다.

이 세 가지를 담은 최소 구조가 BBoxAnnotationItem입니다.

utils/sliceRenderer.ts — BBoxAnnotationItem 타입

/** BE bbox/contour annotation 단일 항목 */
export interface BBoxAnnotationItem {
  instance_number: number;          // 슬라이스 번호 (0-indexed)
  aneurysm_id:     number;          // 병변 ID — 동일 병변 슬라이스 추적
  type:            'bbox' | 'contour'; // 렌더링 방식 선택
  graphic_data:    [number, number][]; // 픽셀 좌표 배열
  color:           string;           // CSS 색상 문자열 (ex. '#ff4444')
}

실제 응답 예시

// GET /dicomweb/v1/axial-bbox/studies/{study_uid}
{
  "study_uid": "1.2.840.114...",
  "annotations": [

    // 슬라이스 150번: aneurysm #1, bbox 타입
    {
      "instance_number": 150,
      "aneurysm_id":     1,
      "type":            "bbox",
      "graphic_data":    [[120, 80], [200, 160]],
      "color":           "#ff4444"
    },

    // 슬라이스 151번: 같은 aneurysm #1, contour 타입
    {
      "instance_number": 151,
      "aneurysm_id":     1,
      "type":            "contour",
      "graphic_data": [
        [122, 82], [180, 80], [198, 130],
        [160, 162], [118, 155]
      ],
      "color":           "#ff4444"
    },

    // 슬라이스 200번: aneurysm #2 (별도 병변)
    {
      "instance_number": 200,
      "aneurysm_id":     2,
      "type":            "bbox",
      "graphic_data":    [[300, 200], [380, 280]],
      "color":           "#44aaff"
    }
  ]
}

💡 graphic_data의 좌표계는 AxialGridViewer 기준 픽셀 좌표입니다. Canvas 1:1 복셀 매핑과 일치하므로 FE에서 별도 좌표 변환 없이 바로 strokeRect / lineTo에 사용할 수 있습니다. BBoxOverlay(VTK)에서는 IJK→World→Display 변환이 필요하며, 이는 3편에서 다룹니다.

graphic_data 해석 규칙

type	graphic_data 형식	해석
bbox	[[x0, y0], [x1, y1]] (최소 2점)	min(x), min(y) → max(x), max(y)로 strokeRect 결정
contour	[[x0,y0], [x1,y1], ...] (최소 3점)	첫 점에서 moveTo, 이후 lineTo, 마지막에 closePath

02 · API Layer

fetchAxialBBox — API 함수 추가

niftiApi.ts에 BBox 전용 fetch 함수와 응답 타입을 추가합니다. 기존 fetch 패턴과 동일한 구조이므로 통일성을 유지합니다.

api/niftiApi.ts

import type { BBoxAnnotationItem } from '../utils/sliceRenderer';

/** /axial-bbox/ 엔드포인트 응답 */
export interface AxialBBoxResponse {
  study_uid:   string;
  annotations: BBoxAnnotationItem[];
}

/**
 * Axial BBox annotation JSON을 API에서 가져온다
 * GET /dicomweb/v1/axial-bbox/studies/{study_uid}
 *
 * @param studyUid  스터디 UID
 * @returns         AxialBBoxResponse (study_uid + annotations[])
 */
export async function fetchAxialBBox(studyUid: string): Promise<AxialBBoxResponse> {
  const baseURL = API_SERVER_URI || '';
  const url = `${baseURL}/dicomweb/v1/axial-bbox/studies/${studyUid}`;

  const response = await fetch(url, { headers: getAuthHeaders() });
  if (!response.ok) {
    throw new Error(
      `Axial BBox fetch failed: ${response.status} ${response.statusText}`
    );
  }
  return response.json();
}

⚡ 기존 fetchAxialSegVolume은 수십 MB ArrayBuffer를 받아서 IndexedDB 캐싱 로직까지 포함했습니다. fetchAxialBBox는 JSON 파싱 한 줄이 전부입니다. 캐싱도 불필요합니다 — 응답이 수 KB이므로 매번 fetch해도 부담이 없습니다.

03 · Hook Changes

useNiftiLoader — Seg에서 BBox로

핵심 로딩 훅인 useNiftiLoader.ts에서 가장 많은 코드가 변경되었습니다. Seg 관련 로직이 전부 빠지고 BBox fetch가 그 자리를 대체합니다.

제거된 import

// ❌ 제거
import { fetchAxialSegVolume, fetchSegVolume } from '../api/niftiApi';
import vtkDataArray from '@kitware/vtk.js/Common/Core/DataArray';
import { createSegVtkImageData, createSegPlanarSlices } from '../utils/vtkMapper';
import type { SegProcessRequest, SegProcessResponse } from '../workers/segWorker';

추가된 import

// ✅ 추가
import { fetchAxialBBox } from '../api/niftiApi';
import type { BBoxAnnotationItem } from '../utils/sliceRenderer';

loadVolumes 내부 — fetch 병렬화 변경

// ─── Before ───────────────────────────────────────────
const [baseResult, segResult] = await Promise.allSettled([
  fetchBase(),
  fetchSegVolume(studyUid),            // NIfTI ArrayBuffer
]);

// seg Worker 처리 (리샘플 + RGBA 변환) ...
const segResp = await runSegWorker(segBuffer, baseDims);
createSegVtkImageData(segResp);
createSegPlanarSlices(segImageData);

// ─── After ────────────────────────────────────────────
const [baseResult, bboxResult] = await Promise.allSettled([
  fetchBase(),
  shouldSkipSeg || !studyUid
    ? Promise.reject(new Error('BBox skipped'))
    : fetchAxialBBox(studyUid),           // JSON 수 KB
]);

// JSON 파싱만 — Worker 없음, VTK ImageData 없음
if (bboxResult.status === 'fulfilled') {
  setBboxAnnotations(bboxResult.value.annotations);
}

반환값에 bboxAnnotations 추가

// return 타입 변경
return {
  isLoading,
  error,
  windowLevel,
  loadVolumes,
  bboxAnnotations,    // ✅ 새로 추가 (BBoxAnnotationItem[] | null)
};

04 · Canvas Drawing

drawBBoxOverlay — Canvas 2D 렌더링 함수

sliceRenderer.ts에 추가된 함수입니다. AxialGridViewer에서 각 셀의 renderAxialSlice() 직후 같은 ctx에 호출해 bbox/contour를 덧그립니다.

utils/sliceRenderer.ts — drawBBoxOverlay()

/**
 * Canvas 2D에 BBox/Contour 어노테이션을 그린다.
 * renderAxialSlice() 호출 직후 같은 ctx에 사용.
 *
 * @param ctx         렌더링 대상 Canvas 2D Context
 * @param annotations BBoxAnnotationItem 배열 (전체)
 * @param sliceK      현재 슬라이스 번호 (K축 인덱스)
 * @param lineWidth   선 굵기 (기본 2)
 */
export function drawBBoxOverlay(
  ctx:         CanvasRenderingContext2D,
  annotations: BBoxAnnotationItem[],
  sliceK:      number,
  lineWidth:   number = 2,
): void {

  // 1. 현재 슬라이스에 해당하는 annotation만 필터링
  const sliceAnnotations = annotations.filter(
    a => a.instance_number === sliceK
  );
  if (sliceAnnotations.length === 0) return;  // 없으면 즉시 종료

  ctx.save();
  ctx.lineWidth = lineWidth;

  for (const ann of sliceAnnotations) {
    ctx.strokeStyle = ann.color;

    // 2a. BBox — strokeRect으로 단일 사각형
    if (ann.type === 'bbox' && ann.graphic_data.length >= 2) {
      const xs = ann.graphic_data.map(p => p[0]);
      const ys = ann.graphic_data.map(p => p[1]);
      ctx.strokeRect(
        Math.min(...xs),               // x 시작
        Math.min(...ys),               // y 시작
        Math.max(...xs) - Math.min(...xs),  // width
        Math.max(...ys) - Math.min(...ys),  // height
      );
    }

    // 2b. Contour — 폴리라인 + closePath
    else if (ann.type === 'contour' && ann.graphic_data.length >= 3) {
      ctx.beginPath();
      ctx.moveTo(ann.graphic_data[0][0], ann.graphic_data[0][1]);
      for (let i = 1; i < ann.graphic_data.length; i++) {
        ctx.lineTo(ann.graphic_data[i][0], ann.graphic_data[i][1]);
      }
      ctx.closePath();
      ctx.stroke();
    }
  }

  ctx.restore();  // strokeStyle, lineWidth 원복
}

📐 graphic_data에 점이 2개 이상이면 min/max로 사각형을 결정합니다. BE가 꼭 [좌상단, 우하단] 순서로 주지 않아도 되고, 여러 점의 볼록 껍질(convex hull)로 전달해도 strokeRect가 올바르게 그려집니다.

05 · AxialGridViewer

AxialGridViewer — 기존 Canvas에 덧그리기

AxialGridViewer는 이미 Canvas 2D로 슬라이스를 그리고 있었습니다. 여기에 drawBBoxOverlay를 한 줄만 추가하면 됩니다. 컴포넌트 구조 자체는 거의 바뀌지 않았습니다.

Props 추가

interface AxialGridViewerProps {
  // ... 기존 props (baseScalars, segScalars, windowLevel 등) ...
  bboxAnnotations: BBoxAnnotationItem[] | null;  // ✅ 추가
}

renderAll 내부 — 슬라이스 렌더 직후 bbox 추가

// renderAll 함수 내부 — 각 셀(sliceK) 렌더링 루프
for (const { ctx, sliceK } of cells) {

  // 기존: 슬라이스 픽셀 렌더링 (변경 없음)
  renderAxialSlice(
    ctx, baseScalars, baseDims, sliceK,
    colorWindow, colorLevel, baseLUT,
    segScalars, segDims, segLabelLUT,
  );

  // ✅ 추가: 같은 ctx에 bbox 오버레이
  if (bboxAnnotations && bboxAnnotations.length > 0) {
    drawBBoxOverlay(ctx, bboxAnnotations, sliceK);
  }
}

06 · BBoxOverlay Component

BBoxOverlay.tsx — VTK 뷰포트 위 Canvas 오버레이

MPR 뷰(Axial/Sagittal/Coronal)는 VTK WebGL Canvas 위에 투명 Canvas를 겹치는 방식으로 오버레이합니다. AxialGridViewer와 달리 VTK 좌표 변환이 필요한 것이 핵심 차이입니다.

⚠️ VTK 좌표 변환(IJK→World→Display) 로직은 이 글의 범위를 벗어납니다. 3편에서 전체를 다룹니다. 여기서는 컴포넌트의 Props 계약과 렌더링 트리거 구조만 살펴봅니다.

Props 설계

interface BBoxOverlayProps {
  containerRef:          React.RefObject<HTMLElement | null>;
  fullScreenRendererRef: React.RefObject<VtkFullScreenRenderWindow | null>;
  renderers:             RendererSet | null;     // 3개 뷰 렌더러 세트
  imageData:             VtkImageData | null;   // IJK 공간 계산용
  sliceIndices:          SliceIndices | null;   // 현재 I/J/K 인덱스
  annotations:           BBoxAnnotationItem[] | null;
  lineWidth?:            number;               // 기본 2
}

렌더링 트리거 — onModified 구독

VTK는 카메라가 변경(줌/팬/리사이즈)될 때마다 renderWindow.onModified 이벤트를 발생시킵니다. 이 이벤트를 구독해 bbox Canvas를 자동 재그리기합니다.

// BBoxOverlay.tsx 내부 — VTK 변경 구독
useEffect(() => {
  const rw = fullScreenRendererRef.current?.getRenderWindow();
  if (!rw) return;

  // VTK 카메라 변경(줌·팬·리사이즈) 시 Canvas 재그리기
  const sub = rw.onModified(() => {
    drawOverlay();   // IJK→World→Display 좌표 재계산 후 Canvas 업데이트
  });

  return () => sub.unsubscribe();
}, [fullScreenRendererRef, annotations, sliceIndices]);

NiftiViewer에서의 통합

// NiftiViewer.tsx
const { isLoading, error, windowLevel, loadVolumes, bboxAnnotations } = niftiLoader;

// VTK 컨테이너 내부에 조건부 렌더링
{bboxAnnotations && bboxAnnotations.length > 0 && displaySliceIndices && (
  <BBoxOverlay
    containerRef={containerRef}
    fullScreenRendererRef={fullScreenRendererRef}
    renderers={renderersRef.current}
    imageData={baseImageDataRef.current}
    sliceIndices={displaySliceIndices}
    annotations={bboxAnnotations}
  />
)}

🧩 BBoxOverlay는 bboxAnnotations가 없거나 비어 있으면 아예 마운트되지 않습니다. SEG가 없는 스터디에서 불필요한 Canvas DOM 생성과 VTK 이벤트 구독이 발생하지 않습니다.

07 · Data Flow

2편 구현 전체 데이터 흐름

08 · Summary

2편 요약

구성 요소	역할	핵심 변경
BBoxAnnotationItem	전체 시스템의 공통 데이터 타입	instance_number, type, graphic_data, color
fetchAxialBBox()	JSON 수신 API 함수	기존 seg fetch 대체, 캐싱 불필요
useNiftiLoader	로딩 훅	Seg Worker 제거, BBox allSettled 병렬 fetch
drawBBoxOverlay()	Canvas 2D 렌더 함수	sliceK 필터 → strokeRect / lineTo
AxialGridViewer	4×4 슬라이스 그리드	renderAxialSlice 후 drawBBoxOverlay 추가 2줄
BBoxOverlay.tsx	MPR 3뷰 오버레이 컴포넌트	VTK Canvas 위 투명 Canvas, onModified 구독

📌 3편 예고: BBoxOverlay 내부에서 annotation의 2D 픽셀 좌표를 VTK 3D 공간(IJK→World)으로 변환하고, 다시 각 뷰의 Display 좌표로 투영하는 과정 — 그리고 Axial에는 원본 좌표를, Sagittal/Coronal에는 3D 바운딩 박스를 투영하는 뷰별 렌더링 전략을 상세히 다룹니다.

다음 글

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

3편 보기 →

NIfTI Viewer 프로젝트 · SEG → BBox 전환 시리즈 2편 · 2026