[React] Cornerstone3D의 최적화와영상 로드 기술 완전 분석

Technical Deep Dive

Cornerstone3D의 최적화와
영상 로드 기술 완전 분석

Web Worker 디코딩, 스트리밍 볼륨, HTJ2K Progressive Loading, VoxelManager까지 — 내부 동작 원리를 파헤칩니다.

Streaming Volume HTJ2K Progressive Web Worker 디코딩 VoxelManager Request Pool GPU 텍스처 공유

01 · Overview

왜 의료 영상 로딩은 특별히 어렵나?

일반 웹 이미지와 달리 의료 영상 데이터는 극단적인 제약 조건을 가집니다. 512×512 픽셀 CT 슬라이스 300장은 압축 해제 시 약 150MB이며, PET-CT Fusion처럼 여러 시리즈를 동시에 렌더링할 경우 GPU와 CPU 메모리 모두 빠르게 한계에 도달합니다. Cornerstone3D는 이 문제를 단일 기술이 아닌 여러 레이어의 최적화 전략을 조합해 해결합니다.

150MB+

CT 300슬라이스 비압축

1회

GPU 텍스처 업로드 횟수

50%↓

VoxelManager 메모리 절감

66ms

HTJ2K 첫 렌더 시간

💡 이 글에서 다루는 기술들은 단독으로 작동하지 않습니다. Request Pool → Web Worker 디코딩 → 스트리밍 → GPU 업로드 → Prefetch가 유기적으로 맞물려 작동하는 구조입니다.

02 · Architecture

영상 로딩 전체 파이프라인

DICOMweb 서버에서 영상을 요청해 화면에 표시하기까지, Cornerstone3D 내부에서 어떤 단계가 순서대로 실행되는지 전체 흐름을 살펴봅니다.

03 · Web Worker

오프메인스레드 디코딩 — 화면이 멈추지 않는 이유

브라우저의 메인 스레드에서 DICOM 파일을 디코딩하면 UI가 완전히 멈춥니다. Cornerstone3D는 Web Worker를 통해 디코딩 연산을 완전히 메인 스레드 밖으로 분리합니다. v2.0부터는 HTTP Fetch와 Decode를 독립적으로 비동기 처리해 파이프라인 효율을 극대화합니다.

Legacy 방식

메인 스레드 순차 처리

• fetch → decode → render 순차 실행
• 디코딩 중 UI 완전 블로킹
• HTTP 요청 6개 단위 묶음 처리
• 한 이미지 지연 시 전체 대기

Cornerstone3D — 현재

Fetch / Decode 완전 분리

• Fetch와 Decode를 독립 비동기 큐로 운영
• 디코딩 중에도 UI 반응 유지
• Worker Pool로 다중 병렬 디코딩
• Transferable 객체로 복사 없이 데이터 전달

⚡ v2.0부터 Web Worker는 SharedArrayBuffer 의존성을 제거했습니다. 이전에는 SAB를 위해 서버에 COOP/COEP 헤더 설정이 필요했지만, 이제 Transferable 방식으로 동일한 성능을 달성합니다.

지원하는 코덱 디코더는 Workers 내에서 동적 로드됩니다.

Transfer Syntax	포맷	디코더	특징
1.2.840.10008.1.2.1	Uncompressed	Native	별도 디코더 불필요
1.2.840.10008.1.2.4.90	JPEG 2000 Lossless	openjpeg (WASM)	고품질 무손실
1.2.840.10008.1.2.4.202	HTJ2K	openhtj2k (WASM)	Progressive 디코딩 지원
1.2.840.10008.1.2.4.70	JPEG Lossless	libjpeg (WASM)	—
1.2.840.10008.1.2.5	RLE Lossless	Built-in	—

04 · Request Pool Manager

Request Pool Manager — 요청 우선순위 제어

Cornerstone3D는 모든 이미지 요청을 단순히 FIFO로 처리하지 않습니다. RequestPoolManager가 요청을 3단계 우선순위 큐로 분류하여 사용자 인터랙션에 영향이 없도록 스케줄링합니다.

🖱️

interaction

사용자가 직접 보고 있는 슬라이스. 즉시 로드. 다른 요청보다 항상 우선.

📦

prefetch

현재 슬라이스 인근 프리패치. 백그라운드에서 조용히 로드.

🖼️

thumbnail

