@itwin/core-geometry 4.5.0-dev.3 → 4.5.0-dev.30

package/lib/esm/polyface/Polyface.js

@@ -6,6 +6,7 @@
  * @module Polyface
  */
 /* eslint-disable @typescript-eslint/naming-convention, no-empty */
+// cspell:word internaldocs
 import { GeometryQuery } from "../curve/GeometryQuery";
 import { Geometry } from "../Geometry";
 import { GrowableXYArray } from "../geometry3d/GrowableXYArray";
@@ -21,6 +22,7 @@ import { PolyfaceData } from "./PolyfaceData";
  * @public
  */
 export class Polyface extends GeometryQuery {
+    /** Constructor */
     constructor(data) {
         super();
         /** String name for schema properties */
@@ -28,69 +30,102 @@ export class Polyface extends GeometryQuery {
         this.data = data;
     }
     /** Flag indicating if the mesh display must assume both sides are visible. */
-    get twoSided() { return this.data.twoSided; }
-    set twoSided(value) { this.data.twoSided = value; }
-    /** Flag indicating if the mesh closure is unknown (0), open sheet (1), closed (2) */
-    get expectedClosure() { return this.data.expectedClosure; }
-    set expectedClosure(value) { this.data.expectedClosure = value; }
+    get twoSided() {
+        return this.data.twoSided;
+    }
+    set twoSided(value) {
+        this.data.twoSided = value;
+    }
+    /**
+     * 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.data.expectedClosure;
+    }
+    set expectedClosure(value) {
+        this.data.expectedClosure = value;
+    }
     /**
-       * Check validity of indices into a data array.
-       * * It is valid to have  both indices and data undefined.
-       * * It is NOT valid for just one to be defined.
-       * * Index values at indices[indexPositionA <= i < indexPositionB] must be valid indices to the data array.
-       * @param indices array of indices.
-       * @param indexPositionA first index to test
-       * @param indexPositionB one past final index to test
-       * @param data data array
-       * @param dataLength length of data array
-       */
+     * Check validity of indices into a data array.
+     * * It is valid to have both indices and data undefined.
+     * * It is NOT valid for just one to be defined.
+     * * Index values at indices[indexPositionA <= i < indexPositionB] must be valid indices to the data array.
+     * @param indices array of indices.
+     * @param indexPositionA first index to test.
+     * @param indexPositionB one past final index to test.
+     * @param data data array.
+     * @param dataLength length of data array.
+     */
     static areIndicesValid(indices, indexPositionA, indexPositionB, data, dataLength) {
         if (indices === undefined && data === undefined)
             return true;
-        if (!indices || !data)
+        if (indices === undefined || data === undefined)
             return false;
         if (indexPositionA < 0 || indexPositionA >= indices.length)
             return false;
-        if (indexPositionB < indexPositionA || indexPositionB > indices.length)
+        if (indexPositionB <= indexPositionA || indexPositionB > indices.length)
             return false;
         for (let i = indexPositionA; i < indexPositionB; i++)
             if (indices[i] < 0 || indices[i] >= dataLength)
                 return false;
         return true;
     }
-    /**
-     * Returns the number of facets of this polyface. Subclasses should override.
-     */
+    /** Returns the number of facets of this polyface. Subclasses should override. */
     get facetCount() {
         return undefined;
     }
 }
 /**
- * An `IndexedPolyface` is a set of facets which can have normal, param, and color arrays with independent point, normal, param, and color indices.
+ * An `IndexedPolyface` is a set of facets which can have normal, param, and color arrays with independent point,
+ * normal, param, and color indices.
  * @public
  */
 export class IndexedPolyface extends Polyface {
+    /**
+     * Constructor for a new polyface.
+     * @param data PolyfaceData arrays to capture.
+     * @param facetStart optional array of facet start indices (e.g. known during clone)
+     * @param facetToFacetData optional array of face identifiers (e.g. known during clone)
+     */
+    constructor(data, facetStart, facetToFaceData) {
+        super(data);
+        if (facetStart)
+            this._facetStart = facetStart.slice(); // deep copy
+        else {
+            this._facetStart = [];
+            this._facetStart.push(0);
+        }
+        if (facetToFaceData)
+            this._facetToFaceData = facetToFaceData.slice(); // deep copy
+        else
+            this._facetToFaceData = [];
+    }
     /** Test if other is an instance of `IndexedPolyface` */
-    isSameGeometryClass(other) { return other instanceof IndexedPolyface; }
+    isSameGeometryClass(other) {
+        return other instanceof IndexedPolyface;
+    }
     /** Tests for equivalence between two IndexedPolyfaces. */
     isAlmostEqual(other) {
         if (other instanceof IndexedPolyface) {
-            return this.data.isAlmostEqual(other.data) && NumberArray.isExactEqual(this._facetStart, other._facetStart) &&
+            return this.data.isAlmostEqual(other.data) &&
+                NumberArray.isExactEqual(this._facetStart, other._facetStart) &&
                 NumberArray.isExactEqual(this._facetToFaceData, other._facetToFaceData);
         }
         return false;
     }
+    /** Returns true if either the point array or the point index array is empty. */
+    get isEmpty() {
+        return this.data.pointCount === 0 || this.data.pointIndex.length === 0;
+    }
     /**
-     * Returns true if either the point array or the point index array is empty.
-     */
-    get isEmpty() { return this.data.pointCount === 0 || this.data.pointIndex.length === 0; }
-    /**
-     * * apply the transform to points
-     * * apply the (inverse transpose of) the matrix part to normals
-     * * If determinant is negative, also
+     * Transform the mesh.
+     * * Apply the transform to points.
+     * * Apply the (inverse transpose of the) matrix part to normals.
+     * * If determinant of the transform matrix is negative, also
      *   * negate normals
      *   * reverse index order around each facet.
-     * @param transform
      */
     tryTransformInPlace(transform) {
         if (!this.data.tryTransformInPlace(transform))
@@ -111,52 +146,47 @@ export class IndexedPolyface extends Polyface {
         const result = new IndexedPolyface(this.data.clone(), this._facetStart.slice(), this._facetToFaceData.slice());
         return result;
     }
-    /** Return a deep clone with transformed points and normals */
+    /**
+     * Return a deep clone with transformed points and normals.
+     * @see [[IndexedPolyface.tryTransformInPlace]] for details of how transform is done.
+     */
     cloneTransformed(transform) {
         const result = this.clone();
         result.tryTransformInPlace(transform);
         return result;
     }
     /** Reverse the order of indices around all facets. */
-    reverseIndices() { this.data.reverseIndices(this._facetStart); }
+    reverseIndices() {
+        this.data.reverseIndices(this._facetStart);
+    }
     /** Reverse the direction of all normal vectors. */
-    reverseNormals() { this.data.reverseNormals(); }
-    /** return face data using a facet index. This is the REFERENCE to the FacetFaceData, not a copy. Returns undefined if none found. */
+    reverseNormals() {
+        this.data.reverseNormals();
+    }
+    /**
+     * Return face data using a facet index.
+     * * Returns `undefined` if none found.
+     * * This is the REFERENCE to the FacetFaceData not a copy.
+     */
     tryGetFaceData(i) {
+        if (i < 0 || i >= this._facetToFaceData.length)
+            return undefined;
         const faceIndex = this._facetToFaceData[i];
-        if (faceIndex >= this.data.face.length)
+        if (faceIndex < 0 || faceIndex >= this.data.face.length)
             return undefined;
         return this.data.face[faceIndex];
     }
     /**
-     * Constructor for a new polyface.
-     * @param data PolyfaceData arrays to capture.
-     * @param facetStart optional array of facet start indices (e.g. known during clone)
-     * @param facetToFacetData optional array of face identifiers (e.g. known during clone)
-     */
-    constructor(data, facetStart, facetToFaceData) {
-        super(data);
-        if (facetStart)
-            this._facetStart = facetStart.slice();
-        else {
-            this._facetStart = [];
-            this._facetStart.push(0);
-        }
-        if (facetToFaceData)
-            this._facetToFaceData = facetToFaceData.slice();
-        else
-            this._facetToFaceData = [];
-    }
-    /**
-     * * Add facets from source to this polyface.
-     * * Optionally reverse facet indices as per PolyfaceData.reverseIndicesSingleFacet() with preserveStart = false, and invert source normals.
-     * * Optionally apply a transform to points and normals.
+     * Add facets from `source` to `this` polyface.
+     * * Optionally reverse facet indices as per `PolyfaceData.reverseIndicesSingleFacet()` with `preserveStart = false` and
+     * invert source normals.
+     * * Optionally apply a `transform` to points and normals.
      * * Will only copy param, normal, color, and face data if we are already tracking them AND/OR the source contains them.
      */
     addIndexedPolyface(source, reversed, transform) {
         const numSourceFacets = source.facetCount;
-        // Add point, point index, and edge visibility data
-        // Note: there is no need to build an intermediate index map since all points are added
+        // add point, point index, and edge visibility data
+        // note that there is no need to build an intermediate index map since all points are added
         const startOfNewPoints = this.data.point.length;
         const xyz = Point3d.create();
         for (let i = 0; i < source.data.point.length; i++) {
@@ -183,11 +213,11 @@ export class IndexedPolyface extends Polyface {
             }
             this.terminateFacet(false);
         }
-        // Add param and param index data
+        // add param and param index data
         if (undefined !== this.data.param && undefined !== source.data.param && undefined !== source.data.paramIndex) {
             const startOfNewParams = this.data.param.length;
             this.data.param.pushFromGrowableXYArray(source.data.param);
-            for (let i = 0; i < numSourceFacets; i++) { // Expect facet start and ends for points to match normals
+            for (let i = 0; i < numSourceFacets; i++) { // expect facet start and ends for points to match normals
                 const i0 = source._facetStart[i];
                 const i1 = source._facetStart[i + 1];
                 if (reversed) {
@@ -200,7 +230,7 @@ export class IndexedPolyface extends Polyface {
                 }
             }
         }
-        // Add normal and normal index data
+        // add normal and normal index data
         if (undefined !== this.data.normal && undefined !== source.data.normal && undefined !== source.data.normalIndex) {
             const startOfNewNormals = this.data.normal.length;
             for (let i = 0; i < source.data.normal.length; i++) {
@@ -211,7 +241,7 @@ export class IndexedPolyface extends Polyface {
                     sourceNormal.scaleInPlace(-1.0);
                 this.addNormal(sourceNormal);
             }
-            for (let i = 0; i < numSourceFacets; i++) { // Expect facet start and ends for points to match normals
+            for (let i = 0; i < numSourceFacets; i++) { // expect facet start and ends for points to match normals
                 const i0 = source._facetStart[i];
                 const i1 = source._facetStart[i + 1];
                 if (reversed) {
@@ -224,12 +254,12 @@ export class IndexedPolyface extends Polyface {
                 }
             }
         }
-        // Add color and color index data
+        // add color and color index data
         if (undefined !== this.data.color && undefined !== source.data.color && undefined !== source.data.colorIndex) {
             const startOfNewColors = this.data.color.length;
             for (const sourceColor of source.data.color)
                 this.addColor(sourceColor);
-            for (let i = 0; i < numSourceFacets; i++) { // Expect facet start and ends for points to match colors
+            for (let i = 0; i < numSourceFacets; i++) { // expect facet start and ends for points to match colors
                 const i0 = source._facetStart[i];
                 const i1 = source._facetStart[i + 1];
                 if (reversed) {
@@ -242,7 +272,7 @@ export class IndexedPolyface extends Polyface {
                 }
             }
         }
-        // Add face and facetToFace index data
+        // add face and facetToFace index data
         if (source.data.face.length !== 0) {
             const startOfNewFaceData = this.data.face.length;
             for (const face of source.data.face) {
@@ -254,25 +284,31 @@ export class IndexedPolyface extends Polyface {
             }
         }
     }
-    /** Return the total number of param indices in zero-terminated style, which includes
-     * * all the indices in the packed zero-based table
+    /**
+     * Return the total number of indices in zero-terminated style, which includes
+     * * all the indices in the packed zero-based table.
      * * one additional index for the zero-terminator of each facet.
-     * @note Note that all index arrays (point, normal, param, color) have the same counts, so there
+     * @note Note that all index arrays (pointIndex, normalIndex, paramIndex, colorIndex) have the same counts, so there
      * is not a separate query for each of them.
      */
-    get zeroTerminatedIndexCount() { return this.data.pointIndex.length + this._facetStart.length - 1; }
-    /** Create an empty facet set, with coordinate and index data to be supplied later.
-     * @param needNormals true if normals will be constructed
-     * @param needParams true if uv parameters will be constructed
-     * @param needColors true if colors will e constructed.
+    get zeroTerminatedIndexCount() {
+        return this.data.pointIndex.length + this._facetStart.length - 1;
+    }
+    /**
+     * Create an empty facet set with coordinate and index data to be supplied later.
+     * @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.
      */
     static create(needNormals = false, needParams = false, needColors = false, twoSided = false) {
         return new IndexedPolyface(new PolyfaceData(needNormals, needParams, needColors, twoSided));
     }
-    /** add (a clone of ) a point. return its 0 based index.
-     * @param point point coordinates
-     * @param priorIndex optional index of prior point to check for repeated coordinates
-     * @returns Returns the zero-based index of the added or reused point.
+    /**
+     * Add (a clone of) a point to point array.
+     * @param point the point.
+     * @param priorIndex (optional) index of prior point to check for possible duplicate value.
+     * @returns the zero-based index of the added or duplicate point.
      */
     addPoint(point, priorIndex) {
         if (priorIndex !== undefined) {
@@ -283,12 +319,21 @@ export class IndexedPolyface extends Polyface {
         this.data.point.pushXYZ(point.x, point.y, point.z);
         return this.data.point.length - 1;
     }
-    /** add a point.
-     * @returns Returns the zero-based index of the added point.
+    /**
+     * Add a point to point array.
+     * @param x the x coordinate of point.
+     * @param y the y coordinate of point.
+     * @param z the z coordinate of point.
+     * @returns the zero-based index of the added point.
      */
-    addPointXYZ(x, y, z) { this.data.point.pushXYZ(x, y, z); return this.data.point.length - 1; }
-    /** Add a uv param.
-     * @returns 0-based index of the added param.
+    addPointXYZ(x, y, z) {
+        this.data.point.pushXYZ(x, y, z);
+        return this.data.point.length - 1;
+    }
+    /**
+     * Add (a clone of) a uv parameter to the parameter array.
+     * @param param the parameter.
+     * @returns zero-based index of the added param.
      */
     addParam(param) {
         if (!this.data.param)
@@ -296,10 +341,13 @@ export class IndexedPolyface extends Polyface {
         this.data.param.push(param);
         return this.data.param.length - 1;
     }
-    /** Add a uv parameter to the parameter array.
+    /**
+     * Add a uv parameter to the parameter array.
+     * @param u the u part of parameter.
+     * @param v the v part of parameter.
      * @param priorIndexA first index to check for possible duplicate value.
      * @param priorIndexB second index to check for possible duplicate value.
-     * @returns 0-based index of the added or reused param.
+     * @returns zero-based index of the added or duplicate parameter.
      */
     addParamUV(u, v, priorIndexA, priorIndexB) {
         if (!this.data.param)
@@ -311,37 +359,39 @@ export class IndexedPolyface extends Polyface {
         this.data.param.pushXY(u, v);
         return this.data.param.length - 1;
     }
-    /** Add a normal vector
+    /**
+     * Add (a clone of) a normal vector to the normal array.
+     * @param normal the normal vector.
      * @param priorIndexA first index to check for possible duplicate value.
      * @param priorIndexB second index to check for possible duplicate value.
-     * @returns 0-based index of the added or reused normal.
+     * @returns zero-based index of the added or duplicate normal.
      */
     addNormal(normal, priorIndexA, priorIndexB) {
+        // check if `normal` is duplicate of `dataNormal` at index `i`
+        const normalIsDuplicate = (i) => {
+            const distance = this.data.normal.distanceIndexToPoint(i, normal);
+            return distance !== undefined && Geometry.isSmallMetricDistance(distance);
+        };
         if (this.data.normal !== undefined) {
-            let distance;
-            if (priorIndexA !== undefined) {
-                distance = this.data.normal.distanceIndexToPoint(priorIndexA, normal);
-                if (distance !== undefined && Geometry.isSmallMetricDistance(distance))
-                    return priorIndexA;
-            }
-            if (priorIndexB !== undefined) {
-                distance = this.data.normal.distanceIndexToPoint(priorIndexB, normal);
-                if (distance !== undefined && Geometry.isSmallMetricDistance(distance))
-                    return priorIndexB;
-            }
-            // Note: Do NOT attempt to chain to tail if no prior indices given.
-            // But if they are, look also to the tail.
+            if (priorIndexA !== undefined && normalIsDuplicate(priorIndexA))
+                return priorIndexA;
+            if (priorIndexB !== undefined && normalIsDuplicate(priorIndexB))
+                return priorIndexB;
+            // check the tail index for possible duplicate
             if (priorIndexA !== undefined || priorIndexB !== undefined) {
                 const tailIndex = this.data.normal.length - 1;
-                distance = this.data.normal.distanceIndexToPoint(tailIndex, normal);
-                if (distance !== undefined && Geometry.isSmallMetricDistance(distance))
+                if (normalIsDuplicate(tailIndex))
                     return tailIndex;
             }
         }
         return this.addNormalXYZ(normal.x, normal.y, normal.z);
     }
-    /** Add a normal vector given by direct coordinates
-     * @returns 0-based index of the added or reused param.
+    /**
+     * Add a normal vector to the normal array.
+     * @param x the x coordinate of normal.
+     * @param y the y coordinate of normal.
+     * @param z the z coordinate of normal.
+     * @returns zero-based index of the added normal vector.
      */
     addNormalXYZ(x, y, z) {
         if (!this.data.normal)
@@ -349,8 +399,10 @@ export class IndexedPolyface extends Polyface {
         this.data.normal.pushXYZ(x, y, z);
         return this.data.normal.length - 1;
     }
-    /** Add a color
-     * @returns 0-based index of the added or reused color.
+    /**
+     * Add a color to the color array
+     * @param color the color.
+     * @returns zero-based index of the added color.
      */
     addColor(color) {
         if (!this.data.color)
@@ -359,46 +411,54 @@ export class IndexedPolyface extends Polyface {
         return this.data.color.length - 1;
     }
     /** Add a point index with edge visibility flag. */
-    addPointIndex(index, visible = true) { this.data.pointIndex.push(index); this.data.edgeVisible.push(visible); }
-    /** Add a normal index */
+    addPointIndex(index, visible = true) {
+        this.data.pointIndex.push(index);
+        this.data.edgeVisible.push(visible);
+    }
+    /** Add a normal index. */
     addNormalIndex(index) {
         if (!this.data.normalIndex)
             this.data.normalIndex = [];
         this.data.normalIndex.push(index);
     }
-    /** Add a param index */
+    /** Add a param index. */
     addParamIndex(index) {
         if (!this.data.paramIndex)
             this.data.paramIndex = [];
         this.data.paramIndex.push(index);
     }
-    /** Add a color index */
+    /** Add a color index. */
     addColorIndex(index) {
         if (!this.data.colorIndex)
             this.data.colorIndex = [];
         this.data.colorIndex.push(index);
     }
-    /** clean up the open facet.  return the returnValue (so caller can easily return cleanupOpenFacet("message")) */
+    /**
+     * Clean up the open facet.
+     * @deprecated in 4.x to remove nebulous "open facet" concept from the API. Call [[PolyfaceData.trimAllIndexArrays]]
+     * instead.
+     */
     cleanupOpenFacet() {
         this.data.trimAllIndexArrays(this.data.pointIndex.length);
     }
-    /** announce the end of construction of a facet.
-     *
-     * * The "open" facet is checked for:
-     *
-     * **  Same number of indices among all active index arrays --  point, normal, param, color
-     * **  All indices are within bounds of the respective data arrays.
-     * *  in error cases, all index arrays are trimmed back to the size when previous facet was terminated.
-     * *  "undefined" return is normal.   Any other return is a description of an error.
+    /**
+     * Announce the end of construction of a facet.
+     * * Optionally check for:
+     *   * Same number of indices among all active index arrays -- point, normal, param, color
+     *   * All indices are within bounds of the respective data arrays.
+     * * In error cases, all index arrays are trimmed back to the size when previous facet was terminated.
+     * * A return value of `undefined` is normal. Otherwise, a string array of error messages is returned.
      */
     terminateFacet(validateAllIndices = true) {
         const numFacets = this._facetStart.length - 1;
-        const lengthA = this._facetStart[numFacets]; // number of indices in accepted facets
-        const lengthB = this.data.pointIndex.length; // number of indices including the open facet
+        // number of indices in accepted facets
+        const lengthA = this._facetStart[numFacets];
+        // number of indices in all facets (accepted facet plus the last facet to be accepted)
+        const lengthB = this.data.pointIndex.length;
         if (validateAllIndices) {
             const messages = [];
             if (lengthB < lengthA + 2)
-                messages.push("Less than 3 indices in open facet");
+                messages.push("Less than 3 indices in the last facet");
             if (this.data.normalIndex && this.data.normalIndex.length !== lengthB)
                 messages.push("normalIndex count must match pointIndex count");
             if (this.data.paramIndex && this.data.paramIndex.length !== lengthB)
@@ -407,71 +467,100 @@ export class IndexedPolyface extends Polyface {
                 messages.push("colorIndex count must equal pointIndex count");
             if (this.data.edgeVisible.length !== lengthB)
                 messages.push("visibleIndex count must equal pointIndex count");
+            if (!Polyface.areIndicesValid(this.data.pointIndex, lengthA, lengthB, this.data.point, this.data.point ? this.data.point.length : 0))
+                messages.push("invalid point indices in the last facet");
             if (!Polyface.areIndicesValid(this.data.normalIndex, lengthA, lengthB, this.data.normal, this.data.normal ? this.data.normal.length : 0))
-                messages.push("invalid normal indices in open facet");
+                messages.push("invalid normal indices in the last facet");
+            if (!Polyface.areIndicesValid(this.data.paramIndex, lengthA, lengthB, this.data.param, this.data.param ? this.data.param.length : 0))
+                messages.push("invalid param indices in the last facet");
+            if (!Polyface.areIndicesValid(this.data.colorIndex, lengthA, lengthB, this.data.color, this.data.color ? this.data.color.length : 0))
+                messages.push("invalid color indices in the last facet");
             if (messages.length > 0) {
-                this.cleanupOpenFacet();
+                this.data.trimAllIndexArrays(lengthA);
                 return messages;
             }
         }
-        // appending to facetStart accepts the facet !!!
-        this._facetStart.push(lengthB);
+        this._facetStart.push(lengthB); // append start index of the future facet
         return undefined;
     }
-    /**
-     * All terminated facets added since the declaration of the previous face
-     * will be grouped into a new face with their own 2D range.
-     */
-    /** (read-only property) number of facets */
-    get facetCount() { return this._facetStart.length - 1; }
-    /** (read-only property) number of faces */
-    get faceCount() { return this.data.faceCount; }
-    /** (read-only property) number of points */
-    get pointCount() { return this.data.pointCount; }
-    /** (read-only property) number of colors */
-    get colorCount() { return this.data.colorCount; }
-    /** (read-only property) number of parameters */
-    get paramCount() { return this.data.paramCount; }
-    /** (read-only property) number of normals */
-    get normalCount() { return this.data.normalCount; }
+    /** Number of facets (read-only property). */
+    get facetCount() {
+        return this._facetStart.length - 1;
+    }
+    /** Number of faces (read-only property). */
+    get faceCount() {
+        return this.data.faceCount;
+    }
+    /** Number of points (read-only property). */
+    get pointCount() {
+        return this.data.pointCount;
+    }
+    /** Number of colors (read-only property). */
+    get colorCount() {
+        return this.data.colorCount;
+    }
+    /** Number of parameters (read-only property). */
+    get paramCount() {
+        return this.data.paramCount;
+    }
+    /** Number of normals (read-only property). */
+    get normalCount() {
+        return this.data.normalCount;
+    }
+    /** Test if `index` is a valid facet index. */
+    isValidFacetIndex(index) {
+        return index >= 0 && index < this.facetCount;
+    }
     /** Return the number of edges in a particular facet. */
     numEdgeInFacet(facetIndex) {
         if (this.isValidFacetIndex(facetIndex))
             return this._facetStart[facetIndex + 1] - this._facetStart[facetIndex];
         return 0;
     }
-    /** test if `index` is a valid facet index. */
-    isValidFacetIndex(index) { return index >= 0 && index + 1 < this._facetStart.length; }
-    /** ASSUME valid facet index . .. return its start index in index arrays. */
-    facetIndex0(index) { return this._facetStart[index]; }
-    /** ASSUME valid facet index . .. return its end index in index arrays. */
-    facetIndex1(index) { return this._facetStart[index + 1]; }
-    /** create a visitor for this polyface */
-    createVisitor(numWrap = 0) { return IndexedPolyfaceVisitor.create(this, numWrap); }
+    /** ASSUME valid facet index. Return start index of facet in pointIndex arrays. */
+    facetIndex0(index) {
+        return this._facetStart[index];
+    }
+    /** ASSUME valid facet index. Return one past end index of facet in pointIndex arrays. */
+    facetIndex1(index) {
+        return this._facetStart[index + 1];
+    }
+    /** Create a visitor for this polyface */
+    createVisitor(numWrap = 0) {
+        return IndexedPolyfaceVisitor.create(this, numWrap);
+    }
     /** Return the range of (optionally transformed) points in this mesh. */
-    range(transform, result) { return this.data.range(result, transform); }
-    /** Extend `range` with coordinates from this mesh */
-    extendRange(range, transform) { this.data.range(range, transform); }
-    /** Given the index of a facet, return the data pertaining to the face it is a part of. */
+    range(transform, result) {
+        return this.data.range(result, transform);
+    }
+    /** Extend `range` with coordinates from this mesh. */
+    extendRange(range, transform) {
+        this.data.range(range, transform);
+    }
+    /**
+     * Given the index of a facet, return the data pertaining to the face it is a part of.
+     * @deprecated in 4.x. Use [[IndexedPolyface.tryGetFaceData]], which verifies the index is in range.
+     */
     getFaceDataByFacetIndex(facetIndex) {
         return this.data.face[this._facetToFaceData[facetIndex]];
     }
     /**
-     * All terminated facets since the last face declaration will be mapped to a single new FacetFaceData object
-     * using facetToFaceData[]. FacetFaceData holds the 2D range of the face. Returns true if successful, false otherwise.
+     * Set new FacetFaceData.
+     * * All terminated facets since the last face declaration will be mapped to a single new FacetFaceData object using
+     * facetToFaceData[]. FacetFaceData holds the 2D range of the face. Returns `true` if successful, `false` otherwise.
      */
     setNewFaceData(endFacetIndex = 0) {
         const facetStart = this._facetToFaceData.length;
         if (facetStart >= this._facetStart.length)
             return false;
-        if (0 === endFacetIndex) // The default for endFacetIndex is really the last facet
-            endFacetIndex = this._facetStart.length; // Last facetStart index corresponds to the next facet if we were to create one
+        if (0 === endFacetIndex) // the default for endFacetIndex is really the last facet
+            endFacetIndex = this._facetStart.length; // last facet index corresponds to the future facet
         const faceData = FacetFaceData.createNull();
         const visitor = IndexedPolyfaceVisitor.create(this, 0);
-        if (!visitor.moveToReadIndex(facetStart)) { // Move visitor to first facet of new face
+        if (!visitor.moveToReadIndex(facetStart)) { // move visitor to first facet of new face
             return false;
         }
-        // If parameter range is provided (by the polyface planeSet clipper) then use it
+        // if parameter range is provided (by the polyface planeSet clipper) then use it
         const paramDefined = this.data.param !== undefined;
         const setParamRange = faceData.paramRange.isNull && paramDefined;
         do {
@@ -486,7 +575,7 @@ export class IndexedPolyface extends Polyface {
             this._facetToFaceData.push(0 === this._facetStart[i] ? 0 : faceDataIndex);
         return true;
     }
-    /** Second step of double dispatch:  call `handler.handleIndexedPolyface(this)` */
+    /** Second step of double dispatch: call `handler.handleIndexedPolyface(this)`. */
     dispatchToGeometryHandler(handler) {
         return handler.handleIndexedPolyface(this);
     }