@itwin/core-geometry 4.8.0-dev.9 → 4.9.0-dev.1

package/lib/cjs/polyface/PolyfaceBuilder.js

@@ -44,10 +44,10 @@ const IndexedPolyfaceVisitor_1 = require("./IndexedPolyfaceVisitor");
 const Polyface_1 = require("./Polyface");
 const PolyfaceQuery_1 = require("./PolyfaceQuery");
 /**
- * A FacetSector
- * * initially holds coordinate data for a place where xyz and sectionDerivative are known
- * * normal is computed as a deferred step using an edge to adjacent place on ruled surface
- * * indices are set up even later.
+ * A FacetSector.
+ * * Initially holds coordinate data for a place where xyz and sectionDerivative are known.
+ * * Normal is computed as a deferred step using an edge to adjacent place on ruled surface.
+ * * Indices are set up even later.
  */
 class FacetSector {
     constructor(needNormal = false, needUV = false, needSectionDerivative = false) {
@@ -66,8 +66,9 @@ class FacetSector {
             this.sectionDerivative = Point3dVector3d_1.Vector3d.create();
         }
     }
-    /** copy contents (not pointers) from source
-     * * ASSUME all fields defined in this are defined int the source (undefined check only needed on this)
+    /**
+     * Copy contents (not pointers) from `other`.
+     * * ASSUME all fields defined in the instance are defined in `other`.
      */
     copyContentsFrom(other) {
         this.xyz.setFromPoint3d(other.xyz);
@@ -81,10 +82,11 @@ class FacetSector {
         if (this.sectionDerivative)
             this.sectionDerivative.setFrom(other.sectionDerivative);
     }
-    /** access xyz, derivative from given arrays.
-     * * ASSUME corresponding defined conditions
+    /**
+     * Access xyz, derivative from given arrays.
+     * * ASSUME corresponding defined conditions.
      * * xyz and derivative are set.
-     * * index fields for updated data are cleared to -1.
+     * * Index fields for updated data are cleared to -1.
      */
     loadIndexedPointAndDerivativeCoordinatesFromPackedArrays(i, packedXYZ, packedDerivatives, fractions, v) {
         packedXYZ.getPoint3dAtCheckedPointIndex(i, this.xyz);
@@ -106,16 +108,14 @@ class FacetSector {
             uvw.z = 0.0;
     }
     /**
-     * given two sectors with xyz and sectionDerivative (u derivative)
-     * use the edge from A to B as v direction in-surface derivative.
-     * compute cross products (and normalize)
-     * @param sectorA "lower" sector
-     * @param sectorB "upper" sector
-     *
+     * Given two sectors with xyz and sectionDerivative (u derivative), use the edge from A to B as v direction
+     * in-surface derivative. Compute cross products (and normalize).
+     * @param sectorA "lower" sector.
+     * @param sectorB "upper" sector.
      */
     static computeNormalsAlongRuleLine(sectorA, sectorB) {
-        // We expect that if sectionDerivative is defined so is normal.
-        // (If not, the cross product calls will generate normals that are never used ..  not good, garbage collector will clean up.)
+        // We expect that if a sector's sectionDerivative is defined, then so is its normal. If a normal is undefined, the
+        // crossProduct returns an object that goes unused---not good, but the garbage collector will clean it up.
         if (sectorA.sectionDerivative && sectorB.sectionDerivative) {
             const vectorAB = FacetSector._edgeVector;
             Point3dVector3d_1.Vector3d.createStartEnd(sectorA.xyz, sectorB.xyz, vectorAB);
@@ -130,12 +130,10 @@ class FacetSector {
 }
 FacetSector._edgeVector = Point3dVector3d_1.Vector3d.create();
 /**
- *
  * * Simple construction for strongly typed GeometryQuery objects:
  *
  *  * Create a builder with `builder = PolyfaceBuilder.create()`
  *  * Add GeometryQuery objects:
- *
  *    * `builder.addGeometryQuery(g: GeometryQuery)`
  *    * `builder.addCone(cone: Cone)`
  *    * `builder.addTorusPipe(surface: TorusPipe)`
@@ -146,7 +144,7 @@ FacetSector._edgeVector = Point3dVector3d_1.Vector3d.create();
  *    * `builder.addSphere(sphere: Sphere)`
  *    * `builder.addBox(box: Box)`
  *    * `builder.addIndexedPolyface(polyface)`
- *  *  Extract with `builder.claimPolyface(true)`
+ *  * Extract with `builder.claimPolyface(true)`
  *
  * * Simple construction for ephemeral constructive data:
  *
@@ -162,9 +160,10 @@ FacetSector._edgeVector = Point3dVector3d_1.Vector3d.create();
  *    * `builder.addTrianglesInUncheckedConvexPolygon(linestring, toggle)`
  *    * `builder.addUVGridBody(surface,numU, numV, createFanInCaps)`
  *    * `builder.addGraph(Graph, acceptFaceFunction)`
- *  *  Extract with `builder.claimPolyface(true)`
+ *  * Extract with `builder.claimPolyface(true)`
+ *
+ * * Low-level detail construction -- direct use of indices:
  *
- * * Low-level detail construction -- direct use of indices
  *  * Create a builder with `builder = PolyfaceBuilder.create()`
  *  * Add GeometryQuery objects
  *    * `builder.addPoint(point)`
@@ -172,17 +171,21 @@ FacetSector._edgeVector = Point3dVector3d_1.Vector3d.create();
  *    * `builder.addPointXYZ(x,y,z)`
  *    * `builder.addTriangleFacet(points)`
  *    * `builder.addQuadFacet(points)`
-  * @public
+ * @public
  */
 class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
-    /** return (pointer to) the `StrokeOptions` in use by the builder. */
-    get options() { return this._options; }
+    /** Return (pointer to) the `StrokeOptions` in use by the builder. */
+    get options() {
+        return this._options;
+    }
     /** Ask if this builder is reversing vertex order as loops are received. */
-    get reversedFlag() { return this._reversed; }
+    get reversedFlag() {
+        return this._reversed;
+    }
     /**
      * Extract the polyface.
-     * @param compress whether to cluster vertices (default true)
-     * @param tolerance compression tolerance (default Geometry.smallMetricDistance)
+     * @param compress whether to cluster vertices (default `true`).
+     * @param tolerance compression tolerance (default `Geometry.smallMetricDistance`).
      */
     claimPolyface(compress = true, tolerance = Geometry_1.Geometry.smallMetricDistance) {
         if (compress)
@@ -190,7 +193,9 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         return this._polyface;
     }
     /** Toggle (reverse) the flag controlling orientation flips for newly added facets. */
-    toggleReversedFacetFlag() { this._reversed = !this._reversed; }
+    toggleReversedFacetFlag() {
+        this._reversed = !this._reversed;
+    }
     constructor(options) {
         super();
         this._options = options ? options : StrokeOptions_1.StrokeOptions.createForFacets();
@@ -198,25 +203,27 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         this._reversed = false;
     }
     /**
-     * Create a builder with given StrokeOptions
-     * @param options StrokeOptions (captured)
+     * Create a builder with given StrokeOptions.
+     * @param options StrokeOptions (captured).
      */
     static create(options) {
         return new PolyfaceBuilder(options);
     }
-    /** add facets for a transformed unit box. */
+    /** Add facets for a transformed unit box. */
     addTransformedUnitBox(transform) {
         this.addTransformedRangeMesh(transform, Range_1.Range3d.createXYZXYZ(0, 0, 0, 1, 1, 1));
     }
-    /** Add facets for a transformed range box.
+    /**
+     * Add facets for a transformed range box.
      * * For best results, the transformed range corners should define a nonzero volume or area.
-     * @param transform applied to the range points before adding to the polyface
-     * @param range sides become 6 quad polyface facets
-     * @param faceSelector for each face in the order of BoxTopology.cornerIndexCCW, faceSelector[i]===false skips that facet.
+     * @param transform applied to the range points before adding to the polyface.
+     * @param range sides become 6 quad polyface facets.
+     * @param faceSelector for each face in the order of `BoxTopology.cornerIndexCCW`, `faceSelector[i] === false` skips
+     * that facet.
     */
     addTransformedRangeMesh(transform, range, faceSelector) {
         const pointIndex0 = this._polyface.data.pointCount;
-        // these will have sequential indices starting at pointIndex0 . . .
+        // these will have sequential indices starting at pointIndex0
         const points = range.corners();
         for (const p of points)
             this._polyface.addPoint(transform.multiplyPoint3d(p));
@@ -238,9 +245,11 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             faceCounter++;
         }
     }
-    /** Add triangles from points[0] to each far edge.
-     * @param ls linestring with point coordinates
-     * @param toggle if true, wrap the triangle creation in toggleReversedFacetFlag.
+    /**
+     * Add triangles from `conePoint` to each far edge.
+     * @param conePoint the common vertex of all triangles.
+     * @param ls linestring with point coordinates.
+     * @param toggle if `true`, wrap the triangle creation in toggleReversedFacetFlag.
      */
     addTriangleFan(conePoint, ls, toggle) {
         const n = ls.numPoints();
@@ -259,12 +268,11 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                 this.toggleReversedFacetFlag();
         }
     }
-    /** Add triangles from points[0] to each far edge
-     * * Assume the polygon is convex.
-     * * i.e. simple triangulation from point0
-     * * i.e. simple cross products give a good normal.
-     * @param ls linestring with point coordinates
-     * @param reverse if true, wrap the triangle creation in toggleReversedFacetFlag.
+    /**
+     * Add triangles from the first point of the linestring to the subsequent edges of the linestring.
+     * * No checks are made for polygon convexity or edge collinearity, conditions which would ensure positive area triangles.
+     * @param ls linestring with point coordinates.
+     * @param reverse if `true`, wrap the triangle creation in toggleReversedFacetFlag.
      */
     addTrianglesInUncheckedConvexPolygon(ls, toggle) {
         const n = ls.numPoints();
@@ -309,36 +317,36 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                 this.toggleReversedFacetFlag();
         }
     }
-    /**
-     * Announce point coordinates.
-     */
+    /** Add a point to the polyface. */
     addPoint(xyz) {
         return this._polyface.addPoint(xyz);
     }
     /**
-     * Announce point coordinates.
+     * Add a point to the polyface.
      * @deprecated in 3.x. Use addPoint instead.
      */
     findOrAddPoint(xyz) {
         return this.addPoint(xyz);
     }
-    /**
-     * Announce uv parameter coordinates.
-     */
+    /** Add a uv parameter to the polyface. */
     addParamXY(x, y) {
         return this._polyface.addParamUV(x, y);
     }
     /**
-     * Announce uv parameter coordinates.
+     * Add a uv parameter to the polyface.
      * @deprecated in 3.x. Use addParamXY instead.
      */
     findOrAddParamXY(x, y) {
         return this.addParamXY(x, y);
     }
     /**
-     * Announce point coordinates.  The implementation is free to either create a new point or (if known) return index of a prior point with the same coordinates.
-     * @returns Returns the point index in the Polyface.
-     * @param index Index of the point in the linestring.
+     * Add a point to the polyface. The implementation is free to either create a new point or return the index of a
+     * prior point with the same coordinates.
+     * @param ls the linestring.
+     * @param index index of the point in the linestring.
+     * @param transform (optional) transform to be applied.
+     * @param priorIndex (optional) index of a prior point to check for possible duplicate value.
+     * @returns the point index in the polyface.
      */
     findOrAddPointInLineString(ls, index, transform, priorIndex) {
         const q = ls.pointAt(index, PolyfaceBuilder._workPointFindOrAddA);
@@ -350,9 +358,13 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         return undefined;
     }
     /**
-     * Announce point coordinates.  The implementation is free to either create a new point or (if known) return index of a prior point with the same coordinates.
-     * @returns Returns the point index in the Polyface.
-     * @param index Index of the point in the linestring.
+     * Add a point to the polyface. The implementation is free to either create a new point or return the index of a
+     * prior point with the same coordinates.
+     * @param xyz the array of points.
+     * @param index index of the point in the array.
+     * @param transform (optional) transform to be applied.
+     * @param priorIndex (optional) index of a prior point to check for possible duplicate value.
+     * @returns the point index in the polyface.
      */
     findOrAddPointInGrowableXYZArray(xyz, index, transform, priorIndex) {
         const q = xyz.getPoint3dAtCheckedPointIndex(index, PolyfaceBuilder._workPointFindOrAddA);
@@ -364,9 +376,13 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         return undefined;
     }
     /**
-     * Announce point coordinates.  The implementation is free to either create a new point or (if known) return index of a prior point with the same coordinates.
-     * @returns Returns the point index in the Polyface.
-     * @param index Index of the point in the linestring.
+     * Add a normal to the polyface. The implementation is free to either create a new normal or return the index of a
+     * prior normal with the same coordinates.
+     * @param xyz the array of normals.
+     * @param index index of the normal in the array.
+     * @param transform (optional) transform to be applied.
+     * @param priorIndex (optional) index of a prior point to check for possible duplicate value.
+     * @returns the normal index in the polyface.
      */
     findOrAddNormalInGrowableXYZArray(xyz, index, transform, priorIndex) {
         const q = xyz.getVector3dAtCheckedVectorIndex(index, PolyfaceBuilder._workVectorFindOrAdd);
@@ -378,40 +394,49 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         return undefined;
     }
     /**
-     * Announce uv parameter coordinates.
-     * @returns Returns the uv parameter index in the Polyface.
-     * @param index Index of the param in the linestring.
+     * Add a uv parameter to the polyface.
+     * @param data the array of uv data.
+     * @param index index of the param in the array.
+     * @returns the uv parameter index in the polyface.
      */
     addParamInGrowableXYArray(data, index) {
         if (!data)
             return undefined;
         const q = data.getPoint2dAtCheckedPointIndex(index, PolyfaceBuilder._workUVFindOrAdd);
-        if (q) {
+        if (q)
             return this._polyface.addParam(q);
-        }
         return undefined;
     }
     /**
-     * Announce uv parameter coordinates.
+     * Add a uv parameter to the polyface.
      * @deprecated in 3.x. Use addParamInGrowableXYArray instead.
      */
     findOrAddParamInGrowableXYArray(data, index) {
         return this.addParamInGrowableXYArray(data, index);
     }
     /**
-     * Announce param coordinates, taking u from ls.fractions and v from parameter.  The implementation is free to either create a new param or (if known) return index of a prior point with the same coordinates.
-     * @returns Returns the point index in the Polyface.
-     * @param index Index of the point in the linestring.
+     * Add a uv parameter to the polyface, taking `u` from `ls.fractions` and `v` from input. The implementation is
+     * free to either create a new param or return the index of a prior param with the same coordinates.
+     * @param ls the linestring.
+     * @param index index of the point in the linestring.
+     * @param v the v parameter.
+     * @param priorIndexA (optional) an index of a prior param to check for possible duplicate value.
+     * @param priorIndexB (optional) another index of a prior param to check for possible duplicate value.
+     * @returns the uv parameter index in the polyface.
      */
     findOrAddParamInLineString(ls, index, v, priorIndexA, priorIndexB) {
-        const u = (ls.fractions && index < ls.fractions.length) ? ls.fractions.atUncheckedIndex(index) : index / ls.points.length;
+        const u = (ls.fractions && index < ls.fractions.length) ?
+            ls.fractions.atUncheckedIndex(index) : index / ls.points.length;
         return this._polyface.addParamUV(u, v, priorIndexA, priorIndexB);
     }
     /**
-     * Announce normal coordinates found at index in the surfaceNormal array stored on the linestring
-     * @returns Returns the point index in the Polyface.
-     * @param index Index of the point in the linestring.
-     * @param priorIndex possible prior normal index to reuse
+     * Add a normal to the polyface.
+     * @param ls the linestring.
+     * @param index Index of the normal in the linestring's surface normal array.
+     * @param transform (optional) transform to be applied.
+     * @param priorIndexA (optional) an index of a prior normal to check for possible duplicate value.
+     * @param priorIndexB (optional) another index of a prior normal to check for possible duplicate value.
+     * @returns the normal index in the polyface.
      */
     findOrAddNormalInLineString(ls, index, transform, priorIndexA, priorIndexB) {
         const linestringNormals = ls.packedSurfaceNormals;
@@ -425,14 +450,12 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
         return undefined;
     }
-    /**
-     * Announce point coordinates.
-     */
+    /** Add a point to the polyface. */
     addPointXYZ(x, y, z) {
         return this._polyface.addPointXYZ(x, y, z);
     }
     /**
-     * Announce point coordinates.
+     * Add a point to the polyface.
      * @deprecated in 3.x. Use addPointXYZ instead.
      */
     findOrAddPointXYZ(x, y, z) {
@@ -454,18 +477,22 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         normal = normal ? normal : Point3dVector3d_1.Vector3d.create();
         return normal;
     }
-    // ###: Consider case where normals will be reversed and point through the other end of the facet
+    // ### TODO: Consider case where normals will be reversed and point through the other end of the facet.
     /**
      * Add a quad to the polyface given its points in order around the edges.
-     * @param points array of at least three vertices
-     * @param params optional array of at least four uv parameters (if undefined, params are calculated without reference data)
-     * @param normals optional array of at least four vectors (if undefined, the quad is assumed to be planar and its normal is calculated)
-     * @param colors optional array of at least four colors
+     * @param points array of at least four vertices.
+     * @param params (optional) array of at least four uv parameters (if `undefined`, params are calculated without
+     * reference data).
+     * @param normals (optional) array of at least four vectors (if `undefined`, the quad is assumed to be planar and its
+     * normal is calculated).
+     * @param colors (optional) array of at least four colors.
      */
     addQuadFacet(points, params, normals, colors) {
         if (points instanceof GrowableXYZArray_1.GrowableXYZArray)
             points = points.getPoint3dArray();
-        // If params and/or normals are needed, calculate them first
+        if (points.length < 4)
+            return;
+        // if params and/or normals are needed, calculate them first
         const needParams = this.options.needParams;
         const needNormals = this.options.needNormals;
         const needColors = this.options.needColors;
@@ -515,7 +542,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             }
         }
         if (this._options.shouldTriangulate) {
-            // Add as two triangles, with a diagonal along the shortest distance
+            // add as two triangles, with a diagonal along the shortest distance
             const vectorAC = points[0].vectorTo(points[2]);
             const vectorBD = points[1].vectorTo(points[3]);
             // Note: We pass along any values for normals or params that we calculated
@@ -530,7 +557,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             return;
         }
         let idx0, idx1, idx2, idx3;
-        // Add params if needed
+        // add params if needed
         if (needParams) {
             idx0 = this._polyface.addParam(param0);
             idx1 = this._polyface.addParam(param1);
@@ -538,7 +565,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             idx3 = this._polyface.addParam(param3);
             this.addIndexedQuadParamIndexes(idx0, idx1, idx3, idx2);
         }
-        // Add normals if needed
+        // add normals if needed
         if (needNormals) {
             idx0 = this._polyface.addNormal(normal0);
             idx1 = this._polyface.addNormal(normal1);
@@ -546,7 +573,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             idx3 = this._polyface.addNormal(normal3);
             this.addIndexedQuadNormalIndexes(idx0, idx1, idx3, idx2);
         }
-        // Add colors if needed
+        // add colors if needed
         if (needColors) {
             idx0 = this._polyface.addColor(color0);
             idx1 = this._polyface.addColor(color1);
@@ -554,18 +581,19 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             idx3 = this._polyface.addColor(color3);
             this.addIndexedQuadColorIndexes(idx0, idx1, idx3, idx2);
         }
-        // Add point and point indexes last (terminates the facet)
+        // add point and point indexes last (terminates the facet)
         idx0 = this.addPoint(points[0]);
         idx1 = this.addPoint(points[1]);
         idx2 = this.addPoint(points[2]);
         idx3 = this.addPoint(points[3]);
         this.addIndexedQuadPointIndexes(idx0, idx1, idx3, idx2);
     }
