@aibee/owlly 1.0.26 → 1.0.29

package/lib/owlly/utils/bvh-tree.js

@@ -0,0 +1,539 @@
+/**
+ * bvh-tree
+ * A Bounding Volume Hierarchy data structure implementation.
+ * https://github.com/benraziel/bvh-tree
+ *
+ * 该文件是外部引入的类, 用于创建 FloorModel 的 BVH 树
+ *
+ * @author Ben Raziel
+  * @ignore
+ */
+import { Externals } from '../stage/externals';
+/**
+ * A node in the [[BVHTree]] structure
+ *
+ */
+class BVHNode {
+    /**
+      * Constructor of BVHNode
+      * @param {Point} extentsMin the min coords of this node's bounding box ({x,y,z})
+      * @param {Point} extentsMax the max coords of this node's bounding box ({x,y,z})
+      * @param {number} startIndex an index in the bbox array, where the first element of this node is located
+      * @param {number} endIndex an index in the bbox array, where the last of this node is located,
+      * plus 1 (meaning that its non-inclusive).
+      * @param {number} the distance of this node from the root for the bvh tree. root node has level=0,
+      * its children have level=1 etc.
+      */
+    constructor(extentsMin, extentsMax, startIndex, endIndex, level) {
+        this.extentsMin = extentsMin;
+        this.extentsMax = extentsMax;
+        this.startIndex = startIndex;
+        this.endIndex = endIndex;
+        this.level = level;
+        this.node0 = null;
+        this.node1 = null;
+    }
+    elementCount() {
+        return this.endIndex - this.startIndex;
+    }
+    centerX() {
+        return (this.extentsMin.x + this.extentsMax.x) * 0.5;
+    }
+    centerY() {
+        return (this.extentsMin.y + this.extentsMax.y) * 0.5;
+    }
+    centerZ() {
+        return (this.extentsMin.z + this.extentsMax.z) * 0.5;
+    }
+    clearShapes() {
+        this.startIndex = -1;
+        this.endIndex = -1;
+    }
+    calcBoundingSphereRadius(extentsMin, extentsMax) {
+        const centerX = (extentsMin.x + extentsMax.x) * 0.5;
+        const centerY = (extentsMin.y + extentsMax.y) * 0.5;
+        const centerZ = (extentsMin.z + extentsMax.z) * 0.5;
+        const extentsMinDistSqr = (centerX - extentsMin.x) * (centerX - extentsMin.x)
+            + (centerY - extentsMin.y) * (centerY - extentsMin.y)
+            + (centerZ - extentsMin.z) * (centerZ - extentsMin.z);
+        const extentsMaxDistSqr = (centerX - extentsMax.x) * (centerX - extentsMax.x)
+            + (centerY - extentsMax.y) * (centerY - extentsMax.y)
+            + (centerZ - extentsMax.z) * (centerZ - extentsMax.z);
+        return Math.sqrt(Math.max(extentsMinDistSqr, extentsMaxDistSqr));
+    }
+}
+/**
+ * BVH树
+ */
+class BVHTree {
+    /**
+     * 创建BVH树对象
+     * @param {Vector3[][]} triangles 三角形数组，BVH树基于此构建
+     * @param {number} maxTrianglesPerNode 每个树结点包含的最多三角形数量
+     */
+    constructor(triangles, maxTrianglesPerNode) {
+        const trianglesArray = [];
+        trianglesArray.length = triangles.length * 9;
+        for (let i = 0; i < triangles.length; i += 1) {
+            const p0 = triangles[i][0];
+            const p1 = triangles[i][1];
+            const p2 = triangles[i][2];
+            trianglesArray[i * 9] = p0.x;
+            trianglesArray[i * 9 + 1] = p0.y;
+            trianglesArray[i * 9 + 2] = p0.z;
+            trianglesArray[i * 9 + 3] = p1.x;
+            trianglesArray[i * 9 + 4] = p1.y;
+            trianglesArray[i * 9 + 5] = p1.z;
+            trianglesArray[i * 9 + 6] = p2.x;
+            trianglesArray[i * 9 + 7] = p2.y;
+            trianglesArray[i * 9 + 8] = p2.z;
+        }
+        this.trianglesArray = trianglesArray;
+        this.maxTrianglesPerNode = maxTrianglesPerNode || 10;
+        this.bboxArray = this.calcBoundingBoxes(trianglesArray);
+        // clone a helper array
+        this.bboxHelper = new Float32Array(this.bboxArray.length);
+        this.bboxHelper.set(this.bboxArray);
+        // create the root node, add all the triangles to it
+        const triangleCount = trianglesArray.length / 9;
+        const extents = this.calcExtents(0, triangleCount, BVHTree.EPSILON);
+        this.rootNode = new BVHNode(extents[0], extents[1], 0, triangleCount, 0);
+        this.nodesToSplit = [this.rootNode];
+        while (this.nodesToSplit.length > 0) {
+            const node = this.nodesToSplit.pop();
+            if (node) {
+                this.splitNode(node);
+            }
+        }
+    }
+    vector3SetFromArray(v, array, firstElementPos) {
+        v.set(array[firstElementPos], array[firstElementPos + 1], array[firstElementPos + 2]);
+    }
+    /**
+     * Returns a list of all the triangles in the BVH which interected a specific node.
+     * We use the BVH node structure to first cull out nodes which do not intereset the ray.
+     * For rays that did intersect, we test intersection of the ray with each triangle
+     * @param {Vector3} rayOrigin the origin position of the ray.
+     * @param {Vector3} rayDirection the direction vector of the ray.
+     * @param {boolean} backfaceCulling if 'true', only intersections with front-faces of the mesh will be performed.
+     * @return {{}[]} IntersectionResult an array of intersection result, one for each triangle which intersected the BVH，
+     * each item in the form of:
+     * {
+     *  triangle: Vector3[];
+     *  triangleIndex: number;
+     *  intersectionPoint: Vector3;
+     * }
+    */
+    intersectRay(rayOrigin, rayDirection, backfaceCulling) {
+        const nodesToIntersect = [this.rootNode];
+        const trianglesInIntersectingNodes = []; // a list of nodes that intersect the ray (according to their bounding box)
+        const intersectingTriangles = [];
+        let i;
+        const { THREE } = Externals.getInstance();
+        const invRayDirection = new THREE.Vector3(1.0 / rayDirection.x, 1.0 / rayDirection.y, 1.0 / rayDirection.z);
+        // go over the BVH tree, and extract the list of triangles that lie in nodes that intersect the ray.
+        // note: these triangles may not intersect the ray themselves
+        while (nodesToIntersect.length > 0) {
+            const node = nodesToIntersect.pop();
+            if (node) {
+                if (this.intersectNodeBox(rayOrigin, invRayDirection, node)) {
+                    if (node.node0) {
+                        nodesToIntersect.push(node.node0);
+                    }
+                    if (node.node1) {
+                        nodesToIntersect.push(node.node1);
+                    }
+                    for (i = node.startIndex; i < node.endIndex; i += 1) {
+                        trianglesInIntersectingNodes.push(this.bboxArray[i * 7]);
+                    }
+                }
+            }
+        }
+        // go over the list of candidate triangles, and check each of them using ray triangle intersection
+        const a = new THREE.Vector3();
+        const b = new THREE.Vector3();
+        const c = new THREE.Vector3();
+        const rayOriginVec3 = new THREE.Vector3(rayOrigin.x, rayOrigin.y, rayOrigin.z);
+        const rayDirectionVec3 = new THREE.Vector3(rayDirection.x, rayDirection.y, rayDirection.z);
+        for (i = 0; i < trianglesInIntersectingNodes.length; i += 1) {
+            const triIndex = trianglesInIntersectingNodes[i];
+            this.vector3SetFromArray(a, this.trianglesArray, triIndex * 9);
+            this.vector3SetFromArray(b, this.trianglesArray, triIndex * 9 + 3);
+            this.vector3SetFromArray(c, this.trianglesArray, triIndex * 9 + 6);
+            const intersectionPoint = this.intersectRayTriangle(a, b, c, rayOriginVec3, rayDirectionVec3, backfaceCulling || false);
+            if (intersectionPoint) {
+                intersectingTriangles.push({
+                    triangle: [a.clone(), b.clone(), c.clone()],
+                    triangleIndex: triIndex,
+                    intersectionPoint,
+                });
+            }
+        }
+        return intersectingTriangles;
+    }
+    /**
+     * 获得与指定射线方向相交的最接近射线起点的相交结果
+     * @param rayOrigin 射线起点
+     * @param rayDirection 射线方向
+     * @param backfaceCulling 可选，是否忽略背面
+     */
+    nearestIntersection(rayOrigin, rayDirection, backfaceCulling) {
+        const direction = rayDirection.clone().normalize();
+        const results = this.intersectRay(rayOrigin, direction, backfaceCulling);
+        if (results.length === 0)
+            return null;
+        let ret = null;
+        let minDist = Number.MAX_VALUE;
+        for (let i = 0; i < results.length; i += 1) {
+            const item = results[i];
+            const dist = item.intersectionPoint.clone().sub(rayOrigin).dot(direction);
+            if (dist >= 0.0 && dist < minDist) {
+                ret = item;
+                minDist = dist;
+            }
+        }
+        return ret;
+    }
+    calcBoundingBoxes(trianglesArray) {
+        let p0x;
+        let p0y;
+        let p0z;
+        let p1x;
+        let p1y;
+        let p1z;
+        let p2x;
+        let p2y;
+        let p2z;
+        let minX;
+        let minY;
+        let minZ;
+        let maxX;
+        let maxY;
+        let maxZ;
+        const triangleCount = trianglesArray.length / 9;
+        const bboxArray = new Float32Array(triangleCount * 7);
+        for (let i = 0; i < triangleCount; i += 1) {
+            p0x = trianglesArray[i * 9];
+            p0y = trianglesArray[i * 9 + 1];
+            p0z = trianglesArray[i * 9 + 2];
+            p1x = trianglesArray[i * 9 + 3];
+            p1y = trianglesArray[i * 9 + 4];
+            p1z = trianglesArray[i * 9 + 5];
+            p2x = trianglesArray[i * 9 + 6];
+            p2y = trianglesArray[i * 9 + 7];
+            p2z = trianglesArray[i * 9 + 8];
+            minX = Math.min(Math.min(p0x, p1x), p2x);
+            minY = Math.min(Math.min(p0y, p1y), p2y);
+            minZ = Math.min(Math.min(p0z, p1z), p2z);
+            maxX = Math.max(Math.max(p0x, p1x), p2x);
+            maxY = Math.max(Math.max(p0y, p1y), p2y);
+            maxZ = Math.max(Math.max(p0z, p1z), p2z);
+            this.setBox(bboxArray, i, i, minX, minY, minZ, maxX, maxY, maxZ);
+        }
+        return bboxArray;
+    }
+    setBox(bboxArray, pos, triangleId, minX, minY, minZ, maxX, maxY, maxZ) {
+        bboxArray[pos * 7] = triangleId;
+        bboxArray[pos * 7 + 1] = minX;
+        bboxArray[pos * 7 + 2] = minY;
+        bboxArray[pos * 7 + 3] = minZ;
+        bboxArray[pos * 7 + 4] = maxX;
+        bboxArray[pos * 7 + 5] = maxY;
+        bboxArray[pos * 7 + 6] = maxZ;
+    }
+    copyBox(sourceArray, sourcePos, destArray, destPos) {
+        destArray[destPos * 7] = sourceArray[sourcePos * 7];
+        destArray[destPos * 7 + 1] = sourceArray[sourcePos * 7 + 1];
+        destArray[destPos * 7 + 2] = sourceArray[sourcePos * 7 + 2];
+        destArray[destPos * 7 + 3] = sourceArray[sourcePos * 7 + 3];
+        destArray[destPos * 7 + 4] = sourceArray[sourcePos * 7 + 4];
+        destArray[destPos * 7 + 5] = sourceArray[sourcePos * 7 + 5];
+        destArray[destPos * 7 + 6] = sourceArray[sourcePos * 7 + 6];
+    }
+    // private getBox(bboxArray: Float32Array, pos: number,
+    //   outputBox: {triangleId: number;
+    //     minX: number; minY: number; minZ: number;
+    //     maxX: number; maxY: number; maxZ: number;
+    //   }): void {
+    //   outputBox.triangleId = bboxArray[pos * 7];
+    //   outputBox.minX = bboxArray[pos * 7 + 1];
+    //   outputBox.minY = bboxArray[pos * 7 + 2];
+    //   outputBox.minZ = bboxArray[pos * 7 + 3];
+    //   outputBox.maxX = bboxArray[pos * 7 + 4];
+    //   outputBox.maxY = bboxArray[pos * 7 + 5];
+    //   outputBox.maxZ = bboxArray[pos * 7 + 6];
+    // }
+    calcExtents(startIndex, endIndex, _expandBy) {
+        const expandBy = _expandBy || 0.0;
+        const { THREE } = Externals.getInstance();
+        if (startIndex >= endIndex) {
+            return [new THREE.Vector3(0, 0, 0), new THREE.Vector3(0, 0, 0)];
+        }
+        let minX = Number.MAX_VALUE;
+        let minY = Number.MAX_VALUE;
+        let minZ = Number.MAX_VALUE;
+        let maxX = -Number.MAX_VALUE;
+        let maxY = -Number.MAX_VALUE;
+        let maxZ = -Number.MAX_VALUE;
+        for (let i = startIndex; i < endIndex; i += 1) {
+            minX = Math.min(this.bboxArray[i * 7 + 1], minX);
+            minY = Math.min(this.bboxArray[i * 7 + 2], minY);
+            minZ = Math.min(this.bboxArray[i * 7 + 3], minZ);
+            maxX = Math.max(this.bboxArray[i * 7 + 4], maxX);
+            maxY = Math.max(this.bboxArray[i * 7 + 5], maxY);
+            maxZ = Math.max(this.bboxArray[i * 7 + 6], maxZ);
+        }
+        return [
+            new THREE.Vector3(minX - expandBy, minY - expandBy, minZ - expandBy),
+            new THREE.Vector3(maxX + expandBy, maxY + expandBy, maxZ + expandBy),
+        ];
+    }
+    splitNode(node) {
+        if ((node.elementCount() <= this.maxTrianglesPerNode) || (node.elementCount() === 0)) {
+            return;
+        }
+        const { startIndex, endIndex } = node;
+        const leftNode = [new Array(), new Array(), new Array()];
+        const rightNode = [new Array(), new Array(), new Array()];
+        const extentCenters = [node.centerX(), node.centerY(), node.centerZ()];
+        const extentsLength = [
+            node.extentsMax.x - node.extentsMin.x,
+            node.extentsMax.y - node.extentsMin.y,
+            node.extentsMax.z - node.extentsMin.z,
+        ];
+        const objectCenter = [];
+        objectCenter.length = 3;
+        for (let i = startIndex; i < endIndex; i += 1) {
+            objectCenter[0] = (this.bboxArray[i * 7 + 1] + this.bboxArray[i * 7 + 4]) * 0.5; // center = (min + max) / 2
+            objectCenter[1] = (this.bboxArray[i * 7 + 2] + this.bboxArray[i * 7 + 5]) * 0.5; // center = (min + max) / 2
+            objectCenter[2] = (this.bboxArray[i * 7 + 3] + this.bboxArray[i * 7 + 6]) * 0.5; // center = (min + max) / 2
+            for (let j = 0; j < 3; j += 1) {
+                if (objectCenter[j] < extentCenters[j]) {
+                    leftNode[j].push(i);
+                }
+                else {
+                    rightNode[j].push(i);
+                }
+            }
+        }
+        // check if we couldn't split the node by any of the axes (x, y or z). halt here,
+        // dont try to split any more (cause it will always fail, and we'll enter an infinite loop
+        const splitFailed = [];
+        splitFailed.length = 3;
+        splitFailed[0] = (leftNode[0].length === 0) || (rightNode[0].length === 0);
+        splitFailed[1] = (leftNode[1].length === 0) || (rightNode[1].length === 0);
+        splitFailed[2] = (leftNode[2].length === 0) || (rightNode[2].length === 0);
+        if (splitFailed[0] && splitFailed[1] && splitFailed[2]) {
+            return;
+        }
+        // choose the longest split axis. if we can't split by it, choose next best one.
+        const splitOrder = [0, 1, 2];
+        splitOrder.sort((axis0, axis1) => (extentsLength[axis1] - extentsLength[axis0]));
+        let leftElements;
+        let rightElements;
+        for (let j = 0; j < 3; j += 1) {
+            const candidateIndex = splitOrder[j];
+            if (!splitFailed[candidateIndex]) {
+                leftElements = leftNode[candidateIndex];
+                rightElements = rightNode[candidateIndex];
+                break;
+            }
+        }
+        // sort the elements in range (startIndex, endIndex) according to which node they should be at
+        const node0Start = startIndex;
+        const node0End = node0Start + (leftElements !== undefined ? leftElements.length : 0);
+        const node1Start = node0End;
+        const node1End = endIndex;
+        let currElement;
+        let helperPos = node.startIndex;
+        let concatenatedElements = [];
+        if (leftElements) {
+            concatenatedElements = leftElements;
+        }
+        if (rightElements) {
+            concatenatedElements = concatenatedElements.concat(rightElements);
+        }
+        for (let i = 0; i < concatenatedElements.length; i += 1) {
+            currElement = concatenatedElements[i];
+            this.copyBox(this.bboxArray, currElement, this.bboxHelper, helperPos);
+            helperPos += 1;
+        }
+        // copy results back to main array
+        const subArr = this.bboxHelper.subarray(node.startIndex * 7, node.endIndex * 7);
+        this.bboxArray.set(subArr, node.startIndex * 7);
+        // create 2 new nodes for the node we just split, and add links to them from the parent node
+        const node0Extents = this.calcExtents(node0Start, node0End, BVHTree.EPSILON);
+        const node1Extents = this.calcExtents(node1Start, node1End, BVHTree.EPSILON);
+        const node0 = new BVHNode(node0Extents[0], node0Extents[1], node0Start, node0End, node.level + 1);
+        const node1 = new BVHNode(node1Extents[0], node1Extents[1], node1Start, node1End, node.level + 1);
+        node.node0 = node0;
+        node.node1 = node1;
+        node.clearShapes();
+        // add new nodes to the split queue
+        this.nodesToSplit.push(node0);
+        this.nodesToSplit.push(node1);
+    }
+    calcTValues(minVal, maxVal, rayOriginCoord, invdir) {
+        const res = { min: 0, max: 0 };
+        if (invdir >= 0) {
+            res.min = (minVal - rayOriginCoord) * invdir;
+            res.max = (maxVal - rayOriginCoord) * invdir;
+        }
+        else {
+            res.min = (maxVal - rayOriginCoord) * invdir;
+            res.max = (minVal - rayOriginCoord) * invdir;
+        }
+        return res;
+    }
+    intersectNodeBox(rayOrigin, invRayDirection, node) {
+        const t = this.calcTValues(node.extentsMin.x, node.extentsMax.x, rayOrigin.x, invRayDirection.x);
+        const ty = this.calcTValues(node.extentsMin.y, node.extentsMax.y, rayOrigin.y, invRayDirection.y);
+        if ((t.min > ty.max) || (ty.min > t.max)) {
+            return false;
+        }
+        // These lines also handle the case where tmin or tmax is NaN
+        // (result of 0 * Infinity). x !== x returns true if x is NaN
+        if (ty.min > t.min || Number.isNaN(t.min)) {
+            t.min = ty.min;
+        }
+        if (ty.max < t.max || Number.isNaN(t.max)) {
+            t.max = ty.max;
+        }
+        const tz = this.calcTValues(node.extentsMin.z, node.extentsMax.z, rayOrigin.z, invRayDirection.z);
+        if ((t.min > tz.max) || (tz.min > t.max)) {
+            return false;
+        }
+        if (tz.min > t.min || Number.isNaN(t.min)) {
+            t.min = tz.min;
+        }
+        if (tz.max < t.max || Number.isNaN(t.max)) {
+            t.max = tz.max;
+        }
+        // return point closest to the ray (positive side)
+        if (t.max < 0) {
+            return false;
+        }
+        return true;
+    }
+    intersectRayTriangle(a, b, c, rayOrigin, rayDirection, backfaceCulling) {
+        const { THREE } = Externals.getInstance();
+        // Compute the offset origin, edges, and normal.
+        const diff = new THREE.Vector3();
+        const edge1 = new THREE.Vector3();
+        const edge2 = new THREE.Vector3();
+        const normal = new THREE.Vector3();
+        // from http://www.geometrictools.com/LibMathematics/Intersection/Wm5IntrRay3Triangle3.cpp
+        edge1.subVectors(b, a);
+        edge2.subVectors(c, a);
+        normal.crossVectors(edge1, edge2);
+        // Solve Q + t*D = b1*E1 + bL*E2 (Q = kDiff, D = ray direction,
+        // E1 = kEdge1, E2 = kEdge2, N = Cross(E1,E2)) by
+        //   |Dot(D,N)|*b1 = sign(Dot(D,N))*Dot(D,Cross(Q,E2))
+        //   |Dot(D,N)|*b2 = sign(Dot(D,N))*Dot(D,Cross(E1,Q))
+        //   |Dot(D,N)|*t = -sign(Dot(D,N))*Dot(Q,N)
+        let DdN = rayDirection.dot(normal);
+        let sign;
+        if (DdN > 0) {
+            if (backfaceCulling) {
+                return null;
+            }
+            sign = 1;
+        }
+        else if (DdN < 0) {
+            sign = -1;
+            DdN = -DdN;
+        }
+        else {
+            return null;
+        }
+        diff.subVectors(rayOrigin, a);
+        const DdQxE2 = sign * rayDirection.dot(edge2.crossVectors(diff, edge2));
+        // b1 < 0, no intersection
+        if (DdQxE2 < 0) {
+            return null;
+        }
+        const DdE1xQ = sign * rayDirection.dot(edge1.cross(diff));
+        // b2 < 0, no intersection
+        if (DdE1xQ < 0) {
+            return null;
+        }
+        // b1+b2 > 1, no intersection
+        if (DdQxE2 + DdE1xQ > DdN) {
+            return null;
+        }
+        // Line intersects triangle, check if ray does.
+        const QdN = -sign * diff.dot(normal);
+        // t < 0, no intersection
+        if (QdN < 0) {
+            return null;
+        }
+        // Ray intersects triangle.
+        const t = QdN / DdN;
+        const result = new THREE.Vector3();
+        return result.copy(rayDirection).multiplyScalar(t).add(rayOrigin);
+    }
+    static addTriangles(triangles, threeObj) {
+        // threeObj.children.forEach((child: Object3D) => {
+        //   // console.info('#BVHTree# addTriangles child:', child);
+        //   this.addTriangles(triangles, child);
+        // });
+        const { THREE } = Externals.getInstance();
+        if (!(threeObj instanceof THREE.Mesh)) {
+            // console.log('#BVHTree# addTriangles returns');
+            return;
+        }
+        const threeMesh = threeObj;
+        const geometry = threeMesh.geometry;
+        // 获得顶点数组
+        const vertexArr = geometry.attributes.position.array;
+        // console.info('#BVHTree# vertexArray:', vertexArr);
+        // 获得索引数组
+        const indexArr = geometry.index ? geometry.index.array : null;
+        let triangleCount = 0;
+        if (indexArr) {
+            // 如果索引数组存在，利用索引数组和顶点数组构建bvhtree
+            triangleCount = indexArr.length / 3;
+            // console.log(`#BVHTree# addTriangles #0 triangleCount=${triangleCount}`);
+            // triangles.length = triangleCount;
+            for (let i = 0; i < triangleCount; i += 1) {
+                triangles.push([
+                    new THREE.Vector3(vertexArr[3 * indexArr[3 * i]], vertexArr[3 * indexArr[3 * i] + 1], vertexArr[3 * indexArr[3 * i] + 2]),
+                    new THREE.Vector3(vertexArr[3 * indexArr[3 * i + 1]], vertexArr[3 * indexArr[3 * i + 1] + 1], vertexArr[3 * indexArr[3 * i + 1] + 2]),
+                    new THREE.Vector3(vertexArr[3 * indexArr[3 * i + 2]], vertexArr[3 * indexArr[3 * i + 2] + 1], vertexArr[3 * indexArr[3 * i + 2] + 2]),
+                ]);
+            }
+        }
+        else {
+            // 如果索引数组不存在，通过顶点数组构建bvhtree
+            triangleCount = vertexArr.length / 9;
+            // console.log(`#BVHTree# addTriangles #1 triangleCount=${triangleCount}`);
+            // triangles.length = triangleCount;
+            for (let i = 0; i < triangleCount; i += 1) {
+                triangles.push([
+                    new THREE.Vector3(vertexArr[i * 9], vertexArr[i * 9 + 1], vertexArr[i * 9 + 2]),
+                    new THREE.Vector3(vertexArr[i * 9 + 3], vertexArr[i * 9 + 4], vertexArr[i * 9 + 5]),
+                    new THREE.Vector3(vertexArr[i * 9 + 6], vertexArr[i * 9 + 7], vertexArr[i * 9 + 8]),
+                ]);
+            }
+        }
+    }
+    /**
+    * 构建bvhtree
+    * @ignore
+    * @param {Object3D} threeObj 需要创建BVH树的Object3D根对象
+    * @returns {BVHTree}
+    */
+    static createBVHTree(threeObj) {
+        // threeObj.updateWorldMatrix(false, true);
+        const triangles = [];
+        // this.addTriangles(triangles, threeObj);
+        threeObj.traverse((obj) => {
+            this.addTriangles(triangles, obj);
+        });
+        // console.info('#BVHTree# triangles:', triangles);
+        const bvh = new BVHTree(triangles, 7);
+        return bvh;
+    }
+}
+BVHTree.EPSILON = 1e-6;
+export { BVHTree, BVHNode };

