bvh

A plugin that uses three-mesh-bvh to speed up raycasting and enable spatial queries against Three.js objects. Any Mesh, BatchedMesh, or Points that are created in the component and child component where this plugin is called are patched with BVH raycasting methods.

1
<script lang="ts">
2
  import Scene from './Scene.svelte'
3
  import { Canvas } from '@threlte/core'
4
  import { type BVHOptions, BVHSplitStrategy } from '@threlte/extras'
5
  import { Pane, Checkbox, List, Slider } from 'svelte-tweakpane-ui'
6

7
  let options = $state<Required<BVHOptions> & { helper: boolean }>({
8
    enabled: true,
9
    helper: true,
10
    strategy: BVHSplitStrategy.SAH,
11
    indirect: false,
12
    verbose: false,
13
    maxDepth: 20,
14
    maxLeafTris: 10,
15
    setBoundingBox: true
16
  })
17
</script>
18

19
<Pane
20
  title="bvh"
21
  position="fixed"
22
>
23
  <Checkbox
24
    label="enabled"
25
    bind:value={options.enabled}
26
  />
27
  <Checkbox
28
    label="helper"
29
    bind:value={options.helper}
30
  />
31
  <Checkbox
32
    label="setBoundingBox"
33
    bind:value={options.setBoundingBox}
34
  />
35
  <List
36
    bind:value={options.strategy}
37
    label="strategy"
38
    options={{
39
      SAH: BVHSplitStrategy.SAH,
40
      CENTER: BVHSplitStrategy.CENTER,
41
      AVERAGE: BVHSplitStrategy.AVERAGE
42
    }}
43
  />
44
  <Slider
45
    label="maxDepth"
46
    bind:value={options.maxDepth}
47
    step={1}
48
  />
49
  <Slider
50
    label="maxLeafTris"
51
    bind:value={options.maxLeafTris}
52
    step={1}
53
  />
54
</Pane>
55

56
<Canvas>
57
  <Scene {...options} />
58
</Canvas>

1
<script lang="ts">
2
  import {
3
    OrbitControls,
4
    Grid,
5
    useGltf,
6
    Environment,
7
    Wireframe,
8
    bvh,
9
    interactivity,
10
    type BVHOptions
11
  } from '@threlte/extras'
12
  import { T, useTask } from '@threlte/core'
13
  import { BufferAttribute, DynamicDrawUsage, Mesh, Vector3, type Face } from 'three'
14

15
  let { ...rest }: BVHOptions = $props()
16

17
  const { raycaster } = interactivity()
18
  raycaster.firstHitOnly = true
19

20
  bvh(() => rest)
21

22
  const gltf = useGltf('/models/stanford_bunny.glb')
23
  const mesh = $derived($gltf ? ($gltf.nodes['Object_2'] as Mesh) : undefined)
24

25
  $effect(() => {
26
    if (mesh) {
27
      const array = new Float32Array(3 * mesh.geometry.getAttribute('position').count).fill(1)
28
      const attribute = new BufferAttribute(array, 3).setUsage(DynamicDrawUsage)
29
      mesh.geometry.setAttribute('color', attribute)
30
    }
31
  })
32

33
  const faces = new Set<Face>()
34

35
  useTask(() => {
36
    const attribute = mesh?.geometry.getAttribute('color')
37

38
    if (!attribute) {
39
      return
40
    }
41

42
    for (const face of faces) {
43
      let gb = attribute.getY(face.a)
44

45
      gb += 0.01
46

47
      if (gb >= 1) {
48
        gb = 1
49
        faces.delete(face)
50
      }
51

52
      attribute.setXYZ(face.a, 1, gb, gb)
53
      attribute.setXYZ(face.b, 1, gb, gb)
54
      attribute.setXYZ(face.c, 1, gb, gb)
55

56
      attribute.needsUpdate = true
57
    }
58
  })
59
</script>
60

61
<T.PerspectiveCamera
62
  makeDefault
63
  position.x={-1.3}
64
  position.y={1.8}
65
  position.z={1.8}
66
  fov={50}
67
  oncreate={(ref) => ref.lookAt(0, 0.6, 0)}
68
>
69
  <OrbitControls
70
    enableDamping
71
    enableZoom={false}
72
    enablePan={false}
73
    target={[0, 0.6, 0]}
74
  />
75
</T.PerspectiveCamera>
76

