@geoblocks/cesium-bvh 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020-present, camptocamp SA
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# Bounding volume hierarchy for triangles
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rays and nearest-point queries against a triangle soup: the nearest hit along a ray, whether any lies within a distance, how many, every
+one, and the closest triangle to a point; and, over line segments, those near a point or in a box. Flat typed arrays (a worker takes them as they are), no dependency: not Cesium, not three.js, not the
+DOM. It serves a CesiumJS scene's picking, collisions and measuring, and anything else that asks questions of triangles.
+
+- nodes packed depth first in typed arrays, the left child right after its parent
+- a split chosen over binned surface areas (SAH); a ray walks the near child first, and a query that wants any hit stops at the first
+- a ray hits both sides of a face; the least distance from its start, 0.1 mm by default, is yours to set (a negative one, `-Infinity`, counts a hit at the start)
+- a hint (the triangle that blocked the last ray) is tried first: the rays of a point toward a sun five minutes on are near each other
+
+## Installation
+
+```bash
+npm i --save @geoblocks/cesium-bvh
+```
+
+## Usage
+
+```js
+import {buildBvh, bvhQueries} from '@geoblocks/cesium-bvh';
+
+// a triangle each, nine numbers: its first corner, then its two edges from it (`trianglesOf(groups)` makes them of groups
+// of `{vertices, triangles}`: x, y, z a vertex, three indices a triangle)
+const tris = Float64Array.of(-5, -5, 0, 10, 0, 0, 0, 10, 0);
+const bvh = buildBvh(tris);                  // a subset of the triangles by number: buildBvh(tris, [0, 2, 5])
+const queries = bvhQueries(bvh, {min: 0.01}); // a ray starting on a surface is not to hit it
+
+queries.nearest(0, 0, 3, 0, 0, -1, 100);     // 3, the distance of the nearest hit within 100 m, or Infinity
+queries.nearestHit(0, 0, 3, 0, 0, -1, 100);  // {triangle: 0, distance: 3}, the same with its triangle, or undefined
+queries.any(0, 0, 3, 0, 0, -1, 100);         // 0, the number of a triangle hit, or -1
+queries.count(0, 0, 3, 0, 0, -1, 100, 6);    // 1, the hits, counted to 6
+queries.hits(0, 0, 3, 0, 0, -1, 100);        // [3], every hit, nearest first
+queries.closest(0, 0, 0.5, 2);               // {triangle: 0, distance: 0.5, point: [0, 0, 0]}, the nearest triangle within 2 m and its nearest point, or undefined
+```
+
+Line segments (edges), a tree of their own:
+
+```js
+import {buildSegmentBvh, segmentQueries} from '@geoblocks/cesium-bvh';
+
+const segments = Float64Array.of(0, 0, 0, 1, 0, 0,   5, 5, 5, 6, 5, 5);   // a segment each, six numbers: its two ends
+const edges = segmentQueries(buildSegmentBvh(segments));
+
+edges.near(5.5, 5, 5.05, 0.1);                       // [1], the segments within 0.1 m of a point
+edges.overlapping(-1, -1, -1, 0.5, 1, 1);            // [0], those whose boxes meet a box
+```
+
+Triangles that moved (a piece dragged, a door opened), the tree kept: its boxes made again from the leaves up, in place, a few milliseconds for 45,000 triangles (a build takes 130):
+
+```js
+refitBvh(bvh, movedTris);   // the same triangles, the same numbers, new places; `queries` made of `bvh` follow
+```
+
+The tree is plain arrays (`bounds`, `meta`, `data`, `ids`): send them to a worker, and make the queries there.
+
+## Not here
+
+- A tree that restructures as triangles move: `refitBvh` keeps the shape, so it answers right but slower the farther triangles have gone; rebuild it then.
+- Triangles by a box, a sphere or a capsule: the arrays are laid out to walk, as `closest` and the segments' queries do.