package/lib/owlly/utils/camera.d.ts

@@ -0,0 +1,37 @@
+import { NS_THREE } from '../stage/externals';
+import { Camera as CameraElement } from '../element/camera';
+/**
+ * 相机相关的工具, 提供各类相机的工具函数
+ */
+declare class Camera {
+    /**
+     * 根据 Spherical Coordinate 确定 lookAt 坐标
+     * @param param0 相机坐标
+     * @param yaw 相机当前 yaw
+     * @param pitch 相机当前 pitch
+     * @returns 看向的方向与俯瞰时与 X 轴的夹角
+     */
+    static getCameraLookAtPositionByYawPitch({ x, y, z }: {
+        x: number;
+        y: number;
+        z: number;
+    }, yaw: number, pitch: number): {
+        position: NS_THREE.Vector3;
+        degree: number;
+    };
+    /**
+     * 根据 yaw pitch 设置相机的朝向
+     * @param camera 相机元素
+     */
+    static setCameraLookAtByYawPitch(camera: CameraElement): void;
+    /**
+     * 根据相机朝向获取 yaw pitch
+     * @param v 方向向量
+     * @returns yaw 与 pitch
+     */
+    static getYawPitchFromCameraLookVector(v: NS_THREE.Vector3): {
+        yaw: number;
+        pitch: number;
+    };
+}
+export { Camera };

