AI 튜토리얼

WonderSnap으로 GPU 파티클 모델 구축 및 제어

이 튜토리얼에서는 WonderSnap을 설치하고 로컬에서 실행하는 방법, 제스처나 키보드 입력으로 인터랙티브 파티클 모델을 제어하는 방법, 성능 설정을 조정하는 방법, 고급 교육 기능을 살펴보는 방법, Playwright 테스트 스위트를 실행하는 방법을 설명합니다.

2026년 9월 29일약 12분 소요

WonderSnap이란?

WonderSnap은 절차적으로 생성된 모델을 최대 250,000개의 GPU 기반 파티클로 이루어진 빛나는 구름으로 바꾸는 브라우저 기반 3D 경험입니다. 손가락을 튕겨 파티클을 불러오고, 이를 랜드마크나 해부학적 구조로 구성하며, 손으로 모델을 회전하고, 조립체를 라벨이 표시된 분해도로 펼칠 수 있습니다.

이 애플리케이션은 온디바이스 손 추적, 사용자 지정 제스처 인식, 절차적 모델, 직접 작성한 WebGL2 렌더러를 결합합니다. Three.js, 게임 엔진 또는 프론트엔드 프레임워크를 사용하지 않습니다. 웹캠 영상은 사용자의 기기에 남아 있으며 서버로 전송되지 않습니다.

웹캠은 선택 사항입니다. 모든 필수 상호작용은 화면 컨트롤, 키보드, 마우스로도 이용할 수 있습니다.

주요 기능

GPU 파티클 렌더링: 파티클 물리는 WebGL2 변환 피드백을 통해 실행되며 최대 250,000개의 파티클을 지원합니다.
온디바이스 손 추적: MediaPipe Hand Landmarker가 손당 21개의 랜드마크로 최대 두 손을 추적합니다.
제스처 인식: 사용자 지정 분류기가 손가락 튕기기, 주먹, 펼친 손, 가리키기, 집기, 브이 사인, 손 회전, 양손 확대·축소를 인식합니다.
33개의 절차적 모델: 컬렉션에는 랜드마크, 해부학, 생물학, 엔진, 차량, 기계 모델이 포함되어 있습니다.
인터랙티브 부품: 이름이 지정된 구성 요소를 빛나게 하고, 분해도로 분리하고, 라벨을 표시하며, 자세히 살펴보도록 꺼낼 수 있습니다.
애니메이션 해부학: 심장은 분당 72회 박동하고, 폐는 4.5초 주기로 호흡합니다.
교육 도구: 퀴즈 모드에서는 부품을 식별하도록 질문하며, 설명 및 음성 기능으로 부품을 안내합니다.
음성 제어: Chrome과 Edge에서 show me the heart, zoom in, quiz와 같은 명령을 처리할 수 있습니다.
절개 보기 및 녹화: 빛나는 단면을 표시하고 장면을 WebM 동영상으로 저장할 수 있습니다.

요구 사항

WonderSnap을 설치하기 전에 다음 항목을 준비하세요:

Node.js 18 이상.
문서에 안내된 브라우저 환경을 위한 Chrome 또는 Edge.
제스처 컨트롤을 사용하려면 웹캠.
WebGL2를 지원하는 브라우저와 기기.

카메라는 localhost 또는 HTTPS 주소에서만 액세스할 수 있습니다. index.html을 두 번 클릭해 애플리케이션을 실행하지 말고, 포함된 로컬 서버를 사용하세요.

WonderSnap 설치 및 시작

1. 저장소 복제

git clone https://github.com/AkbarSheikh-debug/wondersnap.git
cd wondersnap

2. 종속성 설치

npm install

이 단계에서는 손 추적 런타임도 node_modules에서 사용할 수 있도록 준비합니다. MediaPipe가 로드되지 않으면 설치가 성공적으로 완료되었는지 확인하세요.

3. 로컬 서버 시작

npm start

Chrome 또는 Edge에서 http://localhost:5173을 여세요. 손 추적을 활성화하려면 카메라로 시작을 선택하고, 마우스, 키보드, 화면 컨트롤을 사용하려면 카메라 없이 계속을 선택하세요.

4. 필요한 경우 다른 포트 사용

포트 5173이 이미 사용 중이면 시작 명령에 다른 포트를 전달하세요:

npm start -- 8080

그런 다음 http://localhost:8080을 열 수 있습니다.

기본 제스처 워크플로

카메라 액세스를 허용한 후 웹캠이 손을 선명하게 볼 수 있는 위치에 손을 놓으세요. 일반적인 상호작용 순서는 다음과 같습니다:

손가락을 튕겨 파티클을 불러옵니다. 다시 튕기면 현재 모델이 녹아 사라집니다.
주먹을 쥐어 선택한 경이로운 대상, 장기, 차량, 엔진 또는 기계를 구성합니다.
손을 들고, 비틀거나 기울여 구성된 모델을 회전하고 기울입니다.
손을 펼쳐 경이로운 대상을 다음 모델로 이동합니다. 장기, 엔진, 차량의 경우 손을 펼치는 정도에 따라 부품이 바깥으로 얼마나 분해되어 펼쳐질지 조절되며, 손을 오므리면 다시 합쳐집니다.
부품을 가리키고 손가락을 그 위에 대고 있으면 선택됩니다. 부품이 빛나고 정보 카드에 해당 부품의 역할이 표시됩니다.
집기 동작으로 선택한 부품을 자신 쪽으로 당깁니다. 다시 집으면 원래 위치로 돌아갑니다.
양손을 사용해 두 손 사이의 거리를 바꾸면 확대하거나 축소할 수 있습니다.
브이 사인을 만들어 다음 모델로 이동합니다.

키보드와 마우스 사용

웹캠이 없거나 더 정밀하게 제어하려면 키보드와 마우스를 사용하세요. 부품을 클릭해 선택하고 장면을 드래그해 회전할 수 있습니다.

Space: 손가락 튕기기를 시뮬레이션합니다.
F, O, V: 주먹, 편 손, 브이 사인 동작을 실행합니다.
Left Arrow 및 Right Arrow: 이전 또는 다음 모델을 선택합니다.
E, Up Arrow, Down Arrow 또는 마우스 휠: 분해도 조정합니다.
+, -, 0: 확대/축소를 변경하거나 초기화합니다. Control 키와 마우스 휠을 함께 사용할 수도 있습니다.
C: 카메라를 켜거나 끕니다.
L: 부품 레이블을 표시하거나 숨깁니다.
R: 자동 회전을 켜거나 끕니다.
G: 손을 이용한 회전을 활성화하거나 비활성화합니다.
X: 절단 단면을 활성화합니다. , 및 .을 사용하여 절단면을 조금씩 이동합니다.
Q: 퀴즈 모드를 시작합니다.
M: 음성 명령 및 음성 읽기 기능을 사용합니다.
K: 동영상을 녹화합니다.
D: 내장 데모를 재생합니다.
I: 선택한 부품을 설명합니다.
Esc: 현재 부품의 선택을 해제합니다.
H: 도움말을 표시합니다.

모델 컬렉션 탐색

WonderSnap에는 실제 측정값을 바탕으로 제작된 절차적 모델 33개가 6개 그룹으로 구성되어 있습니다.

경이로운 건축물: 에펠탑, 기자의 대피라미드, 타지마할, 빅벤, 시드니 오페라 하우스를 포함한 랜드마크 11개입니다.
해부학: 뇌, 박동하는 심장, 호흡하는 폐, 골격, 층별로 표현된 인체를 포함한 모델 10개입니다.
생물학: 지퍼처럼 풀 수 있는 DNA 이중 나선과 동물 세포입니다.
엔진: 직렬 4기통, 슈퍼차지 HEMI V8, 터보팬 제트, 9기통 성형 엔진입니다.
탈것: 스포츠카, 오토바이, 여객기, 단 분리가 구현된 새턴 V입니다.
기계: 기계식 손목시계와 셀, 버스바, 냉각 장치, 배터리 관리 시스템이 포함된 전기차 배터리 팩입니다.

교육 기능 사용

레이블이 지정된 부품 검사

구성 요소를 가리키거나 클릭하여 선택합니다. 선택한 부품이 빛나고 해당 카드에 기능이 설명됩니다. L로 레이블을 활성화하면 이름과 개별 부품을 연결하는 지시선이 표시됩니다.

퀴즈 시작

Q를 눌러 퀴즈 모드로 들어갑니다. WonderSnap은 찾기: 해마와 같은 문제를 제시합니다. 요청된 구성 요소를 가리키거나 클릭합니다. 퀴즈는 5개의 문제로 구성되며 점수가 표시됩니다.

음성으로 장면 제어

M을 눌러 음성 명령과 음성 읽기 기능에 접근합니다. 지원되는 예로는 심장을 보여 줘, 열어 줘, 오른쪽 심방은 어디야, 확대해, 퀴즈가 있습니다. 음성 합성은 Chrome 및 Edge에서 지원됩니다.

단면 만들기

X를 눌러 절단면 보기를 활성화합니다. 절단면이 손을 따라 움직이며 빛나는 단면을 보여 줍니다. 제스처 입력을 사용하지 않을 때는 , 및 .으로 절단면을 조금씩 이동합니다.

