Anatomy Three.js — 대화형 3D 기술 도해

Three.js + GLSL로 대화형 아이소메트릭 3D 기술 일러스트레이션을 구축합니다. 모든 도해는 기술적 아이디어를 책상 위에 놓을 수 있는 물리적 벤치탑 장비 또는 단면 시험 장치로 설명합니다: 두꺼운 경사진 베이스플레이트에 선반 다리, 도메인에 적합한 하우징과 링키지, 주된 내부 로터 또는 움직이는 피사체, 직접 드래그 가능한 3D 제어 장치와 해당 기계 전용으로 제작된 계측기, 그리고 기계 내부의 물리적 매체(불, 플라즈마, 유체, 다운워시, 빔)에만 엄격히 제한된 맞춤형 GLSL 셰이더로 구성됩니다.

1,500줄의 모놀리식 HTML 파일을 작성하고 머릿속으로 3D 좌표를 추측하는 대신, 먼저 사용자와 장치 및 상호작용 방식을 조율한 후(0단계), figures/<slug>/ 내에서 6개의 분리된 단계로 각 도해를 구축합니다. 불변의 kit/ 엔진을 기반으로 하며, 모든 단계는 2계층 3D 공간 + 직교 시각 검증 장치로 검증됩니다.

디렉터리 구조

anatomy-threejs/
├── SKILL.md                    # Stage 0 개요 + 6단계 워크플로우 & 에이전트 진입점
├── kit/                        # 불변 엔진 — 여기서 임포트하며, 도해별로 절대 수정하지 않음
│   ├── shaders.mjs             # 5개 테마, 4톤 + 상단 캡 셀 셰이더, 반전-실루엣, 주름선
│   ├── primitives.mjs          # 축 인식 슬래브, 실린더, 기어, 나사, 널링, 눈금
│   ├── registry.mjs            # Recorder3D: .group(), .part(), .anchor(), .tube(), .interactable(), .tag()
│   ├── audit3d.mjs             # 헤드리스 Node 3D 공간 감사 (충돌, 부유, 보어, 튜브)
│   ├── runtime.mjs             # 직교 리그, 레이캐스트 3D 드래그, 맞춤 제어, 스프링, __ANATOMY_DEBUG__
│   ├── bundle.mjs              # 도해 모듈을 단일 자체 포함 HTML 파일로 컴파일
│   └── shell.html              # 반응형 카드 크롬, 5개 테마 CSS 변수, 기능 인식 제어
├── scripts/
│   ├── inspect.mjs             # 헤드리스 Chrome (CDP) 2x2 직교 청사진 & 조인트 오버레이
│   ├── drive.mjs               # 대화형 연락처 시트 + 히어로 스틸 + 모바일 390px 확인
│   └── chrome-port.mjs         # 제로 종속성 WebSocket + 헤드리스 Chrome용 PNG 스티처
├── references/
│   ├── craft-3d.md             # 3D 좌표계, 톤 계층 구조, 맞춤 제어, 안티패턴
│   ├── kit-3d.md               # Recorder3D, 프리미티브, 셰이더, 런타임 API 참조
│   └── verify-3d.md            # [COLLISION], [FLOATING], [TUBE KINK] 및 직교 뷰 해석 및 수정 방법
└── figures/
    └── <slug>/                 # 도해 작업 공간 (예: figures/wankel-engine/)
        ├── model.mjs           # Stage 1: 순수 수학, 치수, SPEC.features, SPEC.controls, 앵커
        ├── base.mjs            # Stage 2: 베드플레이트, 발, 후광, 자, 황동 명판
        ├── structure.mjs       # Stage 3: 받침대, 프레임/하우징, 포트, 체결 부품
        ├── subject.mjs         # Stage 4: 움직이는 핵심 어셈블리 (로터, 블레이드, 씰, 기어)
        ├── mechanism.mjs       # Stage 5: 맞춤 제어, 계측기, 3D 상호작용 요소, 튜브, updateKinematics()
        ├── shader.mjs          # Stage 6: 활성 물리 매체로 제한된 맞춤형 GLSL 셰이더
        ├── build.mjs           # CLI 진입점: --test-model, --audit, 전체 HTML 번들
        └── dist/
            └── <slug>.html     # 컴파일된 자체 포함 대화형 도해

