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

package/lib/cjs/geometry3d/Point2dVector2d.js

@@ -20,11 +20,20 @@ const Angle_1 = require("./Angle");
  * @public
  */
 class XY {
-    constructor(x = 0, y = 0) { this.x = x; this.y = y; }
+    constructor(x = 0, y = 0) {
+        this.x = x;
+        this.y = y;
+    }
     /** Set both x and y. */
-    set(x = 0, y = 0) { this.x = x; this.y = y; }
+    set(x = 0, y = 0) {
+        this.x = x;
+        this.y = y;
+    }
     /** Set both x and y to zero */
-    setZero() { this.x = 0; this.y = 0; }
+    setZero() {
+        this.x = 0;
+        this.y = 0;
+    }
     /** Set both x and y from other. */
     setFrom(other) {
         if (other) {
@@ -37,16 +46,30 @@ class XY {
         }
     }
     /** Freeze this instance so it is read-only */
-    freeze() { return Object.freeze(this); }
+    freeze() {
+        return Object.freeze(this);
+    }
     /** Returns true if this and other have equal x,y parts within Geometry.smallMetricDistance. */
-    isAlmostEqual(other, tol) { return Geometry_1.Geometry.isSameCoordinate(this.x, other.x, tol) && Geometry_1.Geometry.isSameCoordinate(this.y, other.y, tol); }
+    isAlmostEqual(other, tol) {
+        return Geometry_1.Geometry.isSameCoordinate(this.x, other.x, tol) && Geometry_1.Geometry.isSameCoordinate(this.y, other.y, tol);
+    }
     /** Returns true if this and other have equal x,y parts within Geometry.smallMetricDistance. */
-    isAlmostEqualXY(x, y, tol) { return Geometry_1.Geometry.isSameCoordinate(this.x, x, tol) && Geometry_1.Geometry.isSameCoordinate(this.y, y, tol); }
+    isAlmostEqualXY(x, y, tol) {
+        return Geometry_1.Geometry.isSameCoordinate(this.x, x, tol) && Geometry_1.Geometry.isSameCoordinate(this.y, y, tol);
+    }
     /** return a json array  `[x,y]`   */
-    toJSON() { return [this.x, this.y]; }
+    toJSON() {
+        return [this.x, this.y];
+    }
     /** return a json object `{x: 1, y:2}`  */
-    toJSONXY() { return { x: this.x, y: this.y }; }
-    /** Set x and y from a JSON source such as `[1,2]` or `{x:1, y:2}` */
+    toJSONXY() {
+        return { x: this.x, y: this.y };
+    }
+    /**
+     * Set x and y from a JSON input such as `[1,2]` or `{x:1, y:2}`
+     * * If no JSON input is provided, 0 would be used as default values for x and y.
+     * @param json the JSON input
+     * */
     setFromJSON(json) {
         if (Array.isArray(json)) {
             this.set(json[0] || 0, json[1] || 0);
@@ -62,39 +85,76 @@ class XY {
     distance(other) {
         const xDist = other.x - this.x;
         const yDist = other.y - this.y;
-        return (Math.sqrt(xDist * xDist + yDist * yDist));
+        return Math.sqrt(xDist * xDist + yDist * yDist);
     }
     /** Return squared distance from this point to other */
     distanceSquared(other) {
         const xDist = other.x - this.x;
         const yDist = other.y - this.y;
-        return (xDist * xDist + yDist * yDist);
+        return xDist * xDist + yDist * yDist;
     }
     /** Return the largest absolute distance between corresponding components */
     maxDiff(other) {
         return Math.max(Math.abs(this.x - other.x), Math.abs(this.y - other.y));
     }
+    /**
+     * Return the x,y component corresponding to 0,1.
+     */
+    at(index) {
+        if (index < 0.5)
+            return this.x;
+        return this.y;
+    }
+    /**
+     * Set value at index 0 or 1.
+     */
+    setAt(index, value) {
+        if (index < 0.5)
+            this.x = value;
+        else
+            this.y = value;
+    }
+    /** Return the index (0,1) of the x,y component with largest absolute value */
+    indexOfMaxAbs() {
+        let index = 0;
+        const a = Math.abs(this.x);
+        const b = Math.abs(this.y);
+        if (b > a) {
+            index = 1;
+        }
+        return index;
+    }
     /** returns true if the x,y components are both small by metric metric tolerance */
     get isAlmostZero() {
         return Geometry_1.Geometry.isSmallMetricDistance(this.x) && Geometry_1.Geometry.isSmallMetricDistance(this.y);
     }
     /** Return the largest absolute value of any component */
-    maxAbs() { return Math.max(Math.abs(this.x), Math.abs(this.y)); }
+    maxAbs() {
+        return Math.max(Math.abs(this.x), Math.abs(this.y));
+    }
     /** Return the magnitude of the vector */
-    magnitude() { return Math.sqrt(this.x * this.x + this.y * this.y); }
+    magnitude() {
+        return Math.sqrt(this.x * this.x + this.y * this.y);
+    }
     /** Return the squared magnitude of the vector.  */
-    magnitudeSquared() { return this.x * this.x + this.y * this.y; }
+    magnitudeSquared() {
+        return this.x * this.x + this.y * this.y;
+    }
     /** returns true if the x,y components are exactly equal. */
-    isExactEqual(other) { return this.x === other.x && this.y === other.y; }
+    isExactEqual(other) {
+        return this.x === other.x && this.y === other.y;
+    }
     /** returns true if x,y match `other` within metric tolerance */
-    isAlmostEqualMetric(other) { return this.maxDiff(other) <= Geometry_1.Geometry.smallMetricDistance; }
+    isAlmostEqualMetric(other, distanceTol = Geometry_1.Geometry.smallMetricDistance) {
+        return this.maxDiff(other) <= distanceTol;
+    }
     /** Return a (full length) vector from this point to other */
     vectorTo(other, result) {
         return Vector2d.create(other.x - this.x, other.y - this.y, result);
     }
     /** Return a unit vector from this point to other */
-    unitVectorTo(target, result) {
-        return this.vectorTo(target, result).normalize(result);
+    unitVectorTo(other, result) {
+        return this.vectorTo(other, result).normalize(result);
     }
     /** cross product of vectors from origin to targets */
     static crossProductToPoints(origin, targetA, targetB) {
@@ -107,9 +167,13 @@ exports.XY = XY;
  */
 class Point2d extends XY {
     /** Constructor for Point2d */
-    constructor(x = 0, y = 0) { super(x, y); }
+    constructor(x = 0, y = 0) {
+        super(x, y);
+    }
     /** return a new Point2d with x,y coordinates from this. */
-    clone(result) { return Point2d.create(this.x, this.y, result); }
+    clone(result) {
+        return Point2d.create(this.x, this.y, result);
+    }
     /**
      * Return a point (newly created unless result provided) with given x,y coordinates
      * @param x x coordinate
@@ -124,8 +188,16 @@ class Point2d extends XY {
         }
         return new Point2d(x, y);
     }
-    /** Convert JSON `[1,2]` or `{x:1, y:2}` to a Point2d instance */
-    static fromJSON(json) { const val = new Point2d(); val.setFromJSON(json); return val; }
+    /**
+     * Set x and y from a JSON input such as `[1,2]` or `{x:1, y:2}`
+     * * If no JSON input is provided, 0 would be used as default values for x and y.
+     * @param json the JSON input
+     * */
+    static fromJSON(json) {
+        const val = new Point2d();
+        val.setFromJSON(json);
+        return val;
+    }
     /** Create (or optionally reuse) a Point2d from another object with fields x and y */
     static createFrom(xy, result) {
         if (xy)
@@ -133,19 +205,22 @@ class Point2d extends XY {
         return Point2d.create(0, 0, result);
     }
     /** Create a Point2d with both coordinates zero. */
-    static createZero(result) { return Point2d.create(0, 0, result); }
-    /** Starting at this point, move along vector by tangentFraction of the vector length, and to the left by leftFraction of
-     * the perpendicular vector length.
+    static createZero(result) {
+        return Point2d.create(0, 0, result);
+    }
+    /** Starting at this point, move along vector by tangentFraction of the vector length, and then
+     * to the left by leftFraction of the perpendicular vector length.
      * @param tangentFraction distance to move along the vector, as a fraction of vector
      * @param leftFraction distance to move perpendicular to the vector, as a fraction of the rotated vector
+     * @param vector the other vector
      */
     addForwardLeft(tangentFraction, leftFraction, vector) {
         const dx = vector.x;
         const dy = vector.y;
         return Point2d.create(this.x + tangentFraction * dx - leftFraction * dy, this.y + tangentFraction * dy + leftFraction * dx);
     }
-    /** Interpolate at tangentFraction between this instance and point.   Move by leftFraction along the xy perpendicular
-     * of the vector between the points.
+    /** Interpolate at tangentFraction between this instance and point, and then Move by leftFraction
+     * along the xy perpendicular of the vector between the points.
      */
     forwardLeftInterpolate(tangentFraction, leftFraction, point) {
         const dx = point.x - this.x;
@@ -193,10 +268,13 @@ class Point2d extends XY {
      * @param targetB target of second vector
      */
     dotVectorsToTargets(targetA, targetB) {
-        return (targetA.x - this.x) * (targetB.x - this.x) +
-            (targetA.y - this.y) * (targetB.y - this.y);
+        return (targetA.x - this.x) * (targetB.x - this.x) + (targetA.y - this.y) * (targetB.y - this.y);
     }
-    /** Returns the (scalar) cross product of two points/vectors, computed from origin to target1 and target2 */
+    /**
+     * Returns the (scalar) cross product of vector from this to targetA and vector from this to targetB
+     * @param target1 target of first vector
+     * @param target2 target of second vector
+     */
     crossProductToPoints(target1, target2) {
         const x1 = target1.x - this.x;
         const y1 = target1.y - this.y;
@@ -204,16 +282,18 @@ class Point2d extends XY {
         const y2 = target2.y - this.y;
         return x1 * y2 - y1 * x2;
     }
-    /** Return the fractional coordinate of the projection of this instance x,y onto the line from startPoint to endPoint.
+    /** Return the fractional coordinate of the projection of this instance x,y onto the
+     * line from startPoint to endPoint.
      * @param startPoint start point of line
      * @param endPoint end point of line
      * @param defaultFraction fraction to return if startPoint and endPoint are equal.
      */
-    fractionOfProjectionToLine(startPoint, endPoint, defaultFraction) {
+    fractionOfProjectionToLine(startPoint, endPoint, defaultFraction = 0) {
         const denominator = startPoint.distanceSquared(endPoint);
         if (denominator < Geometry_1.Geometry.smallMetricDistanceSquared)
-            return defaultFraction ? defaultFraction : 0;
-        return startPoint.dotVectorsToTargets(endPoint, this) / denominator;
+            return defaultFraction;
+        const numerator = startPoint.dotVectorsToTargets(endPoint, this);
+        return numerator / denominator;
     }
 }
 exports.Point2d = Point2d;
@@ -221,9 +301,13 @@ exports.Point2d = Point2d;
  * @public
  */
 class Vector2d extends XY {
-    constructor(x = 0, y = 0) { super(x, y); }
+    constructor(x = 0, y = 0) {
+        super(x, y);
+    }
     /** Return a new Vector2d with the same x,y */
-    clone(result) { return Vector2d.create(this.x, this.y, result); }
+    clone(result) {
+        return Vector2d.create(this.x, this.y, result);
+    }
     /** Return a new Vector2d with given x and y */
     static create(x = 0, y = 0, result) {
         if (result) {
@@ -233,12 +317,24 @@ class Vector2d extends XY {
         }
         return new Vector2d(x, y);
     }
-    /** Return a (new) Vector2d with components 1,0 */
-    static unitX(scale = 1) { return new Vector2d(scale, 0); }
-    /** Return a (new) Vector2d with components 0,1 */
-    static unitY(scale = 1) { return new Vector2d(0, scale); }
+    /**
+     * Return a (new) Vector2d with components scale,0
+     * If scale is not given default value 1 is used.
+     */
+    static unitX(scale = 1) {
+        return new Vector2d(scale, 0);
+    }
+    /**
+     * Return a (new) Vector2d with components 0,scale
+     * If scale is not given default value 1 is used.
+     */
+    static unitY(scale = 1) {
+        return new Vector2d(0, scale);
+    }
     /** Return a Vector2d with components 0,0 */
-    static createZero(result) { return Vector2d.create(0, 0, result); }
+    static createZero(result) {
+        return Vector2d.create(0, 0, result);
+    }
     /** copy contents from another Point3d, Point2d, Vector2d, or Vector3d, or leading entries of Float64Array */
     static createFrom(data, result) {
         if (data instanceof Float64Array) {
@@ -250,8 +346,16 @@ class Vector2d extends XY {
         }
         return Vector2d.create(data.x, data.y, result);
     }
-    /** Return a new Vector2d from json structured as `[1,2]` or `{x:1,y:2}` */
-    static fromJSON(json) { const val = new Vector2d(); val.setFromJSON(json); return val; }
+    /**
+     * Set x and y from a JSON input such as `[1,2]` or `{x:1, y:2}`
+     * * If no JSON input is provided, 0 would be used as default values for x and y.
+     * @param json the JSON input
+     * */
+    static fromJSON(json) {
+        const val = new Vector2d();
+        val.setFromJSON(json);
+        return val;
+    }
     /** Return a new Vector2d from polar coordinates for radius and Angle from x axis */
     static createPolar(r, theta) {
         return Vector2d.create(r * theta.cos(), r * theta.sin());
@@ -262,6 +366,7 @@ class Vector2d extends XY {
     }
     /**
      * Return a vector that bisects the angle between two normals and extends to the intersection of two offset lines
+     * * returns `undefined` if `unitPerpA = -unitPerpB` (i.e., are opposite)
      * @param unitPerpA unit perpendicular to incoming direction
      * @param unitPerpB  unit perpendicular to outgoing direction
      * @param offset offset distance
@@ -270,12 +375,13 @@ class Vector2d extends XY {
         let bisector = unitPerpA.plus(unitPerpB);
         bisector = bisector.normalize();
         if (bisector) {
-            const c = offset * bisector.dotProduct(unitPerpA);
+            const c = bisector.dotProduct(unitPerpA);
+            bisector.scale(offset, bisector);
             return bisector.safeDivideOrNull(c);
         }
         return undefined;
     }
-    /** Return a (new or optionally reused) vector which is `this` divided by denominator
+    /** Return a (new or optionally reused) vector which is `this` divided by `denominator`
      * * return undefined if denominator is zero.
      */
     safeDivideOrNull(denominator, result) {
@@ -290,12 +396,22 @@ class Vector2d extends XY {
         result = result ? result : new Vector2d();
         return this.safeDivideOrNull(mag, result);
     }
-    /** return the fractional projection of spaceVector onto this */
+    /**
+     * 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) {
-        const numerator = this.dotProduct(target);
+        /*
+         * projection length is (this.target)/||target||
+         * but here we return (this.target)/||target||^2
+         */
         const denominator = target.magnitudeSquared();
         if (denominator < Geometry_1.Geometry.smallMetricDistanceSquared)
             return defaultFraction ? defaultFraction : 0;
+        const numerator = this.dotProduct(target);
         return numerator / denominator;
     }
     /** Return a new vector with components negated from this instance. */
@@ -308,7 +424,7 @@ class Vector2d extends XY {
     /** Return a vector same length as this but rotated 90 degrees counter clockwise */
     rotate90CCWXY(result) {
         result = result ? result : new Vector2d();
-        // 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;
@@ -318,7 +434,7 @@ class Vector2d extends XY {
     /** Return a vector same length as this but rotated 90 degrees clockwise */
     rotate90CWXY(result) {
         result = result ? result : new Vector2d();
-        // 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;
@@ -330,6 +446,7 @@ class Vector2d extends XY {
         result = result ? result : new Vector2d();
         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;
         const d2 = xx * xx + yy * yy;
@@ -344,6 +461,7 @@ class Vector2d extends XY {
     rotateXY(angle, result) {
         const s = angle.sin();
         const c = angle.cos();
+        // save x,y to allow aliasing ("this" can be passed to the function as "result")
         const xx = this.x;
         const yy = this.y;
         result = result ? result : new Vector2d();
@@ -351,18 +469,26 @@ class Vector2d extends XY {
         result.y = xx * s + yy * c;
         return result;
     }
-    /** return the interpolation {this + fraction * (right - this)} */
-    interpolate(fraction, right, result) {
+    /** 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 vectorB second vector
+    * @param result optional preallocated result.
+    */
+    interpolate(fraction, vectorB, result) {
         result = result ? result : new Vector2d();
-        /* For best last-bit behavior, if fraction is below 0.5, use this as base point.   If above 0.5, use right as base point.   */
+        /*
+         * 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 * (right.x - this.x);
-            result.y = this.y + fraction * (right.y - this.y);
+            result.x = this.x + fraction * (vectorB.x - this.x);
+            result.y = this.y + fraction * (vectorB.y - this.y);
         }
         else {
             const t = fraction - 1.0;
-            result.x = right.x + t * (right.x - this.x);
-            result.y = right.y + t * (right.y - this.y);
+            result.x = vectorB.x + t * (vectorB.x - this.x);
+            result.y = vectorB.y + t * (vectorB.y - this.y);
         }
         return result;
     }
@@ -416,36 +542,47 @@ class Vector2d extends XY {
         return this.scale(length / mag, result);
     }
     /** return the dot product of this with vectorB */
-    dotProduct(vectorB) { return this.x * vectorB.x + this.y * vectorB.y; }
+    dotProduct(vectorB) {
+        return this.x * vectorB.x + this.y * vectorB.y;
+    }
     /** dot product with vector from pointA to pointB */
     dotProductStartEnd(pointA, pointB) {
-        return this.x * (pointB.x - pointA.x)
-            + this.y * (pointB.y - pointA.y);
+        return this.x * (pointB.x - pointA.x) + this.y * (pointB.y - pointA.y);
     }
     /** vector cross product {this CROSS vectorB} */
-    crossProduct(vectorB) { return this.x * vectorB.y - this.y * vectorB.x; }
-    /** return the (signed) angle from this to vectorB.   This is positive if the shortest turn is counterclockwise, negative if clockwise. */
+    crossProduct(vectorB) {
+        return this.x * vectorB.y - this.y * vectorB.x;
+    }
+    /**
+     * return the radians (as a simple number, not strongly typed Angle) signed angle from this to vectorB.
+     * This is positive if the shortest turn is counterclockwise, negative if clockwise.
+     */
+    radiansTo(vectorB) {
+        return Math.atan2(this.crossProduct(vectorB), this.dotProduct(vectorB));
+    }
+    /**
+     * return the (strongly typed) signed angle from this to vectorB.
+     * This is positive if the shortest turn is counterclockwise, negative if clockwise.
+     */
     angleTo(vectorB) {
-        return Angle_1.Angle.createAtan2(this.crossProduct(vectorB), this.dotProduct(vectorB));
-    }
-    /*  smallerUnorientedAngleTo(vectorB: Vector2d): Angle { }
-      signedAngleTo(vectorB: Vector2d, upVector: Vector2d): Angle { }
-      planarAngleTo(vectorB: Vector2d, planeNormal: Vector2d): Angle { }
-      // sectors
-      isInSmallerSector(vectorA: Vector2d, vectorB: Vector2d): boolean { }
-      isInCCWSector(vectorA: Vector2d, vectorB: Vector2d, upVector: Vector2d): boolean { }
-      */
+        return Angle_1.Angle.createRadians(this.radiansTo(vectorB));
+    }
     /**
-     * Test if `this` and `other` area parallel, with angle tolerance `Geometry.smallAngleRadiansSquared`.
+     * 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 for comparison.
-     * @param oppositeIsParallel if true, treat vectors 180 opposite as parallel.  If false, treat those as non-parallel.
+     * @param oppositeIsParallel whether to consider diametrically opposed vectors as parallel.
+     * @param options optional radian and distance tolerances.
      */
-    isParallelTo(other, oppositeIsParallel = 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)
-            return false;
+        if (a2 < distanceSquaredTol || b2 < distanceSquaredTol)
+            return returnValueIfAnInputIsZeroLength;
         const dot = this.dotProduct(other);
         if (dot < 0.0 && !oppositeIsParallel)
             return false;
@@ -453,14 +590,26 @@ class Vector2d extends XY {
         /* a2,b2,cross2 are squared lengths of respective vectors */
         /* cross2 = sin^2(theta) * a2 * b2 */
         /* For small theta, sin^2(theta)~~theta^2 */
-        return cross * cross <= Geometry_1.Geometry.smallAngleRadiansSquared * a2 * b2;
+        return cross * cross <= radianSquaredTol * a2 * b2;
     }
     /**
-     * Returns `true` if `this` vector is perpendicular to `other`.
-     * @param other second vector.
+     * 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) {
-        return Angle_1.Angle.isPerpendicularDotSet(this.magnitudeSquared(), other.magnitudeSquared(), this.dotProduct(other));
+    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();
+        const bb = other.magnitudeSquared();
+        if (aa < distanceSquaredTol || bb < distanceSquaredTol)
+            return returnValueIfAnInputIsZeroLength;
+        const ab = this.dotProduct(other);
+        return ab * ab <= radianSquaredTol * aa * bb;
     }
 }
 exports.Vector2d = Vector2d;