@itwin/core-geometry 5.3.0-dev.8 → 5.3.0

package/lib/esm/geometry3d/GrowableXYZArray.js

@@ -12,42 +12,38 @@ import { Point3d, Vector3d } from "./Point3dVector3d";
 import { PointStreamGrowableXYZArrayCollector, VariantPointDataStream } from "./PointStreaming";
 import { Range1d, Range3d } from "./Range";
 import { Transform } from "./Transform";
-/** `GrowableXYArray` manages a (possibly growing) Float64Array to pack xy coordinates.
+/**
+ * `GrowableXYZArray` manages a (possibly growing) Float64Array to pack xyz coordinates.
  * @public
  */
 export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
-    /**
-     * array of packed xyz xyz xyz components
-     */
+    /** Array of packed xyz xyz xyz components. */
     _data;
-    /**
-     * Number of xyz triples (not floats) in the array
-     */
+    /** Number of xyz triples (not floats) in the array. */
     _xyzInUse;
-    /**
-     * capacity in xyz triples. (not floats)
-     */
+    /** Capacity in xyz triples (not floats). */
     _xyzCapacity;
-    /**
-     * multiplier used by ensureCapacity to expand requested reallocation size
-     */
+    /** Multiplier used by ensureCapacity to expand requested reallocation size. */
     _growthFactor;
-    /** Construct a new GrowablePoint3d array.
-     * @param numPoints initial capacity in xyz triples (default 8)
-     * @param growthFactor used by ensureCapacity to expand requested reallocation size (default 1.5)
+    /**
+     * Construct a new GrowablePoint3d array.
+     * @param numPoints initial capacity in xyz triples (default 8).
+     * @param growthFactor used by ensureCapacity to expand requested reallocation size (default 1.5).
+     * @param data optional pre-existing Float64Array to use as the backing memory. If supplied, numPoints is ignored.
      */
-    constructor(numPoints = 8, growthFactor) {
+    constructor(numPoints = 8, growthFactor, data) {
         super();
-        this._data = new Float64Array(numPoints * 3); // 3 values per point
+        this._data = data || new Float64Array(numPoints * 3); // 3 values per point
         this._xyzInUse = 0;
-        this._xyzCapacity = numPoints;
+        this._xyzCapacity = data ? data.length / 3 : numPoints;
         this._growthFactor = (undefined !== growthFactor && growthFactor >= 1.0) ? growthFactor : 1.5;
     }
-    /** Copy xyz points from source array. Does not reallocate or change active point count.
-     * @param source array to copy from
-     * @param sourceCount copy the first sourceCount points; all points if undefined
-     * @param destOffset copy to instance array starting at this point index; zero if undefined
-     * @return count and offset of points copied
+    /**
+     * Copy xyz points from source array. Does not reallocate or change active point count.
+     * @param source array to copy from.
+     * @param sourceCount copy the first sourceCount points; all points if undefined.
+     * @param destOffset copy to instance array starting at this point index; zero if undefined.
+     * @return count and offset of points copied.
      */
     copyData(source, sourceCount, destOffset) {
         // validate inputs and convert from points to entries
@@ -76,30 +72,47 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         return { count: myCount / 3, offset: myOffset / 3 };
     }
     /** The number of points in use. When the length is increased, the array is padded with zeroes. */
-    get length() { return this._xyzInUse; }
-    set length(newLength) { this.resize(newLength, true); }
+    get length() {
+        return this._xyzInUse;
+    }
+    set length(newLength) {
+        this.resize(newLength, true);
+    }
     /** Return the number of float64 in use. */
-    get float64Length() { return this._xyzInUse * 3; }
-    /** Return the raw packed data.
+    get float64Length() {
+        return this._xyzInUse * 3;
+    }
+    /**
+     * Return the raw packed data.
      * * Note that the length of the returned Float64Array is a count of doubles, and includes the excess capacity
      */
-    float64Data() { return this._data; }
-    /** If necessary, increase the capacity to the new number of points.  Current coordinates and point count (length) are unchanged. */
+    float64Data() {
+        return this._data;
+    }
+    /**
+     * If necessary, increase the capacity to the new number of points.  Current coordinates and point count (length) are
+     * unchanged.
+     */
     ensureCapacity(pointCapacity, applyGrowthFactor = true) {
         if (pointCapacity > this._xyzCapacity) {
             if (applyGrowthFactor)
-                pointCapacity *= this._growthFactor;
+                pointCapacity = Math.trunc(pointCapacity * this._growthFactor);
             const prevData = this._data;
-            this._data = new Float64Array(pointCapacity * 3);
+            if (this._data.buffer instanceof ArrayBuffer)
+                this._data = new Float64Array(new ArrayBuffer(pointCapacity * 3 * this._data.BYTES_PER_ELEMENT));
+            else
+                this._data = new Float64Array(new SharedArrayBuffer(pointCapacity * 3 * this._data.BYTES_PER_ELEMENT));
             this.copyData(prevData, this._xyzInUse);
             this._xyzCapacity = pointCapacity;
         }
     }
     /**
-     * * If pointCount is less than current length, just reset current length to pointCount, effectively trimming active points but preserving original capacity.
-     * * If pointCount is greater than current length, reallocate to exactly pointCount, copy existing points, and optionally pad excess with zero.
-     * @param pointCount new number of active points in array
-     * @param padWithZero when increasing point count, whether to zero out new points (default false)
+     * * If pointCount is less than current length, just reset current length to pointCount, effectively trimming active
+     * points but preserving original capacity.
+     * * If pointCount is greater than current length, reallocate to exactly pointCount, copy existing points, and
+     * optionally pad excess with zero.
+     * @param pointCount new number of active points in array.
+     * @param padWithZero when increasing point count, whether to zero out new points (default false).
     */
     resize(pointCount, padWithZero) {
         if (pointCount >= 0 && pointCount < this._xyzInUse)
@@ -111,10 +124,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             this._xyzInUse = pointCount;
         }
     }
