2nd/10_Wiki/Topic_Programming/DevOps_and_Security/InstancedMesh2.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-instancedmesh2	InstancedMesh2	10_Wiki/Topics	verified	self	three-instanced-mesh2 three.js-instancedmesh2	none	A	0.9	applied	three.js webgl performance instancing rendering		2026-05-10	pending	language framework TypeScript three.js

InstancedMesh2

매 한 줄

"매 InstancedMesh의 진화형 — frustum culling, LOD, BVH, per-instance uniforms를 그대로 지원하는 instancing 솔루션". 매 three.js의 stock InstancedMesh가 모든 instance를 ALWAYS draw 하는 한계를 극복하기 위해 등장한 community library — agargaro/instanced-mesh가 매 2024-2026 사실상 표준으로 자리잡음.

매 핵심

매 stock InstancedMesh의 한계

• 매 frustum culling 부재 → off-screen instance도 GPU에 commit
• 매 per-instance visibility toggle 부재
• 매 LOD 미지원 — 매 distance 무관 동일 mesh draw
• 매 raycasting brute-force — 매 매 instance 매 triangle scan

매 InstancedMesh2 추가 기능

• Per-instance frustum culling: 매 BVH 기반 fast cull
• LOD groups: 매 distance threshold 별 다른 geometry
• BVH acceleration: 매 raycast O(log n)
• Per-instance uniforms: 매 색상/sprite frame/animation time 등
• Shadow culling: 매 shadow camera frustum 별도 cull

매 응용

1. 매 RTS/시뮬레이션 — 매 1k+ unit 매 60fps.
2. 매 archviz — 매 forest/도시 scenery instance.
3. 매 particle alternative — 매 mesh-particle hybrid.

💻 패턴

매 기본 setup

import { InstancedMesh2 } from '@three.ez/instanced-mesh';
import * as THREE from 'three';

const geo = new THREE.BoxGeometry(1, 1, 1);
const mat = new THREE.MeshStandardMaterial();
const count = 10_000;

const mesh = new InstancedMesh2(geo, mat, { capacity: count });
mesh.addInstances(count, (obj, idx) => {
  obj.position.set(
    (Math.random() - 0.5) * 200,
    0,
    (Math.random() - 0.5) * 200,
  );
  obj.color = new THREE.Color(Math.random(), Math.random(), Math.random());
});
mesh.computeBVH();
scene.add(mesh);

매 LOD groups

const lod = new InstancedMesh2(geoHigh, mat, { capacity: 5000 });
lod.addLOD(geoMid, mat, 30);   // 30 units 부터 mid mesh
lod.addLOD(geoLow, mat, 100);  // 100 units 부터 low mesh
lod.addShadowLOD(geoShadow, 50); // shadow 용 별도 LOD

매 per-instance update

mesh.updateInstances((obj, idx) => {
  obj.position.y = Math.sin(time + idx * 0.1);
  obj.rotation.y += 0.01;
});

매 frustum culling toggle

mesh.perObjectFrustumCulled = true;  // default
mesh.sortObjects = true;             // 매 transparent 매 back-to-front

매 raycasting BVH

mesh.computeBVH({ margin: 0 });
const ray = new THREE.Raycaster();
ray.setFromCamera(mouse, camera);
const hits = ray.intersectObject(mesh);
// hits[0].instanceId 매 정확한 instance

매 instance 제거

mesh.removeInstances([0, 5, 10]);  // 매 batch 매 1 frame
mesh.computeBVH();  // 매 dirty 면 rebuild

매 color attribute

mesh.setColorAt(idx, new THREE.Color('red'));
mesh.instanceColor.needsUpdate = true;

매 shader integration

mat.onBeforeCompile = (shader) => {
  shader.vertexShader = shader.vertexShader.replace(
    '#include <begin_vertex>',
    `#include <begin_vertex>
     transformed += instanceMatrix[3].xyz * 0.01;`
  );
};

매 결정 기준

상황	Approach
<500 instance	매 stock InstancedMesh
1k-100k 매 same geometry	InstancedMesh2
매 different geometries	BatchedMesh
매 GPU-driven 매 indirect	매 custom WebGPU

기본값: 매 1k 이상 instance — InstancedMesh2.

🔗 Graph

• 부모: InstancedMesh · three.js
• 변형: BatchedMesh · three-mesh-bvh
• 응용: Frustum Culling · Draw Call
• Adjacent: BVH · Raycasting

🤖 LLM 활용

언제: 매 large-scale 동일 mesh scene — vegetation, crowd, debris. 언제 X: 매 instance 별 geometry 다름 — BatchedMesh 사용.

❌ 안티패턴

• BVH 매 update 안 함: 매 instance 이동 후 raycast 부정확.
• capacity 매 너무 크게: 매 GPU memory 매 낭비.
• per-frame full update: 매 dirty flag 만 flush.

🧪 검증 / 중복

• Verified (@three.ez/instanced-mesh v0.4+, three.js r170+).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — InstancedMesh2 라이브러리 사용법 + LOD/BVH 패턴 정리