package/lib/owlly/utils/camera.js

@@ -0,0 +1,50 @@
+import { Externals } from '../stage/externals';
+/**
+ * 相机相关的工具, 提供各类相机的工具函数
+ */
+class Camera {
+    /**
+     * 根据 Spherical Coordinate 确定 lookAt 坐标
+     * @param param0 相机坐标
+     * @param yaw 相机当前 yaw
+     * @param pitch 相机当前 pitch
+     * @returns 看向的方向与俯瞰时与 X 轴的夹角
+     */
+    static getCameraLookAtPositionByYawPitch({ x, y, z }, yaw, pitch) {
+        /**
+         * up = (0, 0, 1)
+         * ( pitch,   yaw) => (x, y, z)
+         * (     0,     0) => (1, 0, 0)
+         * (  pi/2,     0) => (0, 0, 1)
+         * (     0,  pi/2) => (1, 0, 0)
+         */
+        const xyLen = Math.cos(pitch / 180 * Math.PI);
+        const dx = xyLen * Math.sin(-yaw / 180 * Math.PI);
+        const dy = xyLen * Math.cos(yaw / 180 * Math.PI);
+        const dz = Math.sin(pitch / 180 * Math.PI);
+        const { THREE } = Externals.getInstance();
+        return {
+            position: new THREE.Vector3(x + dx, y + dy, z + dz),
+            degree: yaw,
+        };
+    }
+    /**
+     * 根据 yaw pitch 设置相机的朝向
+     * @param camera 相机元素
+     */
+    static setCameraLookAtByYawPitch(camera) {
+        const { position } = Camera.getCameraLookAtPositionByYawPitch(camera.position.clone(), camera.getYaw(), camera.getPitch());
+        camera.lookAt(position, 0, 0, false);
+    }
+    /**
+     * 根据相机朝向获取 yaw pitch
+     * @param v 方向向量
+     * @returns yaw 与 pitch
+     */
+    static getYawPitchFromCameraLookVector(v) {
+        const pitch = Math.asin(v.z) / Math.PI * 180;
+        const yaw = -Math.atan2(v.x, v.y) / Math.PI * 180;
+        return { yaw, pitch };
+    }
+}
+export { Camera };

