@itwin/core-geometry 4.0.0-dev.55 → 4.0.0-dev.58

package/lib/esm/geometry3d/Point3dVector3d.js

@@ -10,7 +10,8 @@ import { Angle } from "./Angle";
 import { XYAndZ } from "./XYZProps";
 // cspell:words CWXY CCWXY arctan Rodrigues
 /**
- *  * `XYZ` is a minimal object containing x,y,z and operations that are meaningful without change in both point and vector.
+ * * `XYZ` is a minimal object containing x,y,z and operations that are meaningful without change in both
+ * point and vector.
  *  * `XYZ` is not instantiable.
  *  * The derived (instantiable) classes are
  *    * `Point3d`
@@ -54,7 +55,8 @@ export class XYZ {
     static isXYAndZ(arg) {
         return this.isXAndY(arg) && this.hasZ(arg);
     }
-    /** Test if arg is any of:
+    /**
+     * Test if arg is any of:
      * * XAndY
      * * XYAndZ
      * * [number,number]
@@ -63,7 +65,8 @@ export class XYZ {
     static isAnyImmediatePointType(arg) {
         return Point3d.isXAndY(arg) || Geometry.isNumberArray(arg, 2);
     }
-    /** Look for (in order) an x coordinate present as:
+    /**
+     * Look for (in order) an x coordinate present as:
      * * arg.x
      * * arg[0]
      */
@@ -74,7 +77,8 @@ export class XYZ {
             return arg[0];
         return defaultValue;
     }
-    /** Look for (in order) an x coordinate present as:
+    /**
+     * Look for (in order) an x coordinate present as:
      * * arg.y
      * * arg[1]
      */
@@ -85,7 +89,8 @@ export class XYZ {
             return arg[1];
         return defaultValue;
     }
-    /** Look for (in order) an x coordinate present as:
+    /**
+     * Look for (in order) an x coordinate present as:
      * * arg.z
      * * arg[2]
      */
@@ -148,7 +153,8 @@ export class XYZ {
             this.setZero();
         }
     }
-    /** Returns true if this and other have equal x,y,z parts within Geometry.smallMetricDistance.
+    /**
+     * Returns true if this and other have equal x,y,z parts within Geometry.smallMetricDistance.
      * @param other The other XYAndZ to compare
      * @param tol The tolerance for the comparison. If undefined, use [[Geometry.smallMetricDistance]]
      */
