@itwin/core-geometry 5.3.0-dev.2 → 5.3.0-dev.23

package/lib/cjs/geometry3d/GrowableXYZArray.js

@@ -15,42 +15,38 @@ const Point3dVector3d_1 = require("./Point3dVector3d");
 const PointStreaming_1 = require("./PointStreaming");
 const Range_1 = require("./Range");
 const Transform_1 = require("./Transform");
-/** `GrowableXYArray` manages a (possibly growing) Float64Array to pack xy coordinates.
+/**
+ * `GrowableXYZArray` manages a (possibly growing) Float64Array to pack xyz coordinates.
  * @public
  */
 class GrowableXYZArray extends IndexedXYZCollection_1.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
@@ -79,30 +75,47 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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)
@@ -114,10 +127,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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);
@@ -133,11 +143,11 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     /**
      * 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_1.Geometry.smallMetricDistance, result) {
         const dupIndices = source.findOrderedDuplicates(tolerance, true);
@@ -171,14 +181,15 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     /**
      * 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_1.Geometry.smallMetricDistance) {
         return GrowableXYZArray.createCompressed(this, tolerance, this);
     }
-    /** Create an array from various point data formats.
+    /**
+     * Create an array by copying data from various point formats.
      * Valid inputs are:
      * * Point2d
      * * Point3d
@@ -203,23 +214,32 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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 PointStreaming_1.PointStreamGrowableXYZArrayCollector();
         PointStreaming_1.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
@@ -229,7 +249,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
      * * 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 Point3dVector3d_1.Point3d)
@@ -249,7 +269,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         else if (Geometry_1.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);
         }
@@ -266,7 +286,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * 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) {
@@ -277,7 +297,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             }
         }
     }
-    /** 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;
@@ -286,10 +306,11 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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;
@@ -299,7 +320,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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) {
@@ -308,13 +330,12 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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) {
@@ -326,7 +347,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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 `
      */
@@ -334,40 +356,41 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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 Point3dVector3d_1.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 Point2dVector2d_1.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 Point3dVector3d_1.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;
@@ -375,22 +398,22 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
         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;
@@ -398,7 +421,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
         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;
@@ -408,9 +431,9 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * 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) {
@@ -424,13 +447,13 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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);
@@ -438,7 +461,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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]);
@@ -448,8 +471,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * 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))
@@ -461,11 +484,11 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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))
@@ -476,9 +499,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         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 = [];
@@ -487,7 +508,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             result.push(Point3dVector3d_1.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)
@@ -497,7 +518,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -518,7 +539,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -542,7 +563,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -559,9 +580,10 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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) {
@@ -589,7 +611,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -600,16 +622,14 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
                 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;
@@ -621,7 +641,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -660,7 +680,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
                 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)
@@ -678,7 +698,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     /** 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_1.Geometry.hypotenuseXYZ(data[i + 3] - data[i], data[i + 4] - data[i + 1], data[i + 5] - data[i + 2]);
@@ -686,7 +706,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * Multiply each x,y,z by the scale factor.
-     * @param factor
+     * @param factor scale factor.
      */
     scaleInPlace(factor) {
         if (this._data) {
@@ -695,7 +715,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
                 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_1.Geometry.smallMetricDistance) {
         const numCoordinate = 3 * this._xyzInUse;
         const data = this._data;
@@ -706,13 +726,12 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * * 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_1.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)
@@ -724,7 +743,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
                 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;
@@ -735,10 +754,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
         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;
@@ -748,10 +764,10 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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];
@@ -796,21 +812,21 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
         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)) {
@@ -822,8 +838,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
     }
     /**
-     * * 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)) {
@@ -834,7 +850,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -854,8 +870,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * 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)) {
@@ -867,8 +883,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     }
     /**
      * 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)) {
@@ -887,7 +903,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
         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)
@@ -900,7 +916,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         // 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;
@@ -914,7 +930,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         // 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;
@@ -926,19 +942,13 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
             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;
@@ -952,9 +962,9 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
     }
     /**
-     * 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;
@@ -970,11 +980,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
         }
         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_1.Geometry.smallMetricDistance) {
         while (points.length > 1 && points.distanceIndexIndex(0, points.length - 1) < tolerance)
             points.pop();
@@ -982,8 +988,8 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     /**
      * 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) {
@@ -1009,7 +1015,7 @@ class GrowableXYZArray extends IndexedXYZCollection_1.IndexedReadWriteXYZCollect
     /**
      * 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;