@itwin/core-geometry 4.5.0-dev.21 → 4.5.0-dev.24

package/lib/esm/polyface/PolyfaceData.js

@@ -15,39 +15,28 @@ import { Range3d } from "../geometry3d/Range";
 import { ClusterableArray } from "../numerics/ClusterableArray";
 import { PolyfaceAuxData } from "./AuxData";
 import { TaggedNumericData } from "./TaggedNumericData";
+// cspell:word internaldocs
 /**
- * PolyfaceData carries data arrays for point, normal, param, color and their indices.
- *
- * * IndexedPolyface carries a PolyfaceData as a member. (NOT as a base class -- it already has GeometryQuery as base)
- * * IndexedPolyfaceVisitor uses PolyfaceData as a base class.  In this use there is only a single facet in the polyfaceData.
- * * PolyfaceData does not know (!!!) what indices range constitute a facet.  That is managed by derived class or carrier class.
+ * `PolyfaceData` carries data arrays for point, normal, uv-parameters, and color, and index arrays for each.
+ * * Normal, uv-parameter, and color data are optional.
+ * * A given data array is defined if and only if its corresponding index array is defined.
+ * * All defined index arrays have parallel face loop order and structure, and thus the same length.
+ * * `IndexedPolyface` carries a PolyfaceData as a member (NOT as a base class; it already has `GeometryQuery` as base).
+ * * `IndexedPolyfaceVisitor` uses PolyfaceData as a base class. In this use, there is only a single facet in `PolyfaceData`.
+ * * `PolyfaceData` does not know what index range constitutes a given facet. This is managed by a derived/carrier class.
  * @public
  */
 class PolyfaceData {
-    /** boolean tag indicating if the facets are to be considered viewable from the back */
-    get twoSided() { return this._twoSided; }
-    set twoSided(value) { this._twoSided = value; }
-    /** set the `taggedNumericData` member */
-    setTaggedNumericData(data) {
-        this.taggedNumericData = data;
-    }
     /**
-     * Flag indicating if the mesh closure is unknown (0), open sheet (1), closed solid (2).
-     * * A boundary edge of a mesh is defined as an edge with only one connected facet.
-     * * Closed solid is a mesh with no boundary edge. Open sheet is a mesh that has boundary edge(s).
-     */
-    get expectedClosure() { return this._expectedClosure; }
-    set expectedClosure(value) { this._expectedClosure = value; }
-    /** Constructor for facets.
-     *   * The various params control whether respective arrays are to be allocated.
-     *   * If arrayData is provided, all other params are IGNORED.
-     *   *
+     * Constructor for facets.
+     * @param needNormals `true` to allocate empty normal data and index arrays; `false` (default) to leave undefined.
+     * @param needParams `true` to allocate empty uv parameter data and index arrays; `false` (default) to leave undefined.
+     * @param needColors `true` to allocate empty color data and index arrays; `false` (default) to leave undefined.
+     * @param twoSided `true` if the facets are to be considered viewable from the back; `false` (default) if not.
      */
     constructor(needNormals = false, needParams = false, needColors = false, twoSided = false) {
-        this.face = [];
         this.point = new GrowableXYZArray();
         this.pointIndex = [];
-        this.edgeVisible = [];
         if (needNormals) {
             this.normal = new GrowableXYZArray();
             this.normalIndex = [];
@@ -60,6 +49,8 @@ class PolyfaceData {
             this.color = [];
             this.colorIndex = [];
         }
+        this.face = [];
+        this.edgeVisible = [];
         this._twoSided = twoSided;
         this._expectedClosure = 0;
     }
@@ -68,30 +59,29 @@ class PolyfaceData {
         const result = new PolyfaceData();
         result.point = this.point.clone();
         result.pointIndex = this.pointIndex.slice();
-        result.edgeVisible = this.edgeVisible.slice();
-        result.face = this.face.slice();
-        result.twoSided = this.twoSided;
-        result.expectedClosure = this.expectedClosure;
         if (this.normal)
             result.normal = this.normal.clone();
-        if (this.param)
-            result.param = this.param.clone();
-        if (this.color)
-            result.color = this.color.slice();
         if (this.normalIndex)
             result.normalIndex = this.normalIndex.slice();
+        if (this.param)
+            result.param = this.param.clone();
         if (this.paramIndex)
             result.paramIndex = this.paramIndex.slice();
+        if (this.color)
+            result.color = this.color.slice();
         if (this.colorIndex)
             result.colorIndex = this.colorIndex.slice();
+        result.face = this.face.slice();
         if (this.auxData)
             result.auxData = this.auxData.clone();
-        if (this.taggedNumericData) {
+        if (this.taggedNumericData)
             result.taggedNumericData = this.taggedNumericData.clone();
-        }
+        result.edgeVisible = this.edgeVisible.slice();
+        result.twoSided = this.twoSided;
+        result.expectedClosure = this.expectedClosure;
         return result;
     }
-    /** Test for equal indices and nearly equal coordinates */
+    /** Test for equal indices and nearly equal coordinates. */
     isAlmostEqual(other) {
         if (!GrowableXYZArray.isAlmostEqual(this.point, other.point))
             return false;
@@ -109,77 +99,133 @@ class PolyfaceData {
             return false;
         if (!NumberArray.isExactEqual(this.colorIndex, other.colorIndex))
             return false;
-        if (!NumberArray.isExactEqual(this.edgeVisible, other.edgeVisible))
-            return false;
         if (!PolyfaceAuxData.isAlmostEqual(this.auxData, other.auxData))
             return false;
+        if (!TaggedNumericData.areAlmostEqual(this.taggedNumericData, other.taggedNumericData))
+            return false;
+        if (!NumberArray.isExactEqual(this.edgeVisible, other.edgeVisible))
+            return false;
         if (this.twoSided !== other.twoSided)
             return false;
         if (this.expectedClosure !== other.expectedClosure)
             return false;
-        if (!TaggedNumericData.areAlmostEqual(this.taggedNumericData, other.taggedNumericData))
-            return false;
         return true;
     }
     /** Ask if normals are required in this mesh. */
-    get requireNormals() { return undefined !== this.normal; }
+    get requireNormals() {
+        return undefined !== this.normal;
+    }
+    /** Ask if params are required in this mesh. */
+    get requireParams() {
+        return undefined !== this.param;
+    }
+    /** Ask if colors are required in this mesh. */
+    get requireColors() {
+        return undefined !== this.color;
+    }
     /** Get the point count */
-    get pointCount() { return this.point.length; }
+    get pointCount() {
+        return this.point.length;
+    }
     /** Get the normal count */
-    get normalCount() { return this.normal ? this.normal.length : 0; }
+    get normalCount() {
+        return this.normal ? this.normal.length : 0;
+    }
     /** Get the param count */
-    get paramCount() { return this.param ? this.param.length : 0; }
+    get paramCount() {
+        return this.param ? this.param.length : 0;
+    }
     /** Get the color count */
-    get colorCount() { return this.color ? this.color.length : 0; }
-    /** Get the index count.  Note that there is one count, and all index arrays (point, normal, param, color) must match */
-    get indexCount() { return this.pointIndex.length; } // ALWAYS INDEXED ... all index vectors must have same length.
-    /** Get the number of faces.
+    get colorCount() {
+        return this.color ? this.color.length : 0;
+    }
+    /** Get the index count. Note that the point array is always indexed, and index arrays all have the same length. */
+    get indexCount() {
+        return this.pointIndex.length;
+    }
+    /**
+     * Get the number of faces.
      * * Note that a "face" is not a facet.
-     * * A "face" is a subset of facets grouped for application purposes.
+     * * A face is a subset of the Polyface's facets grouped for application purposes.
      */
-    get faceCount() { return this.face.length; }
-    /** return indexed point. This is a copy of the coordinates, not a reference. */
-    getPoint(i, out) {
-        return this.point.getPoint3dAtCheckedPointIndex(i, out);
-    }
-    /** return indexed normal. This is the COPY to the normal, not a reference. */
-    getNormal(i) { return this.normal ? this.normal.getVector3dAtCheckedVectorIndex(i) : undefined; }
-    /** return indexed param. This is the COPY of the coordinates, not a reference. */
-    getParam(i) { return this.param ? this.param.getPoint2dAtCheckedPointIndex(i) : undefined; }
-    /** return indexed color */
-    getColor(i) { return this.color ? this.color[i] : 0; }
-    /** return indexed visibility */
-    getEdgeVisible(i) { return this.edgeVisible[i]; }
-    /** Copy the contents (not pointer) of point[i] into dest. */
-    copyPointTo(i, dest) { this.point.getPoint3dAtUncheckedPointIndex(i, dest); }
-    /** Copy the contents (not pointer) of normal[i] into dest. */
-    copyNormalTo(i, dest) { if (this.normal)
-        this.normal.getVector3dAtCheckedVectorIndex(i, dest); }
-    /** Copy the contents (not pointer) of param[i] into dest. */
-    copyParamTo(i, dest) { if (this.param)
-        this.param.getPoint2dAtCheckedPointIndex(i, dest); }
-    /** test if normal at a specified index matches uv */
-    isAlmostEqualParamIndexUV(index, u, v) {
-        if (this.param !== undefined && index >= 0 && index < this.param.length)
-            return Geometry.isSameCoordinate(u, this.param.getXAtUncheckedPointIndex(index))
-                && Geometry.isSameCoordinate(v, this.param.getYAtUncheckedPointIndex(index));
+    get faceCount() {
+        return this.face.length;
+    }
+    /** Return indexed point at index `i`. This is a COPY of the coordinates, not a reference. */
+    getPoint(i, result) {
+        return this.point.getPoint3dAtCheckedPointIndex(i, result);
+    }
+    /** Return indexed normal at index `i`. This is a COPY of the normal, not a reference. */
+    getNormal(i, result) {
+        return this.normal ? this.normal.getVector3dAtCheckedVectorIndex(i, result) : undefined;
+    }
+    /** Return indexed param at index `i`. This is a COPY of the coordinates, not a reference. */
+    getParam(i, result) {
+        return this.param ? this.param.getPoint2dAtCheckedPointIndex(i, result) : undefined;
+    }
+    /** Return indexed color at index `i`. Index `i` is not checked for validity. */
+    getColor(i) {
+        return this.color ? this.color[i] : 0;
+    }
+    /** Return indexed visibility. at index `i`. Index `i` is not checked for validity. */
+    getEdgeVisible(i) {
+        return this.edgeVisible[i];
+    }
+    /** Get boolean tag indicating if the facets are to be considered viewable from the back. */
+    get twoSided() {
+        return this._twoSided;
+    }
+    set twoSided(value) {
+        this._twoSided = value;
+    }
+    /** Get flag indicating if the mesh closure is unknown (0), open sheet (1), closed solid (2). */
+    get expectedClosure() {
+        return this._expectedClosure;
+    }
+    set expectedClosure(value) {
+        this._expectedClosure = value;
+    }
+    /** Set the tagged geometry data. */
+    setTaggedNumericData(data) {
+        this.taggedNumericData = data;
+    }
+    /** Copy the contents (not pointer) of `point[i]` into `dest`. Index `i` is not checked for validity. */
+    copyPointTo(i, dest) {
+        this.point.getPoint3dAtUncheckedPointIndex(i, dest);
+    }
+    /** Copy the contents (not pointer) of `normal[i]` into `dest`. Index `i` is not checked for validity. */
+    copyNormalTo(i, dest) {
+        if (this.normal)
+            this.normal.getVector3dAtUncheckedVectorIndex(i, dest);
+    }
+    /** Copy the contents (not pointer) of `param[i]` into `dest`. Index `i` is not checked for validity. */
+    copyParamTo(i, dest) {
+        if (this.param)
+            this.param.getPoint2dAtUncheckedPointIndex(i, dest);
+    }
+    /** Test if param at a index `i` matches the given uv */
+    isAlmostEqualParamIndexUV(i, u, v) {
+        if (this.param !== undefined && i >= 0 && i < this.param.length)
+            return Geometry.isSameCoordinate(u, this.param.getXAtUncheckedPointIndex(i))
+                && Geometry.isSameCoordinate(v, this.param.getYAtUncheckedPointIndex(i));
         return false;
     }
     /**
-     * * Copy data from other to this.
+     * Copy data from `other` to `this`.
      * * This is the essence of transferring coordinates spread throughout a large polyface into a visitor's single facet.
-     * * "other" is the large polyface
-     * * "this" is the visitor
-     * * does NOT copy face data - visitors reference the FacetFaceData array for the whole polyface!!
+     * * Common usage: "other" is a Polyface, "this" is a PolyfaceVisitor to receive data from a single facet of the Polyface.
+     * * Does NOT copy face data - visitors reference the FacetFaceData array for the whole polyface.
      * @param other polyface data being mined.
-     * @param index0 start index in other's index arrays
-     * @param index1 end index (one beyond last data accessed0 in other's index arrays
+     * @param index0 start index in other's index arrays.
+     * @param index1 end index (one beyond last data accessed) in other's index arrays.
      * @param numWrap number of points to replicate as wraparound.
      */
     gatherIndexedData(other, index0, index1, numWrap) {
         const numEdge = index1 - index0;
+        if (numWrap > numEdge)
+            numWrap = numEdge;
         const numTotal = numEdge + numWrap;
-        this.resizeAllDataArrays(numTotal);
+        this.resizeAllArrays(numTotal);
         // copy wrapped points
         for (let i = 0; i < numEdge; i++)
             this.point.transferFromGrowableXYZArray(i, other.point, other.pointIndex[index0 + i]);
@@ -190,41 +236,48 @@ class PolyfaceData {
             this.pointIndex[i] = other.pointIndex[index0 + i];
         for (let i = 0; i < numWrap; i++)
             this.pointIndex[numEdge + i] = this.pointIndex[i];
-        // copy wrapped edge visibility
-        for (let i = 0; i < numEdge; i++)
-            this.edgeVisible[i] = other.edgeVisible[index0 + i];
-        for (let i = 0; i < numWrap; i++)
-            this.edgeVisible[numEdge + i] = this.edgeVisible[i];
+        // copy wrapped normals
         if (this.normal && this.normalIndex && other.normal && other.normalIndex) {
             for (let i = 0; i < numEdge; i++)
                 this.normal.transferFromGrowableXYZArray(i, other.normal, other.normalIndex[index0 + i]);
             for (let i = 0; i < numWrap; i++)
                 this.normal.transferFromGrowableXYZArray(numEdge + i, this.normal, i);
+            // copy wrapped normalIndex
             for (let i = 0; i < numEdge; i++)
                 this.normalIndex[i] = other.normalIndex[index0 + i];
             for (let i = 0; i < numWrap; i++)
                 this.normalIndex[numEdge + i] = this.normalIndex[i];
         }
+        // copy wrapped params
         if (this.param && this.paramIndex && other.param && other.paramIndex) {
             for (let i = 0; i < numEdge; i++)
                 this.param.transferFromGrowableXYArray(i, other.param, other.paramIndex[index0 + i]);
             for (let i = 0; i < numWrap; i++)
                 this.param.transferFromGrowableXYArray(numEdge + i, this.param, i);
+            // copy wrapped paramIndex
             for (let i = 0; i < numEdge; i++)
                 this.paramIndex[i] = other.paramIndex[index0 + i];
             for (let i = 0; i < numWrap; i++)
                 this.paramIndex[numEdge + i] = this.paramIndex[i];
         }
+        // copy wrapped colors
         if (this.color && this.colorIndex && other.color && other.colorIndex) {
             for (let i = 0; i < numEdge; i++)
                 this.color[i] = other.color[other.colorIndex[index0 + i]];
             for (let i = 0; i < numWrap; i++)
                 this.color[numEdge + i] = this.color[i];
+            // copy wrapped colorIndex
             for (let i = 0; i < numEdge; i++)
                 this.colorIndex[i] = other.colorIndex[index0 + i];
             for (let i = 0; i < numWrap; i++)
                 this.colorIndex[numEdge + i] = this.colorIndex[i];
         }
+        // copy wrapped edge visibility
+        for (let i = 0; i < numEdge; i++)
+            this.edgeVisible[i] = other.edgeVisible[index0 + i];
+        for (let i = 0; i < numWrap; i++)
+            this.edgeVisible[numEdge + i] = this.edgeVisible[i];
+        // copy wrapped auxData
         if (this.auxData && other.auxData && this.auxData.channels.length === other.auxData.channels.length) {
             for (let iChannel = 0; iChannel < this.auxData.channels.length; iChannel++) {
                 const thisChannel = this.auxData.channels[iChannel];
@@ -241,19 +294,21 @@ class PolyfaceData {
                     }
                 }
             }
+            // copy wrapped auxData index
             for (let i = 0; i < numEdge; i++)
                 this.auxData.indices[i] = other.auxData.indices[index0 + i];
             for (let i = 0; i < numWrap; i++)
                 this.auxData.indices[numEdge + i] = this.auxData.indices[i];
         }
     }
+    /** Trim the `data` arrays to the stated `length`. */
     static trimArray(data, length) {
         if (data && length < data.length)
             data.length = length;
     }
     /**
-     * Trim all index arrays to the stated length.
-     * This is called by PolyfaceBuilder to clean up after an aborted construction sequence.
+     * Trim all index arrays to the stated `length`.
+     * * This is called by PolyfaceBuilder to clean up after an aborted construction sequence.
      */
     trimAllIndexArrays(length) {
         PolyfaceData.trimArray(this.pointIndex, length);
@@ -269,7 +324,78 @@ class PolyfaceData {
             }
         }
     }
-    /** Resize all data arrays to specified length */
+    /**
+     * Resize all data and index arrays to the specified `length`.
+     * * This is used by visitors, whose data and index arrays are all parallel.
+     */
+    resizeAllArrays(length) {
+        if (length > this.point.length) {
+            while (this.point.length < length)
+                this.point.push(Point3d.create());
+            while (this.pointIndex.length < length)
+                this.pointIndex.push(-1);
+            if (this.normal)
+                while (this.normal.length < length)
+                    this.normal.push(Vector3d.create());
+            if (this.normalIndex)
+                while (this.normalIndex.length < length)
+                    this.normalIndex.push(-1);
+            if (this.param)
+                while (this.param.length < length)
+                    this.param.push(Point2d.create());
+            if (this.paramIndex)
+                while (this.paramIndex.length < length)
+                    this.paramIndex.push(-1);
+            if (this.color)
+                while (this.color.length < length)
+                    this.color.push(0);
+            if (this.colorIndex)
+                while (this.colorIndex.length < length)
+                    this.colorIndex.push(-1);
+            while (this.edgeVisible.length < length)
+                this.edgeVisible.push(false);
+            if (this.auxData) {
+                for (const channel of this.auxData.channels) {
+                    for (const channelData of channel.data) {
+                        while (channelData.values.length < length * channel.entriesPerValue)
+                            channelData.values.push(0);
+                    }
+                }
+                if (this.auxData.indices)
+                    this.auxData.indices.push(-1);
+            }
+        }
+        else if (length < this.point.length) {
+            this.point.resize(length);
+            this.pointIndex.length = length;
+            if (this.normal)
+                this.normal.resize(length);
+            if (this.normalIndex)
+                this.normalIndex.length = length;
+            if (this.param)
+                this.param.resize(length);
+            if (this.paramIndex)
+                this.paramIndex.length = length;
+            if (this.color)
+                this.color.length = length;
+            if (this.colorIndex)
+                this.colorIndex.length = length;
+            this.edgeVisible.length = length;
+            if (this.auxData) {
+                for (const channel of this.auxData.channels) {
+                    for (const channelData of channel.data) {
+                        channelData.values.length = length * channel.entriesPerValue;
+                    }
+                }
+                if (this.auxData.indices)
+                    this.auxData.indices.length = length;
+            }
+        }
+    }
+    /**
+     * Resize all data arrays to the specified `length`.
+     * @deprecated in 4.x because name is misleading. Call [[PolyfaceData.resizeAllArrays]] instead.
+     */
     resizeAllDataArrays(length) {
         if (length > this.point.length) {
             while (this.point.length < length)
@@ -315,19 +441,21 @@ class PolyfaceData {
             }
         }
     }
-    /** Return the range of the point array (optionally transformed) */
+    /** Return the range of the point array (optionally transformed). */
     range(result, transform) {
         result = result ? result : Range3d.createNull();
         result.extendArray(this.point, transform);
         return result;
     }
-    /** reverse indices facet-by-facet, with the given facetStartIndex array delimiting faces.
-     *
-     * * facetStartIndex[0] == 0 always -- start of facet zero.
-     * * facet k has indices from facetStartIndex[k] <= i < facetStartIndex[k+1]
-     * * hence for "internal" k, facetStartIndex[k] is both the upper limit of facet k-1 and the start of facet k.
-     * *
-     */
+    /**
+     * Reverse the indices for the specified facets in the index arrays (pointIndex, normalIndex, paramIndex, colorIndex,
+     * and edgeVisible).
+     * @param facetStartIndex start indices of *consecutive* facets to be reversed.
+     * * Consecutive indices in this array define where a given facet is represented in each of the parallel index arrays.
+     * * The indices for facet k are `facetStartIndex[k]` up to (but not including) `facetStartIndex[k + 1]`.
+     * * This implies `facetStartIndex[k + 1]` is both the upper limit of facet k's indices, and the start index of facet k+1.
+     * * For example, passing an IndexedPolyface's _facetStart array into this method reverses every facet.
+    */
     reverseIndices(facetStartIndex) {
         if (facetStartIndex && PolyfaceData.isValidFacetStartIndexArray(facetStartIndex)) {
             PolyfaceData.reverseIndices(facetStartIndex, this.pointIndex, true);
@@ -340,31 +468,33 @@ class PolyfaceData {
             PolyfaceData.reverseIndices(facetStartIndex, this.edgeVisible, false);
         }
     }
-    /** reverse indices facet-by-facet, with the given facetStartIndex array delimiting faces.
-     *
-     * * facetStartIndex[0] == 0 always -- start of facet zero.
-     * * facet k has indices from facetStartIndex[k] <= i < facetStartIndex[k+1]
-     * * hence for "internal" k, facetStartIndex[k] is both the upper limit of facet k-1 and the start of facet k.
-     * *
+    /**
+     * Reverse the indices for the specified facet in the index arrays (pointIndex, normalIndex, paramIndex, colorIndex,
+     * and edgeVisible).
+     * @param facetIndex index of the facet to reverse. The entries of each index array to be reversed are found at
+     * `facetStartIndex[facetIndex] <= i < facetStartIndex[facetIndex + 1]`.
+     * @param facetStartIndex start indices of *consecutive* facets, e.g., an IndexedPolyface's _facetStart array.
+     * See [[reverseIndices]].
      */
-    reverseIndicesSingleFacet(facetId, facetStartIndex) {
-        PolyfaceData.reverseIndicesSingleFacet(facetId, facetStartIndex, this.pointIndex, true);
+    reverseIndicesSingleFacet(facetIndex, facetStartIndex) {
+        PolyfaceData.reverseIndicesSingleFacet(facetIndex, facetStartIndex, this.pointIndex, true);
         if (this.normalIndex !== this.pointIndex)
-            PolyfaceData.reverseIndicesSingleFacet(facetId, facetStartIndex, this.normalIndex, true);
+            PolyfaceData.reverseIndicesSingleFacet(facetIndex, facetStartIndex, this.normalIndex, true);
         if (this.paramIndex !== this.pointIndex)
-            PolyfaceData.reverseIndicesSingleFacet(facetId, facetStartIndex, this.paramIndex, true);
+            PolyfaceData.reverseIndicesSingleFacet(facetIndex, facetStartIndex, this.paramIndex, true);
         if (this.colorIndex !== this.pointIndex)
-            PolyfaceData.reverseIndicesSingleFacet(facetId, facetStartIndex, this.colorIndex, true);
-        PolyfaceData.reverseIndicesSingleFacet(facetId, facetStartIndex, this.edgeVisible, false);
+            PolyfaceData.reverseIndicesSingleFacet(facetIndex, facetStartIndex, this.colorIndex, true);
+        PolyfaceData.reverseIndicesSingleFacet(facetIndex, facetStartIndex, this.edgeVisible, false);
     }
-    /** Scale all the normals by -1 */
+    /** Scale all the normals by -1. */
     reverseNormals() {
         if (this.normal)
             this.normal.scaleInPlace(-1.0);
     }
-    /** Apply `transform` to point and normal arrays and to auxData.
-     * * IMPORTANT This base class is just a data carrier.  It does not know if the index order and normal directions have special meaning.
-     * * i.e. caller must separately reverse index order and normal direction if needed.
+    /**
+     * Apply `transform` to point and normal arrays and to auxData.
+     * * IMPORTANT This base class is just a data carrier. It does not know if the index order and normal directions
+     * have special meaning, i.e., caller must separately reverse index order and normal direction if needed.
      */
     tryTransformInPlace(transform) {
         this.point.multiplyTransformInPlace(transform);
@@ -377,13 +507,14 @@ class PolyfaceData {
      * * Search for duplicates within points, normals, params, and colors.
      * * Compress each data array.
      * * Revise all indexing for the relocated data.
-     * @param tolerance optional tolerance for clustering mesh vertices. Default is [[Geometry.smallMetricDistance]].
+     * @param tolerance (optional) tolerance for clustering mesh vertices. Default is [[Geometry.smallMetricDistance]].
      */
     compress(tolerance = Geometry.smallMetricDistance) {
+        // more info can be found at geometry/internaldocs/Polyface.md
         const packedPoints = ClusterableArray.clusterGrowablePoint3dArray(this.point, tolerance);
         this.point = packedPoints.growablePackedPoints;
         packedPoints.updateIndices(this.pointIndex);
-        // for now, normals, params, and colors use the default tolerance for clustering...
+        // for now, normals, params, and colors use the default tolerance for clustering
         if (this.normalIndex && this.normal) {
             const packedNormals = ClusterableArray.clusterGrowablePoint3dArray(this.normal);
             this.normal = packedNormals.growablePackedPoints;
@@ -401,10 +532,11 @@ class PolyfaceData {
         }
     }
     /**
-     * Test if facetStartIndex is (minimally!) valid:
-     * * length must be nonzero (recall that for "no facets" the facetStartIndexArray still must contain a 0)
+     * Test if `facetStartIndex` is (minimally) valid.
+     * * Length must be nonzero (recall that for "no facets", the `facetStartIndex` array still must contain a 0).
      * * Each entry must be strictly smaller than the one that follows.
-     * @param facetStartIndex array of facetStart data.  facet `i` has indices at `facetsStartIndex[i]` to (one before) `facetStartIndex[i+1]`
+     * @param facetStartIndex start indices of all facets. Facet k starts at facetStartIndex[k] up to (but not including)
+     * `facetStartIndex[k + 1]`
      */
     static isValidFacetStartIndexArray(facetStartIndex) {
         // facetStartIndex for empty facets has a single entry "0" -- empty array is not allowed
@@ -415,8 +547,14 @@ class PolyfaceData {
                 return false;
         return true;
     }
-    /** Reverse data in entire facet indexing arrays.
-     * * parameterized over type T so non-number data -- e.g. boolean visibility flags -- can be reversed.
+    /**
+     * Reverse the indices for the specified facets in the given index array.
+     * * Parameterized over type T so non-number data (e.g., boolean visibility flags) can be reversed.
+     * @param facetStartIndex start indices of *consecutive* facets to be reversed, e.g., an IndexedPolyface's _facetStart
+     * array. See the non-static [[reverseIndices]].
+     * @param indices the index array, e.g., pointIndex, normalIndex, etc.
+     * @param preserveStart `true` to preserve the start index of each facet (e.g., facet [1,2,3,4] becomes [1,4,3,2]);
+     * `false` to reverse all indices (e.g., facet [1,2,3,4] becomes [4,3,2,1]).
      */
     static reverseIndices(facetStartIndex, indices, preserveStart) {
         if (!indices || indices.length === 0)
@@ -426,8 +564,7 @@ class PolyfaceData {
                 for (let i = 0; i + 1 < facetStartIndex.length; i++) {
                     let index0 = facetStartIndex[i];
                     let index1 = facetStartIndex[i + 1];
-                    if (preserveStart) {
-                        // leave [index0] as is so reversed facet starts at same vertex
+                    if (preserveStart) { // leave "index0" as is so reversed facet starts at same vertex
                         while (index1 > index0 + 2) {
                             index1--;
                             index0++;
@@ -436,8 +573,7 @@ class PolyfaceData {
                             indices[index1] = a;
                         }
                     }
-                    else {
-                        // reverse all
+                    else { // reverse all
                         while (index1 > index0 + 1) {
                             index1--;
                             const a = indices[index0];
@@ -452,19 +588,26 @@ class PolyfaceData {
         }
         return false;
     }
-    /** Reverse data in entire facet indexing arrays.
-     * * parameterized over type T so non-number data -- e.g. boolean visibility flags -- can be reversed.
+    /**
+     * Reverse the indices for the specified facet in the specified index array.
+     * * Parameterized over type T so non-number data (e.g., boolean visibility flags) can be reversed.
+     * @param facetIndex index of the facet to reverse. The entries of `indices` to be reversed are found at
+     * `facetStartIndex[facetIndex] <= i < facetStartIndex[facetIndex + 1]`.
+     * @param facetStartIndex start indices of *consecutive* facets, e.g., an IndexedPolyface's _facetStart array.
+     * See [[reverseIndices]].
+     * @param indices the index array, e.g., pointIndex, normalIndex, etc.
+     * @param preserveStart `true` to preserve the start index of each facet (e.g., facet [1,2,3,4] becomes [1,4,3,2]);
+     * `false` to reverse all indices (e.g., facet [1,2,3,4] becomes [4,3,2,1]).
      */
-    static reverseIndicesSingleFacet(facetId, facetStartIndex, indices, preserveStart) {
+    static reverseIndicesSingleFacet(facetIndex, facetStartIndex, indices, preserveStart) {
         if (!indices || indices.length === 0)
             return true; // empty case
         if (indices.length > 0) {
             if (facetStartIndex[facetStartIndex.length - 1] === indices.length
-                && facetId >= 0 && facetId + 1 < facetStartIndex.length) {
-                let index0 = facetStartIndex[facetId];
-                let index1 = facetStartIndex[facetId + 1];
-                if (preserveStart) {
-                    // leave [index0] as is so reversed facet starts at same vertex
+                && facetIndex >= 0 && facetIndex + 1 < facetStartIndex.length) {
+                let index0 = facetStartIndex[facetIndex];
+                let index1 = facetStartIndex[facetIndex + 1];
+                if (preserveStart) { // leave "index0" as is so reversed facet starts at same vertex
                     while (index1 > index0 + 2) {
                         index1--;
                         index0++;
@@ -473,8 +616,7 @@ class PolyfaceData {
                         indices[index1] = a;
                     }
                 }
-                else {
-                    // reverse all
+                else { // reverse all
                     while (index1 > index0 + 1) {
                         index1--;
                         const a = indices[index0];
@@ -489,18 +631,10 @@ class PolyfaceData {
         return false;
     }
 }
-// <ul
-// <li>optional arrays (normal, uv, color) must be indicated at constructor time.
-// <li>all arrays are (independently) indexed.
-// <li>with regret, the point, param, normal, and color arrays are exposed publicly.
-// <li>getX methods are "trusting" -- no bounds check
-// <li>getX methods return references to X.
-// <li> EXCEPT -- for optional arrays, the return 000.
-// <li>copyX methods move data to caller-supplied result..
-// </ul>
-/** Relative tolerance used in tests for planar facets
+/**
+ * Relative tolerance used in tests for planar facets.
  * @internal
- */
+*/
 PolyfaceData.planarityLocalRelTol = 1.0e-13;
 export { PolyfaceData };
 //# sourceMappingURL=PolyfaceData.js.map