-    /**
-     * Make a copy of the (active) points in this array.
-     * (The clone does NOT get excess capacity)
-     */
+    /** Make a copy of the (active) points in this array (the clone does NOT get excess capacity). */
     clone(result) {
         if (!result)
             result = new GrowableXYZArray(this.length);
@@ -130,11 +140,11 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     /**
      * Clone the input array with each successive duplicate point removed.
      * * First and last points are always preserved.
-     * @param source the source array
-     * @param tolerance optional distance tol for compression (default [[Geometry.smallMetricDistance]])
+     * @param source the source array.
+     * @param tolerance optional distance tol for compression (default [[Geometry.smallMetricDistance]]).
      * @param result optional pre-allocated object to populate and return. Can be a reference to `source`, in
      * which case the array is compressed in place and returned.
-     * @see [[cloneCompressed]], [[compressInPlace]], [[PolylineOps.compressShortEdges]]
+     * @see [[cloneCompressed]], [[compressInPlace]], [[PolylineOps.compressShortEdges]].
      */
     static createCompressed(source, tolerance = Geometry.smallMetricDistance, result) {
         const dupIndices = source.findOrderedDuplicates(tolerance, true);
@@ -168,9 +178,9 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     /**
      * Compress the input array by removing successive duplicate points.
      * * First and last points are always preserved.
-     * @param tolerance optional distance tol for compression (default [[Geometry.smallMetricDistance]])
+     * @param tolerance optional distance tol for compression (default [[Geometry.smallMetricDistance]]).
      * @returns the instance array.
-     * @see [[createCompressed]], [[cloneCompressed]], [[PolylineOps.compressShortEdges]]
+     * @see [[createCompressed]], [[cloneCompressed]], [[PolylineOps.compressShortEdges]].
      */
     compressInPlace(tolerance = Geometry.smallMetricDistance) {
         return GrowableXYZArray.createCompressed(this, tolerance, this);
@@ -201,23 +211,32 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         result.pushFrom(data);
         return result;
     }
-    /** Restructure MultiLineStringDataVariant as array of GrowableXYZArray */
+    /**
+     * Create a new GrowableXYZArray capturing the provided data. The data is not copied, just referenced.
+     * @param data source data to capture.
+     * @returns a new GrowableXYZArray object that references the provided data.
+     */
+    static createCapture(data) {
+        return new GrowableXYZArray(0, undefined, data);
+    }
+    /** Restructure MultiLineStringDataVariant as array of GrowableXYZArray. */
     static createArrayOfGrowableXYZArray(data) {
         const collector = new PointStreamGrowableXYZArrayCollector();
         VariantPointDataStream.streamXYZ(data, collector);
         return collector.claimArrayOfGrowableXYZArray();
     }
-    /** push a point to the end of the array */
+    /** Push a point to the end of the array. */
     push(toPush) {
         this.pushXYZ(toPush.x, toPush.y, toPush.z);
     }
-    /** push all points of an array */
+    /** Push all points of an array. */
     pushAll(points) {
         this.ensureCapacity(this._xyzInUse + points.length, false);
         for (const p of points)
             this.push(p);
     }
-    /** Push copies of points from variant sources.
+    /**
+     * Push copies of points from variant sources.
      * Valid inputs are:
      * * Point2d
      * * Point3d
@@ -227,7 +246,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
      * * Any json object satisfying Point3d.isXYAndZ
      * * Any json object satisfying Point3d.isXAndY
      * * A Float64Array of doubles, interpreted as xyzxyz
-     * * An array of any of the above
+     * * An array of any of the above.
      */
     pushFrom(p) {
         if (p instanceof Point3d)
@@ -247,7 +266,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         else if (Geometry.isNumberArray(p, 2))
             this.pushXYZ(p[0], p[1], 0.0);
         else if (Array.isArray(p)) {
-            // direct recursion re-wraps p and goes infinite. Unroll here.
+            // direct recursion re-wraps p and goes infinite; unroll here.
             for (const q of p)
                 this.pushFrom(q);
         }
@@ -264,7 +283,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * Replicate numWrap xyz values from the front of the array as new values at the end.
-     * @param numWrap number of xyz values to replicate
+     * @param numWrap number of xyz values to replicate.
      */
     pushWrap(numWrap) {
         if (this._xyzInUse >= numWrap) {
@@ -275,7 +294,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             }
         }
     }
-    /** append a new point with given x,y,z */
+    /** Append a new point with given x,y,z. */
     pushXYZ(x, y, z) {
         this.ensureCapacity(this._xyzInUse + 1);
         const index = this._xyzInUse * 3;
@@ -284,10 +303,11 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         this._data[index + 2] = z;
         this._xyzInUse++;
     }
-    /** Shift all data forward to make space for numPoints at the front.
+    /**
+     * Shift all data forward to make space for numPoints at the front.
      * * Leading (3*numPoints) doubles are left with prior contents.
-     * * _xyzInUse count is increased
-    */
+     * * _xyzInUse count is increased.
+     */
     shiftForward(numPoints) {
         if (numPoints <= 0)
             return;
@@ -297,7 +317,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         this._data.copyWithin(numAddedDouble, 0, lastIndex);
         this._xyzInUse += numPoints;
     }
-    /** prepend a new point with given x,y,z
+    /**
+     * Prepend a new point with given x,y,z
      * * Remark: this copies all content forward.
      */
     pushFrontXYZ(x, y, z) {
@@ -306,13 +327,12 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         this._data[1] = y;
         this._data[2] = z;
     }
-    /** prepend a new point at the front of the array.
-     *
-     */
+    /** Prepend a new point at the front of the array. */
     pushFront(toPush) {
         this.pushFrontXYZ(toPush.x, toPush.y, toPush.z);
     }
-    /** move the coordinates at fromIndex to toIndex.
+    /**
+     * Move the coordinates at fromIndex to toIndex.
      * * No action if either index is invalid.
      */
     moveIndexToIndex(fromIndex, toIndex) {
@@ -324,7 +344,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             this._data[iB] = this._data[iA];
         }
     }
-    /** Remove one point from the back.
+    /**
+     * Remove one point from the back.
      * * NOTE that (in the manner of std::vector native) this is "just" removing the point -- no point is NOT returned.
      * * Use `back ()` to get the last x,y,z assembled into a `Point3d `
      */
@@ -332,40 +353,41 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         if (this._xyzInUse > 0)
             this._xyzInUse--;
     }