규칙 1 — kit/를 절대 다시 작성하지 않음: Three.js 카메라, 셀 셰이더, 레이캐스트 드래그 핸들러, 스프링 솔버, DOM 크롬, 디버그 장치는 kit/에 있습니다. 도해 파일은 도메인 수학, 3D 부품, 운동학, 상호작용 요소 및 맞춤 매체 셰이더만 정의합니다.

규칙 2 — 형상을 작성하기 전에 참조 문서를 읽을 것:

0/1단계 전에 references/craft-3d.md를 읽어 물리적 장치, 맞춤 제어, 기능 플래그, 톤 계층 및 3D 좌표 프레임을 설계합니다.

2단계 전에 references/kit-3d.md를 읽어 Recorder3D 및 kit/primitives.mjs의 정확한 시그니처를 확인합니다.

--audit, inspect.mjs, 또는 drive.mjs에서 문제가 보고될 때마다 references/verify-3d.md를 읽습니다.

0단계 — 장치 및 상호작용 개요 (구축 전 조율)

파일을 생성하거나 1단계 코드를 작성하기 전에 간결한 장치 및 상호작용 개요를 사용자에게 제안하고, 기계가 수행하는 작업과 사용자가 어떻게 조작하는지에 대해 조율합니다(사용자가 명시적으로 질문 없이 즉시 구축을 지시한 경우에만 대기 건너뜀):

벤치탑 장치 및 주인공 피사체: 물리적 메커니즘과 lit 강조를 받는 단일 어셈블리의 이름을 지정합니다.
직접 3D 조작 (reg.interactable): 읽기가 뷰포트에서 직접 잡고 드래그할 수 있는 3D 어셈블리 또는 컨트롤을 식별합니다(예: 스와시플레이트 드래그하여 기울이기/올리기, 로터 블레이드 피치 변경, 버니어 캐리지 슬라이딩, 링키지 레버 당기기). 회전/시뮬레이션이 일시 중지된 동안에도 포함합니다.
도메인 인증 제어 및 텔레메트리 (SPEC.controls): 이 기계에 속하는 벤치 하드웨어 및 컨트롤 바 슬라이더를 선택합니다(예: 2축 사이클릭 스틱, 컬렉티브 피치 쿼드런트, 각도기 호, 마이크로미터 드럼, 버니어 스케일, 마노미터 튜브). 다른 도해의 회전 노브, 부르동 압력 게이지 또는 유압 박스를 절대 복사하지 마십시오(해당 주제가 정확히 그 계측기를 사용하지 않는 한).
뷰 모드 (SPEC.features): 선택적 모드가 어떤 경우에 자리할지 명시적으로 결정합니다:
- explode: 오직 밀집된 동심 기계(예: 엔진, 기어박스, 펌프)에 대해 true로 설정합니다. 열린 기계적 링키지, 스와시플레이트, 광학 벤치 또는 부품 분리가 링키지 형상을 깨고 복잡성을 추가하는 표면 장치에 대해서는 explode: false로 설정합니다.
- cutaway: 외부 케이싱이 내부 움직이는 부품을 가릴 때 true로 설정합니다. 오픈 프레임 메커니즘의 경우 false로 설정합니다.
- shader: 제한된 물리적 매체(연소 가스, 로터 후류, 빔, 유체 흐름)가 메커니즘을 명확히 할 때 true로 설정합니다.

0단계 관문: 사용자가 개요를 확인하거나 수정합니다(또는 명시적으로 즉시 비대화형 구축을 지시합니다).

6단계 워크플로우

다음 단계를 순서대로 실행합니다. 각 단계는 검증 관문으로 끝납니다 — 명령을 실행하고, 오류를 수정한 후, 파일 읽기 도구로 렌더링된 PNG를 시각적으로 검사한 후 다음 단계로 진행합니다.

1단계 — 모델 및 운동학 (`model.mjs` + `build.mjs`)

Three.js를 다루기 전에 합의된 개요를 순수 물리 수학 모듈로 변환합니다:

figures/<slug>/model.mjs에 물리적 은유를 인코딩합니다:
- SPEC.features: 0단계와 일치하는 { explode: boolean, cutaway: boolean, shader: boolean, crank: boolean }.
- SPEC.interactionHint: 왼쪽 하단에 표시되는 짧은 힌트로, 사용자가 어떤 3D 부품을 직접 드래그할 수 있는지 알려줍니다(예: "스와시플레이트, 스틱 또는 컬렉티브 레버 드래그").
- SPEC.controls: 도메인별 슬라이더 컨트롤 배열({ id, label, min, max, step, initial, title }). runtime.mjs는 이를 컨트롤 바에 렌더링하고, 스프링으로 부드럽게 처리하며, updateKinematics 및 formatReadout에 전달합니다.
- SPEC.auditPoses 및 SPEC.drivePoses: 도메인 대표 자세(극단적인 제어 각도, 일시 정지된 조작, 단면도/테마 확인)는 --audit 및 scripts/drive.mjs에서 사용됩니다. features.explode === false인 경우 분해 자세는 생략합니다.
- SPEC: 모든 중요한 치수(BASE_W, BASE_D, BASE_H, BASE_Y, topSurfaceY, isoElevDeg: 30, isoAzimDeg: -36, initialZoom, initialPanY, minVertSpan, minHorizSpan).
- ANCHORS: 베드플레이트의 명명된 [x, y, z] 장착 좌표(plaqueCenter, rulerCenter 및 도해의 맞춤 제어/계측기 앵커). 표준 아이소메트릭(30° 고도, -36° 방위각)에서 +Z 모서리는 전면 앞치마이고 -X, +Z / +X, +Z는 방해 없는 전면 모서리임을 기억하십시오.
- 순수 상태 및 운동학 함수(Three.js 임포트 없음)는 theta 및 SPEC.controls의 라이브 params에 의해 구동됩니다.
- 텔레메트리 바의 { readout, phase } 문자열을 반환하는 formatReadout({ theta, effectiveRpm, params }).
figures/<slug>/build.mjs를 스캐폴드하고(figures/wankel-engine/build.mjs 또는 figures/helicopter-swashplate/build.mjs 참조), 제목, 부제목, 초기 읽기값 및 범례를 조정합니다.

1단계 관문:

node figures/<slug>/build.mjs --test-model

통과 기준: 전체 $0 \dots 6\pi$ 주기에 걸쳐 모든 앵커가 유한하고 읽기값/상태가 확인되어 종료 코드 0.

2단계 — 베이스 (`base.mjs`)

전체 계기를 접지하는 무거운 기준 베드플레이트를 구축합니다:

base.group (stage: "base")를 만듭니다.
BASE_Y - 0.24에 부드러운 바닥 그림자(makeHaloMesh)를 추가합니다.
buildSlabGeometry(BASE_W, BASE_D, BASE_H, { radius: 0.26, bevel: true, bevelSize: 0.025, bevelThickness: 0.025 })를 사용하여 base.plate를 추가합니다. ramp: "lo", mountOn: "ground"로 설정합니다. topSurfaceY = BASE_Y + BASE_H + 0.025는 상단 베벨 두께를 설명하므로 topSurfaceY에 장착된 부품이 상단 면에 플러시하게 안착되며 가라앉지 않습니다.
reg.anchor(id, x, y, z, baseGroup)을 통해 모든 베드플레이트 장착 앵커를 등록하여 3단계와 5단계가 base.plate에 직접 스냅되도록 합니다.
내장 주변 홈(makePlanOutline), 4개의 선반 다리(base.foot.collar.i + base.foot.pad.i)와 상단 카운터보어 나사(makeScrewDetail), 눈금자(base.ruler + makeRulerTicks), 그리고 보이는 전면 앞치마(+Z)에 리벳으로 고정된 brass 사양 명판(base.plaque)과 각인된 태그(reg.tag("tag-plate", ...))를 추가합니다.

2단계 관문:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base --ortho --out figures/<slug>/dist/inspect-base.png

inspect-base.png를 읽어 다리가 베드플레이트 아래에 깔끔하게 위치하고 황동 명판과 눈금자가 전면 앞치마에서 방해받지 않는지 확인합니다.

3단계 — 구조 (`structure.mjs`)

고정 하중 지지대, 메인 프레임 또는 단면 하우징, 포트/매니폴드 및 체결 부품을 구축합니다:

베이스 플레이트 위에 지지 받침대 또는 기어박스를 플랜지 베이스, 볼트 디테일, 테이퍼진 기둥 및 베어링 새들을 사용하여 장착합니다.
메인 하우징 또는 프레임을 구축합니다(ramp: "mid", outline: "hi"). 전면(+Z)을 열어두거나 단면 덮개(cutawayHide: true)를 장착하여 features.cutaway가 활성화된 경우 표준 아이소메트릭 카메라에서 내부 메커니즘이 완전히 보이도록 합니다.
도메인 인증 포트, 액추에이터 하우징 또는 고정 브래킷을 깔끔하게 바깥쪽으로 향하게 추가합니다. 각 로컬 하위 그룹 내에 로컬 바깥쪽 포트 법선과 함께 3D 포트/터미널 앵커를 등록합니다(reg.anchor("plug.leading.tip", 0, 0.68, 0, spGroup, { dir: [0, 1, 0] })). 이렇게 하면 5단계의 튜브가 정확한 월드 위치에 스냅되고 동축으로 진입/출구됩니다.
SPEC.features.explode가 true이고 장치가 축 방향으로 분리되어야 하는 밀집된 동심 레이어를 가진 경우에만 분리 가능한 하위 그룹에 대해 explode: [ex, ey, ez] 벡터를 설정합니다.

3단계 관문:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure --ortho --out figures/<slug>/dist/inspect-structure.png

inspect-structure.png를 읽습니다(TOP, FRONT, RIGHT, CANONICAL ISO): 포트가 바깥쪽을 향하고, 받침대가 클리핑 없이 베드플레이트와 하우징 모두에 닿으며, 아무것도 떠 있지 않은지 확인합니다.

4단계 — 주제 (`subject.mjs`)

시각적 초점을 지휘하는 주인공 내부 어셈블리를 구축합니다:

주요 움직이는 몸체(예: 로터 바디, 허브 요크)에는 ramp: "hi"를, 활성 작업 요소(rotor.apexSeal.i, blade.airfoil.*)에는 ramp: "lit"을, 정밀 기어 및 피벗에는 ramp: "brass"를 할당합니다.
중첩된 운동학 그룹(orbit -> spin 또는 azimuth -> flap -> pitch)을 만들어 계층적 움직임이 오일러 짐벌 잠금 없이 깔끔하게 구성되도록 합니다.
보어 내부에서 움직이는 부품에 insideBoreOf 및 boreClearanceFn을 전달하여 audit3d.mjs가 감사된 모든 자세에서 벽 관통이 0임을 수학적으로 검증하도록 합니다.
가공된 포켓, 면 홈, 스파 이음새 또는 볼트 패턴을 추가하여 움직임이 명확히 인식되도록 합니다.

4단계 관문:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate subject --ortho --out figures/<slug>/dist/inspect-subject.png

inspect-subject.png를 읽어 피사체의 실루엣, 베벨 및 조인트가 모든 각도에서 명확하게 읽히는지 확인합니다.

5단계 — 메커니즘, 맞춤 제어 및 직접 3D 상호작용 (`mechanism.mjs`)

주제를 도메인 인증 운영자 제어 장치, 텔레메트리 계측기, 직접 3D 드래그 상호작용 및 라우팅에 연결합니다:

0/1단계의 ANCHORS에 도메인 인증 제어 장치를 구축합니다(예: 2축 짐벌 사이클릭 스틱, 노치형 컬렉티브 피치 쿼드런트 레버, 버니어 리드스크류, 널링 스로틀 드럼). 기계가 자체 제어 하드웨어를 요구할 때 다른 도해의 널링 노브나 매니폴드 블록을 절대 복사하지 마십시오.
도메인 인증 텔레메트리를 구축합니다(예: 곡선 블레이드 피치 각도기 호, 선형 이동 스케일, 마노미터 컬럼, 다이얼 게이지). +Z 방향으로 앞쪽에 위치시키거나 CANONICAL ISO에서 주요 실루엣에서 벗어나게 배치합니다.
주요 메커니즘 및/또는 물리적 레버에 대해 reg.interactable(targetId, { cursor, hint, onDrag })로 직접 3D 조작을 등록하여 사용자가 setParam(...)을 통해 뷰포트에서 직접 3D 부품을 드래그할 수 있도록 합니다(회전이 일시 중지된 경우 RPM = 0 또는 PAUSED에도 가능).
reg.tube(id, fromAnchorId, waypoints, toAnchorId, opts)를 사용하여 모든 파이프 및 케이블을 라우팅합니다:
- 부드러운 3D 아치 웨이포인트를 구축하기 위해 reg.getAnchorWorldPos(anchorId) 및 reg.getAnchorWorldDir(anchorId)를 쿼리합니다(length / chord >= 1.12). 인접 부품을 피해 스윕하고 각 포트의 바깥쪽 법선을 따라 동축으로 진입하도록 합니다.
구동 트레인 및 관절 링키지를 구축합니다. 내부 메커니즘을 숨기는 전면 하우징 커버 또는 쉬라우드에 cutawayHide: true를 전달합니다.

