@itwin/core-geometry 3.5.0-dev.45 → 3.5.0-dev.49

package/lib/cjs/geometry3d/Point3dVector3d.js

@@ -518,7 +518,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);
@@ -865,8 +868,18 @@ class Vector3d extends XYZ {
         this.z *= a;
         return true;
     }
-    /** 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 = 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)
@@ -1109,7 +1122,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
@@ -1255,7 +1269,7 @@ class Vector3d extends XYZ {
    * * 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 of rotation.
+   * @param vectorB target vector.
    */
     radiansTo(vectorB) {
         // ||axb|| = ||a|| ||b|| |sin(t)| and a.b = ||a|| ||b|| cos(t) ==>
@@ -1267,7 +1281,7 @@ class Vector3d extends XYZ {
      * * 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` and `signedAngleTo` to take have angle measured in specific plane.
-     * @param vectorB target vector of rotation.
+     * @param vectorB target vector.
      */
     angleTo(vectorB) {
         return Angle_1.Angle.createRadians(this.radiansTo(vectorB));
@@ -1287,7 +1301,7 @@ class Vector3d extends XYZ {
      * * 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 of rotation.
+     * @param vectorB target vector.
      */
     angleToXY(vectorB) {
         return Angle_1.Angle.createAtan2(this.crossProductXY(vectorB), this.dotProductXY(vectorB));
@@ -1299,7 +1313,8 @@ class Vector3d extends XYZ {
    * * 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.
-   * @param vectorB target vector of rotation.
+   * * 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) {
@@ -1318,34 +1333,39 @@ class Vector3d extends XYZ {
    * * 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.
+   * * 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) radians from this vector to vectorB.
+     * 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 planeNormal a normal vector to the plane.
+     * @param vectorB target vector
+     * @param planeNormal the normal vector to the plane.
      */
     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 = vectorB.plusScaled(planeNormal, -vectorB.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 planeNormal a normal vector to the plane.
+     * @param vectorB target vector.
+     * @param planeNormal the normal vector to the plane.
      */
     planarAngleTo(vectorB, planeNormal) {
         return Angle_1.Angle.createRadians(this.planarRadiansTo(vectorB, planeNormal));