-    /** Announce a single quad facet's point indexes.
+    /**
+     * Add a single quad facet from existing points to the polyface.
      * * The actual quad may be reversed or triangulated based on builder setup.
-     * * indexA0 and indexA1 are in the forward order at the "A" end of the quad
-     * * indexB0 and indexB1 are in the forward order at the "B" end of the quad.
-     * * This means ccw/cw ordered vertices v[i] should be passed into this function as i=[0,1,3,2]
+     * * `indexA0` and `indexA1` are in the forward order at the "A" end of the quad
+     * * `indexB0` and `indexB1` are in the forward order at the "B" end of the quad.
+     * * This means ccw/cw ordered vertices v[i] should be passed into this function as i=[0,1,3,2].
      */
     addIndexedQuadPointIndexes(indexA0, indexA1, indexB0, indexB1, terminate = true) {
         if (this._reversed) {
@@ -628,13 +656,14 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this._polyface.addColorIndex(indexB0);
         }
     }
-    // ### TODO: Consider case where normals will be reversed and point through the other end of the facet
+    // ### TODO: Consider case where normals will be reversed and point through the other end of the facet.
     /**
      * Add a triangle to the polyface given its points in order around the edges.
-     * @param points array of at least three vertices
-     * @param params optional array of at least three uv parameters (if undefined, params are calculated without reference data)
-     * @param normals optional array of at least three vectors (if undefined, the normal is calculated)
-     * @param colors optional array of at least three colors
+     * @param points array of at least three vertices.
+     * @param params (optional) array of at least three uv parameters (if `undefined`, params are calculated without
+     * reference data).
+     * @param normals (optional) array of at least three vectors (if `undefined`, the normal is calculated).
+     * @param colors (optional) array of at least three colors.
      */
     addTriangleFacet(points, params, normals, colors) {
         if (points.length < 3)
@@ -653,14 +682,14 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             point1 = points[1];
             point2 = points[2];
         }