-    /**
-     * Clear all xyz data, but leave capacity unchanged.
-     */
+    /** Clear all xyz data, but leave capacity unchanged. */
     clear() {
         this._xyzInUse = 0;
     }
     /**
-     * Get a point by index, strongly typed as a Point3d.  This is unchecked.  Use [[getPoint3dAtCheckedPointIndex]] to have validity test.
-     * @param pointIndex index to access
-     * @param result optional result
+     * Get a point by index, strongly typed as a Point3d. This is unchecked. Use [[getPoint3dAtCheckedPointIndex]] to
+     * have validity test.
+     * @param pointIndex index to access.
+     * @param result optional result.
      */
     getPoint3dAtUncheckedPointIndex(pointIndex, result) {
         const index = 3 * pointIndex;
         return Point3d.create(this._data[index], this._data[index + 1], this._data[index + 2], result);
     }
     /**
-     * Get a point by index, strongly typed as a Point2d.  This is unchecked.  Use [[getPoint2dAtCheckedPointIndex]] to have validity test.
-     * @param pointIndex index to access
-     * @param result optional result
+     * Get a point by index, strongly typed as a Point2d.  This is unchecked.  Use [[getPoint2dAtCheckedPointIndex]] to
+     * have validity test.
+     * @param pointIndex index to access.
+     * @param result optional result.
      */
     getPoint2dAtUncheckedPointIndex(pointIndex, result) {
         const index = 3 * pointIndex;
         return Point2d.create(this._data[index], this._data[index + 1], result);
     }
     /**
-     * Get a vector by index, strongly typed as a Vector3d.  This is unchecked.  Use [[getVector3dAtCheckedVectorIndex]] to have validity test.
-     * @param vectorIndex index to access
-     * @param result optional result
+     * Get a vector by index, strongly typed as a Vector3d.  This is unchecked.  Use [[getVector3dAtCheckedVectorIndex]]
+     * to have validity test.
+     * @param vectorIndex index to access.
+     * @param result optional result.
      */
     getVector3dAtUncheckedVectorIndex(vectorIndex, result) {
         const index = 3 * vectorIndex;
         return Vector3d.create(this._data[index], this._data[index + 1], this._data[index + 2], result);
     }