package/dist/cesium-bvh.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The tree over some triangles.
+ * @param {Float64Array} tris A triangle each, nine numbers: its first corner, then its two edges from it.
+ * @param {Int32Array | number[]} [ids] The triangles to take; all by default.
+ * @param {{leaf?: number}} [options] `leaf`: the most triangles a leaf holds.
+ * @return {{bounds: Float64Array, meta: Int32Array, data: Float64Array, ids: Int32Array, nodes: number}} A node's box (six numbers) and
+ *   `meta` (three: a leaf's first triangle and its count, else its right child, 0, its split axis); `data` the triangles in leaf order
+ *   (the tris' layout), `ids` their numbers in `tris`.
+ */
+export declare function buildBvh(tris: Float64Array, ids?: Int32Array | number[], { leaf }?: {
+    leaf?: number;
+}): {
+    bounds: Float64Array;
+    meta: Int32Array;
+    data: Float64Array;
+    ids: Int32Array;
+    nodes: number;
+};
+/**
+ * The triangles of groups of vertices and indices, as `buildBvh` takes them: nine numbers each, a corner and its two edges from it, the
+ * groups' triangles one after the other, so a triangle's number is its place in the groups' order.
+ * @param {{vertices: ArrayLike<number>, triangles: ArrayLike<number>}[]} groups x, y, z a vertex; three indices a triangle.
+ * @param {Float64Array} [result] Of the right size: filled instead of a new array, for triangles that moved (`refitBvh`).
+ * @return {Float64Array}
+ */
+export declare function trianglesOf(groups: {
+    vertices: ArrayLike<number>;
+    triangles: ArrayLike<number>;
+}[], result?: Float64Array): Float64Array;
+/**
+ * The tree kept for triangles that have moved: their new corners and edges taken, and every box made again from the leaves up, the
+ * tree's shape as it was. A few milliseconds for 45,000 triangles, where a build takes 130; the tree answers right at once, and
+ * the more the triangles have gone from where it was built for them the slower it answers (boxes grown to cover both places): build it
+ * again when many have moved far.
+ * @param {ReturnType<typeof buildBvh>} bvh A tree made by `buildBvh`, changed in place: the queries made of it follow.
+ * @param {Float64Array} tris The triangles the tree was built from, moved: the same layout and numbers.
+ * @return {ReturnType<typeof buildBvh>} The same tree.
+ */
+export declare function refitBvh(bvh: ReturnType<typeof buildBvh>, tris: Float64Array): ReturnType<typeof buildBvh>;
+/**
+ * The tree over some line segments, for `segmentQueries`.
+ * @param {Float64Array} segments A segment each, six numbers: its two ends.
+ * @param {Int32Array | number[]} [ids] The segments to take; all by default.
+ * @param {{leaf?: number}} [options] `leaf`: the most segments a leaf holds.
+ * @return {{bounds: Float64Array, meta: Int32Array, data: Float64Array, ids: Int32Array, nodes: number}} As `buildBvh`'s, `data` six numbers a segment.
+ */
+export declare function buildSegmentBvh(segments: Float64Array, ids?: Int32Array | number[], { leaf }?: {
+    leaf?: number;
+}): {
+    bounds: Float64Array;
+    meta: Int32Array;
+    data: Float64Array;
+    ids: Int32Array;
+    nodes: number;
+};
+/**
+ * The queries of a tree built by `buildBvh`: a ray from (px, py, pz) along the unit (dx, dy, dz), the triangles hit within `reach` meters,
+ * both sides of a face (a hit nearer than `min` is not one); the triangle nearest a point.
+ * @param {ReturnType<typeof buildBvh>} bvh
+ * @param {{min?: number}} [options] `min`: the least distance a hit is from the ray's start, 0.1 mm by default: a ray starting on a surface is
+ *   not to hit it. A negative one (`-Infinity`) lets a hit at the start count: a mover standing on a floor.
+ */
+export declare function bvhQueries({ bounds, meta, data, ids, nodes }: ReturnType<typeof buildBvh>, { min }?: {
+    min?: number;
+}): {
+    /** The distance to the nearest hit within `reach`, or Infinity. */
+    nearest(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ dx: number, /** @type {number} */ dy: number, /** @type {number} */ dz: number, /** @type {number} */ reach: number): number;
+    /** The nearest hit within `reach`: its triangle's number (in the `tris` the tree was built from) and its distance; none: undefined. */
+    nearestHit(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ dx: number, /** @type {number} */ dy: number, /** @type {number} */ dz: number, /** @type {number} */ reach: number): {
+        triangle: number;
+        distance: number;
+    } | undefined;
+    /**
+     * A triangle hit within `reach`, its number, or -1 if none is. `hint`, a triangle that blocked a ray before, is tried first: the rays of
+     * one point toward a sun five minutes on are near the last, and the same triangle most often stops them.
+     */
+    any(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ dx: number, /** @type {number} */ dy: number, /** @type {number} */ dz: number, /** @type {number} */ reach: number, /** @type {number} */ hint?: number): number;
+    /** How many triangles are hit within `reach`, to `cap`. */
+    count(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ dx: number, /** @type {number} */ dy: number, /** @type {number} */ dz: number, /** @type {number} */ reach: number, /** @type {number} */ cap?: number): number;
+    /** The distances of every hit within `reach`, nearest first. */
+    hits(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ dx: number, /** @type {number} */ dy: number, /** @type {number} */ dz: number, /** @type {number} */ reach: number): number[];
+    /** The triangle nearest a point within `radius` meters, its number (in the `tris` the tree was built from), its distance and the nearest point of it; none: undefined. */
+    closest(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ radius: number): {
+        triangle: number;
+        distance: number;
+        point: number[];
+    } | undefined;
+};
+/**
+ * The queries of a tree built by `buildSegmentBvh`: the segments within a distance of a point, and those whose boxes meet a box. Each gives the
+ * segments' numbers in the array the tree was built from, in no order.
+ * @param {ReturnType<typeof buildSegmentBvh>} bvh
+ */
+export declare function segmentQueries({ bounds, meta, data, ids, nodes }: ReturnType<typeof buildSegmentBvh>): {
+    /** The segments within `radius` meters of a point. */
+    near(/** @type {number} */ px: number, /** @type {number} */ py: number, /** @type {number} */ pz: number, /** @type {number} */ radius: number): number[];
+    /** The segments whose boxes (an end to the other) meet the box from (x0, y0, z0) to (x1, y1, z1). */
+    overlapping(/** @type {number} */ x0: number, /** @type {number} */ y0: number, /** @type {number} */ z0: number, /** @type {number} */ x1: number, /** @type {number} */ y1: number, /** @type {number} */ z1: number): number[];
+};
+//# sourceMappingURL=cesium-bvh.d.ts.map

package/dist/cesium-bvh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cesium-bvh.d.ts","sourceRoot":"","sources":["../src/cesium-bvh.js"],"names":[],"mappings":"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"}