-        // Add params if needed
+        // add params if needed
         if (this._options.needParams) {
-            if (params && params.length >= 3) { // Params were given
+            if (params && params.length >= 3) { // params were given
                 idx0 = this._polyface.addParam(params[0]);
                 idx1 = this._polyface.addParam(params[1]);
                 idx2 = this._polyface.addParam(params[2]);
             }
-            else { // Compute params
+            else { // compute params
                 const paramTransform = this.getUVTransformForTriangleFacet(point0, point1, point2);
                 idx0 = this._polyface.addParam(Point2dVector2d_1.Point2d.createFrom(paramTransform ? paramTransform.multiplyPoint3d(point0) : undefined));
                 idx1 = this._polyface.addParam(Point2dVector2d_1.Point2d.createFrom(paramTransform ? paramTransform.multiplyPoint3d(point1) : undefined));
@@ -668,14 +697,14 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             }
             this.addIndexedTriangleParamIndexes(idx0, idx1, idx2);
         }
-        // Add normals if needed
+        // add normals if needed
         if (this._options.needNormals) {
-            if (normals !== undefined && normals.length > 2) { // Normals were given
+            if (normals !== undefined && normals.length > 2) { // normals were given
                 idx0 = this._polyface.addNormal(normals[0]);
                 idx1 = this._polyface.addNormal(normals[1]);
                 idx2 = this._polyface.addNormal(normals[2]);
             }
-            else { // Compute normals
+            else { // compute normals
                 const normal = this.getNormalForTriangularFacet(point0, point1, point2);
                 idx0 = this._polyface.addNormal(normal);
                 idx1 = this._polyface.addNormal(normal);
@@ -683,7 +712,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             }
             this.addIndexedTriangleNormalIndexes(idx0, idx1, idx2);
         }
-        // Add colors if needed and provided
+        // add colors if needed and provided
         if (this._options.needColors) {
             if (colors !== undefined && colors.length > 2) {
                 idx0 = this._polyface.addColor(colors[0]);
@@ -692,15 +721,15 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                 this.addIndexedTriangleColorIndexes(idx0, idx1, idx2);
             }
         }
-        // Add point and point indexes last (terminates the facet)
+        // add point and point indexes last (terminates the facet)
         idx0 = this.addPoint(point0);
         idx1 = this.addPoint(point1);
         idx2 = this.addPoint(point2);
         this.addIndexedTrianglePointIndexes(idx0, idx1, idx2);
     }
-    /** Announce a single triangle facet's point indexes.
-     *
-     * * The actual quad may be reversed or triangulated based on builder setup.
+    /**
+     * Add a single triangular facet from existing points to the polyface.
+     * * The added triangle may be reversed based on builder setup.
      */
     addIndexedTrianglePointIndexes(indexA, indexB, indexC, terminateFacet = true) {
         if (!this._reversed) {
@@ -767,7 +796,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         if (sectorA0.xyz.isAlmostEqual(sectorA1.xyz)
             || sectorA1.xyz.isAlmostEqual(sectorA2.xyz)
             || sectorA2.xyz.isAlmostEqual(sectorA0.xyz)) {
-            // trivially degenerate triangle !!! skip !!!
+            // trivially degenerate triangle; skip!!!
         }
         else {
             if (this._options.needNormals)
@@ -779,7 +808,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     addSectorQuadA01B01(sectorA0, sectorA1, sectorB0, sectorB1) {
         if (sectorA0.xyz.isAlmostEqual(sectorA1.xyz) && sectorB0.xyz.isAlmostEqual(sectorB1.xyz)) {
-            // ignore null quad !!
+            // ignore null quad
         }
         else if (this._options.shouldTriangulate) {
             this.addSectorTriangle(sectorA0, sectorA1, sectorB1);
@@ -793,10 +822,9 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this.addIndexedQuadPointIndexes(sectorA0.xyzIndex, sectorA1.xyzIndex, sectorB0.xyzIndex, sectorB1.xyzIndex, true);
         }
     }
-    /** Add facets between lineStrings with matched point counts.
-     * * surface normals are computed from (a) curve tangents in the linestrings and (b)rule line between linestrings.
-     * * Facets are announced to addIndexedQuad.
-     * * addIndexedQuad is free to apply reversal or triangulation options.
+    /**
+     * Add facets between lineStrings with matched point counts.
+     * * Surface normals are computed from (a) curve tangents in the linestrings and (b) rule line between linestrings.
      */
     addBetweenLineStringsWithRuleEdgeNormals(lineStringA, vA, lineStringB, vB, addClosure = false) {
         const pointA = lineStringA.packedPoints;
@@ -830,7 +858,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             FacetSector.computeNormalsAlongRuleLine(sectorA1, sectorB1);
             this.setSectorIndices(sectorA1);
             this.setSectorIndices(sectorB1);
-            // create the facet ...
+            // create the facet
             this.addSectorQuadA01B01(sectorA0, sectorA1, sectorB0, sectorB1);
             sectorA0.copyContentsFrom(sectorA1);
             sectorB0.copyContentsFrom(sectorB1);
@@ -838,10 +866,9 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         if (addClosure)
             this.addSectorQuadA01B01(sectorA0, sectorA00, sectorB0, sectorB00);
     }
-    /** Add facets between lineStrings with matched point counts.
-     * * point indices pre-stored
-     * * normal indices pre-stored
-     * * uv indices pre-stored
+    /**
+     * Add facets between lineStrings with matched point counts.
+     * * Indices of points, normals, and uv parameters are pre-stored in the linestrings.
      */
     addBetweenLineStringsWithStoredIndices(lineStringA, lineStringB) {
         const pointA = lineStringA.pointIndices;
@@ -877,7 +904,8 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                 }
             }
             else {
-                if (pointA.atUncheckedIndex(i - 1) !== pointA.atUncheckedIndex(i) || pointB.atUncheckedIndex(i - 1) !== pointB.atUncheckedIndex(i)) {
+                if (pointA.atUncheckedIndex(i - 1) !== pointA.atUncheckedIndex(i) ||
+                    pointB.atUncheckedIndex(i - 1) !== pointB.atUncheckedIndex(i)) {
                     this.addIndexedQuadPointIndexes(pointA.atUncheckedIndex(i - 1), pointA.atUncheckedIndex(i), pointB.atUncheckedIndex(i - 1), pointB.atUncheckedIndex(i), false);
                     if (normalA && normalB)
                         this.addIndexedQuadNormalIndexes(normalA.atUncheckedIndex(i - 1), normalA.atUncheckedIndex(i), normalB.atUncheckedIndex(i - 1), normalB.atUncheckedIndex(i));
@@ -888,8 +916,8 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this._polyface.terminateFacet();
         }
     }
-    /** Add facets between lineStrings with matched point counts.
-     *
+    /**
+     * Add facets between lineStrings with matched point counts.
      * * Facets are announced to addIndexedQuad.
      * * addIndexedQuad is free to apply reversal or triangulation options.
      */
@@ -915,7 +943,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
         else {
             const children = curves.children;
-            // just send the children individually -- final s will fix things??
+            // just send the children individually; final compress will fix things??
             if (children)
                 for (const c of children) {
                     this.addBetweenTransformedLineStrings(c, transformA, transformB);
@@ -947,11 +975,9 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             }
         }
     }
-    /**
-     * Add facets from a Cone
-     */
+    /** Add facets from a Cone. */
     addCone(cone) {
-        // ensure identical stroke counts at each end . . .
+        // ensure identical stroke counts at each end
         let strokeCount = 16;
         if (this._options)
             strokeCount = this._options.applyTolerancesToArc(cone.getMaxRadius());
@@ -976,9 +1002,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             }
         }
     }
-    /**
-     * Add facets for a TorusPipe.
-     */
+    /** Add facets for a TorusPipe. */
     addTorusPipe(surface, phiStrokeCount, thetaStrokeCount) {
         const thetaFraction = surface.getThetaFraction();
         let numU = Geometry_1.Geometry.clamp(Geometry_1.Geometry.resolveNumber(phiStrokeCount, 8), 4, 64);
@@ -1022,11 +1046,11 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     /**
      * Add point data (no params, normals) for linestrings.
-     * * This recurses through curve chains (loops and paths)
-     * * linestrings are swept
+     * * This recurses through curve chains (loops and paths).
+     * * LineStrings are swept.
      * * All other curve types are ignored.
-     * @param vector sweep vector
-     * @param contour contour which contains only linestrings
+     * @param contour contour which contains only linestrings.
+     * @param vector sweep vector.
      */
     addLinearSweepLineStringsXYZOnly(contour, vector) {
         if (contour instanceof LineString3d_1.LineString3d) {
@@ -1042,22 +1066,18 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                 pointB = pointA.plus(vector, pointB);
                 indexA1 = this.addPoint(pointA);
                 indexB1 = this.addPoint(pointB);
-                if (i > 0) {
+                if (i > 0)
                     this.addIndexedQuadPointIndexes(indexA0, indexA1, indexB0, indexB1);
-                }
                 indexA0 = indexA1;
                 indexB0 = indexB1;
             }
         }
         else if (contour instanceof CurveCollection_1.CurveChain) {
-            for (const ls of contour.children) {
+            for (const ls of contour.children)
                 this.addLinearSweepLineStringsXYZOnly(ls, vector);
-            }
         }
     }
-    /**
-     * Construct facets for a rotational sweep.
-     */
+    /** Construct facets for a rotational sweep. */
     addRotationalSweep(surface) {
         const contour = surface.getCurves();
         const section0 = StrokeCountChain_1.StrokeCountSection.createForParityRegionOrChain(contour, this._options);
@@ -1080,22 +1100,21 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             const capContour = surface.getSweepContourRef();
             capContour.purgeFacets();
             capContour.emitFacets(this, true, undefined);
-            // final loop pass left transformA at end ..
+            // final loop pass left transformA at end
             capContour.emitFacets(this, false, surface.getFractionalRotationTransform(1.0));
         }
     }
-    /**
-     * Construct facets for any planar region
-     */
+    /** Construct facets for any planar region. */
     addTriangulatedRegion(region) {
         const contour = SweepContour_1.SweepContour.createForLinearSweep(region);
         if (contour)
             contour.emitFacets(this, this.reversedFlag, undefined);
     }
     /**
+     * Apply stroke counts to curve primitives.
      * * Recursively visit all children of data.
-     * * At each primitive, invoke the computeStrokeCountForOptions method, with options from the builder.
-     * @param data
+     * * At each primitive, invoke `computeStrokeCountForOptions` method with options from the builder.
+     * @deprecated in 4.x. This method does nothing and is unneeded.
      */
     applyStrokeCountsToCurvePrimitives(data) {
         const options = this._options;
@@ -1105,9 +1124,9 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         else if (data instanceof CurveCollection_1.CurveCollection) {
             const children = data.children;
             if (children)
-                for (const child of children) {
+                for (const child of children)
+                    // eslint-disable-next-line deprecation/deprecation
                     this.applyStrokeCountsToCurvePrimitives(child);
-                }
         }
     }
     addBetweenStrokeSetsWithRuledNormals(stroke0, stroke1, numVEdge) {
@@ -1127,22 +1146,20 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     createIndicesInLineString(ls, vParam, transform) {
         const n = ls.numPoints();
-        {
-            const pointIndices = ls.ensureEmptyPointIndices();
-            const index0 = this.findOrAddPointInLineString(ls, 0, transform);
-            pointIndices.push(index0);
-            if (n > 1) {
-                let indexA = index0;
-                let indexB;
-                for (let i = 1; i + 1 < n; i++) {
-                    indexB = this.findOrAddPointInLineString(ls, i, transform, indexA);
-                    pointIndices.push(indexB);
-                    indexA = indexB;
-                }
-                // assume last point can only repeat back to zero ...
-                indexB = this.findOrAddPointInLineString(ls, n - 1, transform, index0);
+        const pointIndices = ls.ensureEmptyPointIndices();
+        const index0 = this.findOrAddPointInLineString(ls, 0, transform);
+        pointIndices.push(index0);
+        if (n > 1) {
+            let indexA = index0;
+            let indexB;
+            for (let i = 1; i + 1 < n; i++) {
+                indexB = this.findOrAddPointInLineString(ls, i, transform, indexA);
                 pointIndices.push(indexB);
+                indexA = indexB;
             }
+            // assume last point can only repeat back to zero
+            indexB = this.findOrAddPointInLineString(ls, n - 1, transform, index0);
+            pointIndices.push(indexB);
         }
         if (this._options.needNormals && ls.packedSurfaceNormals !== undefined) {
             const normalIndices = ls.ensureEmptyNormalIndices();
@@ -1156,7 +1173,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                     normalIndices.push(normalIndexB);
                     normalIndexA = normalIndexB;
                 }
-                // assume last point can only repeat back to zero ...
+                // assume last point can only repeat back to zero
                 normalIndexB = this.findOrAddNormalInLineString(ls, n - 1, transform, normalIndex0, normalIndexA);
                 normalIndices.push(normalIndexB);
             }
@@ -1173,7 +1190,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
                     uvIndices.push(uvIndexB);
                     uvIndexA = uvIndexB;
                 }
-                // assume last point can only repeat back to zero ...
+                // assume last point can only repeat back to zero
                 uvIndexB = this.findOrAddParamInLineString(ls, n - 1, vParam, uvIndexA, uvIndex0);
                 uvIndices.push(uvIndexB);
             }
@@ -1200,12 +1217,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             }
         }
     }