썸네일·저해상도 미리보기. 가장 낮은 우선순위.

🔄 인터랙션(스크롤, 클릭) 발생 시 현재 진행 중인 prefetch 요청을 즉시 중단하고 interaction 큐를 먼저 처리합니다. 인터랙션 종료 후 남은 prefetch가 재개됩니다. 이 덕분에 빠른 스크롤에도 현재 슬라이스가 끊기지 않습니다.

// Request Pool 우선순위 설정 예시
import { requestPoolManager } from '@cornerstonejs/core';

// 최대 동시 요청 수 조정
requestPoolManager.setMaxSimultaneousRequests(
  'interaction', 6   // 기본값: 6
);
requestPoolManager.setMaxSimultaneousRequests(
  'prefetch', 10    // 기본값: 10
);

// 수동으로 interaction 우선순위 요청 추가
requestPoolManager.addRequest(
  requestFn, 'interaction', /* addToBeginning = */ true
);

05 · Streaming Volume

스트리밍 볼륨 로더 — 점진적 3D 렌더링

일반적인 볼륨 로더는 모든 슬라이스를 메모리에 올린 후에야 렌더링을 시작합니다. Cornerstone3D의 StreamingImageVolume은 슬라이스가 하나씩 도착하는 즉시 GPU 텍스처를 부분 업데이트해 렌더링합니다.

1

메타데이터 프리패치 (전체 시리즈)

모든 imageId의 PixelSpacing, ImagePosition 등 메타데이터만 먼저 수집합니다. 실제 픽셀 데이터는 아직 가져오지 않아 매우 빠릅니다.

2

Volume 사전 할당 (createAndCacheVolume)

메타데이터 기반으로 전체 볼륨 크기를 계산해 메모리를 미리 예약합니다. 이때 GPU 텍스처도 빈 상태로 생성됩니다.

3

슬라이스 단위 로드 & GPU 부분 업데이트

각 슬라이스가 도착하면 texSubImage3D로 GPU 텍스처의 해당 Z 오프셋 위치만 부분 업데이트합니다. 전체 텍스처를 재업로드하지 않아 매우 효율적입니다.

4

skipCreateImage — Image 객체 생성 생략

볼륨 로딩 시 개별 Cornerstone Image 객체 생성을 건너뜁니다. pixelData를 볼륨 버퍼에 직접 삽입하므로 메모리와 시간 모두 절약됩니다.

5

즉시 렌더링 (Progressive 표시)

슬라이스 절반만 로드된 상태에서도 현재 도착한 데이터로 렌더링이 진행됩니다. 사용자는 로딩 중에도 볼륨을 탐색할 수 있습니다.

// 스트리밍 볼륨 생성 & 로드
import { volumeLoader } from '@cornerstonejs/core';

const volumeId = 'cornerstoneStreamingImageVolume:CT_VOLUME';

// 1단계: 메타데이터 기반 사전 할당
const volume = await volumeLoader.createAndCacheVolume(volumeId, {
  imageIds: ctImageIds,  // 300장 슬라이스 imageId 배열
});

// 2단계: 스트리밍 로드 시작 (즉시 렌더링 가능)
volume.load();  // await 불필요 — 슬라이스 도착 시 자동 렌더링

// viewport에 볼륨 연결
viewport.setVolumes([{ volumeId }]);

06 · Progressive Loading

HTJ2K Progressive Loading — 66ms 첫 렌더

HTJ2K(High Throughput JPEG 2000)는 DICOM 표준에 새로 추가된 압축 포맷으로, 첫 N 바이트만으로 저해상도 버전을 즉시 디코딩할 수 있습니다. Cornerstone3D는 이를 활용해 전체 이미지가 도착하기 전에 먼저 저해상도를 표시하고, 데이터가 누적될수록 해상도를 점진적으로 향상시킵니다.

JLS (일반 JPEG LS)

4,586ms

JLS Reduced

359ms

HTJ2K

66ms

HTJ2K Byte Range

45ms

* 3036×3036 CT 이미지 기준, 첫 렌더 시간 (4G 네트워크)

Progressive Loading은 2단계 Retrieve 설정으로 동작합니다.

// HTJ2K Progressive Loading 설정
import { utilities } from '@cornerstonejs/core';

