[Technical Specification] 웹 기반 노드 합성 엔진에서의 웹캠 실시간 캡처 및 DAG 파이프라인 연동 기술 사양서 & 사용법 가이드

Target System: NukeNode Studio (thesis.hyperbook.com 기술 논문 & 사양서)
Author: Antigravity AI Engineering Team
Date: 2026-08-11

1. 사용법 가이드 (User Operating Guide & UI Visuals)

NukeNode Studio에서 웹캠 카메라를 활용하여 사진을 촬영하고, 이를 비주얼 노드 그래프 파이프라인으로 연결하여 합성하는 단계별 과정입니다.

[Step 1] 웹캠 카메라 모달 실행 (Webcam Capture Modal)

• 상단 헤더의 Webcam 📷 버튼 또는 좌측 라이브러리(Media Bin) 탭의 Webcam Snap 버튼을 클릭합니다.
• 브라우저의 카메라 접근 권한 팝업에서 [허용]을 선택합니다.

[Step 2] 라이브 피드 확인 및 사진 촬영 (Snapshot & Node Injection)

1. 카메라 선택: 내장 웹캠 또는 외장 USB 카메라(Brio 4K 등) 선택.
2. 사진 촬영: [Take Snapshot 📷] 버튼을 클릭하여 원하는 순간의 프레임을 캡처합니다.
3. Read 노드로 추가: [Read 노드로 추가 (Add Node)] 버튼을 클릭하면 캡처된 사진이 Data URL 포맷으로 즉시 NukeNode 노드 그래프의 Read 노드로 등록됩니다.

[Step 3] 비주얼 노드 그래프 합성 (Visual DAG Node Compositing)

• 생성된 Read 이미지 노드를 Keyer (크로마키), ColorGrade, Merge 및 Viewer 노드와 와이어(Wire)로 연결합니다.
• 우측 상단 LIVE COMPOSITE PREVIEW 창을 통해 실시간 합성 결과를 확인합니다.

2. 추진 배경 (Background & Motivation)

2.1 웹 기반 비주얼 효과(VFX) 파이프라인의 부상

기존의 비주얼 컴포지팅(Visual Compositing) 소프트웨어(Foundry Nuke, Adobe After Effects, Blackmagic Fusion 등)는 무거운 데스크톱 런타임 환경에 의존해 왔습니다. 그러나 최근 WebGL 2.0, HTML5 Canvas 2D, Web Workers 및 WebGPU의 발전으로 웹 브라우저 상에서 실시간 렌더링 파이프라인을 구축하는 것이 가능해졌습니다.

2.2 소스 미디어 입출력 방식의 한계 극복

기존 웹 기반 합성 도구는 사용자가 미리 제작된 파일(PNG, MP4 등)을 업로드하는 방식에 국한되었습니다. 하지만 현장 VFX 검토, 증강현실(AR) 프리비주얼라이제이션(Pre-visualization), 사용자 맞춤형 크로마키(Chroma Key) 테스트에서는 사용자의 하드웨어 카메라(Webcam) 소스를 즉각적으로 데이터 파이프라인에 주입하는 기능이 필수적입니다.

2.3 기술적 목적

본 개발 과제는 WebRTC Media Devices API를 활용하여 웹캠의 비디오 스트림을 획득하고, 단일 프레임 스냅샷을 손실 없이 캡처한 후, 이를 노드 기반 아키텍처(DAG: Directed Acyclic Graph)의 Read 노드로 유기적으로 주입하는 경량화된 엔드투엔드 파이프라인을 설계 및 구현하는 것을 목적으로 합니다.

3. 시스템 아키텍처 및 작업 절차 (System Architecture & Procedures)

3.1 전체 데이터 흐름도 (Data Flow Architecture)

