@itwin/core-geometry 5.0.0-dev.2 → 5.0.0-dev.22

package/lib/esm/curve/CurveFactory.js

@@ -5,7 +5,6 @@
 /** @packageDocumentation
  * @module Curve
  */
-// import { Geometry, Angle, AngleSweep } from "../Geometry";
 import { AxisIndex, AxisOrder, Geometry } from "../Geometry";
 import { Angle } from "../geometry3d/Angle";
 import { AngleSweep } from "../geometry3d/AngleSweep";
@@ -30,6 +29,7 @@ import { LineSegment3d } from "./LineSegment3d";
 import { LineString3d } from "./LineString3d";
 import { Loop } from "./Loop";
 import { Path } from "./Path";
+import { RegionOps } from "./RegionOps";
 import { IntegratedSpiral3d } from "./spiral/IntegratedSpiral3d";
 /**
  * Enumeration of geometric output for [CurveFactory.createMiteredSweepSections].
@@ -44,12 +44,13 @@ export var MiteredSweepOutputSelect;
     /** Output planes and sections, as well as the assembled ruled sweep and its stroked mesh. */
     MiteredSweepOutputSelect[MiteredSweepOutputSelect["AlsoMesh"] = 2] = "AlsoMesh";
 })(MiteredSweepOutputSelect || (MiteredSweepOutputSelect = {}));
