[React] SEG 영역만 Zarr로,나머지는 원본 그대로

Sparse Zarr Strategy

SEG 영역만 Zarr로,
나머지는 원본 그대로

세그멘테이션이 있는 청크만 선택적으로 Zarr로 변환하는 Sparse Zarr 전략 — 아이디어의 타당성, 구현 방식, 예상 문제점을 기술적으로 검토합니다.

Sparse Zarr write_empty_chunks=False SEG BBox 분석 하이브리드 서빙 fill_value=0 선택적 청크 변환

01 · Idea Validation

이 아이디어, 기술적으로 타당한가?

결론부터 말하면 — 타당하며, Zarr가 네이티브로 지원하는 개념입니다.

세그멘테이션(SEG) NIfTI는 본질적으로 희소(sparse) 데이터입니다. 뇌종양, 병변, 혈관 등 레이블이 존재하는 복셀은 전체 볼륨의 극히 일부이고, 나머지 대부분은 0(배경)입니다. Zarr는 이 특성을 write_empty_chunks=False + fill_value=0으로 네이티브하게 지원합니다 — 값이 0인 청크 파일은 디스크에 저장하지 않고, 읽을 때 암묵적으로 0을 반환합니다.

💡 핵심 인사이트: Zarr의 Sparse 배열 특성을 활용하면 SEG 데이터가 존재하는 청크만 물리적으로 저장됩니다. SEG가 없는 청크는 파일 자체가 없어도 클라이언트는 fill_value(0)를 받습니다. 즉, "SEG가 있는 곳만 Zarr로"는 별도 구현 없이 write_empty_chunks=False 하나로 자동 달성됩니다.

~5%

일반 SEG의 비영(非零) 복셀 비율

~5%

실제 저장되는 Zarr 청크 비율

95%↓

Zarr 스토리지 절감

0ms

빈 청크 응답 오버헤드

02 · Sparsity of SEG

SEG 데이터는 왜 희소한가

뇌 MRI에서 종양 세그멘테이션을 예로 들면, 전체 볼륨 512×512×200 = 52M 복셀 중 실제 레이블이 있는 복셀은 수천~수만 개에 불과합니다. 64×64×64 청크 기준으로 보면, SEG 데이터를 포함하는 청크는 전체의 극히 일부입니다.

세그멘테이션 볼륨에서 실제로 레이블이 있는 복셀 비율은 매우 낮습니다.

뇌종양 SEG (GBM)

~1~3%

폐 결절 SEG

~0.5~1%

혈관 SEG (전체)

~5~10%

뇌 구조 전체 파셀레이션

~50~70%

* 병변 SEG는 희소도가 높아 Sparse Zarr 효과가 극대화됨. 파셀레이션처럼 전체를 채우는 SEG는 이점 감소

03 · Hybrid Architecture

하이브리드 서빙 아키텍처 — 전체 구조

Base 볼륨은 기존 .nii.gz 그대로, SEG만 Sparse Zarr로 서빙하는 하이브리드 구조입니다. 웹 뷰어는 두 소스를 조합해 렌더링합니다.

📐 Base 볼륨은 전혀 건드리지 않습니다. 기존 .nii.gz 파일을 그대로 두고 SEG NIfTI만 Sparse Zarr로 변환합니다. Base는 기존 nifti-volume-loader로 로드하고, SEG는 커스텀 Zarr ImageLoader로 로드해 두 레이어를 뷰포트에서 합성합니다.

04 · Sparse Zarr 원리

write_empty_chunks=False — 핵심 메커니즘

Zarr가 SEG Sparse 저장을 어떻게 처리하는지 단계별로 살펴봅니다.

1

SEG NIfTI 로드 → 청크 단위 스캔

nibabel로 SEG .nii.gz를 로드하고 Zarr에 쓰기 시작합니다. write_empty_chunks=False로 설정하면 각 청크를 쓰기 전에 전체가 fill_value(0)인지 확인합니다.