sequenceDiagram
    autonumber
    participant User as 사용자 (User)
    participant UI as Header / Media Bin UI
    participant Modal as WebcamModal Component
    participant WebRTC as navigator.mediaDevices
    participant Canvas as Offscreen Canvas Engine
    participant DAG as Node DAG State Manager (App.tsx)
    participant Renderer as canvasRenderer Engine

    User->>UI: [Webcam Snap] 버튼 클릭
    UI->>Modal: isOpen = true 트리거
    Modal->>WebRTC: getUserMedia({ video: true }) 권한 요청
    WebRTC-->>Modal: HTMLMediaElement MediaStream 전달
    Modal->>User: <video> 비디오 라이브 피드 노출
    User->>Modal: [사진 촬영 (Take Snapshot)] 클릭
    Modal->>Canvas: drawImage(video, 0, 0, width, height) 캡처
    Canvas-->>Modal: Base64 Data URL (image/png) 추출
    User->>Modal: [Read 노드로 추가] 클릭
    Modal->>DAG: handleAddNode('read', x, y, { mediaUrl: dataUrl })
    DAG->>Renderer: DAG 렌더링 그래프 재평가 요청
    Renderer-->>User: Live Preview 화면에 합성 결과 실시간 출력

3.2 단계별 처리 절차 (Step-by-Step Procedure)

1. 미디어 스트림 권한 획득 및 디바이스 캡처:
2. navigator.mediaDevices.getUserMedia() 표준 API를 호출하여 하드웨어 입출력 장치 연결.

3. 다중 카메라(내장 웹캠, USB 외장 카메라, 셀피 카메라 등) 입력을 지원하기 위해 enumerateDevices()로 장치 목록 획득.

4. 비디오 하드웨어 프레임 동기화:

5. <video autoplay playsinline muted> 요소에 스트림 바인딩.

6. 비디오 스트림의 원본 해상도(videoWidth, videoHeight) 정보를 추출하여 캡처 품질 보장.

7. 메모리 버퍼 기반 프레임 스냅샷 생성:

8. 오프스크린 HTML5 <canvas>를 동적으로 생성 후 ctx.drawImage()로 비디오 프레임 렌더링.

9. Canvas를 data:image/png;base64,... 포맷 데이터 스트림으로 직렬화.

10. DAG Node 주입 및 상태 갱신:

11. 추출된 Data URL을 파라미터로 갖는 NodeType: 'read' 객체 생성.
12. React 상태 트리(nodes, connections)에 갱신 주입하고 canvasRenderer.ts 파이프라인에 바인딩.

4. 상세 구현 방법 (Implementation Specifications)

4.1 WebRTC 미디어 디바이스 처리 모듈 (WebcamModal.tsx)

// 1. 카메라 스트림 획득 및 비디오 요소 연결
const startCamera = async (deviceId?: string) => {
  setIsInitializing(true);
  setError(null);
  stopCamera();

  try {
    const constraints: MediaStreamConstraints = {
      video: deviceId
        ? { deviceId: { exact: deviceId }, width: { ideal: 1280 }, height: { ideal: 720 } }
        : { width: { ideal: 1280 }, height: { ideal: 720 } },
    };

    const mediaStream = await navigator.mediaDevices.getUserMedia(constraints);
    setStream(mediaStream);

    if (videoRef.current) {
      videoRef.current.srcObject = mediaStream;
      await videoRef.current.play();
    }
  } catch (err: any) {
    handleCameraError(err);
  } finally {
    setIsInitializing(false);
  }
};

4.2 캔버스 프레임 캡처 및 Data URL 변환

// 2. 비디오 라이브 피드 프레임 캡처 엔진
const handleTakeSnapshot = () => {
  const video = videoRef.current;
  if (!video) return;

  const width = video.videoWidth || 1280;
  const height = video.videoHeight || 720;

  // Offscreen Canvas 생성
  const canvas = document.createElement('canvas');
  canvas.width = width;
  canvas.height = height;

  const ctx = canvas.getContext('2d');
  if (!ctx) return;

  // 비디오 프레임을 캔버스 프레임으로 사복사
  ctx.drawImage(video, 0, 0, width, height);

  // PNG 데이터 스냅샷 생성
  const dataUrl = canvas.toDataURL('image/png');
  setCapturedImage(dataUrl);
};

4.3 DAG 그래프 노드 동적 인젝션 (App.tsx)

