2nd/10_Wiki/Topics/DevOps_and_Security/three-mesh-bvh.md

---
id: wiki-2026-0508-three-mesh-bvh
title: three-mesh-bvh
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [three mesh bvh, MeshBVH, three.js BVH]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [three.js, bvh, raycasting, performance, webgl]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: three.js
---

# three-mesh-bvh

## 매 한 줄
> **"매 three.js mesh 의 BVH (Bounding Volume Hierarchy) 가속 구조"**. 매 raycasting / intersection / nearest-point query 를 O(N) → O(log N) 으로 — 매 100k+ triangle scene 에서 60fps raycast 가능. 2026 v0.7+ 가 GPU BVH (`MeshBVHUniformStruct`) 와 WebGPU 지원.

## 매 핵심

### 매 동작 원리
- Mesh geometry 의 triangle 들을 spatial 계층 (AABB 또는 OBB) 으로 분할.
- Built-in `Mesh.raycast` 를 BVH-aware version 으로 monkey-patch (`acceleratedRaycast`).
- Build 옵션: `CENTER` (fast), `AVERAGE` (balanced), `SAH` (Surface Area Heuristic, best query).

### 매 핵심 features
- **Raycast** acceleration.
- **shapecast**: 임의 shape (sphere/box/triangle) 와의 intersection traversal.
- **closestPointToPoint** / **closestPointToGeometry**.
- **CSG**: three-bvh-csg 와 결합한 boolean op.
- **GPU BVH** (2026): shader 에서 BVH traversal — pathtracing, generative geometry.

### 매 응용
1. VR scene 의 hand-controller raycast (수만 mesh).
2. CAD/CAM viewer 의 pick/snap.
3. Pathtracer, denoiser, AI 보조 generative scene.
4. Voxelization / signed-distance field 생성.

## 💻 패턴

### Basic raycast acceleration
```ts
import { computeBoundsTree, disposeBoundsTree, acceleratedRaycast } from 'three-mesh-bvh';
import * as THREE from 'three';

THREE.BufferGeometry.prototype.computeBoundsTree = computeBoundsTree;
THREE.BufferGeometry.prototype.disposeBoundsTree = disposeBoundsTree;
THREE.Mesh.prototype.raycast = acceleratedRaycast;

const mesh = new THREE.Mesh(geometry, material);
geometry.computeBoundsTree({ strategy: 'SAH' });

const raycaster = new THREE.Raycaster();
const hits = raycaster.intersectObject(mesh); // O(log N)
```

### shapecast (sphere intersection)
```ts
import { MeshBVH } from 'three-mesh-bvh';

const bvh = new MeshBVH(geometry);
const sphere = new THREE.Sphere(new THREE.Vector3(0, 1, 0), 0.5);

bvh.shapecast({
  intersectsBounds: (box) => sphere.intersectsBox(box),
  intersectsTriangle: (triangle) => {
    if (triangle.intersectsSphere(sphere)) return true;
    return false;
  },
});
```

### Closest point query
```ts
const target = { point: new THREE.Vector3(), distance: 0, faceIndex: -1 };
bvh.closestPointToPoint(new THREE.Vector3(1, 2, 3), target);
console.log(target.distance, target.point);
```

### Web Worker generation
```ts
import { GenerateMeshBVHWorker } from 'three-mesh-bvh/src/workers/GenerateMeshBVHWorker.js';

const worker = new GenerateMeshBVHWorker();
const bvh = await worker.generate(geometry, { strategy: 'SAH' });
geometry.boundsTree = bvh;
```

### GPU BVH (2026 WebGPU)
```ts
import { MeshBVHUniformStruct } from 'three-mesh-bvh';

const bvhUniform = new MeshBVHUniformStruct();
bvhUniform.updateFrom(bvh);
// shader 에서 bvhIntersectFirstHit(bvh, rayOrigin, rayDirection)
```

### Visualizer (debug)
```ts
import { MeshBVHHelper } from 'three-mesh-bvh';

const helper = new MeshBVHHelper(mesh, 10);
scene.add(helper);
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| <1k tri, 정적 raycast | BVH 불필요 (built-in) |
| 10k+ tri, 매 frame raycast | `computeBoundsTree({ strategy: 'SAH' })` |
| Animation / morph | refit `bvh.refit()` |
| Heavy CAD | Worker + serialize/deserialize |
| Pathtracer / GPU AO | `MeshBVHUniformStruct` |

**기본값**: `SAH` strategy + on demand build, animation 시 `refit()`.

## 🔗 Graph
- 부모: [[BVH]] · [[Three.js]]
- 변형: [[Octree]] · [[K-D Tree]]
- 응용: [[Raycasting]] · [[Collision-Detection]]
- Adjacent: [[BatchedMesh 및 InstancedMesh 성능 벤치마크]] · [[BufferGeometry]]

## 🤖 LLM 활용
**언제**: 매 large mesh raycast / proximity query 가 hot path 일 때 — 특히 VR / CAD / gen AI scene.
**언제 X**: 매 simple sphere/box collision — manual primitive check 가 빠름.

## ❌ 안티패턴
- **매 frame full rebuild**: `refit()` 사용.
- **CENTER strategy 로 build 시간 절약**: query 가 2-3x 느려짐. SAH 의 build cost 는 1회.
- **BVH dispose 안 함**: geometry 교체 시 leak — `geometry.disposeBoundsTree()`.
- **shapecast 의 `intersectsBounds` false positive 무시**: triangle 까지 끝까지 traverse — feedback 손실.

## 🧪 검증 / 중복
- Verified (three-mesh-bvh v0.7+ README, gkjohnson 의 demo & changelog, three.js examples).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — full content with shapecast/GPU BVH + worker |