# gkjohnson/three-mesh-bvh architecture

> Architecture diagram of the GitHub repository gkjohnson/three-mesh-bvh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gkjohnson/three-mesh-bvh
- Repository: https://github.com/gkjohnson/three-mesh-bvh

## Overview

three-mesh-bvh is a three.js spatial-query library. Its principal workflow is to build a BVH over geometry, attach or construct it for an object, then accelerate raycasting or perform direct spatial queries. It also supports specialized primitive and scene hierarchies, asynchronous worker generation, WebGL/WebGPU integrations, and utilities for inspection and geometry preparation. The graph follows documented relationships and sampled imports/calls; several unsampled subsystems are included as capabilities documented by the README, without guessing their internal wiring.

Main entry points: [`src/core/MeshBVH.js`](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/MeshBVH.js) (Mesh BVH), [`src/index.js`](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/index.js) (Public API), [`src/core/GeometryBVH.js`](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/GeometryBVH.js) (Geometry BVH), [`src/webgpu/BVHComputeData.js`](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgpu/BVHComputeData.js) (WebGPU Compute Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["BVH Core"]
  node_api["Public API<br/>[index.js]"]
  node_bvh["Packed BVH<br/>[BVH.js]"]
  node_geometry["Geometry BVH<br/>[GeometryBVH.js]"]
  node_mesh["Mesh BVH<br/>[MeshBVH.js]"]
  node_nodebuffer["Node Layout<br/>[nodeBufferUtils.js]"]
end

subgraph group_queries["Geometry Queries"]
  node_triangle["Triangle Math"]
  node_specialized["Lines and Points<br/>[LineBVH.js]"]
  node_skinned["Skinned Mesh BVH<br/>[SkinnedMeshBVH.js]"]
  node_object["Object BVH<br/>[ObjectBVH.js]"]
end

subgraph group_extensions["Integrations"]
  node_workers["Worker API"]
  node_workerbase["Worker Lifecycle<br/>[WorkerBase.js]"]
  node_workerthread["Worker Builder"]
  node_extensionsapi["Three.js Extensions"]
end

subgraph group_compute["GPU Acceleration"]
  node_webgl["WebGL BVH Textures"]
  node_webgluniform["WebGL Uniforms"]
  node_webgpu["WebGPU Compute Data<br/>[BVHComputeData.js]"]
  node_webgpufns["WebGPU Query Functions<br/>[getShapecastFn.js]"]
end

subgraph group_utilities["Tools"]
  node_debug["BVH Inspection<br/>[Debug.js]"]
  node_helper["BVH Helper<br/>[BVHHelper.js]"]
  node_generator["Static Geometry"]
  node_triangleutils["Triangle Utilities"]
end

node_developer(("three.js App"))

node_developer -->|"imports"| node_api
node_api -->|"exports"| node_mesh
node_api -->|"exports"| node_geometry
node_api -->|"exports"| node_specialized
node_api -->|"exports"| node_object
node_api -->|"exports"| node_skinned
node_api -->|"exports"| node_extensionsapi
node_geometry -->|"extends"| node_bvh
node_mesh -->|"extends"| node_geometry
node_bvh -->|"decodes nodes"| node_nodebuffer
node_mesh -->|"uses triangle math"| node_triangle
node_mesh -->|"sets triangles"| node_triangleutils
node_skinned -->|"extends"| node_geometry
node_object -->|"uses hierarchy"| node_bvh
node_developer -->|"builds BVH"| node_mesh
node_developer -->|"raycasts"| node_mesh
node_workers -->|"inherits lifecycle"| node_workerbase
node_workers -->|"dispatches build"| node_workerthread
node_workerthread -->|"creates proxy BVH"| node_mesh
node_workerthread -->|"generates indirect buffer"| node_geometry
node_webgluniform -->|"packs BVH"| node_mesh
node_webgluniform -->|"creates textures"| node_webgl
node_webgpu -->|"consumes BVH"| node_mesh
node_webgpu -->|"consumes BVH"| node_skinned
node_webgpufns -->|"uses compute data"| node_webgpu
node_debug -->|"inspects hierarchy"| node_bvh
node_helper -->|"visualizes bounds"| node_mesh
node_helper -->|"reads bounds"| node_geometry
node_developer -->|"queries scene"| node_object
node_developer -->|"generates asynchronously"| node_workers
node_developer -->|"uses GPU data"| node_webgluniform
node_developer -.->|"uses compute API"| node_webgpu

click node_api "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/index.js"
click node_bvh "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/BVH.js"
click node_geometry "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/GeometryBVH.js"
click node_mesh "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/MeshBVH.js"
click node_nodebuffer "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/utils/nodeBufferUtils.js"
click node_triangle "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/math/ExtendedTriangle.js"
click node_specialized "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/LineBVH.js"
click node_skinned "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/SkinnedMeshBVH.js"
click node_object "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/ObjectBVH.js"
click node_workers "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/workers/ParallelMeshBVHWorker.js"
click node_workerbase "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/workers/utils/WorkerBase.js"
click node_workerthread "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/workers/parallelMeshBVH.worker.js"
click node_extensionsapi "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/utils/ExtensionUtilities.js"
click node_webgl "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgl/VertexAttributeTexture.js"
click node_webgluniform "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgl/MeshBVHUniformStruct.js"
click node_webgpu "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgpu/BVHComputeData.js"
click node_webgpufns "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgpu/shapecastFns/getShapecastFn.js"
click node_debug "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/debug/Debug.js"
click node_helper "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/objects/BVHHelper.js"
click node_generator "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/utils/StaticGeometryGenerator.js"
click node_triangleutils "https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/utils/TriangleUtilities.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_bvh,node_geometry,node_mesh,node_nodebuffer toneBlue
class node_triangle,node_specialized,node_skinned,node_object toneAmber
class node_workers,node_workerbase,node_workerthread,node_extensionsapi toneMint
class node_webgl,node_webgluniform,node_webgpu,node_webgpufns toneRose
class node_debug,node_helper,node_generator,node_triangleutils,node_developer toneIndigo
```

## Components

### BVH Core

- [Public API](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/index.js): `src/index.js`
- [Packed BVH](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/BVH.js): `src/core/BVH.js`
- [Geometry BVH](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/GeometryBVH.js): `src/core/GeometryBVH.js`
- [Mesh BVH](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/MeshBVH.js): `src/core/MeshBVH.js`
- [Node Layout](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/utils/nodeBufferUtils.js): `src/core/utils/nodeBufferUtils.js`

### Geometry Queries

- [Triangle Math](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/math/ExtendedTriangle.js): `src/math/ExtendedTriangle.js`
- [Lines and Points](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/LineBVH.js): `src/core/LineBVH.js`
- [Skinned Mesh BVH](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/SkinnedMeshBVH.js): `src/core/SkinnedMeshBVH.js`
- [Object BVH](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/core/ObjectBVH.js): `src/core/ObjectBVH.js`

### Integrations

- [Worker API](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/workers/ParallelMeshBVHWorker.js): `src/workers/ParallelMeshBVHWorker.js`
- [Worker Lifecycle](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/workers/utils/WorkerBase.js): `src/workers/utils/WorkerBase.js`
- [Worker Builder](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/workers/parallelMeshBVH.worker.js): `src/workers/parallelMeshBVH.worker.js`
- [Three.js Extensions](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/utils/ExtensionUtilities.js): `src/utils/ExtensionUtilities.js`

### GPU Acceleration

- [WebGL BVH Textures](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgl/VertexAttributeTexture.js): `src/webgl/VertexAttributeTexture.js`
- [WebGL Uniforms](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgl/MeshBVHUniformStruct.js): `src/webgl/MeshBVHUniformStruct.js`
- [WebGPU Compute Data](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgpu/BVHComputeData.js): `src/webgpu/BVHComputeData.js`
- [WebGPU Query Functions](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/webgpu/shapecastFns/getShapecastFn.js): `src/webgpu/shapecastFns/getShapecastFn.js`

### Tools

- [BVH Inspection](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/debug/Debug.js): `src/debug/Debug.js`
- [BVH Helper](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/objects/BVHHelper.js): `src/objects/BVHHelper.js`
- [Static Geometry](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/utils/StaticGeometryGenerator.js): `src/utils/StaticGeometryGenerator.js`
- [Triangle Utilities](https://github.com/gkjohnson/three-mesh-bvh/blob/master/src/utils/TriangleUtilities.js): `src/utils/TriangleUtilities.js`

### Other components

- **three.js App**

## Connections

- three.js App → Public API: imports (evidence: `README.md`)
- Public API → Mesh BVH: exports (evidence: `src/index.js`)
- Public API → Geometry BVH: exports (evidence: `src/index.js`)
- Public API → Lines and Points: exports (evidence: `src/index.js`)
- Public API → Object BVH: exports (evidence: `src/index.js`)
- Public API → Skinned Mesh BVH: exports (evidence: `src/index.js`)
- Public API → Three.js Extensions: exports (evidence: `src/index.js`)
- Geometry BVH → Packed BVH: extends (evidence: `src/core/GeometryBVH.js`)
- Mesh BVH → Geometry BVH: extends (evidence: `src/core/MeshBVH.js`)
- Packed BVH → Node Layout: decodes nodes (evidence: `src/core/BVH.js`)
- Mesh BVH → Triangle Math: uses triangle math (evidence: `src/core/MeshBVH.js`)
- Mesh BVH → Triangle Utilities: sets triangles (evidence: `src/core/MeshBVH.js`)
- Skinned Mesh BVH → Geometry BVH: extends (evidence: `src/core/SkinnedMeshBVH.js`)
- Object BVH → Packed BVH: uses hierarchy (evidence: `src/core/ObjectBVH.js`)
- three.js App → Mesh BVH: builds BVH (evidence: `README.md`)
- three.js App → Mesh BVH: raycasts (evidence: `README.md`)
- Worker API → Worker Lifecycle: inherits lifecycle (evidence: `src/workers/ParallelMeshBVHWorker.js`)
- Worker API → Worker Builder: dispatches build (evidence: `src/workers/ParallelMeshBVHWorker.js`)
- Worker Builder → Mesh BVH: creates proxy BVH (evidence: `src/workers/parallelMeshBVH.worker.js`)
- Worker Builder → Geometry BVH: generates indirect buffer (evidence: `src/workers/parallelMeshBVH.worker.js`)
- WebGL Uniforms → Mesh BVH: packs BVH (evidence: `src/webgl/MeshBVHUniformStruct.js`)
- WebGL Uniforms → WebGL BVH Textures: creates textures (evidence: `src/webgl/MeshBVHUniformStruct.js`)
- WebGPU Compute Data → Mesh BVH: consumes BVH (evidence: `src/webgpu/BVHComputeData.js`)
- WebGPU Compute Data → Skinned Mesh BVH: consumes BVH (evidence: `src/webgpu/BVHComputeData.js`)
- WebGPU Query Functions → WebGPU Compute Data: uses compute data (evidence: `src/webgpu/shapecastFns/getShapecastFn.js`)
- BVH Inspection → Packed BVH: inspects hierarchy (evidence: `src/debug/Debug.js`)
- BVH Helper → Mesh BVH: visualizes bounds (evidence: `src/objects/BVHHelper.js`)
- BVH Helper → Geometry BVH: reads bounds (evidence: `src/objects/BVHHelper.js`)
- three.js App → Object BVH: queries scene (evidence: `README.md`)
- three.js App → Worker API: generates asynchronously (evidence: `README.md`)
- three.js App → WebGL Uniforms: uses GPU data
- three.js App → WebGPU Compute Data: uses compute API