+;
 /**
  * The `CurveFactory` class contains methods for specialized curve constructions.
  * @public
  */
 export class CurveFactory {
-    /** (cautiously) construct and save a line segment between fractional positions. */
+    /** (Cautiously) construct and save a line segment between fractional positions. */
     static addPartialSegment(path, allowBackup, pointA, pointB, fraction0, fraction1) {
         if (allowBackup || (fraction1 > fraction0)) {
             if (pointA !== undefined && pointB !== undefined && !Geometry.isAlmostEqualNumber(fraction0, fraction1))
@@ -146,10 +147,11 @@ export class CurveFactory {
         }
         return path;
     }
-    /** Create a `Loop` with given xy corners and fixed z.
+    /**
+     * Create a `Loop` with given xy corners and fixed z.
      * * The corners always proceed counter clockwise from lower left.
      * * If the radius is too large for the outer rectangle size, it is reduced to half of the the smaller x or y size.
-    */
+     */
     static createRectangleXY(x0, y0, x1, y1, z = 0, filletRadius) {
         let radius = Geometry.correctSmallMetricDistance(filletRadius);
         const xMin = Math.min(x0, x1);
@@ -158,7 +160,13 @@ export class CurveFactory {
         const yMax = Math.max(y0, y1);
         radius = Math.min(Math.abs(radius), 0.5 * (xMax - xMin), 0.5 * (yMax - yMin));
         if (radius === 0.0)
-            return Loop.createPolygon([Point3d.create(xMin, yMin, z), Point3d.create(xMax, yMin, z), Point3d.create(xMax, yMax, z), Point3d.create(xMin, yMax, z), Point3d.create(xMin, yMin, z)]);
+            return Loop.createPolygon([
+                Point3d.create(xMin, yMin, z),
+                Point3d.create(xMax, yMin, z),
+                Point3d.create(xMax, yMax, z),
+                Point3d.create(xMin, yMax, z),
+                Point3d.create(xMin, yMin, z),
+            ]);
         else {
             const vectorU = Vector3d.create(radius, 0, 0);
             const vectorV = Vector3d.create(0, radius, 0);
@@ -166,7 +174,12 @@ export class CurveFactory {
             const y0A = yMin + radius;
             const x1A = xMax - radius;
             const y1A = yMax - radius;
-            const centers = [Point3d.create(x1A, y1A, z), Point3d.create(x0A, y1A, z), Point3d.create(x0A, y0A, z), Point3d.create(x1A, y0A, z)];
+            const centers = [
+                Point3d.create(x1A, y1A, z),
+                Point3d.create(x0A, y1A, z),
+                Point3d.create(x0A, y0A, z),
+                Point3d.create(x1A, y0A, z),
+            ];
             const loop = Loop.create();
             for (let i = 0; i < 4; i++) {
                 const center = centers[i];
@@ -186,10 +199,10 @@ export class CurveFactory {
     /**
      * If `arcB` is a continuation of `arcA`, extend `arcA` (in place) to include the range of `arcB`
      * * This only succeeds if the two arcs are part of identical complete arcs and end of `arcA` matches the beginning of `arcB`.
-     * @param arcA first arc, modified in place
-     * @param arcB second arc, unmodified
-     * @param allowReversed whether to consolidate even when second arc is reversed
-     * @returns whether `arcA` was modified
+     * @param arcA first arc, modified in place.
+     * @param arcB second arc, unmodified.
+     * @param allowReversed whether to consolidate even when second arc is reversed.
+     * @returns whether `arcA` was modified.
      */
     static appendToArcInPlace(arcA, arcB, allowReverse = false) {
         if (arcA.center.isAlmostEqual(arcB.center)) {
@@ -205,7 +218,7 @@ export class CurveFactory {
                 arcA.sweep.setStartEndRadians(arcA.sweep.startRadians, arcA.sweep.startRadians + arcA.sweep.sweepRadians + sweepSign * arcB.sweep.sweepRadians);
                 return true;
             }
-            // Also ok if negated tangent . ..
+            // Also ok if negated tangent
             if (allowReverse) {
                 startB.direction.scaleInPlace(-1.0);
                 if (endA.isAlmostEqual(startB)) {
@@ -218,7 +231,8 @@ export class CurveFactory {
     }
     /**
      * Return a `Path` containing arcs are on the surface of an ellipsoid and pass through a sequence of points.
-     * * Each arc passes through the two given endpoints and in the plane containing the true surface normal at given `fractionForIntermediateNormal`
+     * * Each arc passes through the two given endpoints and in the plane containing the true surface normal at
+     * given `fractionForIntermediateNormal`
      * @param ellipsoid
      * @param pathPoints
      * @param fractionForIntermediateNormal fractional position for surface normal used to create the section plane.
@@ -241,7 +255,7 @@ export class CurveFactory {
     }
     /**
      * Create solid primitives for pipe segments (e.g. Cone or TorusPipe) around line and arc primitives.
-     * @param centerline centerline geometry/
+     * @param centerline centerline geometry.
      * @param pipeRadius radius of pipe.
      */
     static createPipeSegments(centerline, pipeRadius) {
@@ -267,16 +281,22 @@ export class CurveFactory {
         return undefined;
     }
     /**
-     * * Create section arcs for mitered pipe.
-     * * At each end of each pipe, the pipe is cut by the plane that bisects the angle between successive pipe centerlines.
-     * * The arc definitions are constructed so that lines between corresponding fractional positions on the arcs are
-     *     axial lines on the pipes.
-     * * This means that each arc definition axes (aka vector0 and vector90) are _not_ perpendicular to each other.
-     * * 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.
-     * @param centerline centerline of pipe
-     * @param sectionData circle radius, ellipse semi-axis lengths, or full Arc3d
+     * Create section arcs for mitered pipe.
+     * * At the end of each pipe segment, the pipe is mitered by the plane that bisects the angle between successive
+     * centerline segments.
+     * * The section arcs are constructed so that lines between corresponding fractional positions on the arcs are
+     *   axial lines on the pipes.
+     * * This means that the initial arc's vector0 and vector90 lengths and angular separation are _not_ preserved in
+     * the section arcs.
+     * * Circular or elliptical pipe cross sections can be specified by supplying either a radius, a pair of semi-axis
+     * lengths, or an Arc3d:
+     *    * For semi-axis length input, x and y correspond to ellipse local axes perpendicular to each other and to the
+     * start tangent.
+     *    * For Arc3d input, the center is translated to the centerline start point, but otherwise the arc is used as-is
+     * for the first section. For best results, the arc should be perpendicular to the centerline start tangent.
+     * @param centerline centerline of pipe. For best results, ensure no successive duplicate points with e.g.,
+     * [[GrowableXYZArray.createCompressed]].
+     * @param sectionData circle radius, ellipse semi-axis lengths, or full Arc3d (if not full, function makes it full).
      */
     static createMiteredPipeSections(centerline, sectionData) {
         const arcs = [];
@@ -285,15 +305,15 @@ export class CurveFactory {
         const vector0 = Vector3d.create();
         const vector90 = Vector3d.create();
         const vectorBC = Vector3d.create();
-        const currentCenter = Point3d.create();
-        centerline.vectorIndexIndex(0, 1, vectorBC);
-        centerline.getPoint3dAtUncheckedPointIndex(0, currentCenter);
-        let initialSection;
+        const sweep = AngleSweep.create360();
+        centerline.vectorIndexIndex(0, 1, vectorBC); // initially, the start tangent
         if (sectionData instanceof Arc3d) {
-            initialSection = sectionData.clone();
-            initialSection.center.setFrom(currentCenter);
             vector0.setFrom(sectionData.vector0);
             vector90.setFrom(sectionData.vector90);
+            sweep.setFrom(sectionData.sweep); // allow e.g., half-pipe
+            const sectionFacesForward = sectionData.matrixRef.columnDotXYZ(AxisIndex.Z, vectorBC.x, vectorBC.y, vectorBC.z) > 0;
+            if (sectionFacesForward !== sectionData.sweep.isCCW)
+                sweep.reverseInPlace();
         }
         else if (typeof sectionData === "number" || Point3d.isXAndY(sectionData)) {
             const length0 = (typeof sectionData === "number") ? sectionData : sectionData.x;
@@ -301,87 +321,161 @@ export class CurveFactory {
             const baseFrame = Matrix3d.createRigidHeadsUp(vectorBC, AxisOrder.ZXY);
             baseFrame.columnX(vector0).scaleInPlace(length0);
             baseFrame.columnY(vector90).scaleInPlace(length90);
-            initialSection = Arc3d.create(currentCenter, vector0, vector90, AngleSweep.create360());
         }
         else {
             return [];
         }
+        // ASSUME: initial section normal points toward sweep direction for subsequent facet creation
+        const initialSection = Arc3d.create(undefined, vector0, vector90, sweep);
+        centerline.getPoint3dAtUncheckedPointIndex(0, initialSection.centerRef);
         arcs.push(initialSection);
         const vectorAB = Vector3d.create();
         const bisector = Vector3d.create();
+        const center = Point3d.create();
         for (let i = 1; i < centerline.length; i++) {
             vectorAB.setFromVector3d(vectorBC);
-            centerline.getPoint3dAtUncheckedPointIndex(i, currentCenter);
-            if (i + 1 < centerline.length) {
+            centerline.getPoint3dAtUncheckedPointIndex(i, center);
+            if (i + 1 < centerline.length)
                 centerline.vectorIndexIndex(i, i + 1, vectorBC);
-            }
-            else {
+            else
                 vectorBC.setFromVector3d(vectorAB);
-            }
             if (vectorAB.normalizeInPlace() && vectorBC.normalizeInPlace()) {
                 vectorAB.interpolate(0.5, vectorBC, bisector);
-                // On the end ellipse for this pipe section. ..
-                // center comes directly from centerline[i]
-                // vector0 and vector90 are obtained by sweeping the corresponding vectors of the start ellipse to the split plane.
+                // At pipe end, the ellipse center comes directly from centerline[i], and vector0/vector90 are
+                // obtained by sweeping the corresponding vectors of the pipe start ellipse to the bisector plane.
                 moveVectorToPlane(vector0, vectorAB, bisector, vector0);
                 moveVectorToPlane(vector90, vectorAB, bisector, vector90);
-                arcs.push(Arc3d.create(currentCenter, vector0, vector90, AngleSweep.create360()));
+                arcs.push(Arc3d.create(center, vector0, vector90, sweep));
             }
         }
         return arcs;
     }
+    /** For a smooth curve, stroke and return unnormalized start/end tangents. */
+    static strokeSmoothCurve(curve, options) {
+        let startTangent, endTangent;
+        if (curve instanceof CurvePrimitive) {
+            startTangent = curve.fractionToPointAndDerivative(0.0).direction;
+            endTangent = curve.fractionToPointAndDerivative(1.0).direction;
+            const strokes = LineString3d.create();
+            curve.emitStrokes(strokes, options);
+            curve = strokes.packedPoints;
+        }
+        else if (curve instanceof CurveChain) {
+            startTangent = curve.startPointAndDerivative()?.direction;
+            endTangent = curve.endPointAndDerivative()?.direction;
+            const strokes = curve.getPackedStrokes(options);
+            if (!strokes)
+                return undefined;
+            curve = strokes;
+        }
+        else if (Array.isArray(curve))
+            curve = new Point3dArrayCarrier(curve);
+        return { strokes: curve, startTangent, endTangent };
+    }
+    /**
+     * Align two bisector plane normals to given smooth rail tangents or optional overrides.
+     * * Optionally average the normals for physically closed rail.
+     */
+    static alignFirstAndLastBisectorPlanes(firstPlane, lastPlane, smoothRailData, options) {
+        const normal0 = options?.startTangent ?? (smoothRailData?.startTangent ?? firstPlane.getNormalRef());
+        const normal1 = options?.endTangent ?? (smoothRailData?.endTangent ?? lastPlane.getNormalRef());
+        if (options?.wrapIfPhysicallyClosed && firstPlane.getOriginRef().isAlmostEqual(lastPlane.getOriginRef())) {
+            const avgNormal = normal0.plus(normal1);
+            if (avgNormal.tryNormalizeInPlace()) { // ignore cusp at seam
+                firstPlane.getNormalRef().setFrom(avgNormal);
+                lastPlane.getNormalRef().setFrom(avgNormal);
+                return;
+            }
+        }
+        if (normal0.tryNormalizeInPlace())
+            firstPlane.getNormalRef().setFrom(normal0);
+        if (normal1.tryNormalizeInPlace())
+            lastPlane.getNormalRef().setFrom(normal1);
+    }
+    /** Reverse a closed curve or region if necessary so that its orientation is CCW with respect to the plane normal. */
+    static alignClosedCurveToPlane(curve, planeNormal) {
+        let closedCurve;
+        if (curve instanceof CurvePrimitive) {
+            if (curve.startPoint().isAlmostEqual(curve.endPoint()))
+                closedCurve = Loop.create(curve);
+        }
+        else if (curve.isAnyRegion())
+            closedCurve = curve;
+        if (closedCurve) {
+            // The alignment condition is equivalent to positive projected curve area computed wrt to the plane normal.
+            const toLocal = Matrix3d.createRigidHeadsUp(planeNormal).transpose();
+            const projection = closedCurve.cloneTransformed(Transform.createOriginAndMatrix(undefined, toLocal));
+            if (projection) { // now we can ignore z-coords
+                const areaXY = RegionOps.computeXYArea(projection);
+                if (areaXY && areaXY < 0)
+                    curve.reverseInPlace();
+            }
+        }
+    }
     /**
-     * Sweep the initialSection along each segment of the centerLine until it hits the bisector plane at the next vertex.
-     * * The caller should place the initialSection on a plane perpendicular to the first edge.
-     *   * This plane is commonly (but not necessarily) through the start point itself.
-     *   * If the geometry is not "on a perpendicular plane", the output geometry will still be flattened onto the various planes.
-     * * In the "open path" case (i.e when wrapIfPhysicallyClosed is false or the path does not have matched first and last points)
-     *       the first/last output plane will be at the start/end of the first/last edge and on a perpendicular plane.
-     * * In the "closed path" case, the output plane for the first and last point is the bisector of the start and end planes from the "open path" case,
-     *    and the first/last section geometry may be different from `initialSection`.
-     * * The centerline path does NOT have to be planar, however twisting effects effects will appear in the various bisector planes.
-     * @param centerline sweep path, e.g., as stroked from a smooth centerline curve
-     * @param initialSection profile curve to be swept. As noted above, this should be on a plane perpendicular to the first segment of the centerline.
-     * @param options options for computation and output
-     * @return array of sections, starting with `initialSection` projected along the first edge to the first plane.
+     * Projection to target plane, constructing sweep direction from two given planes.
+     * * If successful, push the target plane and swept section to the output arrays and return the swept section.
+     * * If unsuccessful, leave the output arrays alone and return the input section.
+     */
+    static doSweepToPlane(output, edgePlane0, edgePlane1, targetPlane, section) {
+        const sweepVector = Vector3d.createStartEnd(edgePlane0.getOriginRef(), edgePlane1.getOriginRef());
+        const transform = Transform.createFlattenAlongVectorToPlane(sweepVector, targetPlane.getOriginRef(), targetPlane.getNormalRef());
+        if (transform === undefined)
+            return section;
+        const transformedSection = section.cloneTransformed(transform);
+        if (transformedSection === undefined)
+            return section;
+        output.planes.push(targetPlane);
+        output.sections.push(transformedSection);
+        return transformedSection;
+    }
+    /**
+     * Sweep the `initialSection` along each segment of the (stroked) `centerline` until it hits the bisector plane at
+     * the next vertex.
+     * * For best results, the caller should place `initialSection` in a plane perpendicular to the `centerline`
+     * start tangent.
+     *   * This plane is commonly (but not necessarily) through the centerline start point itself.
+     *   * To compute the sections, `initialSection` is projected in the direction of the centerline start tangent onto
+     * the first bisector plane at the centerline start. The result of this projection will be likewise projected onto
+     * the second plane, and so on in sequence.
+     * * By default, the first/last bisector plane normals are set to the centerline start/end tangents. The caller can
+     * override these with tangents supplied in `options`. If the centerline is physically closed and
+     * `options.wrapIfPhysicallyClosed` is true, the first and last plane normals are averaged and equated.
+     * * The centerline path does NOT have to be planar, however non-planarity will result in twisting of the sections
+     * in the bisector planes.
+     * @param centerline sweep path. Will be stroked if smooth.
+     * @param initialSection profile curve to be swept. As noted above, this should be on a plane perpendicular to the
+     * centerline start tangent.
+     * @param options options for computation and output.
+     * @return array of sections, formed from projecting `initialSection` successively onto the bisector planes.
      */
     static createMiteredSweepSections(centerline, initialSection, options) {
+        const rail = this.strokeSmoothCurve(centerline, options.strokeOptions);
+        if (!rail)
+            return undefined;
+        const planes = PolylineOps.createBisectorPlanesForDistinctPoints(rail.strokes);
+        if (!planes || planes.length < 2)
+            return undefined;
+        this.alignFirstAndLastBisectorPlanes(planes[0], planes[planes.length - 1], rail, options);
+        // RuledSweep facet construction assumes the contours are oriented CCW with respect to the sweep direction so that
+        // facet normals point outward. We only have to align the first contour; the rest will inherit its orientation.
+        this.alignClosedCurveToPlane(initialSection, planes[0].getNormalRef());
         const sectionData = { sections: [], planes: [] };
-        const planes = PolylineOps.createBisectorPlanesForDistinctPoints(centerline, options.wrapIfPhysicallyClosed);
-        if (planes !== undefined && planes.length > 1) {
-            // Projection to target plane, constructing sweep direction from two given planes.
-            // If successful, push the target plane and swept section to the output arrays and return the swept section.
-            // If unsuccessful, leave the output arrays alone and return the input section.
-            const doSweepToPlane = function (edgePlane0, edgePlane1, targetPlane, section) {
-                const sweepVector = Vector3d.createStartEnd(edgePlane0.getOriginRef(), edgePlane1.getOriginRef());
-                const transform = Transform.createFlattenAlongVectorToPlane(sweepVector, targetPlane.getOriginRef(), targetPlane.getNormalRef());
-                if (transform === undefined)
-                    return section;
-                const section1 = section.cloneTransformed(transform);
-                if (section1 === undefined)
-                    return section;
-                sectionData.planes.push(targetPlane);
-                sectionData.sections.push(section1);
-                return section1;
-            };
-            let currentSection = doSweepToPlane(planes[0], planes[1], planes[0], initialSection);
-            for (let i = 1; i < planes.length; i++) {
-                currentSection = doSweepToPlane(planes[i - 1], planes[i], planes[i], currentSection);
-            }
-            if (options.outputSelect) {
-                const ruledSweep = RuledSweep.create(sectionData.sections, options.capped ?? false);
-                if (ruledSweep) {
-                    sectionData.ruledSweep = ruledSweep;
-                    if (MiteredSweepOutputSelect.AlsoMesh === options.outputSelect) {
-                        const builder = PolyfaceBuilder.create(options.strokeOptions);
-                        builder.addRuledSweep(ruledSweep);
-                        sectionData.mesh = builder.claimPolyface();
-                    }
+        let currentSection = this.doSweepToPlane(sectionData, planes[0], planes[1], planes[0], initialSection);
+        for (let i = 1; i < planes.length; i++)
+            currentSection = this.doSweepToPlane(sectionData, planes[i - 1], planes[i], planes[i], currentSection);
+        if (options.outputSelect) {
+            const ruledSweep = RuledSweep.create(sectionData.sections, options.capped ?? false);
+            if (ruledSweep) {
+                sectionData.ruledSweep = ruledSweep;
+                if (MiteredSweepOutputSelect.AlsoMesh === options.outputSelect) {
+                    const builder = PolyfaceBuilder.create(options.strokeOptions);
+                    builder.addRuledSweep(ruledSweep);
+                    sectionData.mesh = builder.claimPolyface();
                 }
             }
-            return sectionData;
         }
-        return undefined;
+        return sectionData;
     }
     /**
      * Create a circular arc from start point, tangent at start, radius, optional plane normal, arc sweep.
@@ -398,11 +492,11 @@ export class CurveFactory {
     /**
      * Compute 2 spirals (all in XY) for a symmetric line-to-line transition.
      * * First spiral begins at given start point.
-     * * first tangent aims at shoulder
+     * * first tangent aims at shoulder.
      * * outbound spiral joins line from shoulder to target.
-     * @param spiralType name of spiral type.  THIS MUST BE AN "Integrated" SPIRAL TYPE
+     * @param spiralType name of spiral type. THIS MUST BE AN "Integrated" SPIRAL TYPE.
      * @param startPoint inbound start point.
-     * @param shoulder point target point for (both) spiral-to-line tangencies
+     * @param shoulder point target point for (both) spiral-to-line tangencies.
      * @return array with the computed spirals, or undefined if failure.
      */
     static createLineSpiralSpiralLine(spiralType, startPoint, shoulderPoint, targetPoint) {
@@ -440,9 +534,9 @@ export class CurveFactory {
      * Compute 2 spirals (all in XY) for a symmetric line-to-line transition.
      * * Spiral length is given.
      * * tangency points float on both lines.
-     * @param spiralType name of spiral type.  THIS MUST BE AN "Integrated" SPIRAL TYPE
+     * @param spiralType name of spiral type.  THIS MUST BE AN "Integrated" SPIRAL TYPE.
      * @param pointA inbound start point.
-     * @param shoulder point target point for (both) spiral-to-line tangencies
+     * @param shoulder point target point for (both) spiral-to-line tangencies.
      * @param spiralLength for each part of the spiral pair.
      * @return array with the computed spirals, or undefined if failure.
      */
@@ -480,12 +574,12 @@ export class CurveFactory {
     }
     /**
      * Compute 2 spirals and an arc (all in XY) for a symmetric line-to-line transition.
-     * Spiral lengths and arc radius are given.   (e.g. from design speed standards.)
-     * @param spiralType name of spiral type.  THIS MUST BE AN "Integrated" SPIRAL TYPE
+     * Spiral lengths and arc radius are given (e.g., from design speed standards).
+     * @param spiralType name of spiral type. THIS MUST BE AN "Integrated" SPIRAL TYPE.
      * @param pointA inbound start point.
-     * @param pointB shoulder (target)  point for (both) spiral-to-line tangencies
-     * @param lengthA inbound spiral length
-     * @param lengthB outbound spiral length
+     * @param pointB shoulder (target)  point for (both) spiral-to-line tangencies.
+     * @param lengthA inbound spiral length.
+     * @param lengthB outbound spiral length.
      * @return array with the computed spirals, or undefined if failure.
      */
     static createLineSpiralArcSpiralLine(spiralType, pointA, pointB, pointC, lengthA, lengthB, arcRadius) {
@@ -535,12 +629,7 @@ export class CurveFactory {
         }
         return undefined;
     }
-    /**
-     * Return the intersection point of 3 planes.
-     * @param planeA
-     * @param planeB
-     * @param planeC
-     */
+    /** Return the intersection point of 3 planes. */
     static planePlaneIntersectionRay(planeA, planeB) {
         const altitudeA = planeA.altitudeXYZ(0, 0, 0);
         const altitudeB = planeB.altitudeXYZ(0, 0, 0);
@@ -560,9 +649,7 @@ export class CurveFactory {
         return undefined;
     }
 }
-/**
- * Starting at vectorR, move parallel to vectorV until perpendicular to planeNormal
- */
+/** Starting at vectorR, move parallel to vectorV until perpendicular to planeNormal. */
 function moveVectorToPlane(vectorR, vectorV, planeNormal, result) {
     // find s such that (vectorR + s * vectorV) DOT planeNormal = 0.
     const dotRN = vectorR.dotProduct(planeNormal);