@@ -229,9 +235,7 @@ export class XYZ {
     maxDiff(other) {
         return Math.max(Math.abs(this.x - other.x), Math.abs(this.y - other.y), Math.abs(this.z - other.z));
     }
-    /**
-     * Return the x,y, z component corresponding to 0,1,2.
-     */
+    /** Return the x,y, z component corresponding to 0,1,2 */
     at(index) {
         if (index < 0.5)
             return this.x;
@@ -239,9 +243,7 @@ export class XYZ {
             return this.z;
         return this.y;
     }
-    /**
-     * Set value at index 0 or 1 or 2.
-     */
+    /** Set value at index 0 or 1 or 2 */
     setAt(index, value) {
         if (index < 0.5)
             this.x = value;
@@ -295,27 +297,27 @@ export class XYZ {
     magnitudeSquaredXY() {
         return this.x * this.x + this.y * this.y;
     }
-    /** exact equality test. */
+    /** Exact equality test. */
     isExactEqual(other) {
         return this.x === other.x && this.y === other.y && this.z === other.z;
     }
-    /** equality test with Geometry.smallMetricDistance tolerance */
+    /** Equality test with Geometry.smallMetricDistance tolerance */
     isAlmostEqualMetric(other) {
         return this.maxDiff(other) <= Geometry.smallMetricDistance;
     }
-    /** add x,y,z from other in place. */
+    /** Add x,y,z from other in place. */
     addInPlace(other) {
         this.x += other.x;
         this.y += other.y;
         this.z += other.z;
     }
-    /** add x,y,z from other in place. */
+    /** Add x,y,z from other in place. */
     subtractInPlace(other) {
         this.x -= other.x;
         this.y -= other.y;
         this.z -= other.z;
     }
-    /** add (in place) the scaled x,y,z of other */
+    /** Add (in place) the scaled x,y,z of other */
     addScaledInPlace(other, scale) {
         this.x += scale * other.x;
         this.y += scale * other.y;
@@ -327,7 +329,7 @@ export class XYZ {
         this.y *= scale;
         this.z *= scale;
     }
-    /** add to x, y, z parts */
+    /** Add to x, y, z parts */
     addXYZInPlace(dx = 0.0, dy = 0.0, dz = 0.0) {
         this.x += dx;
         this.y += dy;
@@ -345,7 +347,8 @@ export class XYZ {
     scaledVectorTo(other, scale, result) {
         return Vector3d.create(scale * (other.x - this.x), scale * (other.y - this.y), scale * (other.z - this.z), result);
     }
-    /** Return a unit vector from this vector to other. Return a 000 vector if the input is too small to normalize.
+    /**
+     * Return a unit vector from this vector to other. Return a 000 vector if the input is too small to normalize.
      * @param other target of created vector.
      * @param result optional result vector.
      */
@@ -356,7 +359,7 @@ export class XYZ {
     freeze() {
         return Object.freeze(this);
     }
-    /** access x part of XYZProps (which may be .x or [0]) */
+    /** Access x part of XYZProps (which may be .x or [0]) */
     static x(xyz, defaultValue = 0) {
         if (xyz === undefined)
             return defaultValue;
@@ -366,7 +369,7 @@ export class XYZ {
             return xyz.x;
         return defaultValue;
     }
-    /** access x part of XYZProps (which may be .x or [0]) */
+    /** Access x part of XYZProps (which may be .x or [0]) */
     static y(xyz, defaultValue = 0) {
         if (xyz === undefined)
             return defaultValue;
@@ -376,7 +379,7 @@ export class XYZ {
             return xyz.y;
         return defaultValue;
     }
-    /** access x part of XYZProps (which may be .x or [0]) */
+    /** Access x part of XYZProps (which may be .x or [0]) */
     static z(xyz, defaultValue = 0) {
         if (xyz === undefined)
             return defaultValue;
@@ -411,7 +414,8 @@ export class Point3d extends XYZ {
     clone(result) {
         return Point3d.create(this.x, this.y, this.z, result);
     }
-    /** Create a new Point3d with given coordinates
+    /**
+     * Create a new Point3d with given coordinates
      * @param x x part
      * @param y y part
      * @param z z part
@@ -484,8 +488,8 @@ export class Point3d extends XYZ {
     static createZero(result) {
         return Point3d.create(0, 0, 0, result);
     }
-    /** Return the cross product of the vectors from this to pointA and pointB
-     *
+    /**
+     * Return the cross product of the vectors from this to pointA and pointB
      * *  the result is a vector
      * *  the result is perpendicular to both vectors, with right hand orientation
      * *  the magnitude of the vector is twice the area of the triangle.
@@ -493,21 +497,20 @@ export class Point3d extends XYZ {
     crossProductToPoints(pointA, pointB, result) {
         return Vector3d.createCrossProduct(pointA.x - this.x, pointA.y - this.y, pointA.z - this.z, pointB.x - this.x, pointB.y - this.y, pointB.z - this.z, result);
     }
-    /** Return the magnitude of the cross product of the vectors from this to pointA and pointB
-     */
+    /** Return the magnitude of the cross product of the vectors from this to pointA and pointB */
     crossProductToPointsMagnitude(pointA, pointB) {
         return Geometry.crossProductMagnitude(pointA.x - this.x, pointA.y - this.y, pointA.z - this.z, pointB.x - this.x, pointB.y - this.y, pointB.z - this.z);
     }
-    /** Return the triple product of the vectors from this to pointA, pointB, pointC
-     *
+    /**
+     * 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.
      */
     tripleProductToPoints(pointA, pointB, pointC) {
         return 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);
     }
-    /** Return the cross product of the vectors from this to pointA and pointB
-     *
+    /**
+     * Return the cross product of the vectors from this to pointA and pointB
      * *  the result is a scalar
      * *  the magnitude of the vector is twice the signed area of the triangle.
      * *  this is positive for counter-clockwise order of the points, negative for clockwise.
@@ -517,8 +520,8 @@ export class Point3d extends XYZ {
     }
     /**
      * 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`.
-     * */
+     * * 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);
@@ -571,7 +574,8 @@ export class Point3d extends XYZ {
     static createScale(source, scale, result) {
         return Point3d.create(source.x * scale, source.y * scale, source.z * scale, result);
     }
-    /** create a point that is a linear combination (weighted sum) of 2 input points.
+    /**
+     * Create a point that is a linear combination (weighted sum) of 2 input points.
      * @param pointA first input point
      * @param scaleA scale factor for pointA
      * @param pointB second input point
@@ -609,7 +613,8 @@ export class Point3d extends XYZ {
         return startPoint.dotVectorsToTargets(endPoint, this) / denominator;
     }
 }
-/** 3D vector with `x`,`y`,`z` as properties
+/**
+ * 3D vector with `x`,`y`,`z` as properties
  * @public
  */
 export class Vector3d extends XYZ {
@@ -634,7 +639,7 @@ export class Vector3d extends XYZ {
         return Vector3d.create(this.x, this.y, this.z, result);
     }
     /**
-     * return a Vector3d (new or reused from optional result)
+     * Return a Vector3d (new or reused from optional result)
      * @param x x component
      * @param y y component
      * @param z z component
@@ -687,7 +692,6 @@ export class Vector3d extends XYZ {
     }
     /**
      * Return the cross product of the vectors from origin to pointA and pointB.
-     *
      * * the result is a vector
      * * the result is perpendicular to both vectors, with right hand orientation
      * * the magnitude of the vector is twice the area of the triangle.
@@ -864,7 +868,8 @@ export class Vector3d extends XYZ {
         this.z *= a;
         return true;
     }
-    /** Create a normalized vector from the inputs.
+    /**
+     * Create a normalized vector from the inputs.
      * @param result optional result
      * @returns undefined if and only if normalization fails
     */
@@ -898,7 +903,8 @@ export class Vector3d extends XYZ {
             return defaultFraction;
         return numerator / denominator;
     }
-    /** Return a new vector with components negated from the calling instance.
+    /**
+     * Return a new vector with components negated from the calling instance.
      * @param result optional result vector.
      */
     negate(result) {
@@ -980,7 +986,8 @@ export class Vector3d extends XYZ {
         const normal = this.crossProduct(target).normalize();
         return normal ? normal.crossProduct(this, result) : undefined;
     }
-    /** Rotate this vector 90 degrees around an axis vector.
+    /**
+     * Rotate this vector 90 degrees around an axis vector.
      * * 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
@@ -1069,8 +1076,10 @@ export 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);
     }
@@ -1097,7 +1106,8 @@ export class Vector3d extends XYZ {
             return undefined;
         return this.scale(length / mag, result);
     }
-    /** Compute the cross product of this vector with `vectorB`.   Immediately pass it to `normalize`.
+    /**
+     * Compute the cross product of this vector with `vectorB`.   Immediately pass it to `normalize`.
      * @param vectorB second vector for cross product.
      * @returns see `Vector3d` method `normalize()` for error condition.
      */
@@ -1184,7 +1194,8 @@ export class Vector3d extends XYZ {
     crossProductMagnitude(vectorB) {
         return Math.sqrt(this.crossProductMagnitudeSquared(vectorB));
     }
-    /** Return the dot product of this vector with vectorB.
+    /**
+     * Return the dot product of this vector with vectorB.
      * @param vectorB second vector of cross product
      * @returns the dot product of this instance with vectorB
      */
@@ -1240,7 +1251,8 @@ export 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) wx,wy,wz,w
+    /**
+     * 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.
@@ -1284,7 +1296,7 @@ export class Vector3d extends XYZ {
         return Vector3d.createCrossProduct(this.x, this.y, this.z, vectorB.x, vectorB.y, vectorB.z, result);
     }
     /**
-     * return cross product of `this` with the vector `(x, y, z)`
+     * Return cross product of `this` with the vector `(x, y, z)`
      * @param x x component of second vector
      * @param y y component of second vector
      * @param z z component of second vector
@@ -1294,12 +1306,12 @@ export class Vector3d extends XYZ {
         return Vector3d.createCrossProduct(this.x, this.y, this.z, x, y, z, result);
     }
     /**
-   * Return the angle in radians (not as strongly typed Angle) from this vector to vectorB.
-   * * The returned angle is between 0 and `Math.PI`.
-   * * The returned angle is measured in the plane containing the two vectors.
-   * * Use `planarRadiansTo` and `signedRadiansTo` to return an angle measured in a specific plane.
-   * @param vectorB target vector.
-   */
+     * Return the angle in radians (not as strongly typed Angle) from this vector to vectorB.
+     * * The returned angle is between 0 and `Math.PI`.
+     * * The returned angle is measured in the plane containing the two vectors.
+     * * Use `planarRadiansTo` and `signedRadiansTo` to return an angle measured in a 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).
@@ -1335,16 +1347,16 @@ export class Vector3d extends XYZ {
         return Angle.createAtan2(this.crossProductXY(vectorB), this.dotProductXY(vectorB));
     }
     /**
-   * Return the angle in radians (not as strongly-typed Angle) from this vector to vectorB, measured
-   * in their containing plane whose normal lies in the same half-space as vectorW.
-   * * The returned angle is between `-Math.PI` and `Math.PI`.
-   * * If the cross product of this vector and vectorB lies on the same side of the plane as vectorW,
-   * this function returns `radiansTo(vectorB)`; otherwise, it returns `-radiansTo(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 determines the side of the plane in which the returned angle is measured
-   */
+     * Return the angle in radians (not as strongly-typed Angle) from this vector to vectorB, measured
+     * in their containing plane whose normal lies in the same half-space as vectorW.
+     * * The returned angle is between `-Math.PI` and `Math.PI`.
+     * * If the cross product of this vector and vectorB lies on the same side of the plane as vectorW,
+     * this function returns `radiansTo(vectorB)`; otherwise, it returns `-radiansTo(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 determines the side of the plane in which the returned angle is measured
+     */
     signedRadiansTo(vectorB, vectorW) {
         const p = this.crossProduct(vectorB);
         const theta = Math.atan2(p.magnitude(), this.dotProduct(vectorB));
@@ -1353,7 +1365,8 @@ export class Vector3d extends XYZ {
         else
             return theta;
     }
-    /** Return the (strongly-typed) angle from this vector to vectorB, measured
+    /**
+     * Return the (strongly-typed) angle from this vector to vectorB, measured
      * in their containing plane whose normal lies in the same half-space as vectorW.
      * * The returned angle is between -180 and 180 degrees.
      * * If the cross product of this vector and vectorB lies on the same side of the plane as vectorW,
@@ -1396,15 +1409,19 @@ export class Vector3d extends XYZ {
     planarAngleTo(vectorB, planeNormal) {
         return Angle.createRadians(this.planarRadiansTo(vectorB, planeNormal));
     }
-    /** 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));
     }
-    /** Return the smallest (strongly typed) angle from the (bidirectional) line containing `this`
-     * to the (bidirectional) line containing `vectorB` */
+    /**
+     * Return the smallest (strongly typed) angle from the (bidirectional) line containing `this`
+     * to the (bidirectional) line containing `vectorB`
+     */
     smallerUnorientedAngleTo(vectorB) {
         return Angle.createRadians(this.smallerUnorientedRadiansTo(vectorB));
     }