const retrieveConfig = {
  stages: [
    { id: 'initialImages', retrieveType: 'singleFast' },  // 저해상도 먼저
    { id: 'fullResolution', retrieveType: 'singleFinal' }, // 전체 품질
  ],
  retrieveOptions: {
    singleFast: {
      streaming: true,
      urlParameters: 'accept=image/jhc',  // HTJ2K 요청
    },
    singleFinal: { streaming: true },
  },
};

// 스택 전체에 적용
utilities.imageRetrieveMetadataProvider.add('stack', retrieveConfig);

// 또는 볼륨 전체에 적용
utilities.imageRetrieveMetadataProvider.add(volumeId, retrieveConfig);

⚠️ HTJ2K Byte Range는 서버가 Byte Range Request를 지원해야 합니다. 서버 미지원 시 singleFast 스테이지 요청이 실패할 수 있습니다. 표준 HTJ2K 스트리밍(streaming: true만)은 Byte Range 없이도 동작합니다.

07 · Memory

메모리 최적화 — VoxelManager & 단일 캐시

Cornerstone3D 2.0의 가장 큰 내부 변화는 VoxelManager 도입과 단일 Image Cache 아키텍처로의 전환입니다. 기존에는 Image Cache와 Volume Cache가 별도로 존재해 같은 데이터가 이중으로 메모리를 차지했습니다.

Cornerstone3D v1

이중 캐시 구조

• Image Cache + Volume Cache 별도 운영
• 같은 슬라이스 데이터 두 곳에 중복 저장
• 대형 스칼라 배열(scalarData) CPU에 유지
• 볼륨 전체 메모리 = CPU 배열 + GPU 텍스처
• Stack ↔ Volume 세그멘테이션 동기화 버그

Cornerstone3D v2

단일 Image Cache + VoxelManager

• 오직 Image Cache 하나만 사용 (단일 진실)
• 볼륨 렌더링 시 CPU 스칼라 배열 불필요
• Image → GPU 직접 스트리밍 (CPU 우회)
• Native 데이터 타입 유지 → 렌더 시 변환
• 메모리 사용량 약 50% 절감

// v1: scalarData 직접 접근 (비권장)
const scalarData = volume.scalarData;          // ❌ v2에서 제거됨

// v2: VoxelManager로 효율적 접근
const vm = volume.voxelManager;
const value = vm.getAtIndex(flatIndex);         // ✅ 단일 복셀 접근
const value = vm.getAtIJK(i, j, k);            // ✅ IJK 좌표 접근

// 대량 처리 시 forEach 활용
vm.forEach(({ value, index }) => {
  if (value > 100) vm.setAtIndex(index, 100);
});

// ⚠️ 최후 수단으로만 사용 (메모리 2배 점유)
const fullArray = vm.getCompleteScalarDataArray();

08 · Cache Management

Cache API — 메모리 한도 & 자동 해제

대형 볼륨을 여러 개 로드하면 브라우저가 OOM(Out of Memory)으로 탭을 종료합니다. Cornerstone3D의 Cache API는 최대 메모리 한도를 설정하고, 초과 시 자동으로 오래된 데이터를 해제하는 LRU 방식을 제공합니다.

💾

최대 메모리 한도 설정

전체 이미지 캐시가 차지할 수 있는 최대 바이트를 지정합니다. 초과 시 가장 오래 사용되지 않은 이미지부터 해제됩니다.

🗑️

자동 공간 확보

새 볼륨 할당 전 decacheIfNecessaryUntilBytesAvailable()로 필요한 공간을 자동 확보합니다.

// 캐시 최대 메모리 설정 (기본: 1GB)
import { cache } from '@cornerstonejs/core';

cache.setMaxCacheSize(2 * 1024 * 1024 * 1024);  // 2GB

// 현재 사용량 확인
const { numImagesCached, cacheSizeInBytes } = cache.getCacheStatus();

// 특정 볼륨 제거
cache.purgeVolumeCache(volumeId);

// 전체 캐시 비우기
cache.purgeCache();

09 · GPU Optimization

Shared Volume Mapper — GPU 텍스처 1회 업로드

PET-CT Fusion처럼 같은 볼륨 데이터를 여러 뷰포트에서 다른 카메라 각도로 표시해야 할 때, 나이브한 구현은 뷰포트 수만큼 GPU 텍스처를 복제합니다. Cornerstone3D는 Shared Volume Mapper로 GPU 텍스처를 단 1회만 업로드하고 모든 뷰포트가 재사용합니다.

