@itwin/core-geometry 5.5.0-dev.4 → 5.5.0-dev.6

package/lib/esm/polyface/PolyfaceBuilder.js

@@ -5,6 +5,7 @@
 /** @packageDocumentation
  * @module Polyface
  */
+import { assert } from "@itwin/core-bentley";
 import { Arc3d } from "../curve/Arc3d";
 import { ConstructCurveBetweenCurves } from "../curve/ConstructCurveBetweenCurves";
 import { CurveChain, CurveCollection } from "../curve/CurveCollection";
@@ -125,7 +126,7 @@ class FacetSector {
     static computeNormalsAlongRuleLine(sectorA, sectorB) {
         // 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) {
+        if (sectorA.sectionDerivative && sectorB.sectionDerivative && sectorA.normal && sectorB.normal) {
             const vectorAB = FacetSector._edgeVector;
             Vector3d.createStartEnd(sectorA.xyz, sectorB.xyz, vectorAB);
             sectorA.sectionDerivative.crossProduct(vectorAB, sectorA.normal);
@@ -164,8 +165,8 @@ class FacetSector {
  *    * `builder.addLinearSweepLineStringsXYZOnly(contour, vector)`
  *    * `builder.addPolygon(points, numPointsToUse)`
  *    * `builder.addTransformedUnitBox(transform)`
- *    * `builder.addTriangleFan(conePoint, linestring, toggleOrientation)`
- *    * `builder.addTrianglesInUncheckedConvexPolygon(linestring, toggle)`
+ *    * `builder.addTriangleFan(conePoint, linestring, reverse)`
+ *    * `builder.addTrianglesInUncheckedConvexPolygon(linestring, reverse)`
  *    * `builder.addUVGridBody(surface,numU, numV, createFanInCaps)`
  *    * `builder.addGraph(Graph, acceptFaceFunction)`
  *  * Extract with `builder.claimPolyface(true)`
@@ -261,22 +262,22 @@ export class PolyfaceBuilder extends NullGeometryHandler {
      * 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.
+     * @param reverse if `true`, wrap the triangle creation in toggleReversedFacetFlag.
      */
-    addTriangleFan(conePoint, ls, toggle) {
+    addTriangleFan(conePoint, ls, reverse) {
         const n = ls.numPoints();
         if (n > 2) {
-            if (toggle)
+            if (reverse)
                 this.toggleReversedFacetFlag();
             const index0 = this.addPoint(conePoint);
-            let index1 = this.findOrAddPointInLineString(ls, 0);
+            let index1 = this.findOrAddPointInLineStringUnchecked(ls, 0);
             let index2 = 0;
             for (let i = 1; i < n; i++) {
-                index2 = this.findOrAddPointInLineString(ls, i);
+                index2 = this.findOrAddPointInLineStringUnchecked(ls, i);
                 this.addIndexedTrianglePointIndexes(index0, index1, index2);
                 index1 = index2;
             }
-            if (toggle)
+            if (reverse)
                 this.toggleReversedFacetFlag();
         }
     }
@@ -286,18 +287,20 @@ export class PolyfaceBuilder extends NullGeometryHandler {
      * @param ls linestring with point coordinates.
      * @param reverse if `true`, wrap the triangle creation in toggleReversedFacetFlag.
      */
-    addTrianglesInUncheckedConvexPolygon(ls, toggle) {
+    addTrianglesInUncheckedConvexPolygon(ls, reverse) {
         const n = ls.numPoints();
         if (n > 2) {
-            if (toggle)
+            if (reverse)
                 this.toggleReversedFacetFlag();
             let normal;
             let normalIndex;
             if (this._options.needNormals) {
                 normal = ls.quickUnitNormal(PolyfaceBuilder._workVectorFindOrAdd);
-                if (toggle)
-                    normal.scaleInPlace(-1.0);
-                normalIndex = this._polyface.addNormal(normal);
+                if (normal) {
+                    if (reverse)
+                        normal.scaleInPlace(-1.0);
+                    normalIndex = this._polyface.addNormal(normal);
+                }
             }
             const needParams = this._options.needParams;
             const packedUV = needParams ? ls.packedUVParams : undefined;
@@ -305,27 +308,27 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             let paramIndex1 = -1;
             let paramIndex2 = -1;
             if (packedUV) {
-                paramIndex0 = this.addParamInGrowableXYArray(packedUV, 0);
-                paramIndex1 = this.addParamInGrowableXYArray(packedUV, 1);
+                paramIndex0 = this.addParamInGrowableXYArrayUnchecked(packedUV, 0);
+                paramIndex1 = this.addParamInGrowableXYArrayUnchecked(packedUV, 1);
             }
-            const pointIndex0 = this.findOrAddPointInLineString(ls, 0);
-            let pointIndex1 = this.findOrAddPointInLineString(ls, 1);
+            const pointIndex0 = this.findOrAddPointInLineStringUnchecked(ls, 0);
+            let pointIndex1 = this.findOrAddPointInLineStringUnchecked(ls, 1);
             let pointIndex2 = 0;
             let numEdge = n;
             if (ls.isPhysicallyClosed)
                 numEdge--;
             for (let i = 2; i < numEdge; i++, pointIndex1 = pointIndex2, paramIndex1 = paramIndex2) {
-                pointIndex2 = this.findOrAddPointInLineString(ls, i);
+                pointIndex2 = this.findOrAddPointInLineStringUnchecked(ls, i);
                 this.addIndexedTrianglePointIndexes(pointIndex0, pointIndex1, pointIndex2, false);
                 if (normalIndex !== undefined)
                     this.addIndexedTriangleNormalIndexes(normalIndex, normalIndex, normalIndex);
                 if (packedUV) {
-                    paramIndex2 = this.addParamInGrowableXYArray(packedUV, i);
+                    paramIndex2 = this.addParamInGrowableXYArrayUnchecked(packedUV, i);
                     this.addIndexedTriangleParamIndexes(paramIndex0, paramIndex1, paramIndex2);
                 }
                 this._polyface.terminateFacet();
             }
-            if (toggle)
+            if (reverse)
                 this.toggleReversedFacetFlag();
         }
     }
@@ -341,8 +344,24 @@ export class PolyfaceBuilder extends NullGeometryHandler {
     static _workVectorFindOrAdd = Vector3d.create();
     static _workUVFindOrAdd = Point2d.create();
     /**
-     * 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.
+     * 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.
+     * * The index is unchecked. Use [[findOrAddPointInLineString]] to check index validity.
+     * @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.
+     */
+    findOrAddPointInLineStringUnchecked(ls, index, transform, priorIndex) {
+        const q = ls.pointAtUnchecked(index, PolyfaceBuilder._workPointFindOrAddA);
+        if (transform)
+            transform.multiplyPoint3d(q, q);
+        return this._polyface.addPoint(q, priorIndex);
+    }
+    /**
+     * 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.
@@ -350,35 +369,59 @@ export class PolyfaceBuilder extends NullGeometryHandler {
      * @returns the point index in the polyface.
      */
     findOrAddPointInLineString(ls, index, transform, priorIndex) {
-        const q = ls.pointAt(index, PolyfaceBuilder._workPointFindOrAddA);
-        if (q) {
-            if (transform)
-                transform.multiplyPoint3d(q, q);
-            return this._polyface.addPoint(q, priorIndex);
-        }
+        if (ls.packedPoints.isIndexValid(index))
+            return this.findOrAddPointInLineStringUnchecked(ls, index, transform, priorIndex);
         return undefined;
     }
     /**
-     * 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.
+     * 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.
+     * * The index is unchecked. Use [[findOrAddPointInGrowableXYZArray]] to check index validity.
      * @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.
      */
+    findOrAddPointInGrowableXYZArrayUnchecked(xyz, index, transform, priorIndex) {
+        const q = xyz.getPoint3dAtUncheckedPointIndex(index, PolyfaceBuilder._workPointFindOrAddA);
+        if (transform)
+            transform.multiplyPoint3d(q, q);
+        return this._polyface.addPoint(q, priorIndex);
+    }
+    /**
+     * 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, or undefined if the index is invalid.
+     */
     findOrAddPointInGrowableXYZArray(xyz, index, transform, priorIndex) {
-        const q = xyz.getPoint3dAtCheckedPointIndex(index, PolyfaceBuilder._workPointFindOrAddA);
-        if (q) {
-            if (transform)
-                transform.multiplyPoint3d(q, q);
-            return this._polyface.addPoint(q, priorIndex);
-        }
+        if (xyz.isIndexValid(index))
+            return this.findOrAddPointInGrowableXYZArrayUnchecked(xyz, index, transform, priorIndex);
         return undefined;
     }
     /**
-     * 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.
+     * 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.
+     * * The index is unchecked. Use [[findOrAddNormalInGrowableXYZArray]] to check index validity.
+     * @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.
+     */
+    findOrAddNormalInGrowableXYZArrayUnchecked(xyz, index, transform, priorIndex) {
+        const q = xyz.getVector3dAtUncheckedVectorIndex(index, PolyfaceBuilder._workVectorFindOrAdd);
+        if (transform)
+            transform.multiplyVector(q, q);
+        return this._polyface.addNormal(q, priorIndex);
+    }
+    /**
+     * 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.
@@ -386,14 +429,21 @@ export class PolyfaceBuilder extends NullGeometryHandler {
      * @returns the normal index in the polyface.
      */
     findOrAddNormalInGrowableXYZArray(xyz, index, transform, priorIndex) {
-        const q = xyz.getVector3dAtCheckedVectorIndex(index, PolyfaceBuilder._workVectorFindOrAdd);
-        if (q) {
-            if (transform)
-                transform.multiplyVector(q, q);
-            return this._polyface.addNormal(q, priorIndex);
-        }
+        if (xyz.isIndexValid(index))
+            return this.findOrAddNormalInGrowableXYZArrayUnchecked(xyz, index, transform, priorIndex);
         return undefined;
     }
+    /**
+     * Add a uv parameter to the polyface.
+     * * The index is unchecked. Use [[addParamInGrowableXYArray]] to check index validity.
+     * @param data the array of uv data.
+     * @param index index of the param in the array.
+     * @returns the uv parameter index in the polyface.
+     */
+    addParamInGrowableXYArrayUnchecked(data, index) {
+        const q = data.getPoint2dAtUncheckedPointIndex(index, PolyfaceBuilder._workUVFindOrAdd);
+        return this._polyface.addParam(q);
+    }
     /**
      * Add a uv parameter to the polyface.
      * @param data the array of uv data.
@@ -401,16 +451,15 @@ export class PolyfaceBuilder extends NullGeometryHandler {
      * @returns the uv parameter index in the polyface.
      */
     addParamInGrowableXYArray(data, index) {
-        if (!data)
-            return undefined;
-        const q = data.getPoint2dAtCheckedPointIndex(index, PolyfaceBuilder._workUVFindOrAdd);
-        if (q)
-            return this._polyface.addParam(q);
+        if (data.isIndexValid(index))
+            return this.addParamInGrowableXYArrayUnchecked(data, index);
         return undefined;
     }
     /**
-     * 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.
+     * Add a uv parameter to the polyface, taking `u` from `ls.fractions` and `v` from input.
+     * * If `index` is an invalid index for `ls.fractions`, `u` is computed as `index / ls.points.length`.
+     * * 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.
@@ -419,8 +468,7 @@ export class PolyfaceBuilder extends NullGeometryHandler {
      * @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?.atIndex(index) ?? index / ls.points.length;
         return this._polyface.addParamUV(u, v, priorIndexA, priorIndexB);
     }
     /**
@@ -448,80 +496,91 @@ export class PolyfaceBuilder extends NullGeometryHandler {
     addPointXYZ(x, y, z) {
         return this._polyface.addPointXYZ(x, y, z);
     }
-    /** Returns a transform who can be applied to points on a triangular facet in order to obtain UV parameters. */
-    getUVTransformForTriangleFacet(pointA, pointB, pointC) {
-        const vectorAB = pointA.vectorTo(pointB);
-        const vectorAC = pointA.vectorTo(pointC);
-        const unitAxes = Matrix3d.createRigidFromColumns(vectorAB, vectorAC, AxisOrder.XYZ);
-        const localToWorld = Transform.createOriginAndMatrix(pointA, unitAxes);
-        return localToWorld.inverse();
+    static _workVector0;
+    static _workVector1;
+    /** Returns a uv-to-world transform whose inverse can be applied to points on a triangular facet in order to obtain UV parameters. */
+    getUVTransformForTriangleFacet(pointA, pointB, pointC, result) {
+        const vectorAB = PolyfaceBuilder._workVector0 = pointA.vectorTo(pointB, PolyfaceBuilder._workVector0);
+        const vectorAC = PolyfaceBuilder._workVector1 = pointA.vectorTo(pointC, PolyfaceBuilder._workVector1);
+        return Transform.createRigidFromOriginAndColumns(pointA, vectorAB, vectorAC, AxisOrder.XYZ, result);
     }
     /** Returns the normal to a triangular facet. */
-    getNormalForTriangularFacet(pointA, pointB, pointC) {
-        const vectorAB = pointA.vectorTo(pointB);
-        const vectorAC = pointA.vectorTo(pointC);
-        let normal = vectorAB.crossProduct(vectorAC).normalize();
-        normal = normal ? normal : Vector3d.create();
-        return normal;
-    }
-    // ### TODO: Consider case where normals will be reversed and point through the other end of the facet.
+    getNormalForTriangularFacet(pointA, pointB, pointC, result) {
+        const normal = pointA.crossProductToPoints(pointB, pointC, result);
+        return normal.tryNormalizeInPlace() ? normal : Vector3d.createZero(result);
+    }
+    // below uv/normal temp vars are held by addQuadFacet and should not be used in methods called by it
+    static _workUV0;
+    static _workUV1;
+    static _workUV2;
+    static _workUV3;
+    static _workNormal0;
+    static _workNormal1;
+    static _workNormal2;
+    static _workNormal3;
+    static _workTransform;
     /**
      * Add a quad to the polyface given its points in order around the edges.
      * @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.
+     * @param params (optional) array of at least four uv parameters. If `undefined` or insufficiently sized
+     * or quad is degenerate, and params are needed, uv are calculated from `points`.
+     * @param normals (optional) array of at least four vectors. If `undefined` or insufficiently sized,
+     * and normals are needed, the quad is assumed to be planar and its normal is calculated from `points`.
+     * @param colors (optional) array of at least four colors. If `undefined` or insufficiently sized, and
+     * colors are needed, color 0 is used.
      */
     addQuadFacet(points, params, normals, colors) {
-        if (points instanceof GrowableXYZArray)
-            points = points.getPoint3dArray();
         if (points.length < 4)
             return;
+        if (points instanceof GrowableXYZArray)
+            points = points.getPoint3dArray();
         // 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;
-        let param0, param1, param2, param3;
-        let normal0, normal1, normal2, normal3;
-        let color0, color1, color2, color3;
+        const param0 = PolyfaceBuilder._workUV0 = Point2d.createZero(PolyfaceBuilder._workUV0);
+        const param1 = PolyfaceBuilder._workUV1 = Point2d.createZero(PolyfaceBuilder._workUV1);
+        const param2 = PolyfaceBuilder._workUV2 = Point2d.createZero(PolyfaceBuilder._workUV2);
+        const param3 = PolyfaceBuilder._workUV3 = Point2d.createZero(PolyfaceBuilder._workUV3);
+        const normal0 = PolyfaceBuilder._workNormal0 = Vector3d.createZero(PolyfaceBuilder._workNormal0);
+        const normal1 = PolyfaceBuilder._workNormal1 = Vector3d.createZero(PolyfaceBuilder._workNormal1);
+        const normal2 = PolyfaceBuilder._workNormal2 = Vector3d.createZero(PolyfaceBuilder._workNormal2);
+        const normal3 = PolyfaceBuilder._workNormal3 = Vector3d.createZero(PolyfaceBuilder._workNormal3);
+        let color0 = 0, color1 = 0, color2 = 0, color3 = 0;
         if (needParams) {
-            if (params !== undefined && params.length > 3) {
-                param0 = params[0];
-                param1 = params[1];
-                param2 = params[2];
-                param3 = params[3];
+            if (params && params.length > 3) {
+                param0.setFrom(params[0]);
+                param1.setFrom(params[1]);
+                param2.setFrom(params[2]);
+                param3.setFrom(params[3]);
             }
             else {
-                const paramTransform = this.getUVTransformForTriangleFacet(points[0], points[1], points[2]);
-                if (paramTransform === undefined) {
-                    param0 = param1 = param2 = param3 = Point2d.createZero();
-                }
-                else {
-                    param0 = Point2d.createFrom(paramTransform.multiplyPoint3d(points[0]));
-                    param1 = Point2d.createFrom(paramTransform.multiplyPoint3d(points[1]));
-                    param2 = Point2d.createFrom(paramTransform.multiplyPoint3d(points[2]));
-                    param3 = Point2d.createFrom(paramTransform.multiplyPoint3d(points[3]));
+                // skip points[2] when computing transform so that parallelogram common case gets param2 = (1,1)
+                const paramTransform = PolyfaceBuilder._workTransform = this.getUVTransformForTriangleFacet(points[0], points[1], points[3], PolyfaceBuilder._workTransform);
+                if (paramTransform) {
+                    paramTransform.multiplyInversePoint3dAsPoint2d(points[0], param0);
+                    paramTransform.multiplyInversePoint3dAsPoint2d(points[1], param1);
+                    paramTransform.multiplyInversePoint3dAsPoint2d(points[2], param2);
+                    paramTransform.multiplyInversePoint3dAsPoint2d(points[3], param3);
                 }
             }
         }
         if (needNormals) {
-            if (normals !== undefined && normals.length > 3) {
-                normal0 = normals[0];
-                normal1 = normals[1];
-                normal2 = normals[2];
-                normal3 = normals[3];
+            if (normals && normals.length > 3) {
+                normal0.setFrom(normals[0]);
+                normal1.setFrom(normals[1]);
+                normal2.setFrom(normals[2]);
+                normal3.setFrom(normals[3]);
             }
-            else {
-                normal0 = this.getNormalForTriangularFacet(points[0], points[1], points[2]);
-                normal1 = this.getNormalForTriangularFacet(points[0], points[1], points[2]);
-                normal2 = this.getNormalForTriangularFacet(points[0], points[1], points[2]);
-                normal3 = this.getNormalForTriangularFacet(points[0], points[1], points[2]);
+            else { // same normal at each corner
+                this.getNormalForTriangularFacet(points[0], points[1], points[2], normal0);
+                normal1.setFrom(normal0);
+                normal2.setFrom(normal0);
+                normal3.setFrom(normal0);
             }
         }
         if (needColors) {
-            if (colors !== undefined && colors.length > 3) {
+            if (colors && colors.length > 3) {
                 color0 = colors[0];
                 color1 = colors[1];
                 color2 = colors[2];
@@ -530,10 +589,10 @@ export class PolyfaceBuilder extends NullGeometryHandler {
         }
         if (this._options.shouldTriangulate) {
             // 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
-            if (vectorAC.magnitude() >= vectorBD.magnitude()) {
+            const magSquaredAC = points[0].distanceSquared(points[2]);
+            const magSquaredBD = points[1].distanceSquared(points[3]);
+            // use tiny tol to reduce chance of the odd flipped diagonal in a regular quad grid
+            if (magSquaredAC + Geometry.smallFloatingPoint >= magSquaredBD) {
                 this.addTriangleFacet([points[0], points[1], points[2]], needParams ? [param0, param1, param2] : undefined, needNormals ? [normal0, normal1, normal2] : undefined, needColors ? [color0, color1, color2] : undefined);
                 this.addTriangleFacet([points[0], points[2], points[3]], needParams ? [param0, param2, param3] : undefined, needNormals ? [normal0, normal2, normal3] : undefined, needColors ? [color0, color2, color3] : undefined);
             }
@@ -643,76 +702,74 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             this._polyface.addColorIndex(indexB0);
         }
     }
-    // ### 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 params (optional) array of at least three uv parameters. If `undefined` or insufficiently sized
+     * or quad is degenerate, and params are needed, uv are calculated from `points`.
+     * @param normals (optional) array of at least three vectors. If `undefined` or insufficiently sized,
+     * and normals are needed, the normal is calculated from `points`.
+     * @param colors (optional) array of at least three colors. If `undefined` or insufficiently sized, and
+     * colors are needed, color 0 is used.
      */
     addTriangleFacet(points, params, normals, colors) {
         if (points.length < 3)
             return;
+        if (points instanceof GrowableXYZArray)
+            points = points.getPoint3dArray();
         let idx0;
         let idx1;
         let idx2;
-        let point0, point1, point2;
-        if (points instanceof GrowableXYZArray) {
-            point0 = points.getPoint3dAtCheckedPointIndex(0);
-            point1 = points.getPoint3dAtCheckedPointIndex(1);
-            point2 = points.getPoint3dAtCheckedPointIndex(2);
-        }
-        else {
-            point0 = points[0];
-            point1 = points[1];
-            point2 = points[2];
-        }
-        // add params if needed
-        if (this._options.needParams) {
-            if (params && params.length >= 3) { // params were given
+        if (this.options.needParams) {
+            if (params && params.length > 2) {
                 idx0 = this._polyface.addParam(params[0]);
                 idx1 = this._polyface.addParam(params[1]);
                 idx2 = this._polyface.addParam(params[2]);
             }
-            else { // compute params
-                const paramTransform = this.getUVTransformForTriangleFacet(point0, point1, point2);
-                idx0 = this._polyface.addParam(Point2d.createFrom(paramTransform ? paramTransform.multiplyPoint3d(point0) : undefined));
-                idx1 = this._polyface.addParam(Point2d.createFrom(paramTransform ? paramTransform.multiplyPoint3d(point1) : undefined));
-                idx2 = this._polyface.addParam(Point2d.createFrom(paramTransform ? paramTransform.multiplyPoint3d(point1) : undefined));
+            else { // compute uv params from points
+                const param = PolyfaceBuilder._workUV0 = Point2d.createZero(PolyfaceBuilder._workUV0); // not used by caller
+                const paramTransform = PolyfaceBuilder._workTransform = this.getUVTransformForTriangleFacet(points[0], points[1], points[2], PolyfaceBuilder._workTransform);
+                paramTransform?.multiplyInversePoint3dAsPoint2d(points[0], param);
+                idx2 = idx1 = idx0 = this._polyface.addParam(param);
+                if (paramTransform) {
+                    paramTransform.multiplyInversePoint3dAsPoint2d(points[1], param);
+                    idx1 = this._polyface.addParam(param);
+                    paramTransform.multiplyInversePoint3dAsPoint2d(points[2], param);
+                    idx2 = this._polyface.addParam(param);
+                }
             }
             this.addIndexedTriangleParamIndexes(idx0, idx1, idx2);
         }
-        // add normals if needed
-        if (this._options.needNormals) {
-            if (normals !== undefined && normals.length > 2) { // normals were given
+        if (this.options.needNormals) {
+            if (normals && normals.length > 2) {
                 idx0 = this._polyface.addNormal(normals[0]);
                 idx1 = this._polyface.addNormal(normals[1]);
                 idx2 = this._polyface.addNormal(normals[2]);
             }
-            else { // compute normals
-                const normal = this.getNormalForTriangularFacet(point0, point1, point2);
-                idx0 = this._polyface.addNormal(normal);
-                idx1 = this._polyface.addNormal(normal);
-                idx2 = this._polyface.addNormal(normal);
+            else { // compute the normal from points
+                const normal = PolyfaceBuilder._workNormal0 = Vector3d.createZero(PolyfaceBuilder._workNormal0); // not used by caller
+                this.getNormalForTriangularFacet(points[0], points[1], points[2], normal);
+                idx2 = idx1 = idx0 = this._polyface.addNormal(normal);
             }
             this.addIndexedTriangleNormalIndexes(idx0, idx1, idx2);
         }
         // add colors if needed and provided
-        if (this._options.needColors) {
-            if (colors !== undefined && colors.length > 2) {
+        if (this.options.needColors) {
+            if (colors && colors.length > 2) {
                 idx0 = this._polyface.addColor(colors[0]);
                 idx1 = this._polyface.addColor(colors[1]);
                 idx2 = this._polyface.addColor(colors[2]);
-                this.addIndexedTriangleColorIndexes(idx0, idx1, idx2);
             }
+            else {
+                idx2 = idx1 = idx0 = this._polyface.addColor(0);
+            }
+            this.addIndexedTriangleColorIndexes(idx0, idx1, idx2);
         }
         // 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);
+        idx0 = this.addPoint(points[0]);
+        idx1 = this.addPoint(points[1]);
+        idx2 = this.addPoint(points[2]);
+        this.addIndexedTrianglePointIndexes(idx0, idx1, idx2, true);
     }
     /**
      * Add a single triangular facet from existing points to the polyface.
@@ -856,24 +913,28 @@ export class PolyfaceBuilder extends NullGeometryHandler {
     /**
      * Add facets between lineStrings with matched point counts.
      * * Indices of points, normals, and uv parameters are pre-stored in the linestrings.
+     * * `pointIndices`, `normalIndices`, and `paramIndices` (if used) for both linestrings must be defined and
+     * have the same length.
      */
     addBetweenLineStringsWithStoredIndices(lineStringA, lineStringB) {
         const pointA = lineStringA.pointIndices;
         const pointB = lineStringB.pointIndices;
+        if (!pointA || !pointB || pointA.length < 2 || pointA.length !== pointB.length)
+            return;
+        const n = pointA.length;
         let normalA = lineStringA.normalIndices;
         let normalB = lineStringB.normalIndices;
-        if (!this._options.needNormals) {
+        if (!this._options.needNormals || (normalA && normalB && (normalA.length < n || normalB.length < n))) {
             normalA = undefined;
             normalB = undefined;
         }
         let paramA = lineStringA.paramIndices;
         let paramB = lineStringB.paramIndices;
-        if (!this._options.needParams) {
+        if (!this._options.needParams || (paramA && paramB && (paramA.length < n || paramB.length < n))) {
             paramA = undefined;
             paramB = undefined;
         }
-        const numPoints = pointA.length;
-        for (let i = 1; i < numPoints; i++) {
+        for (let i = 1; i < n; i++) {
             if (this.options.shouldTriangulate) {
                 if (distinctIndices(pointA.atUncheckedIndex(i - 1), pointA.atUncheckedIndex(i), pointB.atUncheckedIndex(i))) {
                     this.addIndexedTrianglePointIndexes(pointA.atUncheckedIndex(i - 1), pointA.atUncheckedIndex(i), pointB.atUncheckedIndex(i), false);
@@ -904,29 +965,30 @@ export class PolyfaceBuilder extends NullGeometryHandler {
         }
     }
     /**
-     * Add facets between lineStrings with matched point counts.
+     * Add facets between transformed lineStrings.
      * * Facets are announced to addIndexedQuad.
      * * addIndexedQuad is free to apply reversal or triangulation options.
      */
     addBetweenTransformedLineStrings(curves, transformA, transformB, addClosure = false) {
         if (curves instanceof LineString3d) {
-            const pointA = curves.points;
-            const numPoints = pointA.length;
-            let indexA0 = this.findOrAddPointInLineString(curves, 0, transformA);
-            let indexB0 = this.findOrAddPointInLineString(curves, 0, transformB);
-            const indexA00 = indexA0;
-            const indexB00 = indexB0;
-            let indexA1 = 0;
-            let indexB1 = 0;
-            for (let i = 1; i < numPoints; i++) {
-                indexA1 = this.findOrAddPointInLineString(curves, i, transformA);
-                indexB1 = this.findOrAddPointInLineString(curves, i, transformB);
-                this.addIndexedQuadPointIndexes(indexA0, indexA1, indexB0, indexB1);
-                indexA0 = indexA1;
-                indexB0 = indexB1;
+            const numPoints = curves.numPoints();
+            if (numPoints > 1) {
+                let indexA0 = this.findOrAddPointInLineStringUnchecked(curves, 0, transformA);
+                let indexB0 = this.findOrAddPointInLineStringUnchecked(curves, 0, transformB);
+                const indexA00 = indexA0;
+                const indexB00 = indexB0;
+                let indexA1 = 0;
+                let indexB1 = 0;
+                for (let i = 1; i < numPoints; i++) {
+                    indexA1 = this.findOrAddPointInLineStringUnchecked(curves, i, transformA);
+                    indexB1 = this.findOrAddPointInLineStringUnchecked(curves, i, transformB);
+                    this.addIndexedQuadPointIndexes(indexA0, indexA1, indexB0, indexB1);
+                    indexA0 = indexA1;
+                    indexB0 = indexB1;
+                }
+                if (addClosure && numPoints > 2)
+                    this.addIndexedQuadPointIndexes(indexA0, indexA00, indexB0, indexB00);
             }
-            if (addClosure)
-                this.addIndexedQuadPointIndexes(indexA0, indexA00, indexB0, indexB00);
         }
         else {
             const children = curves.children;
@@ -1002,8 +1064,8 @@ export class PolyfaceBuilder extends NullGeometryHandler {
         const sizes = surface.maxIsoParametricDistance();
         this.addUVGridBody(surface, numU, numV, Segment1d.create(0, sizes.x), Segment1d.create(0, sizes.y));
         this.toggleReversedFacetFlag();
-        if (surface.capped && thetaFraction < 1.0) {
-            const centerFrame = surface.getConstructiveFrame();
+        const centerFrame = surface.getConstructiveFrame();
+        if (centerFrame && surface.capped && thetaFraction < 1.0) {
             const minorRadius = surface.getMinorRadius();
             const majorRadius = surface.getMajorRadius();
             const a = 2 * minorRadius;
@@ -1049,7 +1111,7 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             let indexB1 = 0;
             const n = contour.numPoints();
             for (let i = 0; i < n; i++) {
-                pointA = contour.pointAt(i, pointA);
+                pointA = contour.pointAtUnchecked(i, pointA);
                 pointB = pointA.plus(vector, pointB);
                 indexA1 = this.addPoint(pointA);
                 indexB1 = this.addPoint(pointB);
@@ -1143,39 +1205,43 @@ export class PolyfaceBuilder extends NullGeometryHandler {
     }
     createIndicesInLineString(ls, vParam, transform) {
         const n = ls.numPoints();
+        if (n < 1)
+            return;
         const pointIndices = ls.ensureEmptyPointIndices();
-        const index0 = this.findOrAddPointInLineString(ls, 0, transform);
+        const index0 = this.findOrAddPointInLineStringUnchecked(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);
+                indexB = this.findOrAddPointInLineStringUnchecked(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);
+            indexB = this.findOrAddPointInLineStringUnchecked(ls, n - 1, transform, index0);
             pointIndices.push(indexB);
         }
-        if (this._options.needNormals && ls.packedSurfaceNormals !== undefined) {
+        if (this._options.needNormals && ls.packedSurfaceNormals && ls.packedSurfaceNormals.length >= n) {
             const normalIndices = ls.ensureEmptyNormalIndices();
             const normalIndex0 = this.findOrAddNormalInLineString(ls, 0, transform);
+            assert(normalIndex0 !== undefined, "expect defined because ls has at least one normal");
             normalIndices.push(normalIndex0);
             if (n > 1) {
                 let normalIndexA = normalIndex0;
                 let normalIndexB;
                 for (let i = 1; i + 1 < n; i++) {
                     normalIndexB = this.findOrAddNormalInLineString(ls, i, transform, normalIndexA);
+                    assert(normalIndexB !== undefined, "expect defined because ls has normal at index i");
                     normalIndices.push(normalIndexB);
                     normalIndexA = normalIndexB;
                 }
-                // assume last point can only repeat back to zero
                 normalIndexB = this.findOrAddNormalInLineString(ls, n - 1, transform, normalIndex0, normalIndexA);
+                assert(normalIndexB !== undefined, "expect defined because ls has normal at index n-1");
                 normalIndices.push(normalIndexB);
             }
         }
-        if (this._options.needParams && ls.packedUVParams !== undefined) {
+        if (this._options.needParams) { // u from ls.fractions, or computed
             const uvIndices = ls.ensureEmptyUVIndices();
             const uvIndex0 = this.findOrAddParamInLineString(ls, 0, vParam);
             uvIndices.push(uvIndex0);
@@ -1187,7 +1253,6 @@ export class PolyfaceBuilder extends NullGeometryHandler {
                     uvIndices.push(uvIndexB);
                     uvIndexA = uvIndexB;
                 }
-                // assume last point can only repeat back to zero
                 uvIndexB = this.findOrAddParamInLineString(ls, n - 1, vParam, uvIndexA, uvIndex0);
                 uvIndices.push(uvIndexB);
             }
@@ -1358,18 +1423,18 @@ export class PolyfaceBuilder extends NullGeometryHandler {
     addPolygonGrowableXYZArray(points) {
         // don't use trailing points that match start point
         let numPointsToUse = points.length;
-        while (numPointsToUse > 2 && Geometry.isSmallMetricDistance(points.distanceIndexIndex(0, numPointsToUse - 1)))
+        while (numPointsToUse > 2 && Geometry.isSmallMetricDistance(points.distanceUncheckedIndexIndex(0, numPointsToUse - 1)))
             numPointsToUse--;
         // strip trailing duplicates
-        while (numPointsToUse > 2 && Geometry.isSmallMetricDistance(points.distanceIndexIndex(numPointsToUse - 2, numPointsToUse - 1)))
+        while (numPointsToUse > 2 && Geometry.isSmallMetricDistance(points.distanceUncheckedIndexIndex(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.
         // cross product magnitude is twice the area.
         if (numPointsToUse === 3) {
-            const cross = points.crossProductIndexIndexIndex(0, 1, 2);
+            const cross = points.crossProductUncheckedIndexIndexIndex(0, 1, 2);
             const q = cross.magnitude();
-            const p = points.distanceIndexIndex(0, 1) + points.distanceIndexIndex(0, 2) + points.distanceIndexIndex(1, 2);
+            const p = points.distanceUncheckedIndexIndex(0, 1) + points.distanceUncheckedIndexIndex(0, 2) + points.distanceUncheckedIndexIndex(1, 2);
             if (q < Geometry.smallMetricDistance * p)
                 numPointsToUse = 0;
         }
@@ -1377,13 +1442,13 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             let index = 0;
             if (!this._reversed) {
                 for (let i = 0; i < numPointsToUse; i++) {
-                    index = this.findOrAddPointInGrowableXYZArray(points, i);
+                    index = this.findOrAddPointInGrowableXYZArrayUnchecked(points, i);
                     this._polyface.addPointIndex(index);
                 }
             }
             else {
                 for (let i = numPointsToUse; --i >= 0;) {
-                    index = this.findOrAddPointInGrowableXYZArray(points, i);
+                    index = this.findOrAddPointInGrowableXYZArrayUnchecked(points, i);
                     this._polyface.addPointIndex(index);
                 }
             }
@@ -1405,7 +1470,7 @@ export class PolyfaceBuilder extends NullGeometryHandler {
     addFacetFromGrowableArrays(points, normals, params, colors, edgeVisible) {
         // don't use trailing points that match start point
         let numPointsToUse = points.length;
-        while (numPointsToUse > 1 && Geometry.isSmallMetricDistance(points.distanceIndexIndex(0, numPointsToUse - 1)))
+        while (numPointsToUse > 1 && Geometry.isSmallMetricDistance(points.distanceUncheckedIndexIndex(0, numPointsToUse - 1)))
             numPointsToUse--;
         let index = 0;
         if (normals && normals.length < numPointsToUse)
@@ -1418,14 +1483,14 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             edgeVisible = undefined;
         if (!this._reversed) {
             for (let i = 0; i < numPointsToUse; i++) {
-                index = this.findOrAddPointInGrowableXYZArray(points, i);
+                index = this.findOrAddPointInGrowableXYZArrayUnchecked(points, i);
                 this._polyface.addPointIndex(index, edgeVisible ? edgeVisible[i] : true);
                 if (normals) {
-                    index = this.findOrAddNormalInGrowableXYZArray(normals, i);
+                    index = this.findOrAddNormalInGrowableXYZArrayUnchecked(normals, i);
                     this._polyface.addNormalIndex(index);
                 }
                 if (params) {
-                    index = this.addParamInGrowableXYArray(params, i);
+                    index = this.addParamInGrowableXYArrayUnchecked(params, i);
                     this._polyface.addParamIndex(index);
                 }
                 if (colors) {
@@ -1436,14 +1501,14 @@ export class PolyfaceBuilder extends NullGeometryHandler {
         }
         else {
             for (let i = numPointsToUse; --i >= 0;) {
-                index = this.findOrAddPointInGrowableXYZArray(points, i);
+                index = this.findOrAddPointInGrowableXYZArrayUnchecked(points, i);
                 this._polyface.addPointIndex(index);
                 if (normals) {
-                    index = this.findOrAddNormalInGrowableXYZArray(normals, i);
+                    index = this.findOrAddNormalInGrowableXYZArrayUnchecked(normals, i);
                     this._polyface.addNormalIndex(index);
                 }
                 if (params) {
-                    index = this.addParamInGrowableXYArray(params, i);
+                    index = this.addParamInGrowableXYArrayUnchecked(params, i);
                     this._polyface.addParamIndex(index);
                 }
                 if (colors) {
@@ -1650,6 +1715,8 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             localToWorld = FrameBuilder.createFrameWithCCWPolygon(points);
         if (localToWorld) {
             const localPoints = localToWorld.multiplyInversePoint3dArray(points);
+            if (!localPoints)
+                return undefined; // should never happen, but go ahead and return undefined since it is in the return type union
             const areaXY = PolygonOps.areaXY(localPoints);
             if (areaXY < 0.0)
                 localPoints.reverse();
@@ -1714,7 +1781,6 @@ export class PolyfaceBuilder extends NullGeometryHandler {
             paramIndex0 = new GrowableFloat64Array(numU);
             paramIndex1 = new GrowableFloat64Array(numU);
         }
-        let indexSwap;
         xyzIndex0.ensureCapacity(numU);
         xyzIndex1.ensureCapacity(numU);
         const uv = Point2d.create();
@@ -1725,62 +1791,57 @@ export class PolyfaceBuilder extends NullGeometryHandler {
         for (let v = 0; v <= numV; v++) {
             // evaluate new points
             xyzIndex1.clear();
-            if (needNormals)
+            if (normalIndex1)
                 normalIndex1.clear();
-            if (needParams)
+            if (paramIndex1)
                 paramIndex1.clear();
             for (let u = 0; u <= numU; u++) {
                 const uFrac = u * du;
                 const vFrac = v * dv;
                 surface.uvFractionToPointAndTangents(uFrac, vFrac, plane);
                 xyzIndex1.push(this._polyface.addPoint(plane.origin));
-                if (needNormals) {
+                if (normalIndex1) {
                     plane.vectorU.crossProduct(plane.vectorV, normal);
                     normal.normalizeInPlace();
                     if (reverse)
                         normal.scaleInPlace(-1.0);
                     normalIndex1.push(this._polyface.addNormal(normal));
                 }
-                if (needParams)
+                if (paramIndex1) {
                     paramIndex1.push(this._polyface.addParam(Point2d.create(uMap ? uMap.fractionToPoint(uFrac) : uFrac, vMap ? vMap.fractionToPoint(vFrac) : vFrac, uv)));
+                }
             }
             if (v > 0) {
                 for (let u = 0; u < numU; u++) {
                     if (!this._options.shouldTriangulate) {
                         this.addIndexedQuadPointIndexes(xyzIndex0.atUncheckedIndex(u), xyzIndex0.atUncheckedIndex(u + 1), xyzIndex1.atUncheckedIndex(u), xyzIndex1.atUncheckedIndex(u + 1), false);
-                        if (needNormals)
+                        if (needNormals && normalIndex0 && normalIndex1)
                             this.addIndexedQuadNormalIndexes(normalIndex0.atUncheckedIndex(u), normalIndex0.atUncheckedIndex(u + 1), normalIndex1.atUncheckedIndex(u), normalIndex1.atUncheckedIndex(u + 1));
-                        if (needParams)
+                        if (needParams && paramIndex0 && paramIndex1)
                             this.addIndexedQuadParamIndexes(paramIndex0.atUncheckedIndex(u), paramIndex0.atUncheckedIndex(u + 1), paramIndex1.atUncheckedIndex(u), paramIndex1.atUncheckedIndex(u + 1));
                         this._polyface.terminateFacet();
                     }
                     else {
                         this.addIndexedTrianglePointIndexes(xyzIndex0.atUncheckedIndex(u), xyzIndex0.atUncheckedIndex(u + 1), xyzIndex1.atUncheckedIndex(u), false);
-                        if (needNormals)
+                        if (normalIndex0 && normalIndex1)
                             this.addIndexedTriangleNormalIndexes(normalIndex0.atUncheckedIndex(u), normalIndex0.atUncheckedIndex(u + 1), normalIndex1.atUncheckedIndex(u));
-                        if (needParams)
+                        if (paramIndex0 && paramIndex1)
                             this.addIndexedTriangleParamIndexes(paramIndex0.atUncheckedIndex(u), paramIndex0.atUncheckedIndex(u + 1), paramIndex1.atUncheckedIndex(u));
                         this._polyface.terminateFacet();
                         this.addIndexedTrianglePointIndexes(xyzIndex1.atUncheckedIndex(u), xyzIndex0.atUncheckedIndex(u + 1), xyzIndex1.atUncheckedIndex(u + 1), false);
-                        if (needNormals)
+                        if (normalIndex0 && normalIndex1)
                             this.addIndexedTriangleNormalIndexes(normalIndex1.atUncheckedIndex(u), normalIndex0.atUncheckedIndex(u + 1), normalIndex1.atUncheckedIndex(u + 1));
-                        if (needParams)
+                        if (paramIndex0 && paramIndex1)
                             this.addIndexedTriangleParamIndexes(paramIndex1.atUncheckedIndex(u), paramIndex0.atUncheckedIndex(u + 1), paramIndex1.atUncheckedIndex(u + 1));
                         this._polyface.terminateFacet();
                     }
                 }
             }
-            indexSwap = xyzIndex1;
-            xyzIndex1 = xyzIndex0;
-            xyzIndex0 = indexSwap;
+            [xyzIndex0, xyzIndex1] = [xyzIndex1, xyzIndex0];
             if (needParams)
-                indexSwap = paramIndex1;
-            paramIndex1 = paramIndex0;
-            paramIndex0 = indexSwap;
+                [paramIndex0, paramIndex1] = [paramIndex1, paramIndex0];
             if (needNormals)
-                indexSwap = normalIndex1;
-            normalIndex1 = normalIndex0;
-            normalIndex0 = indexSwap;
+                [normalIndex0, normalIndex1] = [normalIndex1, normalIndex0];
         }
         xyzIndex0.clear();
         xyzIndex1.clear();
@@ -1894,17 +1955,16 @@ export class PolyfaceBuilder extends NullGeometryHandler {
         ];
         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)
+        if (this.options.needColors && this._polyface.data.color && this._polyface.data.colorIndex)
             colors = [];
         for (let i = 0; i < 4; ++i) {
-            const xyz = this._polyface.data.getPoint(this._polyface.data.pointIndex[indices[i]]);
+            const index = indices[i];
+            const xyz = this._polyface.data.getPoint(this._polyface.data.pointIndex[index]);
             if (undefined === xyz)
                 return false;
             vertices.push(xyz);
-            if (undefined !== colors) {
-                const color = this._polyface.data.getColor(this._polyface.data.colorIndex[indices[i]]);
-                if (undefined === color)
-                    return false;
+            if (colors && this._polyface.data.colorIndex && 0 <= index && index < this._polyface.data.colorIndex.length) {
+                const color = this._polyface.data.getColor(this._polyface.data.colorIndex[index]); // unchecked
                 colors.push(color);
             }
         }