@itwin/core-geometry 3.5.0-dev.7 → 3.5.0

package/lib/cjs/geometry3d/Point3dVector3d.js

@@ -6,6 +6,7 @@
 /** @packageDocumentation
  * @module CartesianGeometry
  */
+// cspell:word CWXY
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Vector3d = exports.Point3d = exports.XYZ = void 0;
 const Geometry_1 = require("../Geometry");
@@ -20,24 +21,42 @@ const XYZProps_1 = require("./XYZProps");
  * @public
  */
 class XYZ {
-    constructor(x = 0, y = 0, z = 0) { this.x = x; this.y = y; this.z = z; }
+    constructor(x = 0, y = 0, z = 0) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+    }
     /**
      * Set the x,y,z  parts.
      * @param x (optional) x part
      * @param y (optional) y part
      * @param z (optional) z part
      */
-    set(x = 0, y = 0, z = 0) { this.x = x; this.y = y; this.z = z; }
+    set(x = 0, y = 0, z = 0) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+    }
     /** Set the x,y,z parts to zero. */
-    setZero() { this.x = 0; this.y = 0; this.z = 0; }
+    setZero() {
+        this.x = 0;
+        this.y = 0;
+        this.z = 0;
+    }
     /** Type guard for XAndY.
      * @note this will return true for an XYAndZ. If you wish to distinguish between the two, call isXYAndZ first.
      */
-    static isXAndY(arg) { return arg.x !== undefined && arg.y !== undefined; }
+    static isXAndY(arg) {
+        return arg.x !== undefined && arg.y !== undefined;
+    }
     /** Type guard to determine whether an object has a member called "z" */
-    static hasZ(arg) { return arg.z !== undefined; }
+    static hasZ(arg) {
+        return arg.z !== undefined;
+    }
     /** Type guard for XYAndZ.  */