결과 녹화

K를 눌러 장면을 녹화하고 WebM 동영상으로 저장합니다.

URL 옵션으로 WonderSnap 구성

쿼리 문자열 옵션을 사용하면 소스 파일을 수정하지 않고 시작 동작을 변경하고 렌더링을 조정할 수 있습니다.

?n=250000: 입자 수를 설정합니다.
?model=12: 지정한 모델 번호로 시작합니다.
?autostart=camera: 시작 화면을 건너뛰고 카메라 모드를 요청합니다.
?autostart=nocamera: 시작 화면을 건너뛰고 카메라 없이 실행합니다.
?trails=0: 입자 잔상을 비활성화합니다.
?dpr=1: 기기 픽셀 비율을 1로 고정합니다. 성능이 낮은 GPU에서 도움이 될 수 있습니다.

옵션은 조합하여 사용할 수 있습니다. 예를 들어 다음 주소는 카메라 없이 시작하고, 입자 100,000개를 사용하며, 기기 픽셀 비율을 1로 고정하고, 잔상을 비활성화합니다.

http://localhost:5173/?autostart=nocamera&n=100000&dpr=1&trails=0

고급 팁

성능이 낮은 하드웨어에서 성능 향상

입자 수와 기기 픽셀 비율은 렌더링 부하에 직접적인 영향을 줍니다. README에서 권장하는 낮은 프레임 속도 설정으로 시작하세요.

http://localhost:5173/?n=100000&dpr=1

필요한 경우 trails=0도 추가하여 입자 잔상을 끕니다.

일관된 시작 링크 사용

데모나 반복 가능한 테스트에서는 model을 autostart 모드와 함께 사용하세요. 그러면 매번 시작 화면과 모델 목록을 수동으로 탐색할 필요가 없습니다.

애플리케이션 아키텍처 이해

기본 렌더링 루프, 피킹, 확대/축소, 분해도, 레이블, 퀴즈, 절단면, 데모 동작은 src/app.js에 있습니다. 웹캠과 MediaPipe 통합은 src/hands.js에 있으며, 음성 제어, 음성 읽기 지원, 녹화 기능은 src/features.js에 구현되어 있습니다.

src/gl/ 디렉터리에는 WebGL2 셰이더와 변환 피드백 렌더러가 있습니다. 제스처 로직, 상태 머신, 컨트롤러, 입자 물리의 CPU 구현은 src/logic/에 있습니다. 절차적 지오메트리 유틸리티는 src/lib/에 있고, 모델 정의는 src/models/에 그룹별로 구성되어 있습니다.

테스트 스위트 실행

WonderSnap에는 Playwright로 작성된 엔드투엔드 및 단위 테스트 36개가 포함되어 있습니다. 테스트는 합성 손과 결정론적 시계를 사용하여 실제 애플리케이션을 실행합니다.

Playwright의 Chromium 브라우저를 한 번 설치합니다.

npx playwright install chromium

그런 다음 테스트를 실행합니다.

npm test

이 제품군은 전체 제스처 흐름, 모든 모델, 분해도, 키보드 및 휠 조작, 반응형 레이아웃, 심장 박동 및 호흡 애니메이션, 양손 확대/축소, 부품 선택, 핀치 상호작용, 퀴즈, 음성 명령, 절개 모드, 녹화, 카메라 대체 동작, 포즈 분류기, 상태 전환, 절차적 모델의 유효성, GPU 물리를 모두 다룹니다. 또한 GPU 셰이더를 CPU 대응 구현과 비교하여 모든 모드에서 약 1e-7까지 검증합니다.

문제 해결

카메라가 시작되지 않습니다: index.html을 직접 여는 대신 http://localhost:5173을 통해 애플리케이션을 열고, 메시지가 표시되면 카메라 권한을 허용하세요.
손 추적이 로드되지 않습니다: npm install을 실행하세요. 추적 런타임은 node_modules에서 제공됩니다.
프레임 속도가 낮습니다: http://localhost:5173/?n=100000&dpr=1을 사용해 보세요.
포트 5173이 사용 중입니다: npm start -- 8080을 실행한 후 http://localhost:8080을 여세요.

결론

WonderSnap은 온디바이스 손 추적, 사용자 지정 제스처 분류기, 절차적 모델링, GPU 파티클 물리를 결합하여 브라우저에서 완전히 실행되는 대화형 교육 경험을 만드는 방법을 보여줍니다. 표준 로컬 설정으로 시작한 다음 스냅, 주먹, 손 펴기, 가리키기, 핀치 상호작용을 익히고 URL 조정, 음성 제어, 퀴즈, 단면 보기, 녹화, 자동화된 테스트 모음을 살펴보세요.