5단계 관문:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure,subject,mechanism --ortho --out figures/<slug>/dist/inspect-mechanism.png
node figures/<slug>/build.mjs    # 전체 대화형 HTML 빌드

inspect-mechanism.png를 읽습니다: 제어 장치가 명확하게 레이블이 지정되고, 튜브가 깔끔하게 라우팅되며, 직접 드래그 인터랙션이 __ANATOMY_DEBUG__에서 작동하는지 확인합니다.

6단계 — 셰이더 (`shader.mjs`)

물리적 매체(연소 화염, 전자기장, 유압 유체, 공기역학적 다운워시)에 대한 맞춤 GLSL 셰이더를 구축합니다 — 단순한 파티클 시스템이나 외부 연출이 아닙니다:

reg.shader({ name, fragmentShader, uniforms, renderOrder, transparent, depthWrite })를 사용합니다.
셰이더가 장치 내부의 제한된 볼륨 내에서만 렌더링되고(예: 실린더 보어 내부, 쉬라우드 팁 제트 내부, 액추에이터 포트 내부) 하우징, 프레임 또는 계측기를 넘어 새어나가지 않도록 합니다.
셰이더가 메커니즘의 물리적 상태(예: uTheta — 크랭크 각도, uRpm — 선택적 블러, 매체 두께, uCutaway — 활성 시 단면 경계 클램프, uExplode — 분해 중 가시성)에 응답하도록 합니다.
외부 연출 효과(안개, 글로우, 부드러운 조명 없음)를 추가하지 마십시오 — 셰이더는 기계가 하는 일의 물리학을 보여주기 위해 존재합니다.

6단계 관문:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --iso --out figures/<slug>/dist/inspect-final.png
node scripts/drive.mjs figures/<slug>/dist/<slug>.html --out figures/<slug>/dist/contact-sheet.png

최종 inspect-final.png를 읽고 모든 3D 좌표가 정확하고 앵커가 손상되지 않았는지 확인합니다. contact-sheet.png로 모든 뷰 모드(회전, 분해, 단면도, 5개 테마, 라이트/다크 UI, 모바일 390px)를 확인합니다.

최종 제공

모든 단계가 통과되면 사용자에게 다음을 표시합니다:

컴파일된 HTML 파일에 대한 파일 경로
5개 테마 미리보기
4뷰 직교 청사진
연락처 시트
"켜기/끄기" 텔레메트리 읽기값, "드래그" 힌트 포함

추가 노트

build.mjs --audit를 실행하면 모든 layer1-2 충돌 감지(경고: [COLLISION] layer1), 보어 관통 검사([BORE WALL]), 매니폴드 관통([FLOATING]), 튜브 킹크([TUBE KINK]) 및 부품이 베이스 위에 떠 있는지([FLOATING] — build.mjs는 부품이 +Y 방향으로 4 이상 떠 있으면 실패)를 확인합니다. 각 경고는 references/verify-3d.md를 참조합니다.
항상 inspect.mjs에서 --isolate 플래그를 사용하여 현재 단계의 부품만 격리하여 엉킨 뷰를 방지합니다.
뷰 모드는 다음과 같이 전환됩니다: Q 회전, W 분해도, E 단면도, R 셰이더.
build.mjs --audit의 DEBUG 섹션에 __ANATOMY_DEBUG__가 표시되면 직접 상호작용 가능한 부품의 중심과 id를 볼 수 있습니다.


---

## 참조

- [craft-3d.md](references/craft-3d.md) — 3D 좌표계, 톤 계층 구조, 맞춤 제어, 안티패턴
- [kit-3d.md](references/kit-3d.md) — Recorder3D, 프리미티브, 셰이더, 런타임 API 참조
- [verify-3d.md](references/verify-3d.md) — [COLLISION], [FLOATING], [TUBE KINK] 및 직교 뷰 해석 및 수정 방법

anatomy-threejs — 인터랙티브 3D 기술 도해