// 3. 웹캠 이미지 데이터를 신규 Read 노드로 자동 바인딩
<WebcamModal
  isOpen={isWebcamOpen}
  onClose={() => setIsWebcamOpen(false)}
  onCapture={(dataUrl) => {
    handleAddNode('read', 220, 220, {
      mediaType: 'image',
      mediaUrl: dataUrl,
    });
  }}
/>

5. 성능 최적화 및 안정성 확보 전략

1. 메모리 누수 방지 (Stream Track Cleanup):

2. 모달 닫힘(onClose) 또는 컴포넌트 언마운트 시 stream.getTracks().forEach(track => track.stop())를 호출하여 브라우저 및 하드웨어 점유 자원을 즉시 해제.

3. CORS 및 크로스 오리진 렌더링 보안:

4. data:image/png;base64 인코딩 방식을 채택하여 외부 서버 요청 없이 브라우저 인메모리 상에서 직접 Canvas 2D 텍스처로 파싱.

5. 반응형 UI/UX 처리:

6. 모바일 및 데스크톱 환경 모두 지원하도록 Tailwind CSS Glassmorphism 기반 UI 설계.

6. 향후 발전 계획 (Future Roadmap & Expansion Plan)

timeline
    title 웹캠 기능 단계별 발전 로드맵
    Phase 1 (완료) : 웹캠 스틸 스냅샷 캡처 : Data URL 변환 : Read 이미지 노드 주입
    Phase 2 (차기 버전) : 라이브 스트림 노드 (Live Stream Node) : 실시간 웹캠 프레임 파이프라인 : 비디오 텍스처 인메모리 바인딩
    Phase 3 (연구 개발) : AI 배경 제거 (Background Removal) : Selfie Segmentation AI 통합 : 크로마키 없는 실시간 인물 누끼 캡처
    Phase 4 (고도화) : WebGPU & 3D 공간 캡처 : Depth Camera (DepthAPI) 연동 : 3D 멀티 레이어 컴포지팅 지원

6.1 [Phase 2] 실시간 비디오 라이브 스트림 노드 (Live Streaming Node)

• 목표: 단순 정지 스틸 사진 캡처를 넘어 웹캠의 MediaStream을 HTMLVideoElement로 직접 캐싱하고, canvasRenderer.ts 평가 루프(requestAnimationFrame)에서 매 프레임마다 실시간으로 캔버스 텍스처를 갱신하도록 확장.
• 기대 효과: 라이브 방송 및 실시간 비디오 합성(Live VFX Compositing) 가능.

6.2 [Phase 3] 웹캠 실시간 AI 배경 제거 (AI Portrait Segmentation)

• 목표: MediaPipe / WebGPU 기반의 Selfie Segmentation AI 모델을 도입하여 크로마키(초록색 배경)가 없어도 웹캠 화면에서 인물 배경을 실시간으로 분리.
• 기대 효과: 전문 장비 없는 일반 웹캠 환경에서도 클릭 한 번으로 고품질 합성 효과 획득.

6.3 [Phase 4] 뎁스 카메라(Depth Camera) 연동 및 3D 공간 합성

• 목표: LiDAR 및 Depth 센서 지원 장치(iPhone, Intel RealSense 등)의 뎁스 맵 데이터 채널을 NukeNode Studio의 Alpha/Z-Depth 채널과 결합.
• 기대 효과: 3D 공간 안에서의 깊이 기반 가상 레이어 합성(3D Spatial Compositing) 구현.

7. 결론 (Conclusion)

본 사양서에서 기술한 웹캠 카메라 캡처 및 DAG 파이프라인 주입 기술은 기존의 정적인 파일 업로드 한계를 극복하고, 사용자 하드웨어 입력 장치와 웹기반 비주얼 효과 엔진 간의 실시간 연동을 성공적으로 구현했습니다.

향후 추진할 라이브 스트림 노드 및 웹 기반 AI 인물 분리 기술과의 결합을 통해 thesis.hyperbook.com 플랫폼의 기술적 차별성과 웹기반 VFX 컴포지팅 분야에서의 확장성을 크게 극복할 것으로 기대됩니다.