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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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)

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

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

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)

import { MeshBVHUniformStruct } from 'three-mesh-bvh';

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

Visualizer (debug)

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