🔧 내부적으로 vtkStreamingOpenGLTexture를 커스터마이징하여 texSubImage3D()로 슬라이스 단위 부분 업데이트를 구현합니다. 전체 텍스처를 교체하는 것이 아니라 해당 Z 슬라이스 오프셋만 갱신하므로 스트리밍 중에도 GPU 부하가 최소화됩니다.

10 · Prefetch

Position-aware Prefetch — 위치 기반 스마트 프리패치

단순 순차 프리패치(1번 → 2번 → 3번 ...)는 사용자가 중간 슬라이스에서 시작하면 비효율적입니다. Cornerstone3D의 stackPrefetch는 현재 슬라이스 위치를 기준으로 가까운 슬라이스부터 우선 로드하고, 여러 뷰포트의 프리패치가 서로 간섭하지 않도록 조율합니다.

📍

Position-aware (위치 인식)

현재 슬라이스 인덱스를 중심으로 ±방향으로 교차하며 로드합니다. 슬라이스 100에서 시작하면 101, 99, 102, 98 순으로 프리패치합니다.

🖥️

Multi-viewport 인식

여러 뷰포트가 동일한 Request Pool을 공유합니다. 한 뷰포트의 프리패치가 다른 뷰포트의 interaction 요청을 막지 않도록 우선순위를 조율합니다.

// stackPrefetch 활성화
import { StackScrollTool, ToolGroupManager } from '@cornerstonejs/tools';
import { cornerstoneTools } from '@cornerstonejs/tools';

const { StackScrollTool, StackScrollMouseWheelTool, PanTool, ZoomTool,
        ToolGroupManager, Enums: csToolsEnums } = cornerstoneTools;

// ToolGroup에 Prefetch 활성화
cornerstoneTools.addTool(cornerstoneTools.StackScrollTool);
toolGroup.addTool(StackScrollTool.toolName, {
  configuration: {
    prefetchCount: 10,     // 앞뒤 10장씩 프리패치
    preventHandleOutsideImage: false,
  },
});

11 · Summary

최적화 기술 한눈에 보기

기술	적용 위치	효과	도입 버전
오프스크린 WebGL 컨텍스트	RenderingEngine	뷰포트 N개도 WebGL 컨텍스트 1개	v1.0
Shared Volume Mapper	GPU 렌더링	동일 볼륨 GPU 텍스처 1회 업로드	v1.0
Web Worker 분리 디코딩	DICOM 로딩	메인 스레드 블로킹 없음	v1.0
Fetch / Decode 독립 비동기	Request Pool	파이프라인 처리량 증가	v2.0
스트리밍 볼륨 로더	Volume 로딩	슬라이스 도착 즉시 렌더링	v1.0
skipCreateImage	Volume 로딩	Image 객체 생성 오버헤드 제거	v1.0
texSubImage3D 부분 업데이트	GPU 업로드	스트리밍 중 GPU 부하 최소화	v1.0
HTJ2K Progressive Loading	네트워크	첫 렌더 66ms (vs 4,586ms)	v1.x
Priority Queue (3단계)	Request Pool	인터랙션 중 끊김 방지	v1.x
Position-aware Prefetch	Stack 뷰어	현재 위치 기준 스마트 프리패치	v1.x
VoxelManager	메모리 관리	메모리 ~50% 절감, CPU 배열 제거	v2.0
단일 Image Cache	캐시 구조	Image/Volume 이중 캐시 제거	v2.0
Native 타입 저장	캐시	불필요한 타입 변환 제거	v2.0

🧭 커스텀 VTK.js 구현과 비교했을 때, 이 최적화 기법들을 모두 직접 구현하려면 상당한 시간이 필요합니다. 특히 HTJ2K Progressive Loading, VoxelManager, Request Pool Priority Queue는 Cornerstone3D가 제공하는 핵심 가치입니다. 반면 비표준 REST API 기반 데이터(NIfTI .nii.gz)를 다루거나 Canvas 기반 커스텀 렌더링이 필요한 경우에는 직접 VTK.js 파이프라인을 구성하는 것이 더 적합합니다.

참고: Cornerstone3D Progressive Loading · VoxelManager · Streaming Volume

2026 · NIfTI Viewer 프로젝트 — Cornerstone3D 최적화 기술 분석