chore(brain): ASTRA 성장 자산 동기화 — 기능 인벤토리·growth(약점프로필/학습큐)·일화기억·장기기억·회의록 원문

2026-06-12 16:37:41 +09:00
parent a97fc7be07
commit 89fb05a28a
781 changed files with 138546 additions and 47 deletions
@@ -0,0 +1,236 @@
+---
+id: wiki-2026-0508-threejs
+title: Three.js
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [Three.js, three, 3D web, WebGL library]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [3d, webgl, webgpu, graphics, threejs]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: typescript
+  framework: three.js-r170
+---
+
+# Three.js
+
+## 매 한 줄
+> **"매 web 의 de-facto 3D library — WebGL/WebGPU 의 high-level wrapper"**. 매 scene graph + materials + lights + cameras + loaders. 2026 r170+ — WebGPURenderer stable, TSL (Three Shading Language), node-based materials. React 통합은 `@react-three/fiber`.
+
+## 매 핵심
+
+### 매 core entities
+- **Scene**: 매 graph root.
+- **Camera**: Perspective / Orthographic.
+- **Renderer**: WebGLRenderer / WebGPURenderer.
+- **Mesh** = Geometry + Material.
+- **Light**: Ambient / Directional / Point / Spot.
+
+### 매 render loop
+- `requestAnimationFrame` → update → renderer.render(scene, camera).
+- 매 r3f 는 자동 loop.
+
+### 매 응용
+1. Product configurator (3D customization).
+2. Data visualization (graph, scatter).
+3. WebXR (VR/AR).
+4. Game / interactive art.
+
+## 💻 패턴
+
+### Vanilla minimal
+```typescript
+import * as THREE from 'three';
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(
+  75, window.innerWidth / window.innerHeight, 0.1, 1000,
+);
+camera.position.z = 5;
+
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(window.innerWidth, window.innerHeight);
+renderer.setPixelRatio(window.devicePixelRatio);
+document.body.appendChild(renderer.domElement);
+
+const geo = new THREE.BoxGeometry(1, 1, 1);
+const mat = new THREE.MeshStandardMaterial({ color: 0x6699ff });
+const cube = new THREE.Mesh(geo, mat);
+scene.add(cube);
+
+scene.add(new THREE.AmbientLight(0xffffff, 0.4));
+const dir = new THREE.DirectionalLight(0xffffff, 1);
+dir.position.set(5, 5, 5);
+scene.add(dir);
+
+renderer.setAnimationLoop(() => {
+  cube.rotation.x += 0.01;
+  cube.rotation.y += 0.01;
+  renderer.render(scene, camera);
+});
+```
+
+### WebGPU renderer (r170+)
+```typescript
+import * as THREE from 'three/webgpu';
+import { color, normalLocal } from 'three/tsl';
+
+const renderer = new THREE.WebGPURenderer({ antialias: true });
+await renderer.init();
+
+const mat = new THREE.MeshBasicNodeMaterial();
+mat.colorNode = color('#6699ff').mul(normalLocal.length());
+```
+
+### React Three Fiber
+```tsx
+import { Canvas, useFrame } from '@react-three/fiber';
+import { OrbitControls, Environment } from '@react-three/drei';
+import { useRef } from 'react';
+import type { Mesh } from 'three';
+
+function Box() {
+  const ref = useRef<Mesh>(null);
+  useFrame((_, dt) => {
+    if (ref.current) ref.current.rotation.y += dt;
+  });
+  return (
+    <mesh ref={ref}>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshStandardMaterial color="#6699ff" />
+    </mesh>
+  );
+}
+
+export default function App() {
+  return (
+    <Canvas camera={{ position: [3, 3, 3] }}>
+      <Environment preset="city" />
+      <Box />
+      <OrbitControls />
+    </Canvas>
+  );
+}
+```
+
+### GLTF model loading
+```typescript
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+
+const draco = new DRACOLoader();
+draco.setDecoderPath('https://www.gstatic.com/draco/v1/decoders/');
+
+const loader = new GLTFLoader();
+loader.setDRACOLoader(draco);
+
+const gltf = await loader.loadAsync('/model.glb');
+scene.add(gltf.scene);
+```
+
+```tsx
+// r3f
+import { useGLTF } from '@react-three/drei';
+function Model() {
+  const { scene } = useGLTF('/model.glb');
+  return <primitive object={scene} />;
+}
+```
+
+### Postprocessing
+```typescript
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+
+const composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene, camera));
+composer.addPass(new UnrealBloomPass(
+  new THREE.Vector2(window.innerWidth, window.innerHeight),
+  0.8, 0.4, 0.85,
+));
+
+renderer.setAnimationLoop(() => composer.render());
+```
+
+### Instanced rendering (10k+ objects)
+```typescript
+const count = 10_000;
+const mesh = new THREE.InstancedMesh(geo, mat, count);
+const dummy = new THREE.Object3D();
+for (let i = 0; i < count; i++) {
+  dummy.position.set(
+    (Math.random() - 0.5) * 100,
+    (Math.random() - 0.5) * 100,
+    (Math.random() - 0.5) * 100,
+  );
+  dummy.updateMatrix();
+  mesh.setMatrixAt(i, dummy.matrix);
+}
+scene.add(mesh);
+```
+
+### Disposal (memory)
+```typescript
+function dispose(obj: THREE.Object3D) {
+  obj.traverse((child) => {
+    if ((child as THREE.Mesh).isMesh) {
+      const m = child as THREE.Mesh;
+      m.geometry.dispose();
+      const mats = Array.isArray(m.material) ? m.material : [m.material];
+      mats.forEach((mat) => mat.dispose());
+    }
+  });
+}
+```
+
+### WebXR (VR)
+```typescript
+renderer.xr.enabled = true;
+import { VRButton } from 'three/addons/webxr/VRButton.js';
+document.body.appendChild(VRButton.createButton(renderer));
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| 매 React app | `@react-three/fiber` + drei |
+| 매 vanilla / lib | three.js direct |
+| 매 GPU compute / advanced shader | WebGPURenderer + TSL |
+| 매 game | Babylon.js / PlayCanvas (more game-oriented) |
+| 매 declarative UI integration | r3f (preferred) |
+
+**기본값**: 매 React → r3f + drei. 매 그 외 → three.js + addons.
+
+## 🔗 Graph
+- 부모: [[3D_Web]] · [[WebGL]]
+- 변형: [[Babylon_js]]
+- 응용: [[React_Three_Fiber]] · [[drei]] · [[WebXR]]
+- Adjacent: [[Shader]] · [[WebGPU]]
+
+## 🤖 LLM 활용
+**언제**: 매 scene scaffold, 매 shader translate, 매 r3f component generation.
+**언제 X**: 매 production shader optimization — 매 hand-tune 필요.
+
+## ❌ 안티패턴
+- **Forgetting dispose**: 매 GPU memory leak.
+- **`new THREE.X` in render loop**: 매 GC pressure.
+- **No `setPixelRatio`**: 매 retina blurry.
+- **Many individual meshes**: 매 instancing 의 사용.
+- **Direct DOM rerender on every frame**: 매 r3f 의 자동 loop 무시.
+
+## 🧪 검증 / 중복
+- Verified (three.js r170 docs, react-three/fiber docs, mrdoob, 2026).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — Three.js r170 with WebGPU, TSL, r3f, instancing |