-    /**
-     *
-     * Add facets from
-     * * The swept contour
-     * * each cap.
-     */
+    /** Add facets from the linear sweep. */
     addLinearSweep(surface) {
         const contour = surface.getCurvesRef();
         const section0 = StrokeCountChain_1.StrokeCountSection.createForParityRegionOrChain(contour, this._options);
@@ -1222,17 +1234,14 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             contourA.emitFacets(this, false, sweepTransform);
         }
     }
-    /**
-     * Add facets from a ruled sweep.
-     */
+    /** Add facets from a ruled sweep. */
     addRuledSweep(surface) {
         const contours = surface.sweepContoursRef();
         let stroke0;
         let stroke1;
         const sectionMaps = [];
-        for (const contour of contours) {
+        for (const contour of contours)
             sectionMaps.push(StrokeCountChain_1.StrokeCountSection.createForParityRegionOrChain(contour.curves, this._options));
-        }
         if (StrokeCountChain_1.StrokeCountSection.enforceStrokeCountCompatibility(sectionMaps)) {
             StrokeCountChain_1.StrokeCountSection.enforceCompatibleDistanceSums(sectionMaps);
             for (let i = 0; i < contours.length; i++) {
@@ -1258,9 +1267,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
         return true;
     }
-    /**
-     * Add facets from a Sphere
-     */
+    /** Add facets from a sphere. */
     addSphere(sphere, strokeCount) {
         let numStrokeTheta = strokeCount ? strokeCount : this.options.applyTolerancesToArc(sphere.maxAxisRadius());
         if (Geometry_1.Geometry.isOdd(numStrokeTheta))
@@ -1280,21 +1287,19 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this.endFace();
         }
     }
-    /**
-     * Add facets from a Box
-     */
+    /** Add facets from a box. */
     addBox(box) {
         const corners = box.getCorners();
         const xLength = Geometry_1.Geometry.maxXY(box.getBaseX(), box.getBaseX());
         const yLength = Geometry_1.Geometry.maxXY(box.getBaseY(), box.getTopY());
         let zLength = 0.0;
-        for (let i = 0; i < 4; i++) {
+        for (let i = 0; i < 4; i++)
             zLength = Geometry_1.Geometry.maxXY(zLength, corners[i].distance(corners[i + 4]));
-        }
         const numX = this._options.applyMaxEdgeLength(1, xLength);
         const numY = this._options.applyMaxEdgeLength(1, yLength);
         const numZ = this._options.applyMaxEdgeLength(1, zLength);
-        // Wrap the 4 out-of-plane faces as a single parameters space with "distance" advancing in x then y then negative x then negative y ...
+        // wrap the 4 out-of-plane faces as a single parameter space with "distance"
+        // advancing in x, then y, then negative x, then negative y
         const uParamRange = Segment1d_1.Segment1d.create(0, xLength);
         const vParamRange = Segment1d_1.Segment1d.create(0, zLength);
         this.addUVGridBody(BilinearPatch_1.BilinearPatch.create(corners[0], corners[1], corners[4], corners[5]), numX, numZ, uParamRange, vParamRange);
@@ -1304,7 +1309,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         this.addUVGridBody(BilinearPatch_1.BilinearPatch.create(corners[3], corners[2], corners[7], corners[6]), numX, numZ, uParamRange, vParamRange);
         uParamRange.shift(xLength);
         this.addUVGridBody(BilinearPatch_1.BilinearPatch.create(corners[2], corners[0], corners[6], corners[4]), numY, numZ, uParamRange, vParamRange);
-        // finally end that wraparound face !!
+        // finally end that wraparound face
         this.endFace();
         if (box.capped) {
             uParamRange.set(0.0, xLength);
@@ -1317,15 +1322,15 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this.endFace();
         }
     }
-    /** Add a polygon to the evolving facets.
-     *
-     * * Add points to the polyface
-     * * indices are added (in reverse order if indicated by the builder state)
-     * @param points array of points.  This may contain extra points not to be used in the polygon
+    /**
+     * Add a polygon to the evolving facets.
+     * * Add points to the polyface.
+     * * Indices are added (in reverse order if indicated by the builder state).
+     * @param points array of points. This may contain extra points not to be used in the polygon.
      * @param numPointsToUse number of points to use.
      */
     addPolygon(points, numPointsToUse) {
-        // don't use trailing points that match start point.
+        // don't use trailing points that match start point
         if (numPointsToUse === undefined)
             numPointsToUse = points.length;
         while (numPointsToUse > 1 && points[numPointsToUse - 1].isAlmostEqual(points[0]))
@@ -1345,23 +1350,23 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
         this._polyface.terminateFacet();
     }
-    /** Add a polygon to the evolving facets.
-     *
+    /**
+     * Add a polygon to the evolving facets.
      * * Add points to the polyface
-     * * indices are added (in reverse order if indicated by the builder state)
+     * * Indices are added (in reverse order if indicated by the builder state).
      * * Arrays with 2 or fewer points are ignored.
      * @param points array of points. Trailing closure points are ignored.
      */
     addPolygonGrowableXYZArray(points) {
-        // don't use trailing points that match start point.
+        // don't use trailing points that match start point
         let numPointsToUse = points.length;
         while (numPointsToUse > 2 && Geometry_1.Geometry.isSmallMetricDistance(points.distanceIndexIndex(0, numPointsToUse - 1)))
             numPointsToUse--;
         // strip trailing duplicates
         while (numPointsToUse > 2 && Geometry_1.Geometry.isSmallMetricDistance(points.distanceIndexIndex(numPointsToUse - 2, numPointsToUse - 1)))
             numPointsToUse--;
-        // ignore triangles for which the height is less than smallMetricDistance times length
-        // sum of edge lengths is twice the perimeter.   If it is flat that's twice the largest base dimension.
+        // ignore triangles for which the height is less than smallMetricDistance times length.
+        // sum of edge lengths is twice the perimeter. If it is flat that's twice the largest base dimension.
         // cross product magnitude is twice the area.
         if (numPointsToUse === 3) {
             const cross = points.crossProductIndexIndexIndex(0, 1, 2);
@@ -1387,19 +1392,20 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this._polyface.terminateFacet();
         }
     }
-    /** Add a polygon to the evolving facets.
-     * * add points to the polyface
-     * * compute each point index as the point is added
-     * * all data arrays are parallel to the point array
-     * * point indices are added in reverse order if indicated by the builder state
-     * @param points array of vertices in order around the facet
-     * @param normals optional array of normals, one per vertex
-     * @param params optional array of uv-parameters, one per vertex
-     * @param colors optional array of colors, one per vertex
-     * @param edgeVisible optional array of flags, one per vertex, true iff edge starting at corresponding vertex is visible
+    /**
+     * Add a polygon to the evolving facets.
+     * * Add points to the polyface.
+     * * Compute each point index as the point is added.
+     * * All data arrays are parallel to the point array.
+     * * Point indices are added in reverse order if indicated by the builder state.
+     * @param points array of vertices in order around the facet.
+     * @param normals (optional) array of normals, one per vertex.
+     * @param params (optional) array of uv-parameters, one per vertex.
+     * @param colors (optional) array of colors, one per vertex.
+     * @param edgeVisible (optional) array of flags, one per vertex, true iff edge starting at corresponding vertex is visible.
      */
     addFacetFromGrowableArrays(points, normals, params, colors, edgeVisible) {
-        // don't use trailing points that match start point.
+        // don't use trailing points that match start point
         let numPointsToUse = points.length;
         while (numPointsToUse > 1 && Geometry_1.Geometry.isSmallMetricDistance(points.distanceIndexIndex(0, numPointsToUse - 1)))
             numPointsToUse--;
@@ -1450,13 +1456,14 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
         this._polyface.terminateFacet();
     }
-    /** Add the current visitor facet to the evolving polyface.
-     * * indices are added (in reverse order if indicated by the builder state)
+    /**
+     * Add the current visitor facet to the evolving polyface.
+     * * Indices are added (in reverse order if indicated by the builder state).
      */
     addFacetFromVisitor(visitor) {
         this.addFacetFromGrowableArrays(visitor.point, visitor.normal, visitor.param, visitor.color, visitor.edgeVisible);
     }
-    /** Add all visitor facets to the evolving polyface (in reverse order if indicated by the builder state) */
+    /** Add all visitor facets to the evolving polyface (in reverse order if indicated by the builder state). */
     addFacetsFromVisitor(visitor) {
         visitor.reset();
         for (; visitor.moveToNextFacet();)
@@ -1465,8 +1472,8 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     /**
      * Add the subset of visitor data indexed by the indices.
      * * Ideally, the subset represents a sub-facet of the visited facet.
-     * @param visitor data for the currently visited facet
-     * @param indices local indices into the visitor data arrays
+     * @param visitor data for the currently visited facet.
+     * @param indices local indices into the visitor data arrays.
      * @returns whether the data was added successfully. Encountering an invalid index returns false.
     */
     addFacetFromIndexedVisitor(visitor, indices) {
@@ -1494,49 +1501,71 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         this.addFacetFromGrowableArrays(xyz, normal, param, color, visible);
         return true;
     }
-    /** Add a polyface, with optional reverse and transform. */
+    /** Add a polyface with optional reverse and transform. */
     addIndexedPolyface(source, reversed = false, transform) {
         this._polyface.addIndexedPolyface(source, reversed, transform);
     }
     /**
      * Produce a new FacetFaceData for all terminated facets since construction of the previous face.
-     * Each facet number/index is mapped to the FacetFaceData through the faceToFaceData array.
-     * Returns true if successful, and false otherwise.
+     * * Each facet number/index is mapped to the FacetFaceData through the faceToFaceData array.
+     * @returns true if successful, and false otherwise.
      */
     endFace() {
         return this._polyface.setNewFaceData();
     }
-    /** Double dispatch handler for Cone */
-    handleCone(g) { return this.addCone(g); }
-    /** Double dispatch handler for TorusPipe */
-    handleTorusPipe(g) { return this.addTorusPipe(g); }
-    /** Double dispatch handler for Sphere */
-    handleSphere(g) { return this.addSphere(g); }
-    /** Double dispatch handler for Box */
-    handleBox(g) { return this.addBox(g); }
-    /** Double dispatch handler for LinearSweep */
-    handleLinearSweep(g) { return this.addLinearSweep(g); }
-    /** Double dispatch handler for RotationalSweep */
-    handleRotationalSweep(g) { return this.addRotationalSweep(g); }
-    /** Double dispatch handler for RuledSweep */
-    handleRuledSweep(g) { return this.addRuledSweep(g); }
-    /** Double dispatch handler for Loop */
-    handleLoop(g) { return this.addTriangulatedRegion(g); }
-    /** Double dispatch handler for ParityRegion */
-    handleParityRegion(g) { return this.addTriangulatedRegion(g); }
-    /** Double dispatch handler for UnionRegion */
-    handleUnionRegion(g) { return this.addTriangulatedRegion(g); }
-    /** add facets for a GeometryQuery object.   This is double dispatch through `dispatchToGeometryHandler(this)` */
-    addGeometryQuery(g) { g.dispatchToGeometryHandler(this); }
+    /** Double dispatch handler for Cone. */
+    handleCone(g) {
+        return this.addCone(g);
+    }
+    /** Double dispatch handler for TorusPipe. */
+    handleTorusPipe(g) {
+        return this.addTorusPipe(g);
+    }
+    /** Double dispatch handler for Sphere. */
+    handleSphere(g) {
+        return this.addSphere(g);
+    }
+    /** Double dispatch handler for Box. */
+    handleBox(g) {
+        return this.addBox(g);
+    }
+    /** Double dispatch handler for LinearSweep. */
+    handleLinearSweep(g) {
+        return this.addLinearSweep(g);
+    }
+    /** Double dispatch handler for RotationalSweep. */
+    handleRotationalSweep(g) {
+        return this.addRotationalSweep(g);
+    }
+    /** Double dispatch handler for RuledSweep. */
+    handleRuledSweep(g) {
+        return this.addRuledSweep(g);
+    }
+    /** Double dispatch handler for Loop. */
+    handleLoop(g) {
+        return this.addTriangulatedRegion(g);
+    }
+    /** Double dispatch handler for ParityRegion. */
+    handleParityRegion(g) {
+        return this.addTriangulatedRegion(g);
+    }
+    /** Double dispatch handler for UnionRegion. */
+    handleUnionRegion(g) {
+        return this.addTriangulatedRegion(g);
+    }
+    /** Add facets for a GeometryQuery object. This is double dispatch through `dispatchToGeometryHandler(this)` */
+    addGeometryQuery(g) {
+        g.dispatchToGeometryHandler(this);
+    }
     /**
      * Add a graph to the builder.
-     * * Visit one node per face
-     * * If `acceptFaceFunction(node)` returns true, pass face coordinates to the builder
+     * * Visit one node per face.
+     * * If `acceptFaceFunction(node)` returns true, pass face coordinates to the builder.
      * * Accepted face edge visibility is determined by `isEdgeVisibleFunction`.
      * * Rely on the builder's compress step to find common vertex coordinates.
-     * @param graph faces to add as facets
-     * @param acceptFaceFunction optional test for whether to add a given face. Default: ignore exterior faces
-     * @param isEdgeVisibleFunction optional test for whether to hide an edge. Default: hide interior edges
+     * @param graph faces to add as facets.
+     * @param acceptFaceFunction optional test for whether to add a given face. Default: ignore exterior faces.
+     * @param isEdgeVisibleFunction optional test for whether to hide an edge. Default: hide interior edges.
      * @internal
      */
     addGraph(graph, acceptFaceFunction = (node) => Graph_1.HalfEdge.testNodeMaskNotExterior(node), isEdgeVisibleFunction = (node) => Graph_1.HalfEdge.testMateMaskExterior(node)) {
@@ -1567,12 +1596,12 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         });
     }
     /**
-     *
-     * * For each node in `faces`
-     *  * add all of its vertices to the polyface
-     *  * add point indices to form a new facet.
-     *    * (Note: no normal or param indices are added)
-     *  * terminate the facet
+     * Add a graph's faces to the builder.
+     * * For each node in `faces`:
+     *  * Add all of its vertices to the polyface.
+     *  * Add point indices to form a new facet.
+     *    * (note: no normal or param indices are added)
+     *  * Terminate the facet.
      * @internal
      */
     addGraphFaces(faces) {
@@ -1590,9 +1619,10 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     /**
      * Create a polyface containing the faces of a HalfEdgeGraph, with test functions to filter faces and hide edges.
      * * This is a static wrapper of [[addGraph]].
-     * @param graph faces to add as facets
-     * @param acceptFaceFunction optional test for whether to add a given face. Default: ignore exterior faces
-     * @param isEdgeVisibleFunction optional test for whether to hide an edge. Default: hide interior edges
+     * @param graph faces to add as facets.
+     * @param options (optional) options for the polyface.
+     * @param acceptFaceFunction optional test for whether to add a given face. Default: ignore exterior faces.
+     * @param isEdgeVisibleFunction optional test for whether to hide an edge. Default: hide interior edges.
      * @internal
      */
     static graphToPolyface(graph, options, acceptFaceFunction = (node) => Graph_1.HalfEdge.testNodeMaskNotExterior(node), isEdgeVisibleFunction = (node) => Graph_1.HalfEdge.testMateMaskExterior(node)) {
@@ -1601,7 +1631,8 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         builder.endFace();
         return builder.claimPolyface();
     }
-    /** Create a polyface containing the faces of a HalfEdgeGraph that are specified by the HalfEdge array.
+    /**
+     * Create a polyface containing the faces of a HalfEdgeGraph that are specified by the HalfEdge array.
      * @internal
      */
     static graphFacesToPolyface(faces) {
@@ -1610,7 +1641,8 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         builder.endFace();
         return builder.claimPolyface();
     }
-    /** Create a polyface containing triangles in a (space) polygon.
+    /**
+     * Create a polyface containing triangles in a (space) polygon.
      * * The polyface contains only coordinate data (no params or normals).
      */
     static polygonToTriangulatedPolyface(points, localToWorld) {
@@ -1631,13 +1663,13 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         return undefined;
     }
     /**
-     * Given arrays of coordinates for multiple facets.
-     * * pointArray[i] is an array of 3 or 4 points
-     * * paramArray[i] is an array of matching number of params
+     * Add facets to the builder given arrays of coordinates for multiple facets.
+     * * pointArray[i] is an array of 3 or 4 points.
+     * * paramArray[i] is an array of matching number of params.
      * * normalArray[i] is an array of matching number of normals.
-     * @param pointArray array of arrays of point coordinates
-     * @param paramArray array of arrays of uv parameters
-     * @param normalArray array of arrays of normals
+     * @param pointArray array of arrays of point coordinates.
+     * @param paramArray (optional) array of arrays of uv parameters.
+     * @param normalArray (optional) array of arrays of normals.
      * @param endFace if true, call this.endFace after adding all the facets.
      */
     addCoordinateFacets(pointArray, paramArray, normalArray, endFace = false) {
@@ -1653,15 +1685,16 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this.endFace();
     }
     /**
+     * Add facets from the parametric surface.
      * * Evaluate `(numU + 1) * (numV + 1)` grid points (in 0..1 in both u and v) on a surface.
      * * Add the facets for `numU * numV` quads.
      * * uv params are the 0..1 fractions.
-     * * normals are cross products of u and v direction partial derivatives.
-     * @param surface
-     * @param numU number of intervals (edges) in the u direction.  (Number of points is `numU + 1`)
-     * @param numV number of intervals (edges) in the v direction.  (Number of points is `numV + 1`)
-     * @param uMap optional mapping from u fraction to parameter space (such as texture)
-     * @param vMap optional mapping from v fraction to parameter space (such as texture)
+     * * Normals are cross products of u and v direction partial derivatives.
+     * @param surface UV surface to evaluate.
+     * @param numU number of intervals (edges) in the u direction (number of points is `numU + 1`).
+     * @param numV number of intervals (edges) in the v direction (number of points is `numV + 1`).
+     * @param uMap optional mapping from u fraction to parameter space (such as texture).
+     * @param vMap optional mapping from v fraction to parameter space (such as texture).
      */
     addUVGridBody(surface, numU, numV, uMap, vMap) {
         let xyzIndex0 = new GrowableFloat64Array_1.GrowableFloat64Array(numU);
@@ -1690,7 +1723,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         const dv = 1.0 / numV;
         const plane = Plane3dByOriginAndVectors_1.Plane3dByOriginAndVectors.createXYPlane();
         for (let v = 0; v <= numV; v++) {
-            // evaluate new points ....
+            // evaluate new points
             xyzIndex1.clear();
             if (needNormals)
                 normalIndex1.clear();
@@ -1740,23 +1773,26 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             indexSwap = xyzIndex1;
             xyzIndex1 = xyzIndex0;
             xyzIndex0 = indexSwap;
-            if (needParams) {
+            if (needParams)
                 indexSwap = paramIndex1;
-                paramIndex1 = paramIndex0;
-                paramIndex0 = indexSwap;
-            }
-            if (needNormals) {
+            paramIndex1 = paramIndex0;
+            paramIndex0 = indexSwap;
+            if (needNormals)
                 indexSwap = normalIndex1;
-                normalIndex1 = normalIndex0;
-                normalIndex0 = indexSwap;
-            }
+            normalIndex1 = normalIndex0;
+            normalIndex0 = indexSwap;
         }
         xyzIndex0.clear();
         xyzIndex1.clear();
     }
     /**
-     * Triangulate the points as viewed in xy.
-     * @param points
+     * Create a polyface from a triangulation of the points.
+     * * The triangulation is computed as seen in the top view: z-coordinates are ignored.
+     * @param points an array of points.
+     * @param options (optional) stroke options. Currently only two options are supported. If `options.needNormals` is
+     * true, all facets are assigned the single normal 001. If `options.needParams` is true, all facet vertices are
+     * assigned uv-parameters equal to their xy-coordinates. These options are rarely useful.
+     * @returns triangulated polyface or `undefined` if triangulation was not possible.
      */
     static pointsToTriangulatedPolyface(points, options) {
         const graph = Triangulation_1.Triangulator.createTriangulatedGraphFromPoints(points);
@@ -1764,21 +1800,20 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             return PolyfaceBuilder.graphToPolyface(graph, options);
         return undefined;
     }
-    /** Create (and add to the builder) triangles that bridge the gap between two linestrings.
-     * * Each triangle will have 1 vertex on one of the linestrings and 2 on the other
+    /**
+     * Add triangular facets between two linestrings.
+     * * Each triangle will have 1 vertex on one of the linestrings and 2 on the other.
      * * Choice of triangles is heuristic, hence does not have a unique solution.
-     * * Logic to choice among the various possible triangle orders prefers
-     *    * Make near-coplanar facets
-     *    * make facets with good aspect ratio.
+     * * Logic for choosing among the various possible triangles prefers:
+     *    * Make near-coplanar facets.
+     *    * Make facets with good aspect ratio.
      *    * This is exercised with a limited number of lookahead points, i.e. greedy to make first-available decision.
      * @param pointsA points of first linestring.
      * @param pointsB points of second linestring.
      */
     addGreedyTriangulationBetweenLineStrings(pointsA, pointsB) {
         const context = GreedyTriangulationBetweenLineStrings_1.GreedyTriangulationBetweenLineStrings.createContext();
-        context.emitTriangles(resolveToIndexedXYZCollectionOrCarrier(pointsA), resolveToIndexedXYZCollectionOrCarrier(pointsB), (triangle) => {
-            this.addTriangleFacet(triangle.points);
-        });
+        context.emitTriangles(resolveToIndexedXYZCollectionOrCarrier(pointsA), resolveToIndexedXYZCollectionOrCarrier(pointsB), (triangle) => { this.addTriangleFacet(triangle.points); });
     }
     addMiteredPipesFromPoints(centerline, sectionData, numFacetAround = 12) {
         const sections = CurveFactory_1.CurveFactory.createMiteredPipeSections(centerline, sectionData);
@@ -1803,13 +1838,14 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
     }
     /**
-     * * Create (and add to the builder) quad facets for a mitered pipe that follows a centerline curve.
-     * * Circular or elliptical pipe cross sections can be specified by supplying either a radius, a pair of semi-axis lengths, or a full Arc3d.
+     * Add quad facets along a mitered pipe that follows a centerline curve.
+     * * Circular or elliptical pipe cross sections can be specified by supplying either a radius, a pair of semi-axis
+     * lengths, or a full Arc3d:
      *    * For semi-axis length input, x corresponds to an ellipse local axis nominally situated parallel to the xy-plane.
-     *    * The center of Arc3d input is translated to the centerline start point to act as initial cross section.
+     *    * For Arc3d input, the center is translated to the centerline start point to act as initial cross section.
      * @param centerline centerline of pipe. If curved, it will be stroked using the builder's StrokeOptions.
-     * @param sectionData circle radius, ellipse semi-axis lengths, or full Arc3d
-     * @param numFacetAround how many equal parameter-space chords around each section
+     * @param sectionData circle radius, ellipse semi-axis lengths, or full Arc3d.
+     * @param numFacetAround how many equal parameter-space chords around each section.
      */
     addMiteredPipes(centerline, sectionData, numFacetAround = 12) {
         if (Array.isArray(centerline)) {
@@ -1830,7 +1866,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
             this.addMiteredPipesFromPoints(linestring.packedPoints, sectionData, numFacetAround);
         }
     }
-    /** Return the polyface index array indices corresponding to the given edge, or undefined if error. */
+    /** Return the polyface index array indices corresponding to the given edge, or `undefined` if error. */
     getEdgeIndices(edge) {
         let indexA = -1;
         let indexB = -1;
@@ -1842,8 +1878,10 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         }
         return (indexA < 0 || indexB < 0) ? undefined : { edgeIndexA: indexA, edgeIndexB: indexB };
     }
