AccelerationStructure

Thin wrapper around the three-mesh-bvh library’s MeshBVH class with some additional specific functionality.

The viewer is using three-mesh-bvh as the backbone for it’s BVH implementation. The AccelerationStructure class is a thin wrapper around the library’s MeshBVH class with some additional specific functionality.

The speckle viewer uses a dual level BVH for optimal acceleration. The AccelerationStructure is the functional element of the bottom-level acceleration structure. Each individual object will have it’s own BVH, encapsulated by an AccelerationStructure object.

Constructors

constructor

constructor(bvh: MeshBVH)

Populates/constructs this acceleration structure with the backing BVH.

Parameters:

• bvh: The backing BVH as a MeshBVH

Accessors

bvh

get bvh(): MeshBVH

Gets the backing BVH.

Returns: MeshBVH

geometry

get geometry(): BufferGeometry

Gets the three.js geometry associated to the BVH.

When building a BVH, three-mesh-bvh library needs a three.js geometry as input. This is that geometry. We don’t use it for rendering.

Returns: BufferGeometry

Methods

buildBVH

static buildBVH(
    indices: number[],
    position: Float32Array,
    options: BVHOptions = DefaultBVHOptions,
    transform?: Matrix4
): MeshBVH

Build a BVH using the provided geometry data.

Parameters:

• indices: Geometry indices
• position: Geometry vertex positions
• options: BVHOptions
• optional transform: A Matrix4 that transforms the geometry data before building the BVH

Returns: MeshBVH

getBoundingBox

getBoundingBox(target?: Box3): Box3

Gets the aabb of the entire BVH.

Parameters:

• optional target: Box3

Returns: Box3

getVertexAtIndex

getVertexAtIndex(index: number): Vector3

Gets position value of a vertex at the given index inside the BVH vertex position array.

Parameters:

• index: number

Returns: Vector3

raycast

raycast(
    ray: Ray,
    materialOrSide: Side | Material | Material[] = FrontSide
): Intersection<Object3D<Event>>[]

Wrapper over three-mesh-bvh raycast function. Keeps original behavior,but makes sure input and output spaces are correct.

Parameters:

• ray: Ray to intersect with
• materialOrSide: Side | Material | Material[]

Returns: Intersection

raycastFirst

raycastFirst(
    ray: Ray,
    materialOrSide: Side | Material | Material[] = FrontSide
): Intersection<Object3D<Event>>[]

Identical to raycast but stops at first intersection found.

Parameters:

• ray: Ray to intersect with
• materialOrSide: Side | Material | Material[]

Returns: Intersection

shapecast

shapecast(
    callbacks: {
      intersectsBounds: (
        box: Box3,
        isLeaf: boolean,
        score: number | undefined,
        depth: number,
        nodeIndex: number
      ) => ShapecastIntersection | boolean

      traverseBoundsOrder?: (box: Box3) => number
    } & (
      | {
          intersectsRange: (
            triangleOffset: number,
            triangleCount: number,
            contained: boolean,
            depth: number,
            nodeIndex: number,
            box: Box3
          ) => boolean
        }
      | {
          intersectsTriangle: (
            triangle: ExtendedTriangle,
            triangleIndex: number,
            contained: boolean,
            depth: number
          ) => boolean | void
        }
    )
  ): boolean

Generic mechanism to intersect the BVH with various shapes/objects. The callbacks provide granular access to several stages of the BVH intersection process.

Parameters:

• callbacks: More details here

Returns: boolean

transformInput

transformInput<T extends Vector3 | Ray | Box3>(input: T): T

Transform input vector, ray or box from world space into the acceleration structure’s space.

All the AccelerationStructure methods that deal with querying the BVH: getBoundingBox, getVertexAtIndex, raycast, raycastFirst, shapecast already call this function implicitly.

Parameters:

• input: Vector3 | Ray | Box3

Returns: Vector3 | Ray | Box3

transformOutput

transformOutput<T extends Vector3 | Ray | Box3>(output: T): T

Transform input vector, ray or box from the acceleration structure’s space into world space.

Parameters:

• input: Vector3 | Ray | Box3
  All the AccelerationStructure methods that deal with querying the BVH: getBoundingBox, getVertexAtIndex, raycast, raycastFirst, shapecast already call this function implicitly.

Returns: Vector3 | Ray | Box3

Typedefs

VectorLike

type VectorLike = { x: number; y: number; z?: number; w?: number }

Archtype for Vector2, Vector3 and Vector4.

BVHOptions

interface BVHOptions {
  strategy: SplitStrategy
  maxDepth: number
  maxLeafTris: number
  verbose: boolean
  useSharedArrayBuffer: boolean
  setBoundingBox: boolean
  onProgress?: () => void
  [SKIP_GENERATION]: boolean
}

Based off the original options defined in three-mesh-bvh