2

비영(非零) 복셀 포함 청크 → 디스크에 압축 저장

하나라도 레이블(>0)이 있는 청크는 파일로 저장됩니다. 예: c/2/3/1. 해당 청크는 내부의 배경(0) 복셀도 함께 압축 저장됩니다. blosc/zstd로 압축하면 0이 많은 청크는 압축률이 매우 높습니다.

3

순수 배경(0) 청크 → 파일 미생성 (암묵적 0)

모든 복셀이 0인 청크는 파일을 쓰지 않고 건너뜁니다. 디스크에 아무 파일도 없습니다. 이것이 SEG Sparse Zarr의 핵심입니다.

4

클라이언트가 빈 청크 요청 시

브라우저가 c/0/0/0 같은 빈 청크를 HTTP GET으로 요청하면 서버가 404를 반환합니다. Zarr 클라이언트 라이브러리는 이를 "해당 청크가 fill_value(0)로만 채워진 것"으로 해석하고 자동으로 0 배열을 반환합니다. 에러가 아닙니다.

5

결과: 전체 SEG 볼륨이 정확히 재현됨

실제 파일이 있는 청크 → 실제 레이블, 파일 없는 청크 → 0. 전체를 합치면 원본 SEG NIfTI와 동일한 데이터가 됩니다. 클라이언트는 차이를 모릅니다.

# Sparse Zarr SEG 생성 — write_empty_chunks=False 핵심
import zarr
import nibabel as nib
import numpy as np

# SEG NIfTI 로드
seg_img = nib.load('seg.nii.gz')
seg_data = seg_img.get_fdata().astype(np.uint8)

# ── Sparse Zarr 생성 ──────────────────────────────────
store = zarr.open('seg.nii.zarr', mode='w')
seg_arr = store.require_dataset(
    'seg',
    shape=seg_data.shape,          # (512, 512, 300)
    chunks=(64, 64, 64),           # 청크 크기
    dtype=np.uint8,
    fill_value=0,                  # 빈 청크 = 0으로 해석
    compressor=zarr.Blosc(
        cname='zstd', clevel=5,
        shuffle=zarr.Blosc.BITSHUFFLE  # 0 많은 SEG에 효과적
    )
)

# ★ 핵심: 빈 청크는 파일 저장 안 함
seg_arr.write_empty_chunks = False  # 또는 생성 시 config에서 설정
seg_arr[:] = seg_data                # SEG 청크만 파일 생성됨

# 결과 확인
import os
chunk_files = list(store.store.keys())
print(f"총 가능한 청크 수: {np.prod([s//c for s,c in zip(seg_data.shape,[64,64,64])])}")
print(f"실제 저장된 청크: {len([k for k in chunk_files if not k.endswith('.json')])}")
# 총 가능한 청크 수: 256  →  실제 저장된 청크: 7 (SEG 있는 것만)

05 · BBox Pre-Analysis

SEG BBox 사전 분석으로 변환 가속

"SEG가 있는 곳을 알고 있다면"이라는 전제가 추가된 경우, 변환 전에 바운딩 박스를 먼저 계산해 더 효율적으로 처리할 수 있습니다. 전체 볼륨을 순회하지 않고 SEG 존재 구간만 청크 변환합니다.

🔍

방법 A: BBox 사전 계산

SEG NIfTI 전체를 스캔해 비영 복셀의 min/max 좌표를 구하고, 해당 청크 범위만 Zarr로 변환합니다. 나머지 청크는 아예 접근하지 않습니다.

⚡

방법 B: write_empty_chunks=False

BBox 분석 없이 그냥 전체를 씁니다. Zarr가 자동으로 빈 청크를 건너뜁니다. 구현이 단순하고, 대용량에서도 쓰기 오버헤드가 낮습니다.

🎯

방법 C: Lazy/On-demand 변환