-    /** copy xyz into strongly typed Point3d */
+    /** Copy xyz into strongly typed Point3d. */
     getPoint3dAtCheckedPointIndex(pointIndex, result) {
         if (this.isIndexValid(pointIndex)) {
             const index = 3 * pointIndex;
@@ -373,22 +395,22 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
         return undefined;
     }
-    /** access x of indexed point */
+    /** Access x of indexed point. */
     getXAtUncheckedPointIndex(pointIndex) {
         const index = 3 * pointIndex;
         return this._data[index];
     }
-    /** access y of indexed point */
+    /** Access y of indexed point. */
     getYAtUncheckedPointIndex(pointIndex) {
         const index = 3 * pointIndex;
         return this._data[index + 1];
     }
-    /** access y of indexed point */
+    /** Access z of indexed point. */
     getZAtUncheckedPointIndex(pointIndex) {
         const index = 3 * pointIndex;
         return this._data[index + 2];
     }
-    /** copy xy into strongly typed Point2d */
+    /** Copy xy into strongly typed Point2d. */
     getPoint2dAtCheckedPointIndex(pointIndex, result) {
         if (this.isIndexValid(pointIndex)) {
             const index = 3 * pointIndex;
@@ -396,7 +418,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
         return undefined;
     }
-    /** copy xyz into strongly typed Vector3d */
+    /** Copy xyz into strongly typed Vector3d. */
     getVector3dAtCheckedVectorIndex(vectorIndex, result) {
         if (this.isIndexValid(vectorIndex)) {
             const index = 3 * vectorIndex;
@@ -406,9 +428,9 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * Read coordinates from source array, place them at index within this array.
-     * @param destIndex point index where coordinates are to be placed in this array
-     * @param source source array
-     * @param sourceIndex point index in source array
+     * @param destIndex point index where coordinates are to be placed in this array.
+     * @param source source array.
+     * @param sourceIndex point index in source array.
      * @returns true if destIndex and sourceIndex are both valid.
      */
     transferFromGrowableXYZArray(destIndex, source, sourceIndex) {
@@ -422,13 +444,13 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         return false;
     }
     /**
-     * push coordinates from the source array to the end of this array.
-     * @param source source array
-     * @param sourceIndex xyz index within the source.  If undefined, entire source is pushed.
+     * Push coordinates from the source array to the end of this array.
+     * @param source source array.
+     * @param sourceIndex xyz index within the source. If undefined, entire source is pushed.
      * @returns number of points pushed.
      */
     pushFromGrowableXYZArray(source, sourceIndex) {
-        // full array push  . . .
+        // full array push
         if (sourceIndex === undefined) {
             const numXYZAdd = source.length;
             this.ensureCapacity(this.length + numXYZAdd, false);
@@ -436,7 +458,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             this._xyzInUse += numXYZAdd;
             return numXYZAdd;
         }
-        // single point push . . .
+        // single point push
         if (source.isIndexValid(sourceIndex)) {
             const j = sourceIndex * 3;
             this.pushXYZ(source._data[j], source._data[j + 1], source._data[j + 2]);
@@ -446,8 +468,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * Set the coordinates of a single point.
-     * @param pointIndex index of point to set
-     * @param value coordinates to set
+     * @param pointIndex index of point to set.
+     * @param value coordinates to set.
      */
     setAtCheckedPointIndex(pointIndex, value) {
         if (!this.isIndexValid(pointIndex))
@@ -459,11 +481,11 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         return true;
     }
     /**
-     * Set the coordinates of a single point given as coordinates
-     * @param pointIndex index of point to set
-     * @param x x coordinate
-     * @param y y coordinate
-     * @param z z coordinate
+     * Set the coordinates of a single point given as coordinates.
+     * @param pointIndex index of point to set.
+     * @param x x coordinate.
+     * @param y y coordinate.
+     * @param z z coordinate.
      */
     setXYZAtCheckedPointIndex(pointIndex, x, y, z) {
         if (!this.isIndexValid(pointIndex))
@@ -474,9 +496,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         this._data[index] = z;
         return true;
     }
-    /**
-     * Copy all points into a simple array of Point3d
-     */
+    /** Copy all points into a simple array of Point3. */
     getPoint3dArray() {
         const n = 3 * this._xyzInUse;
         const result = [];
@@ -485,7 +505,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             result.push(Point3d.create(data[i], data[i + 1], data[i + 2]));
         return result;
     }
-    /** multiply each point by the transform, replace values. */
+    /** Multiply each point by the transform, replace values. */
     static multiplyTransformInPlace(transform, data) {
         if (Array.isArray(data)) {
             for (const d of data)
@@ -495,7 +515,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             data.multiplyTransformInPlace(transform);
         }
     }
-    /** multiply each point by the transform, replace values. */
+    /** Multiply each point by the transform, replace values. */
     multiplyTransformInPlace(transform) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -516,7 +536,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             data[i + 2] = coffs[6] * x + coffs[7] * y + coffs[8] * z + z0;
         }
     }
-    /** reverse the order of points. */
+    /** Reverse the order of points. */
     reverseInPlace() {
         const n = this.length;
         let j0, j1;
@@ -540,7 +560,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             data[j1] = a;
         }
     }
-    /** multiply each xyz (as a vector) by matrix, replace values. */
+    /** Multiply each xyz (as a vector) by matrix, replace values. */
     multiplyMatrix3dInPlace(matrix) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -557,9 +577,10 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             data[i + 2] = coffs[6] * x + coffs[7] * y + coffs[8] * z;
         }
     }
-    /** multiply each xyz (as a vector) by matrix inverse transpose, renormalize the vector, replace values.
-     * * This is the way to apply a matrix (possibly with skew and scale) to a surface normal, and
-     *      have it end up perpendicular to the transformed in-surface vectors.
+    /**
+     * Multiply each xyz (as a vector) by matrix inverse transpose, renormalize the vector, replace values.
+     * * This is the way to apply a matrix (possibly with skew and scale) to a surface normal, and have it end up
+     * perpendicular to the transformed in-surface vectors.
      * * Return false if matrix is not invertible or if any normalization fails.
      */
     multiplyAndRenormalizeMatrix3dInverseTransposeInPlace(matrix) {
@@ -587,7 +608,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             z1 = coffs[2] * x + coffs[5] * y + coffs[8] * z;
             a = x1 * x1 + y1 * y1 + z1 * z1;
             if (a < tol) {
-                // put the originals back ..
+                // put the originals back
                 x1 = x;
                 y1 = y;
                 z1 = z;
@@ -598,16 +619,14 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
                 x1 *= q;
                 y1 *= q;
                 z1 *= q;
-            } // else -- q is near 1, no need to do the division !!
+            } // else if q is near 1, no need to do the division
             data[i] = x1;
             data[i + 1] = y1;
             data[i + 2] = z1;
         }
         return numFail === 0;
     }