77
{#if $gltf}
78
  <T
79
    is={$gltf.nodes['Object_2'] as Mesh}
80
    scale={10}
81
    rotation.x={-Math.PI / 2}
82
    position.y={-0.35}
83
    onpointermove={({ face }) => {
84
      const attribute = mesh?.geometry.getAttribute('color')
85

86
      if (face && attribute) {
87
        attribute.setXYZ(face.a, 1, 0, 0)
88
        attribute.setXYZ(face.b, 1, 0, 0)
89
        attribute.setXYZ(face.c, 1, 0, 0)
90
        faces.add(face)
91
      }
92
    }}
93
  >
94
    <T.MeshStandardMaterial
95
      roughness={0.1}
96
      metalness={0.4}
97
      vertexColors
98
    />
99
    <Wireframe />
100
  </T>
101
{/if}
102

103
<T.DirectionalLight />
104

105
<Environment url="/textures/equirectangular/hdr/shanghai_riverside_1k.hdr" />
106

107
<Grid
108
  sectionThickness={1}
109
  infiniteGrid
110
  cellColor="#dddddd"
111
  sectionColor="#ffffff"
112
  sectionSize={1}
113
  cellSize={0.5}
114
  type="circular"
115
  fadeOrigin={new Vector3()}
116
  fadeDistance={20}
117
  fadeStrength={10}
118
/>

Basic example

The plugin can be configured by passing a function that returns an object or $state rune as an argument. The following options are available and will be set for every Three.js object.

1
<script lang="ts">
2
  import { T } from '@threlte/core'
3
  import { bvh, interactivity, BVHSplitStrategy, type BVHOptions } from '@threlte/extras'
4

5
  // Usually, you'll also want to call the interactivity plugin.
6
  const { raycaster } = interactivity()
7

8
  // This option is usually set with three-mesh-bvh,
9
  // unless you need multiple hits.
10
  raycaster.firstHitOnly = true
11

12
  // These are the default options.
13
  const options = $state<BVHOptions>({
14
    enabled: true,
15
    helper: false,
16
    strategy: BVHSplitStrategy.SAH,
17
    indirect: false,
18
    verbose: false,
19
    maxDepth: 20,
20
    maxLeafTris: 10,
21
    setBoundingBox: true
22
  })
23

24
  bvh(() => options)
25
</script>

Setting options at a per object level is possible with the bvh prop.

1
<T.Mesh bvh={{ maxDepth: 10 }}>
2
  <T.TorusGeometry />
3
  <T.MeshStandardMaterial >
4
</T.Mesh>

If you want this prop to be typesafe, you can extend Threlte.UserProps like so:

1
import type { InteractivityProps, BVHProps } from '@threlte/extras'
2

3
declare global {
4
  namespace Threlte {
5
    interface UserProps extends InteractivityProps, BVHProps {}
6
  }
7
}

Points

The bvh plugin will shapecast against points, attempting to match Three.js’ raycasting behavior with added three-mesh-bvh optimizations.

1
<script lang="ts">
2
  import Scene from './Scene.svelte'
3
  import { Canvas } from '@threlte/core'
4
  import { type BVHOptions, BVHSplitStrategy } from '@threlte/extras'
5
  import { Pane, Checkbox, List, Slider } from 'svelte-tweakpane-ui'
6

7
  const options = $state<Required<BVHOptions> & { helper: boolean; firstHitOnly: boolean }>({
8
    enabled: true,
9
    strategy: BVHSplitStrategy.SAH,
10
    indirect: false,
11
    verbose: false,
12
    maxDepth: 40,
13
    maxLeafTris: 20,
14
    setBoundingBox: true,
15

16
    firstHitOnly: false,
17
    helper: false
18
  })
19
</script>
20

21
<Pane
22
  title="bvh"
23
  position="fixed"
24
>
25
  <Checkbox
26
    label="enabled"
27
    bind:value={options.enabled}
28
  />
29
  <Checkbox
30
    label="helper"
31
    bind:value={options.helper}
32
  />
33
  <Checkbox
34
    label="firstHitOnly"
35
    bind:value={options.firstHitOnly}
36
  />
37
  <Checkbox
38
    label="setBoundingBox"
39
    bind:value={options.setBoundingBox}
40
  />
41
  <List
42
    bind:value={options.strategy}
43
    label="strategy"
44
    options={{
45
      SAH: BVHSplitStrategy.SAH,
46
      CENTER: BVHSplitStrategy.CENTER,
47
      AVERAGE: BVHSplitStrategy.AVERAGE
48
    }}
49
  />
50
  <Slider
51
    label="maxDepth"
52
    bind:value={options.maxDepth}
53
    step={1}
54
  />
55
  <Slider
56
    label="maxLeafTris"
57
    bind:value={options.maxLeafTris}
58
    step={1}
59
  />
60
</Pane>
61

62
<Canvas>
63
  <Scene {...options} />
64
</Canvas>

1
<script lang="ts">
2
  import {
3
    OrbitControls,
4
    useGltf,
5
    bvh,
6
    interactivity,
7
    type BVHOptions,
8
    PointsMaterial
9
  } from '@threlte/extras'
10
  import { T, useTask } from '@threlte/core'
11
  import { BufferAttribute, DynamicDrawUsage, Points, type Vector3Tuple } from 'three'
12

13
  let { ...rest }: BVHOptions & { firstHitOnly: boolean } = $props()
14

15
  const { raycaster } = interactivity()
16
  raycaster.params.Points.threshold = 0.5
17

18
  $effect(() => {
19
    raycaster.firstHitOnly = rest.firstHitOnly
20
  })
21

22
  bvh(() => rest)
23

24
  const gltf = useGltf('/models/stairs.glb')
25

26
  const points = $derived.by(() => {
27
    if (!$gltf) {
28
      return
29
    }
30

31
    const results = $gltf.nodes['Object'] as Points
32
    const array = new Float32Array(3 * results.geometry.getAttribute('position').count).fill(1)
33
    const attribute = new BufferAttribute(array, 3).setUsage(DynamicDrawUsage)
34
    results.geometry.setAttribute('color', attribute)
35

36
    return results
37
  })
38

39
  useTask(() => {
40
    if (!points) return
41

42
    const attribute = points.geometry.getAttribute('color')
43

44
    const indices = points.userData.indices as Set<number>
45
    if (indices.size > 0) {
46
      for (const index of indices) {
47
        let gb = attribute.getY(index)
48

49
        gb += 0.005
50

51
        if (gb >= 1) {
52
          gb = 1
53
          indices.delete(index)
54
        }
55

56
        attribute.setXYZ(index, 1, gb, gb)
57
      }
58

59
      attribute.needsUpdate = true
60
    }
61
  })
62

63
  let visible = $state(false)
64
  let point = $state.raw<Vector3Tuple>([0, 0, 0])
65
</script>
66

67
<T.PerspectiveCamera
68
  makeDefault
69
  position.x={20}
70
  position.y={20}
71
  position.z={-20}
72
  fov={50}
73
>
74
  <OrbitControls
75
    enableDamping
76
    enableZoom={false}
77
    enablePan={false}
78
  />
79
</T.PerspectiveCamera>
80

81
{#if points}
82
  <T
83
    is={points}
84
    rotation.x={-Math.PI / 2}
85
    userData.indices={new Set<number>()}
86
    onpointerenter={() => {
87
      visible = true
88
    }}
89
    onpointerleave={() => {
90
      visible = false
91
    }}
92
    onpointermove={(event) => {
93
      point = event.point.toArray()
94
      if (event.index) {
95
        points.geometry.getAttribute('color').setXYZ(event.index, 1, 0, 0)
96
        points.userData.indices.add(event.index)
97
      }
98
    }}
99
  >
100
    <PointsMaterial
101
      size={0.2}
102
      vertexColors
103
      transparent
104
      toneMapped={false}
105
      opacity={0.75}
106
    />
107
  </T>
108
{/if}
109

110
<T.Mesh
111
  position={point}
112
  renderOrder={1}
113
  {visible}
114
  bvh={{ enabled: false }}
115
>
116
  <T.SphereGeometry args={[0.5]} />
117
  <T.MeshBasicMaterial
118
    color="red"
119
    depthTest={false}
120
    transparent
121
    opacity={0.5}
122
  />
123
</T.Mesh>
124

125
<T.DirectionalLight />

Limitations

To avoid unnecessary bounds tree computations, the plugin will not recompute bounds trees when geometry changes occur. The plugin is set to recompute only if a reference to a mesh changes. So, if you want to recompute a bounds tree based on a geometry change, you’ll have to regenerate the mesh as well.

1
{#key geometry}
2
  <T.Mesh>
3
    <T is={geometry} />
4
    <T.MeshStandardMaterial />
5
  </T.Mesh>
6
{/key}