AI 서버가 SEG를 생성하는 즉시 레이블별 BBox를 반환 → 웹 뷰어 요청 시 해당 청크만 실시간 변환·캐싱합니다.

# 방법 A: BBox 사전 분석 → 청크 범위만 변환
import numpy as np

def get_seg_chunk_range(seg_data: np.ndarray, chunk_size: int = 64):
    """SEG 데이터가 있는 청크 좌표 범위를 반환"""
    nonzero = np.nonzero(seg_data)  # 비영 복셀 좌표
    if len(nonzero[0]) == 0:
        return None  # 레이블 없음

    min_z, max_z = nonzero[2].min(), nonzero[2].max()
    min_y, max_y = nonzero[1].min(), nonzero[1].max()
    min_x, max_x = nonzero[0].min(), nonzero[0].max()

    # 청크 좌표로 변환 (청크 경계로 확장)
    return {
        'z': (int(min_z // chunk_size), int(max_z // chunk_size) + 1),
        'y': (int(min_y // chunk_size), int(max_y // chunk_size) + 1),
        'x': (int(min_x // chunk_size), int(max_x // chunk_size) + 1),
    }

chunk_range = get_seg_chunk_range(seg_data)
# {'z': (2, 5), 'y': (3, 5), 'x': (3, 6)} → 2×2×3 = 12개 청크만 변환

# BBox 범위 슬라이스만 Zarr에 쓰기
if chunk_range:
    z0, z1 = chunk_range['z']
    y0, y1 = chunk_range['y']
    x0, x1 = chunk_range['x']
    for zi in range(z0, z1):
        for yi in range(y0, y1):
            for xi in range(x0, x1):
                sl = (
                    slice(xi*64, (xi+1)*64),
                    slice(yi*64, (yi+1)*64),
                    slice(zi*64, (zi+1)*64)
                )
                chunk = seg_data[sl]
                if chunk.any():      # SEG 있는 청크만
                    seg_arr[sl] = chunk  # 파일 생성

⚡ BBox 사전 분석(방법 A)은 변환 시간을 추가로 90%+ 단축할 수 있습니다. SEG가 볼륨의 5%에 있다면 전체 스캔 대신 해당 청크만 접근해 쓰기 IO를 최소화합니다. AI 파이프라인에서 이미 레이블 BBox를 알고 있다면 별도 스캔 없이 바로 활용하세요.

06 · Storage & Performance

스토리지 절감 & 성능 비교

항목	SEG .nii.gz (기존)	SEG 전체 Zarr	SEG Sparse Zarr (SEG 영역만)
파일 크기 / 용량	~30 MB (gzip 압축)	~600 MB (Int16, 64³ 청크)	~16 MB (SEG 청크만)
첫 렌더 대기 시간	30 MB 전체 수신 후 (~5초)	해당 청크 즉시 (~수백ms)	해당 청크 즉시
현재 슬라이스 fetch	전체 gzip 해제 필요	해당 청크 4~8개 fetch	SEG 청크만 fetch 빈 슬라이스=0 즉시 반환
변환 시간	불필요	~30초 (전체 볼륨)	~3초 (BBox 분석 포함)
파일 수	1개	256개 (8×8×4)	7~15개 (SEG 청크만)
Base 볼륨 변경	없음	없음	없음 (완전 분리)
구현 복잡도	낮음	중간	중간+ (커스텀 로더 필요)

* 512×512×300 볼륨, 종양 SEG (~3% 비영 복셀), 64×64×64 청크 기준 추정치

07 · Issues

예상 문제점 & 대응 전략

1

청크 경계 레이블 잘림 (Boundary Clipping)

SEG 레이블이 청크 경계에 걸쳐 있을 때 — 64번째 복셀에 레이블이 있고 65번째는 없는 경우 — 두 개의 인접 청크에 데이터가 나뉘어 저장됩니다. 이 자체는 문제가 아니지만, 클라이언트에서 청크를 조합할 때 경계 처리를 정확히 해야 렌더링 이음새 아티팩트가 없습니다.

대응: Zarr 클라이언트 라이브러리(zarrita 등)가 자동으로 인접 청크를 이어붙입니다. 슬라이스 단위로 요청 시 필요한 청크가 자동 결정됩니다.

2

빈 청크 404 에러 처리 — 클라이언트 구현 의존

커스텀 Zarr ImageLoader를 직접 구현할 경우, 빈 청크의 HTTP 404를 "에러"가 아닌 "정상 응답(fill_value)"으로 처리하는 로직을 명시적으로 구현해야 합니다. zarrita, zarr-js 같은 라이브러리는 이를 자동 처리하지만, 직접 fetch로 구현한다면 놓치기 쉬운 함정입니다.

대응: 반드시 검증된 Zarr 클라이언트 라이브러리를 사용하거나, 404 → 0-filled 배열 반환 로직을 명시적으로 테스트합니다.

3

Base + SEG 좌표 정렬 (Alignment)

Base .nii.gz와 SEG .nii.zarr의 복셀 격자가 정확히 일치해야 합니다. 동일한 origin, spacing, direction이어야 오버레이가 맞습니다. AI 파이프라인에서 생성된 SEG가 Base와 다른 해상도나 크기라면 리샘플링이 필요합니다.

대응: Zarr 변환 전 nibabel로 affine 행렬을 비교해 일치를 검증합니다. zarr.json에 NIfTI affine 정보를 저장하고, 클라이언트에서 로드 시 Base와 비교·검증합니다.

4

파셀레이션처럼 전체를 채우는 SEG는 이점 감소

FreeSurfer 뇌 파셀레이션처럼 전체 볼륨의 50~70%에 레이블이 있는 경우 빈 청크 비율이 낮아 Sparse 효과가 줄어듭니다. 이 경우 모든 청크가 저장되어 전체 Zarr와 차이가 없습니다.

대응: 변환 전 비영 복셀 비율을 계산해 30% 미만일 때만 Sparse Zarr를 선택하고, 그 이상이면 일반 Zarr 또는 .nii.gz를 유지합니다.

5

CORS + 두 서버 소스 혼용

Base는 REST API로, SEG는 정적 서버(S3)로 서빙한다면 두 개의 서로 다른 origin에서 데이터를 가져와야 합니다. 각각 CORS 설정이 필요하고, 네트워크 경로가 다르면 레이턴시가 달라 두 레이어의 로딩 완료 시점이 불일치합니다.

대응: Base와 SEG를 동일한 도메인으로 서빙하거나, 프록시 레이어를 두어 단일 origin으로 통일합니다. 로딩 중에는 Base만 먼저 표시하고 SEG가 로드되면 오버레이를 추가하는 점진적 표시를 구현합니다.

08 · Client Implementation

웹 뷰어 통합 — 커스텀 SEG Zarr 로더

// seg-zarr-loader.ts — SEG Sparse Zarr 커스텀 ImageLoader
import { imageLoader, metaData } from '@cornerstonejs/core';
import * as zarr from 'zarrita';

interface SegZarrMeta {
  store: zarr.Array;
  shape: number[];
  chunkSize: number;
  affine: number[][];  // NIfTI sform으로부터
}

const segStores = new Map<string, SegZarrMeta>();

// 1. Zarr 메타데이터 초기화
export async function initSegZarr(zarrUrl: string) {
  const fetchStore = new zarr.FetchStore(zarrUrl);
  const arr = await zarr.open(fetchStore.resolve('seg'), { kind: 'array' });
  const attrs = await zarr.getAttributes(fetchStore.resolve('seg'));

  segStores.set(zarrUrl, {
    store: arr,
    shape: arr.shape,
    chunkSize: arr.chunks[0],  // 64
    affine: attrs.nifti_header?.affine,
  });
  return arr.shape[2];  // 슬라이스 수 반환
}

// 2. 슬라이스 단위 SEG ImageLoader
function segZarrLoader(imageId: string) {
  // imageId: 'seg-zarr://http://server/seg.nii.zarr#150'
  const [url, sliceStr] = imageId.replace('seg-zarr://', '').split('#');
  const sliceIdx = parseInt(sliceStr);
  const meta = segStores.get(url);

  const promise = (async () => {
    // Zarr에서 해당 슬라이스 fetch
    // 빈 청크(SEG 없음) → zarrita가 자동으로 0 배열 반환 (404 처리 내장)
    const sliceData = await zarr.get(meta.store, [null, null, sliceIdx]);

    return {
      imageId,
      rows: sliceData.shape[0],
      columns: sliceData.shape[1],
      columnPixelSpacing: 1,
      rowPixelSpacing: 1,
      color: false,
      minPixelValue: 0,
      maxPixelValue: 255,
      // Uint8 SEG 데이터
      getPixelData: () => new Uint8Array(sliceData.data.buffer),
    };
  })();

  return { promise };
}

// 3. Cornerstone3D에 등록
imageLoader.registerImageLoader('seg-zarr', segZarrLoader);

// ── 사용 예시 ──────────────────────────────────────
const sliceCount = await initSegZarr('http://server/seg.nii.zarr');

// SEG imageId 배열 생성
const segImageIds = Array.from({ length: sliceCount }, (_, i) =>
  `seg-zarr://http://server/seg.nii.zarr#${i}`
);

// SEG Viewport에 로드 (Stack or Volume)
viewport.setStack(segImageIds);

09 · Conclusion

결론 — 이 전략은 언제 쓰고, 언제 피해야 하나

✅

이 전략이 효과적인 경우

• 병변 SEG — 종양, 결절, 경색 등 (전체 대비 <30%)
• 혈관 SEG — 선형 구조, 희소
• AI 모델이 SEG BBox를 함께 출력하는 파이프라인
• Base 볼륨은 그대로 두고 SEG만 빠르게 로드하고 싶을 때
• S3/CDN에서 정적 서빙 가능한 환경

⚠️

피해야 하거나 한계인 경우

• 파셀레이션 SEG — 전체 채움 (Sparse 이점 없음)
• 커스텀 Zarr 로더 없이 CS3D 기본 사용 시
• CORS 설정 불가능한 환경
• Base와 SEG 해상도·좌표계가 다른 경우
• 실시간 SEG 업데이트가 빈번한 경우 (캐시 무효화 복잡)

🧭 이 전략의 핵심 가치는 "Base를 건드리지 않고 SEG만 최적화"한다는 점입니다. 기존 .nii.gz 서빙 파이프라인을 유지하면서, SEG만 Sparse Zarr로 교체해 초기 로딩 속도와 메모리를 동시에 개선할 수 있습니다. 특히 AI 추론 결과 SEG를 웹 뷰어에서 즉시 오버레이해야 하는 시나리오에 적합합니다.

체크포인트	상태	비고
기술적 타당성	검증됨	Zarr write_empty_chunks=False 네이티브 지원
Base 볼륨 영향	없음	완전히 분리된 파이프라인
스토리지 절감	~95%	병변 SEG 기준 (희소도 높을수록 효과 큼)
CS3D 공식 지원	없음	커스텀 ImageLoader 구현 필요
구현 난이도	중간	zarrita + 커스텀 로더 약 200줄
파셀레이션 SEG 적합성	낮음	비영 비율 높으면 이점 감소
프로덕션 안정성	검증 필요	404→0 처리, 청크 경계 검증 필수

참고: Zarr write_empty_chunks · NIfTI-Zarr 스펙 · Zarr 공식 문서

2026 · NIfTI Viewer 프로젝트 — SEG 선택적 Sparse Zarr 기술검토