Speckle Docs

# TopLevelAccelerationStructure

The viewer is using three-mesh-bvh (opens new window) as the backbone for it's BVH implementation. The AccelerationStructure class is a thin wrapper around the library's MeshBVH (opens new window) 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

#

Properties

accelerationStructure

#

Methods

getBoundingBox raycast raycastFirst refit shapecast

#

Typedefs

ExtendedIntersection ExtendedShapeCastCallbacks

#

Constructors

# constructor

constructor(batchObjects: BatchObject[])
1

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;
1

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

WARNING

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

# getBoundingBox

getBoundingBox(target?: Box3): Box3
1

Gets the aabb of the entire top level BVH.

Parameters

Returns: Box3 (opens new window)

# raycast

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

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

Returns: ExtendedIntersection

# raycastFirst

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

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

Returns: ExtendedIntersection

# raycastFirst

refit(): void
1

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

TIP

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

Returns: void

# shapecast

shapecast(callbacks: ExtendedShapeCastCallbacks): boolean
1

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

Returns: boolean

#

Typedefs

# ExtendedIntersection

interface ExtendedIntersection extends Intersection {
  batchObject?: BatchObject;
  material?: Material;
}
1
2
3
4

Extension of three.js's default Intersection.

# 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;
    }
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

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

← Viewer →