-    /** Create a side face between base and swept facets along a base boundary edge.
-     * * Assumes numBaseFacets base facets were added to this builder, immediately followed by the same number of swept facets with opposite orientation (first index not preserved).
+    /**
+     * Create a side face between base and swept facets along a base boundary edge.
+     * * Assumes numBaseFacets base facets were added to this builder, immediately followed by the same number of swept
+     * facets with opposite orientation (first index not preserved).
     */
     addSweptFace(baseBoundaryEdge, numBaseFacets) {
         const edge = this.getEdgeIndices(baseBoundaryEdge);
@@ -1862,7 +1900,12 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         const edgeIndexOffsetInFaceLoopB = edge.edgeIndexB - baseFacetIndexStart;
         const sweptEdgeIndexOffsetInFaceLoopA = (numBaseFacetEdges - 1) - edgeIndexOffsetInFaceLoopA;
         const sweptEdgeIndexOffsetInFaceLoopB = (numBaseFacetEdges - 1) - edgeIndexOffsetInFaceLoopB;
-        const indices = [edge.edgeIndexB, edge.edgeIndexA, sweptFacetIndexStart + sweptEdgeIndexOffsetInFaceLoopA, sweptFacetIndexStart + sweptEdgeIndexOffsetInFaceLoopB];
+        const indices = [
+            edge.edgeIndexB,
+            edge.edgeIndexA,
+            sweptFacetIndexStart + sweptEdgeIndexOffsetInFaceLoopA,
+            sweptFacetIndexStart + sweptEdgeIndexOffsetInFaceLoopB,
+        ];
         const vertices = [];
         let colors; // try to re-use colors; missing normals and params will be computed if needed
         if (undefined !== this.options.needColors && undefined !== this._polyface.data.color && undefined !== this._polyface.data.colorIndex)
@@ -1883,11 +1926,13 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
         return true;
     }
     /**
-     * Add facets from the source polyface, from its translation along the vector, and from its swept boundary edges, to form a polyface that encloses a volume.
-     * @param source the surface mesh to sweep
-     * @param sweepVector the direction and length to sweep the surface mesh
-     * @param triangulateSides whether to triangulate side facets, or leave as quads
-     * @returns whether the added facets comprise a simple sweep. If false, the resulting mesh may have self-intersections, be non-manifold, have inconsistently oriented facets, etc.
+     * Add facets from the source polyface, from its translation along the vector, and from its swept boundary edges,
+     * to form a polyface that encloses a volume.
+     * @param source the surface mesh to sweep.
+     * @param sweepVector the direction and length to sweep the surface mesh.
+     * @param triangulateSides whether to triangulate side facets, or leave as quads.
+     * @returns whether the added facets comprise a simple sweep. If false, the resulting mesh may have self-intersections,
+     * be non-manifold, have inconsistently oriented facets, etc.
      */
     addSweptIndexedPolyface(source, sweepVector, triangulateSides = false) {
         let isSimpleSweep = true;