TopLevelAccelerationStructure

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 TopLevelAccelerationStructure is a BVH comprised of several other BVHs. Each viewer batch will have a single top level acceleration structure containing all the BVHs of the individual objects that make up the batch.

Constructors

constructor

constructor(batchObjects: BatchObject[])

Populates/constructs this top level acceleration structure with the group of objects that comprise it.

Parameters:

• batchObjects: The group of BatchObjects that will make up this top level acceleration structure

Properties

accelerationStructure

accelerationStructure: AccelerationStructure

The top-level AccelerationStructure built on top of the group of bottom-level BVHs.

The top-level acceleration structure does not have it’s own transformation space. It’s identical to the world space. Unlike the bottom-level acceleration structure which is always centered around the world origin.

Returns: AccelerationStructure

Methods

closestPointToPoint

closestPointToPoint(point: Vector3): HitPointInfo | null

Returns the closest point on the BVH to the provided argument

Parameters:

• point: Vector3 The point in space we want to find the closest point in the BVH to

Returns: HitPointInfo

getBoundingBox

getBoundingBox(target?: Box3): Box3

Gets the aabb of the entire top level BVH.

Parameters:

• optional target: Box3

Returns: Box3

raycast

raycast(
    ray: Ray,
    materialOrSide: Side | Material | Material[] = FrontSide
): ExtendedIntersection[]

Wrapper over three-mesh-bvh raycast function. Queries the top-level BVH first, then if it finds intersections, it goes down to the bottom-level BVHs and raycasts against them.

Parameters:

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

Returns: ExtendedIntersection

raycastFirst

raycastFirst(
    ray: Ray,
    materialOrSide: Side | Material | Material[] = FrontSide
): ExtendedIntersection

Identical to raycast but stops at first intersection found. Queries the top-level BVH first, then if it finds intersections, it goes down to the bottom-level BVHs and raycasts against them.

Parameters:

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

Returns: ExtendedIntersection

refit

refit(): void

Rebuilds the top level acceleration structure. Whenever any of the comprising batch objects update their transfromation, a refit needs to be called.

refit is called automatically whenever any of the comprising BatchObjects update their transformation.

Returns: void

shapecast

shapecast(callbacks: ExtendedShapeCastCallbacks): boolean

Generic mechanism to intersect the BVH with various shapes/objects. The callbacks provide granular access to several stages of both the top-level BVH and bottom-level BVH intersection process.

Parameters:

• callbacks: ExtendedShapeCastCallbacks

Returns: boolean

Typedefs

ExtendedShapeCastCallbacks

type ExtendedShapeCastCallbacks = {
  intersectsTAS?: (
    box: Box3,
    isLeaf: boolean,
    score: number | undefined,
    depth: number,
    nodeIndex: number
  ) => ShapecastIntersection | boolean
  intersectTASRange?: (batchObject: BatchObject) => ShapecastIntersection | boolean
  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,
        batchObject?: BatchObject
      ) => boolean | void
    }
)

Extension of three-mesh-bvh shapecast callbacks with the addition of top level acceleration structure stages.