package/lib/owlly/utils/cube-texture-cache.d.ts

@@ -0,0 +1,25 @@
+import { NS_THREE } from '../stage/externals';
+declare class CubeTextureCache {
+    private cubeTextureCache;
+    private workingTasks;
+    static sharedInstance: CubeTextureCache;
+    static disposeAll(): void;
+    dispose(): void;
+    constructor(capacity: number);
+    /**
+     * @ignore
+     * 获取立方体贴图，先从缓存中获取，若未命中则异步加载立方体贴图
+     * @param cubeTextureURLs 立方体贴图六个面的图像URL数组
+     */
+    loadCubeTexture(cubeTextureURLs: string[], cacheAnyway?: boolean, recycleIntermediateTextures?: boolean): Promise<NS_THREE.CubeTexture>;
+    /**
+     * 获取一组立方体贴图，若没命中则异步加载
+     * @param textureURLsArray 需要获取的立方体贴图URL数组，其每个元素是一个6元素的数组，表示一个立方体贴图的六个面
+     * @param waitForReadyCount 指定函数必须在textureURLsArray中的前多少个立方体贴图获取到以后才能返回
+     * 比如在即将显示一个全景点时，指定必须等指定全景点的立方体贴图获取到后才能返回，而其周围全景点可以同时预加载但不用等
+     */
+    preloadCubeTextures(textureURLsArray: (string[] | undefined)[], waitForReadyCount: number, recycleIntermediateTextures?: boolean[]): Promise<NS_THREE.CubeTexture[]>;
+    recycleCubeTexture(cubeTextureURLs: string[]): void;
+    getCapacity(): number;
+}
+export { CubeTextureCache };