-    /** multiply each xyz (as a point) by a homogeneous matrix and update as the normalized point
-     *
-     */
+    /** Multiply each xyz (as a point) by a homogeneous matrix and update as the normalized point. */
     multiplyMatrix4dAndQuietRenormalizeMatrix4d(matrix) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -619,7 +638,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             data[i + 2] = xyz1.z;
         }
     }
-    /** multiply each point by the transform, replace values. */
+    /** Multiply each point by the transform, replace values. */
     tryTransformInverseInPlace(transform) {
         const data = this._data;
         const nDouble = this.float64Length;
@@ -658,7 +677,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
                 rangeToExtend.extendXYZ(data[i], data[i + 1], data[i + 2]);
         }
     }
-    /** get range of points. */
+    /** Get range of points. */
     getRange(transform, result) {
         let range = result;
         if (range)
@@ -676,7 +695,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     /** Sum the lengths of segments between points. */
     sumLengths() {
         let sum = 0.0;
-        const n = 3 * (this._xyzInUse - 1); // Length already takes into account what specifically is in use
+        const n = 3 * (this._xyzInUse - 1); // length already takes into account what specifically is in use
         const data = this._data;
         for (let i = 0; i < n; i += 3)
             sum += Geometry.hypotenuseXYZ(data[i + 3] - data[i], data[i + 4] - data[i + 1], data[i + 5] - data[i + 2]);
@@ -684,7 +703,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * Multiply each x,y,z by the scale factor.
-     * @param factor
+     * @param factor scale factor.
      */
     scaleInPlace(factor) {
         if (this._data) {
@@ -693,7 +712,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
                 this._data[i] = this._data[i] * factor;
         }
     }
-    /** test if all points are within tolerance of a plane. */
+    /** Test if all points are within tolerance of a plane. */
     isCloseToPlane(plane, tolerance = Geometry.smallMetricDistance) {
         const numCoordinate = 3 * this._xyzInUse;
         const data = this._data;
@@ -704,13 +723,12 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * * If not already closed, push a copy of the first point.
-     * * If already closed within tolerance, force exact copy
-     * * otherwise leave unchanged.
+     * * If already closed within tolerance, force exact copy.
+     * * Otherwise leave unchanged.
      */
     forceClosure(tolerance = Geometry.smallMetricDistance) {
         const d = this.distanceIndexIndex(0, this.length - 1);
-        // leave the empty array alone.
-        // Note that singleton will generate 0 distance and do nothing.
+        // leave the empty array alone; note that singleton will generate 0 distance and do nothing
         if (d === undefined) {
         }
         else if (d > tolerance)
@@ -722,7 +740,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
                 this._data[i0 + i] = this._data[i];
         }
     }
-    /** Compute a point at fractional coordinate between points i and j */
+    /** Compute a point at fractional coordinate between points i and j. */
     interpolate(i, fraction, j, result) {
         if (this.isIndexValid(i) && this.isIndexValid(j)) {
             const fraction0 = 1.0 - fraction;
@@ -733,10 +751,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
         return undefined;
     }
-    /**
-     * * Compute a point at fractional coordinate between points i and j of source
-     * * push onto this array.
-     */
+    /** Compute a point at fractional coordinate between points i and j of source and push onto this array. */
     pushInterpolatedFromGrowableXYZArray(source, i, fraction, j) {
         if (source.isIndexValid(i) && source.isIndexValid(j)) {
             const fraction0 = 1.0 - fraction;
@@ -746,10 +761,10 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             this.pushXYZ(fraction0 * data[i] + fraction * data[j], fraction0 * data[i + 1] + fraction * data[j + 1], fraction0 * data[i + 2] + fraction * data[j + 2]);
         }
     }
-    /** Sum the signed areas of the projection to xy plane */
+    /** Sum the signed areas of the projection to xy plane. */
     areaXY() {
         let area = 0.0;
-        const n = 3 * this._xyzInUse; // float count !!
+        const n = 3 * this._xyzInUse; // float count
         if (n > 6) {
             const x0 = this._data[n - 3];
             const y0 = this._data[n - 2];
@@ -794,21 +809,21 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
         return undefined;
     }
-    /** Compute the dot product of pointIndex with [x,y,z] */
+    /** Compute the dot product of pointIndex with [x,y,z]. */
     evaluateUncheckedIndexDotProductXYZ(pointIndex, x, y, z) {
         const i = pointIndex * 3;
         const data = this._data;
         return data[i] * x + data[i + 1] * y + data[i + 2] * z;
     }
-    /** Compute the dot product of pointIndex with [x,y,z] */
+    /** Compute the dot product of pointIndex with [x,y,z]. */
     evaluateUncheckedIndexPlaneAltitude(pointIndex, plane) {
         const i = pointIndex * 3;
         const data = this._data;
         return plane.altitudeXYZ(data[i], data[i + 1], data[i + 2]);
     }
     /**
-     * * compute the cross product from indexed origin t indexed targets targetAIndex and targetB index.
-     * * accumulate it to the result.
+     * Compute the cross product from indexed origin t indexed targets targetAIndex and targetB index.
+     * * Accumulate it to the result.
      */
     accumulateCrossProductIndexIndexIndex(originIndex, targetAIndex, targetBIndex, result) {
         if (this.isIndexValid(originIndex) && this.isIndexValid(targetAIndex) && this.isIndexValid(targetBIndex)) {
@@ -820,8 +835,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
     }
     /**
-     * * compute the cross product from indexed origin t indexed targets targetAIndex and targetB index.
-     * * accumulate it to the result.
+     * Compute the cross product from indexed origin t indexed targets targetAIndex and targetB index.
+     * * Accumulate it to the result.
      */
     accumulateScaledXYZ(index, scale, sum) {
         if (this.isIndexValid(index)) {
@@ -832,7 +847,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             sum.z += scale * data[i + 2];
         }
     }
-    /** Compute the cross product of vectors from from origin to indexed targets i and j */
+    /** Compute the cross product of vectors from from origin to indexed targets i and j. */
     crossProductXYAndZIndexIndex(origin, targetAIndex, targetBIndex, result) {
         if (this.isIndexValid(targetAIndex) && this.isIndexValid(targetBIndex)) {
             const j = targetAIndex * 3;
@@ -852,8 +867,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * Return distance squared between indicated points.
-     * @param i first point index
-     * @param j second point index
+     * @param i first point index.
+     * @param j second point index.
      */
     distanceSquaredIndexIndex(i, j) {
         if (this.isIndexValid(i) && this.isIndexValid(j)) {
@@ -865,8 +880,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     }
     /**
      * Return distance between indicated points.
-     * @param i first point index
-     * @param j second point index
+     * @param i first point index.
+     * @param j second point index.
      */
     distanceIndexIndex(i, j) {
         if (this.isIndexValid(i) && this.isIndexValid(j)) {
@@ -885,7 +900,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
         return undefined;
     }
-    /** test for near equality between two `GrowableXYZArray`. */
+    /** Test for near equality between two `GrowableXYZArray`. */
     static isAlmostEqual(dataA, dataB) {
         if (dataA && dataB) {
             if (dataA.length !== dataB.length)
@@ -898,7 +913,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         // if both are null it is equal, otherwise unequal
         return (!dataA && !dataB);
     }
-    /** Return an array of block indices sorted per compareLexicalBlock function */
+    /** Return an array of block indices sorted per compareLexicalBlock function. */
     sortIndicesLexical() {
         const n = this._xyzInUse;
         // let numCompare = 0;
@@ -912,7 +927,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         // console.log (n, numCompare);
         return result;
     }
-    /** compare two blocks in simple lexical order. */
+    /** Compare two blocks in simple lexical order. */
     compareLexicalBlock(ia, ib) {
         let ax = 0;
         let bx = 0;
@@ -924,19 +939,13 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
             if (ax < bx)
                 return -1;
         }
-        return ia - ib; // so original order is maintained among duplicates !!!!
+        return ia - ib; // so original order is maintained among duplicates
     }
-    /** Access a single double at offset within a block.  This has no index checking. */
+    /** Access a single double at offset within a block. This has no index checking. */
     component(pointIndex, componentIndex) {
         return this._data[3 * pointIndex + componentIndex];
     }
-    /**
-     * add points at regular steps from `other`
-     * @param source
-     * @param pointIndex0
-     * @param step
-     * @param numAdd
-     */
+    /** Add points at regular steps from `other`. */
     addSteppedPoints(other, pointIndex0, step, numAdd) {
         const dataB = other._data;
         let b0 = pointIndex0 * 3;
@@ -950,9 +959,9 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
     }
     /**
-     * find the min and max distance between corresponding indexed points.   Excess points are ignored.
-     * @param arrayA first array
-     * @param arrayB second array
+     * Find the min and max distance between corresponding indexed points. Excess points are ignored.
+     * @param arrayA first array.
+     * @param arrayB second array.
      */
     static distanceRangeBetweenCorrespondingPoints(arrayA, arrayB) {
         const dataA = arrayA._data;
@@ -968,11 +977,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
         }
         return range;
     }
-    /**
-     * remove trailing point(s) within tolerance of the start point.
-     * @param points
-     * @param tolerance
-     */
+    /** Remove trailing point(s) within tolerance of the start point. */
     static removeClosure(points, tolerance = Geometry.smallMetricDistance) {
         while (points.length > 1 && points.distanceIndexIndex(0, points.length - 1) < tolerance)
             points.pop();
@@ -980,8 +985,8 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     /**
      * Compute frame for a triangle formed by three (unchecked!) points identified by index.
      * * z direction of frame is 001.
-     * * Transform axes from origin to targetA and targetB
-     * * in local coordinates (u,v,w) the xy interior of the triangle is `u>=0, v>= 0, w>= 0, u+v+w<1`
+     * * Transform axes from origin to targetA and targetB.
+     * * in local coordinates (u,v,w) the xy interior of the triangle is `u>=0, v>= 0, w>= 0, u+v+w<1`.
      * * Return undefined if transform is not invertible, e.g. if points are in a vertical plane.
      */
     fillLocalXYTriangleFrame(originIndex, targetAIndex, targetBIndex, result) {
@@ -1007,7 +1012,7 @@ export class GrowableXYZArray extends IndexedReadWriteXYZCollection {
     /**
      * Pass the (x,y,z) of each point to a function which returns a replacement for one of the 3 components.
      * @param componentIndex Index (0,1,2) of component to be replaced.
-     * @param func function to be called as `func(x,y,z)`, returning a replacement value for componentIndex
+     * @param func function to be called as `func(x,y,z)`, returning a replacement value for componentIndex.
      */
     mapComponent(componentIndex, func) {
         const n = this._data.length;