-    static isXYAndZ(arg) { return this.isXAndY(arg) && this.hasZ(arg); }
+    static isXYAndZ(arg) {
+        return this.isXAndY(arg) && this.hasZ(arg);
+    }
     /** Test if arg is any of:
      * * XAndY
      * * XYAndZ
@@ -120,6 +139,7 @@ class XYZ {
     /**
      * Set the x,y,z parts from a Vector3d
      * This is the same effect as `setFrom(other)` with no pretesting of variant input type
+     * * Set to zeros if `other` is undefined.
      */
     setFromVector3d(other) {
         if (other) {
@@ -150,13 +170,21 @@ class XYZ {
             && Geometry_1.Geometry.isSameCoordinate(this.y, other.y, tol);
     }
     /** Return a JSON object as array `[x,y,z]` */
-    toJSON() { return this.toArray(); }
+    toJSON() {
+        return this.toArray();
+    }
     /** Return as an array `[x,y,z]` */
-    toArray() { return [this.x, this.y, this.z]; }
+    toArray() {
+        return [this.x, this.y, this.z];
+    }
     /** Return a JSON object as key value pairs `{x: value, y: value, z: value}` */
-    toJSONXYZ() { return { x: this.x, y: this.y, z: this.z }; }
+    toJSONXYZ() {
+        return { x: this.x, y: this.y, z: this.z };
+    }
     /** Pack the x,y,z values in a Float64Array. */
-    toFloat64Array() { return Float64Array.of(this.x, this.y, this.z); }
+    toFloat64Array() {
+        return Float64Array.of(this.x, this.y, this.z);
+    }
     /**
      * Set the x,y,z properties from one of several json forms:
      *
@@ -215,7 +243,7 @@ class XYZ {
         return this.y;
     }
     /**
-     * Return the x,y, z component corresponding to 0,1,2.
+     * Set value at index 0 or 1 or 2.
      */
     setAt(index, value) {
         if (index < 0.5)
@@ -242,28 +270,54 @@ class XYZ {
     }
     /** Return true if the x,y,z components are all nearly zero to tolerance Geometry.smallMetricDistance */
     get isAlmostZero() {
-        return Geometry_1.Geometry.isSmallMetricDistance(this.x) && Geometry_1.Geometry.isSmallMetricDistance(this.y) && Geometry_1.Geometry.isSmallMetricDistance(this.z);
+        return Geometry_1.Geometry.isSmallMetricDistance(this.x) &&
+            Geometry_1.Geometry.isSmallMetricDistance(this.y) &&
+            Geometry_1.Geometry.isSmallMetricDistance(this.z);
     }
     /** Return true if the x,y,z components are all exactly zero */
-    get isZero() { return this.x === 0.0 && this.y === 0.0 && this.z === 0.0; }
+    get isZero() {
+        return this.x === 0.0 && this.y === 0.0 && this.z === 0.0;
+    }
     /** Return the largest absolute value of any component */
-    maxAbs() { return Math.max(Math.abs(this.x), Math.abs(this.y), Math.abs(this.z)); }
+    maxAbs() {
+        return Math.max(Math.abs(this.x), Math.abs(this.y), Math.abs(this.z));
+    }
     /** Return the sqrt of the sum of squared x,y,z parts */
-    magnitude() { return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z); }
+    magnitude() {
+        return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
+    }
     /** Return the sum of squared x,y,z parts */
-    magnitudeSquared() { return this.x * this.x + this.y * this.y + this.z * this.z; }
+    magnitudeSquared() {
+        return this.x * this.x + this.y * this.y + this.z * this.z;
+    }
     /** Return sqrt of the sum of squared x,y parts */
-    magnitudeXY() { return Math.sqrt(this.x * this.x + this.y * this.y); }
+    magnitudeXY() {
+        return Math.sqrt(this.x * this.x + this.y * this.y);
+    }
     /** Return the sum of squared x,y parts */
-    magnitudeSquaredXY() { return this.x * this.x + this.y * this.y; }
+    magnitudeSquaredXY() {
+        return this.x * this.x + this.y * this.y;
+    }
     /** exact equality test. */
-    isExactEqual(other) { return this.x === other.x && this.y === other.y && this.z === other.z; }
+    isExactEqual(other) {
+        return this.x === other.x && this.y === other.y && this.z === other.z;
+    }
     /** equality test with Geometry.smallMetricDistance tolerance */
-    isAlmostEqualMetric(other) { return this.maxDiff(other) <= Geometry_1.Geometry.smallMetricDistance; }
+    isAlmostEqualMetric(other) {
+        return this.maxDiff(other) <= Geometry_1.Geometry.smallMetricDistance;
+    }
     /** add x,y,z from other in place. */
-    addInPlace(other) { this.x += other.x; this.y += other.y; this.z += other.z; }
+    addInPlace(other) {
+        this.x += other.x;
+        this.y += other.y;
+        this.z += other.z;
+    }
     /** add x,y,z from other in place. */
-    subtractInPlace(other) { this.x -= other.x; this.y -= other.y; this.z -= other.z; }
+    subtractInPlace(other) {
+        this.x -= other.x;
+        this.y -= other.y;
+        this.z -= other.z;
+    }
     /** add (in place) the scaled x,y,z of other */
     addScaledInPlace(other, scale) {
         this.x += scale * other.x;
@@ -271,11 +325,21 @@ class XYZ {
         this.z += scale * other.z;
     }
     /** Multiply the x, y, z parts by scale. */
-    scaleInPlace(scale) { this.x *= scale; this.y *= scale; this.z *= scale; }
+    scaleInPlace(scale) {
+        this.x *= scale;
+        this.y *= scale;
+        this.z *= scale;
+    }
     /** add to x, y, z parts */
-    addXYZInPlace(dx = 0.0, dy = 0.0, dz = 0.0) { this.x += dx; this.y += dy; this.z += dz; }
+    addXYZInPlace(dx = 0.0, dy = 0.0, dz = 0.0) {
+        this.x += dx;
+        this.y += dy;
+        this.z += dz;
+    }
     /** Clone strongly typed as Point3d */
-    cloneAsPoint3d() { return Point3d.create(this.x, this.y, this.z); }
+    cloneAsPoint3d() {
+        return Point3d.create(this.x, this.y, this.z);
+    }
     /** Return a (full length) vector from this point to other */
     vectorTo(other, result) {
         return Vector3d.create(other.x - this.x, other.y - this.y, other.z - this.z, result);
@@ -288,9 +352,13 @@ class XYZ {
      * @param other target of created vector.
      * @param result optional result vector.
      */
-    unitVectorTo(target, result) { return this.vectorTo(target, result).normalize(result); }
+    unitVectorTo(target, result) {
+        return this.vectorTo(target, result).normalize(result);
+    }
     /** Freeze this XYZ */
-    freeze() { return Object.freeze(this); }
+    freeze() {
+        return Object.freeze(this);
+    }
     /** access x part of XYZProps (which may be .x or [0]) */
     static x(xyz, defaultValue = 0) {
         if (xyz === undefined)
@@ -328,7 +396,9 @@ exports.XYZ = XYZ;
  */
 class Point3d extends XYZ {
     /** Constructor for Point3d */
-    constructor(x = 0, y = 0, z = 0) { super(x, y, z); }
+    constructor(x = 0, y = 0, z = 0) {
+        super(x, y, z);
+    }
     /**
      * Convert json to Point3d.  Accepted forms are:
      * * `[1,2,3]` --- array of numbers
@@ -336,9 +406,15 @@ class Point3d extends XYZ {
      * *  object with x,y, and (optional) z as numeric properties {x: xValue, y: yValue, z: zValue}
      * @param json json value.
      */
-    static fromJSON(json) { const val = new Point3d(); val.setFromJSON(json); return val; }
+    static fromJSON(json) {
+        const val = new Point3d();
+        val.setFromJSON(json);
+        return val;
+    }
     /** Return a new Point3d with the same coordinates */
-    clone(result) { return Point3d.create(this.x, this.y, this.z, result); }
+    clone(result) {
+        return Point3d.create(this.x, this.y, this.z, result);
+    }
     /** Create a new Point3d with given coordinates
      * @param x x part
      * @param y y part
@@ -384,7 +460,7 @@ class Point3d extends XYZ {
     /**
      * Copy and unweight xyzw.
      * @param xyzData flat array of x,y,z,w,x,y,z,w for multiple points
-     * @param pointIndex index of point to extract.   This index is multiplied by 4 to obtain starting index in the array.
+     * @param pointIndex index of point to extract. This index is multiplied by 4 to obtain starting index in the array.
      * @param result optional result point.
      */
     static createFromPackedXYZW(xyzData, pointIndex, result) {
@@ -409,7 +485,9 @@ class Point3d extends XYZ {
         return result;
     }
     /** Create a new point with 000 xyz */
-    static createZero(result) { return Point3d.create(0, 0, 0, result); }
+    static createZero(result) {
+        return Point3d.create(0, 0, 0, result);
+    }
     /** Return the cross product of the vectors from this to pointA and pointB
      *
      * *  the result is a vector
@@ -427,7 +505,7 @@ class Point3d extends XYZ {
     /** Return the triple product of the vectors from this to pointA, pointB, pointC
      *
      * * This is a scalar (number)
-     * *  This is 6 times the (signed) volume of the tetrahedron on the 4 points.
+     * * This is 6 times the (signed) volume of the tetrahedron on the 4 points.
      */
     tripleProductToPoints(pointA, pointB, pointC) {
         return Geometry_1.Geometry.tripleProduct(pointA.x - this.x, pointA.y - this.y, pointA.z - this.z, pointB.x - this.x, pointB.y - this.y, pointB.z - this.z, pointC.x - this.x, pointC.y - this.y, pointC.z - this.z);
@@ -441,7 +519,10 @@ class Point3d extends XYZ {
     crossProductToPointsXY(pointA, pointB) {
         return Geometry_1.Geometry.crossProductXYXY(pointA.x - this.x, pointA.y - this.y, pointB.x - this.x, pointB.y - this.y);
     }
-    /** Return a point interpolated between this point and the right param. */
+    /**
+     * Return a point interpolated between `this` point and the `other` point.
+     * * fraction specifies where the interpolated point is located on the line passing `this` and `other`.
+     * */
     interpolate(fraction, other, result) {
         if (fraction <= 0.5)
             return Point3d.create(this.x + fraction * (other.x - this.x), this.y + fraction * (other.y - this.y), this.z + fraction * (other.z - this.z), result);
@@ -524,9 +605,7 @@ class Point3d extends XYZ {
             (targetA.y - this.y) * (targetB.y - this.y) +
             (targetA.z - this.z) * (targetB.z - this.z);
     }
-    /** Return the fractional projection of this onto a line between points.
-     *
-     */
+    /** Return the fractional projection of this onto a line between points. */
     fractionOfProjectionToLine(startPoint, endPoint, defaultFraction = 0) {
         const denominator = startPoint.distanceSquared(endPoint);
         if (denominator < Geometry_1.Geometry.smallMetricDistanceSquared)
@@ -539,7 +618,9 @@ exports.Point3d = Point3d;
  * @public
  */
 class Vector3d extends XYZ {
-    constructor(x = 0, y = 0, z = 0) { super(x, y, z); }
+    constructor(x = 0, y = 0, z = 0) {
+        super(x, y, z);
+    }
     /**
      * Return an array of vectors constructed from groups of 3 entries in a Float64Array.
      * Any incomplete group at the tail of the array is ignored.
@@ -554,7 +635,9 @@ class Vector3d extends XYZ {
      * Copy xyz from this instance to a new (or optionally reused) Vector3d
      * @param result optional instance to reuse.
      */
-    clone(result) { return Vector3d.create(this.x, this.y, this.z, result); }
+    clone(result) {
+        return Vector3d.create(this.x, this.y, this.z, result);
+    }
     /**
      * return a Vector3d (new or reused from optional result)
      * @param x x component
@@ -643,7 +726,11 @@ class Vector3d extends XYZ {
      * *  object with x,y, and (optional) z as numeric properties {x: xValue, y: yValue, z: zValue}
      * @param json json value.
      */
-    static fromJSON(json) { const val = new Vector3d(); val.setFromJSON(json); return val; }
+    static fromJSON(json) {
+        const val = new Vector3d();
+        val.setFromJSON(json);
+        return val;
+    }
     /** Copy contents from another Point3d, Point2d, Vector2d, or Vector3d */
     static createFrom(data, result) {
         if (data instanceof Float64Array) {
@@ -719,7 +806,7 @@ class Vector3d extends XYZ {
         return undefined;
     }
     /**
-     * Set (replace) xzz components so they are a vector from point0 to point1
+     * Set (replace) xyz components so they are a vector from point0 to point1
      * @param point0 start point of computed vector
      * @param point1 end point of computed vector.
      */
@@ -729,13 +816,21 @@ class Vector3d extends XYZ {
         this.z = point1.z - point0.z;
     }
     /** Return a vector with 000 xyz parts. */
-    static createZero(result) { return Vector3d.create(0, 0, 0, result); }
+    static createZero(result) {
+        return Vector3d.create(0, 0, 0, result);
+    }
     /** Return a unit X vector optionally multiplied by a scale  */
-    static unitX(scale = 1) { return new Vector3d(scale, 0, 0); }
-    /** Return a unit Y vector  */
-    static unitY(scale = 1) { return new Vector3d(0, scale, 0); }
-    /** Return a unit Z vector  */
-    static unitZ(scale = 1) { return new Vector3d(0, 0, scale); }
+    static unitX(scale = 1) {
+        return new Vector3d(scale, 0, 0);
+    }
+    /** Return a unit Y vector optionally multiplied by a scale  */
+    static unitY(scale = 1) {
+        return new Vector3d(0, scale, 0);
+    }
+    /** Return a unit Z vector optionally multiplied by a scale  */
+    static unitZ(scale = 1) {
+        return new Vector3d(0, 0, scale);
+    }
     /** Divide by denominator, but return undefined if denominator is zero. */
     safeDivideOrNull(denominator, result) {
         if (denominator !== 0.0) {
@@ -744,8 +839,8 @@ class Vector3d extends XYZ {
         return undefined;
     }
     /**
-     * Return a pair object containing (a) property `v` which is a unit vector in the direction
-     * of the input and (b) property mag which is the magnitude (length) of the input (instance) prior to normalization.
+     * Return a pair object containing (a) property `v` which is a unit vector in the direction of the input
+     * and (b) property mag which is the magnitude (length) of the input (instance) prior to normalization.
      * If the instance (input) is a near zero length the `v` property of the output is undefined.
      * @param result optional result.
      */
@@ -758,7 +853,9 @@ class Vector3d extends XYZ {
      * Return a unit vector parallel with this.  Return undefined if this.magnitude is near zero.
      * @param result optional result.
      */
-    normalize(result) { return this.normalizeWithLength(result).v; }
+    normalize(result) {
+        return this.normalizeWithLength(result).v;
+    }
     /**
      * If this vector has nonzero length, divide by the length to change to a unit vector.
      * @returns true if normalization completed.
@@ -772,8 +869,31 @@ class Vector3d extends XYZ {
         this.z *= a;
         return true;
     }
-    /** Return the fractional projection of spaceVector onto this */
+    /** Create a normalized vector from the inputs.
+     * @param result optional result
+     * @returns undefined if and only if normalization fails
+    */
+    static createNormalized(x = 0, y = 0, z = 0, result) {
+        if (undefined === result)
+            result = Vector3d.create(x, y, z);
+        else
+            result.set(x, y, z);
+        if (result.normalizeInPlace())
+            return result;
+        return undefined;
+    }
+    /**
+     * Return fractional projection of target vector onto this
+     * * It's returning the signed projection magnitude divided by the target magnitude. In other words,
+     * it's returning the length of the projection as a fraction of the target magnitude.
+     * @param target the target vector
+     * @param defaultFraction the returned value in case magnitude square of target vector is very small
+     * */
     fractionOfProjectionToVector(target, defaultFraction = 0) {
+        /*
+         * projection length is (this.target)/||target||
+         * but here we return (this.target)/||target||^2
+         */
         const numerator = this.dotProduct(target);
         const denominator = target.magnitudeSquared();
         if (denominator < Geometry_1.Geometry.smallMetricDistanceSquared)
@@ -793,7 +913,7 @@ class Vector3d extends XYZ {
     /** Return a vector same length as this but rotate 90 degrees CCW */
     rotate90CCWXY(result) {
         result = result ? result : new Vector3d();
-        // save x,y to allow aliasing ..
+        // save x,y to allow aliasing ("this" can be passed to the function as "result")
         const xx = this.x;
         const yy = this.y;
         result.x = -yy;
@@ -801,6 +921,17 @@ class Vector3d extends XYZ {
         result.z = this.z;
         return result;
     }
+    /** Return a vector same length as this but rotated 90 degrees clockwise */
+    rotate90CWXY(result) {
+        result = result ? result : new Vector3d();
+        // save x,y to allow aliasing ("this" can be passed to the function as "result")
+        const xx = this.x;
+        const yy = this.y;
+        result.x = yy;
+        result.y = -xx;
+        result.z = this.z;
+        return result;
+    }
     /**
      * Return a vector which is in the xy plane, perpendicular ot the xy part of this vector, and of unit length.
      * * If the xy part is 00, the return is the rotated (but not normalized) xy parts of this vector.
@@ -810,6 +941,7 @@ class Vector3d extends XYZ {
         result = result ? result : new Vector3d();
         const xx = this.x;
         const yy = this.y;
+        // save x,y to allow aliasing ("this" can be passed to the function as "result")
         result.x = -yy;
         result.y = xx;
         result.z = 0.0;
@@ -839,17 +971,23 @@ class Vector3d extends XYZ {
         return result;
     }
     /**
-     * Return a (new or optionally preallocated) vector that is rotated 90 degrees in the plane of this vector and the target vector.
+     * Return a (new or optionally preallocated) vector that is rotated 90 degrees in
+     * the plane of this vector and the target vector.
      * @param target Second vector which defines the plane of rotation.
      * @param result optional preallocated vector for result.
-     * @returns rotated vector, or undefined if the cross product of this and the the target cannot be normalized (i.e. if the target and this are colinear)
+     * @returns rotated vector, or undefined if the cross product of this and
+     *          the the target cannot be normalized (i.e. if the target and this are colinear)
      */
     rotate90Towards(target, result) {
         const normal = this.crossProduct(target).normalize();
         return normal ? normal.crossProduct(this, result) : undefined;
     }
     /** Rotate this vector 90 degrees around an axis vector.
-     * @returns the (new or optionally reused result) rotated vector, or undefined if the axis vector cannot be normalized.
+     * * Note that simple cross is in the plane perpendicular to axis -- it loses the part
+     * of "this" that is along the axis. The unit and scale is supposed to fix that.
+     * This matches with Rodrigues' rotation formula because cos(theta) = 0 and sin(theta) = 1
+     * @returns the (new or optionally reused result) rotated vector, or undefined if the axis
+     * vector cannot be normalized.
      */
     rotate90Around(axis, result) {
         const unitNormal = axis.normalize();
@@ -857,12 +995,17 @@ class Vector3d extends XYZ {
     }
     /**
      * Return a vector computed at fractional position between this vector and vectorB
-     * @param fraction fractional position.  0 is at `this`.  1 is at `vectorB`.  True fractions are "between", negatives are "before this", beyond 1 is "beyond vectorB".
+     * @param fraction fractional position.  0 is at `this`.  1 is at `vectorB`.
+     *                 True fractions are "between", negatives are "before this", beyond 1 is "beyond vectorB".
      * @param vectorB second vector
      * @param result optional preallocated result.
      */
     interpolate(fraction, vectorB, result) {
         result = result ? result : new Vector3d();
+        /*
+         * For best last-bit behavior, if fraction is below 0.5, use this as base point.
+         * If above 0.5, use vectorB as base point.
+         */
         if (fraction <= 0.5) {
             result.x = this.x + fraction * (vectorB.x - this.x);
             result.y = this.y + fraction * (vectorB.y - this.y);
@@ -928,7 +1071,8 @@ class Vector3d extends XYZ {
     static createAdd2Scaled(vectorA, scaleA, vectorB, scaleB, result) {
         return Vector3d.create(vectorA.x * scaleA + vectorB.x * scaleB, vectorA.y * scaleA + vectorB.y * scaleB, vectorA.z * scaleA + vectorB.z * scaleB, result);
     }
-    /** Return the (strongly typed Vector3d) `thisVector3d + vectorA * scalarA + vectorB * scalarB` with all components presented as numbers */
+    /** Return the (strongly typed Vector3d) `thisVector3d + vectorA * scalarA + vectorB * scalarB`
+     * with all components presented as numbers */
     static createAdd2ScaledXYZ(ax, ay, az, scaleA, bx, by, bz, scaleB, result) {
         return Vector3d.create(ax * scaleA + bx * scaleB, ay * scaleA + by * scaleB, az * scaleA + bz * scaleB, result);
     }
@@ -963,7 +1107,8 @@ class Vector3d extends XYZ {
         return this.crossProduct(vectorB, result).normalize(result);
     }
     /**
-     * Compute the cross product of this vector with `vectorB`.   Normalize it, using given xyz as default if length is zero.
+     * Compute the cross product of this vector with `vectorB`.   Normalize it, using given xyz as
+     * default if length is zero.
      * @param vectorB second vector of cross product
      * @param x x value for default result
      * @param y y value for default result
@@ -1007,7 +1152,8 @@ class Vector3d extends XYZ {
         return true;
     }
     /**
-     * Compute cross product with `vectorB`.
+     * Compute cross product with `vectorB`
+     * * cross product vector will have the given length.
      * @param vectorB second vector for cross product.
      * @param productLength desired length of result vector.
      * @param result optional preallocated vector
@@ -1096,17 +1242,18 @@ class Vector3d extends XYZ {
         return this.x * (pointB.x - pointA.x)
             + this.y * (pointB.y - pointA.y);
     }
-    /** Dot product with vector from pointA to pointB, with pointB given as (weighted) x,y,z,w
-     * * pointB is a homogeneous point that has to be unweighted
+    /** Dot product with vector from pointA to pointB, with pointB given as (weighted) wx,wy,wz,w
+     * * We need to unweight pointB (which is a homogeneous point) to be able to participate in the
+     * vector dot product
      * * if the weight is near zero metric, the return is zero.
      */
-    dotProductStartEndXYZW(pointA, x, y, z, w) {
+    dotProductStartEndXYZW(pointA, wx, wy, wz, w) {
         if (Geometry_1.Geometry.isSmallMetricDistance(w))
             return 0.0;
         const dw = 1.0 / w;
-        return this.x * (dw * x - pointA.x)
-            + this.y * (dw * y - pointA.y)
-            + this.z * (dw * z - pointA.z);
+        return this.x * (dw * wx - pointA.x)
+            + this.y * (dw * wy - pointA.y)
+            + this.z * (dw * wz - pointA.z);
     }
     /** Return the dot product of the instance and vectorB, using only the x and y parts. */
     dotProductXY(vectorB) {
@@ -1148,133 +1295,167 @@ class Vector3d extends XYZ {
         return Vector3d.createCrossProduct(this.x, this.y, this.z, x, y, z, result);
     }
     /**
-     * Return the (Strongly typed) angle from this vector to vectorB.
+   * Return the (radians as a simple number, not strongly typed Angle) angle from this vector to vectorB.
+   * * The returned angle is always positive and no larger than 180 degrees (PI radians)
+   * * The returned angle is "in the plane containing the two vectors"
+   * * Use `planarRadiansTo` and `signedRadiansTo` to take have angle measured in specific plane.
+   * @param vectorB target vector.
+   */
+    radiansTo(vectorB) {
+        // ||axb|| = ||a|| ||b|| |sin(t)| and a.b = ||a|| ||b|| cos(t) ==>
+        // ||axb|| / a.b = sin(t)/cos(t) = tan(t) ==> t = arctan(||axb|| / a.b).
+        return Math.atan2(this.crossProductMagnitude(vectorB), this.dotProduct(vectorB));
+    }
+    /**
+     * Return the (strongly typed) angle from this vector to vectorB.
      * * The returned angle is always positive and no larger than 180 degrees (PI radians)
      * * The returned angle is "in the plane containing the two vectors"
-     * * Use `planarAngleTo`, `signedAngleTo`, `angleToXY` to take have angle measured in specific plane.
-     * @param vectorB target vector of rotation.
+     * * Use `planarAngleTo` and `signedAngleTo` to take have angle measured in specific plane.
+     * @param vectorB target vector.
      */
     angleTo(vectorB) {
-        return Angle_1.Angle.createAtan2(this.crossProductMagnitude(vectorB), this.dotProduct(vectorB));
+        return Angle_1.Angle.createRadians(this.radiansTo(vectorB));
     }
     /**
-     * Return the (Strongly typed) angle from this vector to the plane perpendicular to planeNormal.
+     * Return the (strongly typed) angle from this vector to the plane perpendicular to planeNormal.
      * * The returned vector is signed
-     * * The returned vector is (as degrees) always less than or equal to 90 degrees.
-     * @param planeNormal a normal vector to the plane
+     * * The returned vector is (as degrees) always between -90 and 90 degrees.
+     * * The function returns "PI/2 - angleTo(planeNormal)"
+     * @param planeNormal a normal vector to the plane.
      */
-    angleFromPerpendicular(vectorB) {
-        return Angle_1.Angle.createAtan2(this.dotProduct(vectorB), this.crossProductMagnitude(vectorB));
+    angleFromPerpendicular(planeNormal) {
+        return Angle_1.Angle.createAtan2(this.dotProduct(planeNormal), this.crossProductMagnitude(planeNormal));
     }
     /**
-     * Return the (Strongly typed) angle from this vector to vectorB,using only the xy parts.
-     * * The returned angle can range from negative 180 degrees (negative PI radians) to positive 180 degrees (positive PI radians), not closed on the negative side.
-     * * Use `planarAngleTo`, `signedAngleTo`, `angleToXY` to take have angle measured in other planes.
-     * @param vectorB target vector of rotation.
+     * Return the (Strongly typed) angle from this vector to vectorB, using only the xy parts.
+     * * The returned angle can range from negative 180 degrees (negative PI radians) to positive 180
+     * * degrees (positive PI radians), not closed on the negative side.
+     * * Use `planarAngleTo` and `signedAngleTo` to take have angle measured in other planes.
+     * @param vectorB target vector.
      */
     angleToXY(vectorB) {
         return Angle_1.Angle.createAtan2(this.crossProductXY(vectorB), this.dotProductXY(vectorB));
     }
     /**
-     * Return the (radians as a simple number, not strongly typed Angle) radians from this vector to vectorB.
+   * Return the (simple number of radians, not Strongly typed Angle) angle from this vector to vectorB, measured
+   * in the plane containing both, with vectorW indicating which side to view to control sign of the angle.
+   * * The returned angle can range from negative PI to positive PI (not closed on negative side)
+   * * The returned angle is "in the plane containing the two vectors"
+   * * The returned angle has the same sign as vectorW dot product (thisVector cross vectorB)
+   * * vectorW does not have to be perpendicular to the plane.
+   * * Use planarRadiansTo to measure the angle between vectors that are projected to another plane.
+   * @param vectorB target vector.
+   * @param vectorW distinguishes between the sides of the plane.
+   */
+    signedRadiansTo(vectorB, vectorW) {
+        const p = this.crossProduct(vectorB);
+        const theta = Math.atan2(p.magnitude(), this.dotProduct(vectorB));
+        if (vectorW.dotProduct(p) < 0.0)
+            return -theta;
+        else
+            return theta;
+    }
+    /**
+   * Return the (strongly typed Angle) angle from this vector to vectorB, measured in the plane containing both,
+   * with vectorW indicating which side to view to control sign of the angle.
+   * * The returned angle can range from negative 180 degrees (negative PI radians) to positive 180 degrees
+   * * (positive PI radians), not closed on the negative side.
+   * * The returned angle is "in the plane containing the two vectors"
+   * * `vectorW` distinguishes between the sides of the plane, but does not have to be perpendicular.
+   * * The returned angle has the same sign as vectorW dot product (thisVector cross vectorB)
+   * * Use planarRadiansTo to measure the angle between vectors that are projected to another plane.
+   * @param vectorB target vector.
+   * @param vectorW distinguishes between the sides of the plane.
+   */
+    signedAngleTo(vectorB, vectorW) {
+        return Angle_1.Angle.createRadians(this.signedRadiansTo(vectorB, vectorW));
+    }
+    /**
+     * Return the radians (as a simple number, not strongly typed Angle) from this vector to vectorB,
+     * measured between their projections to the plane with the given normal.
      * * The returned angle can be positive or negative, with magnitude no larger than PI radians
-     * * Use signedRadiansTo` to take have angle measured in other planes.
-     * @param vectorB target vector of rotation.
+     * @param vectorB target vector
+     * @param planeNormal the normal vector to the plane.
      */
-    planarRadiansTo(vector, planeNormal) {
+    planarRadiansTo(vectorB, planeNormal) {
         const square = planeNormal.dotProduct(planeNormal);
         if (square === 0.0)
             return 0.0;
         const factor = 1.0 / square;
-        const projection0 = this.plusScaled(planeNormal, -this.dotProduct(planeNormal) * factor);
-        const projection1 = vector.plusScaled(planeNormal, -vector.dotProduct(planeNormal) * factor);
-        return projection0.signedRadiansTo(projection1, planeNormal);
+        /*
+         * projection of vector 'v' on normal 'n' is given by vProj = [dot(v,n)/||n||^2]*n
+         * and projection of 'v' on the plane is given by 'v - vProj'
+        */
+        const thisProj = this.plusScaled(planeNormal, -this.dotProduct(planeNormal) * factor);
+        const vectorBProj = vectorB.plusScaled(planeNormal, -vectorB.dotProduct(planeNormal) * factor);
+        return thisProj.signedRadiansTo(vectorBProj, planeNormal);
     }
     /**
-     * Return the (as strongly typed Angle) Angle from this vector to vectorB.
+     * Return the angle (as strongly typed Angle) from this vector to vectorB,
+     * measured between their projections to the plane with the given normal.
      * * The returned angle can range from negative PI to positive PI (not closed on negative side)
-     * * Use signedRadiansTo` to take have angle measured in other planes.
-     * @param vectorB target vector of rotation.
+     * @param vectorB target vector.
+     * @param planeNormal the normal vector to the plane.
      */
-    planarAngleTo(vector, planeNormal) {
-        return Angle_1.Angle.createRadians(this.planarRadiansTo(vector, planeNormal));
+    planarAngleTo(vectorB, planeNormal) {
+        return Angle_1.Angle.createRadians(this.planarRadiansTo(vectorB, planeNormal));
     }
-    /**
-     * Return the (simple number of radians, not Strongly typed Angle) angle from this vector to vectorB, measured in the plane containing both, with vectorW indicating which side to view to control sign of the angle.
-     * * The returned angle can range from negative PI to positive PI (not closed on negative side)
-     * * The returned angle is "in the plane containing the two vectors"
-     * * `vectorW` distinguishes between the sides of the plane, but does not have to be perpendicular.
-     * * The returned angle has the same sign as vectorW dot product (thisVector cross vectorB)
-     * @param vectorB target vector of rotation.
-     */
-    signedRadiansTo(vector1, vectorW) {
-        const p = this.crossProduct(vector1);
-        const theta = Math.atan2(p.magnitude(), this.dotProduct(vector1));
-        if (vectorW.dotProduct(p) < 0.0)
-            return -theta;
-        else
-            return theta;
-    }
-    /**
-     * Return the (strongly typed Angle) angle from this vector to vectorB, measured in the plane containing both, with vectorW indicating which side to view to control sign of the angle.
-     * * The returned angle can range from negative 180 degrees (negative PI radians) to positive 180 degrees (positive PI radians), not closed on the negative side.
-     * * The returned angle is "in the plane containing the two vectors"
-     * * `vectorW` distinguishes between the sides of the plane, but does not have to be perpendicular.
-     * * The returned angle has the same sign as vectorW dot product (thisVector cross vectorB)
-     * @param vectorB target vector of rotation.
-     */
-    signedAngleTo(vector1, vectorW) { return Angle_1.Angle.createRadians(this.signedRadiansTo(vector1, vectorW)); }
-    /** Return the smallest (strongly typed) angle from the (bidirectional) line containing `this` to the (bidirectional) line containing `vectorB` */
-    smallerUnorientedAngleTo(vectorB) {
-        return Angle_1.Angle.createRadians(this.smallerUnorientedRadiansTo(vectorB));
-    }
-    /** Return the smallest angle (in radians) from the (bidirectional) line containing `this` to the (bidirectional) line containing `vectorB` */
+    /** Return the smallest angle (in radians) from the (bidirectional) line containing `this`
+   * to the (bidirectional) line containing `vectorB` */
     smallerUnorientedRadiansTo(vectorB) {
         const c = this.dotProduct(vectorB);
         const s = this.crossProductMagnitude(vectorB);
         return Math.atan2(Math.abs(s), Math.abs(c));
     }
-    /*
-      signedAngleTo(vectorB: Vector3d, upVector: Vector3d): Angle { }
-      // sectors
-      isInSmallerSector(vectorA: Vector3d, vectorB: Vector3d): boolean { }
-      isInCCWSector(vectorA: Vector3d, vectorB: Vector3d, upVector: Vector3d): boolean { }
-      */
+    /** Return the smallest (strongly typed) angle from the (bidirectional) line containing `this`
+     * to the (bidirectional) line containing `vectorB` */
+    smallerUnorientedAngleTo(vectorB) {
+        return Angle_1.Angle.createRadians(this.smallerUnorientedRadiansTo(vectorB));
+    }
     /**
      * Test if this vector is parallel to other.
+     * * The input tolerances in `options`, if given, are considered to be squared for efficiency's sake,
+     * so if you have a distance or angle tolerance t, you should pass in t * t.
      * @param other second vector in comparison
-     * @param oppositeIsParallel if the vectors are on the same line but in opposite directions, return this value.
+     * @param oppositeIsParallel whether to consider diametrically opposed vectors as parallel
      * @param returnValueIfAnInputIsZeroLength if either vector is near zero length, return this value.
+     * @param options optional radian and distance tolerances.
      */
-    isParallelTo(other, oppositeIsParallel = false, returnValueIfAnInputIsZeroLength = false) {
+    isParallelTo(other, oppositeIsParallel = false, returnValueIfAnInputIsZeroLength = false, options) {
+        var _a, _b;
+        const radianSquaredTol = (_a = options === null || options === void 0 ? void 0 : options.radianSquaredTol) !== null && _a !== void 0 ? _a : Geometry_1.Geometry.smallAngleRadiansSquared;
+        const distanceSquaredTol = (_b = options === null || options === void 0 ? void 0 : options.distanceSquaredTol) !== null && _b !== void 0 ? _b : Geometry_1.Geometry.smallMetricDistanceSquared;
         const a2 = this.magnitudeSquared();
         const b2 = other.magnitudeSquared();
-        // we know both are 0 or positive -- no need for
-        if (a2 < Geometry_1.Geometry.smallMetricDistanceSquared || b2 < Geometry_1.Geometry.smallMetricDistanceSquared)
+        if (a2 < distanceSquaredTol || b2 < distanceSquaredTol)
             return returnValueIfAnInputIsZeroLength;
         const dot = this.dotProduct(other);
         if (dot < 0.0 && !oppositeIsParallel)
-            return returnValueIfAnInputIsZeroLength;
+            return false;
         const cross2 = this.crossProductMagnitudeSquared(other);
         /* a2,b2,cross2 are squared lengths of respective vectors */
         /* cross2 = sin^2(theta) * a2 * b2 */
         /* For small theta, sin^2(theta)~~theta^2 */
-        return cross2 <= Geometry_1.Geometry.smallAngleRadiansSquared * a2 * b2;
+        return cross2 <= radianSquaredTol * a2 * b2;
     }
     /**
      * Test if this vector is perpendicular to other.
+     * * The input tolerances in `options`, if given, are considered to be squared for efficiency's sake,
+     * so if you have a distance or angle tolerance t, you should pass in t * t.
      * @param other second vector in comparison
      * @param returnValueIfAnInputIsZeroLength if either vector is near zero length, return this value.
+     * @param options optional radian and distance tolerances.
      */
-    isPerpendicularTo(other, returnValueIfAnInputIsZeroLength = false) {
+    isPerpendicularTo(other, returnValueIfAnInputIsZeroLength = false, options) {
+        var _a, _b;
+        const radianSquaredTol = (_a = options === null || options === void 0 ? void 0 : options.radianSquaredTol) !== null && _a !== void 0 ? _a : Geometry_1.Geometry.smallAngleRadiansSquared;
+        const distanceSquaredTol = (_b = options === null || options === void 0 ? void 0 : options.distanceSquaredTol) !== null && _b !== void 0 ? _b : Geometry_1.Geometry.smallMetricDistanceSquared;
         const aa = this.magnitudeSquared();
-        if (aa < Geometry_1.Geometry.smallMetricDistanceSquared)
-            return returnValueIfAnInputIsZeroLength;
         const bb = other.magnitudeSquared();
-        if (bb < Geometry_1.Geometry.smallMetricDistanceSquared)
+        if (aa < distanceSquaredTol || bb < distanceSquaredTol)
             return returnValueIfAnInputIsZeroLength;
         const ab = this.dotProduct(other);
-        return ab * ab <= Geometry_1.Geometry.smallAngleRadiansSquared * aa * bb;
+        return ab * ab <= radianSquaredTol * aa * bb;
     }
 }
 exports.Vector3d = Vector3d;