@khanacademy/kmath 0.2.0 → 0.3.1

package/dist/geometry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A collection of geomtry-related utility functions
+ */
+import { type Coord } from "@khanacademy/perseus-core";
+type Line = [Coord, Coord];
+export type Range = [number, number];
+export type SineCoefficient = [
+    number,
+    number,
+    number,
+    number
+];
+export declare function sign(val: number): 0 | 1 | -1;
+export declare function ccw(a: Coord, b: Coord, c: Coord): number;
+export declare function collinear(a: Coord, b: Coord, c: Coord): boolean;
+export declare function intersects(ab: Line, cd: Line): boolean;
+export declare function polygonSidesIntersect(vertices: Coord[]): boolean;
+export declare function vector(a: any, b: any): number[];
+export declare function reverseVector(vector: Coord): Coord;
+export declare function clockwise(points: Coord[]): boolean;
+export declare function magnitude(v: ReadonlyArray<Coord>): number;
+export declare function angleMeasures(coords: ReadonlyArray<Coord>): ReadonlyArray<number>;
+export declare function similar(coords1: ReadonlyArray<Coord>, coords2: ReadonlyArray<Coord>, tolerance: number): boolean;
+export declare function lawOfCosines(a: number, b: number, c: number): number;
+export declare function canonicalSineCoefficients([amplitude, angularFrequency, phase, verticalOffset,]: [any, any, any, any]): any[];
+export declare function rotate<T>(array: ReadonlyArray<T>, n?: number): ReadonlyArray<T>;
+export declare function getLineEquation(first: Coord, second: Coord): string;
+export declare function getLineIntersection(firstPoints: ReadonlyArray<Coord>, secondPoints: ReadonlyArray<Coord>): string;
+export {};

package/dist/index.d.ts

@@ -4,4 +4,10 @@ export * as vector from "./vector";
 export * as point from "./point";
 export * as line from "./line";
 export * as ray from "./ray";
+export * as angles from "./angles";
+export * as geometry from "./geometry";
+export * as coefficients from "./coefficients";
 export { default as KhanMath, sum } from "./math";
+export type { Range, SineCoefficient } from "./geometry";
+export type { NamedSineCoefficient, QuadraticCoefficient } from "./coefficients";
+export type * from "./types";

package/dist/index.js

@@ -12,7 +12,7 @@ var ___default = /*#__PURE__*/_interopDefaultLegacy(_);
 
 // This file is processed by a Rollup plugin (replace) to inject the production
 const libName = "@khanacademy/kmath";
-const libVersion = "0.2.0";
+const libVersion = "0.3.1";
 perseusCore.addLibraryVersionToPerseusDebug(libName, libVersion);
 
 /**
@@ -41,7 +41,7 @@ function equal$4(x, y, tolerance) {
   }
   return Math.abs(x - y) < tolerance;
 }
-function sign(x, tolerance) /* Should be: 0 | 1 | -1 */{
+function sign$1(x, tolerance) /* Should be: 0 | 1 | -1 */{
   return equal$4(x, 0, tolerance) ? 0 : Math.abs(x) / x;
 }
 function isInteger(num, tolerance) {
@@ -110,7 +110,7 @@ var number = /*#__PURE__*/Object.freeze({
     EPSILON: EPSILON,
     is: is$2,
     equal: equal$4,
-    sign: sign,
+    sign: sign$1,
     isInteger: isInteger,
     round: round$2,
     roundTo: roundTo$2,
@@ -220,7 +220,7 @@ function codirectional(v1, v2, tolerance) {
   v2 = normalize(v2);
   return equal$3(v1, v2, tolerance);
 }
-function collinear(v1, v2, tolerance) {
+function collinear$1(v1, v2, tolerance) {
   return codirectional(v1, v2, tolerance) || codirectional(v1, negate(v2), tolerance);
 }
 
@@ -311,7 +311,7 @@ function ceilTo$1(vec, increment) {
   return vec.map((elem, i) => ceilTo$2(elem, increment[i] || increment));
 }
 
-var vector = /*#__PURE__*/Object.freeze({
+var vector$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
     zip: zip,
     map: map,
@@ -325,7 +325,7 @@ var vector = /*#__PURE__*/Object.freeze({
     scale: scale,
     equal: equal$3,
     codirectional: codirectional,
-    collinear: collinear,
+    collinear: collinear$1,
     polarRadFromCart: polarRadFromCart$1,
     polarDegFromCart: polarDegFromCart$1,
     cartFromPolarRad: cartFromPolarRad$1,
@@ -471,7 +471,7 @@ function equal$1(line1, line2, tolerance) {
   // Compare the directions of the lines
   const v1 = subtract(line1[1], line1[0]);
   const v2 = subtract(line2[1], line2[0]);
-  if (!collinear(v1, v2, tolerance)) {
+  if (!collinear$1(v1, v2, tolerance)) {
     return false;
   }
   // If the start point is the same for the two lines, then they are the same
@@ -481,7 +481,7 @@ function equal$1(line1, line2, tolerance) {
   // Make sure that the direction to get from line1 to
   // line2 is the same as the direction of the lines
   const line1ToLine2Vector = subtract(line2[0], line1[0]);
-  return collinear(v1, line1ToLine2Vector, tolerance);
+  return collinear$1(v1, line1ToLine2Vector, tolerance);
 }
 
 var line = /*#__PURE__*/Object.freeze({
@@ -512,6 +512,377 @@ var ray = /*#__PURE__*/Object.freeze({
     equal: equal
 });
 
+/**
+ * A collection of geomtry-related utility functions
+ */
+
+// This should really be a readonly tuple of [number, number]
+
+// Given a number, return whether it is positive (1), negative (-1), or zero (0)
+function sign(val) {
+  if (perseusCore.approximateEqual(val, 0)) {
+    return 0;
+  }
+  return val > 0 ? 1 : -1;
+}
+
+// Determine whether three points are collinear (0), for a clockwise turn (negative),
+// or counterclockwise turn (positive)
+function ccw(a, b, c) {
+  return (b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]);
+}
+function collinear(a, b, c) {
+  return perseusCore.approximateEqual(ccw(a, b, c), 0);
+}
+
+// Given rect bounding points A and B, whether point C is inside the rect
+function pointInRect(a, b, c) {
+  return c[0] <= Math.max(a[0], b[0]) && c[0] >= Math.min(a[0], b[0]) && c[1] <= Math.max(a[1], b[1]) && c[1] >= Math.min(a[1], b[1]);
+}
+
+// Whether line segment AB intersects line segment CD
+// http://www.geeksforgeeks.org/check-if-two-given-line-segments-intersect/
+function intersects(ab, cd) {
+  const triplets = [[ab[0], ab[1], cd[0]], [ab[0], ab[1], cd[1]], [cd[0], cd[1], ab[0]], [cd[0], cd[1], ab[1]]];
+  const orientations = ___default["default"].map(triplets, function (triplet) {
+    return sign(ccw(...triplet));
+  });
+  if (orientations[0] !== orientations[1] && orientations[2] !== orientations[3]) {
+    return true;
+  }
+  for (let i = 0; i < 4; i++) {
+    if (orientations[i] === 0 && pointInRect(...triplets[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Whether any two sides of a polygon intersect each other
+function polygonSidesIntersect(vertices) {
+  for (let i = 0; i < vertices.length; i++) {
+    for (let k = i + 1; k < vertices.length; k++) {
+      // If any two vertices are the same point, sides overlap
+      if (kmath.point.equal(vertices[i], vertices[k])) {
+        return true;
+      }
+
+      // Find the other end of the sides starting at vertices i and k
+      const iNext = (i + 1) % vertices.length;
+      const kNext = (k + 1) % vertices.length;
+
+      // Adjacent sides always intersect (at the vertex); skip those
+      if (iNext === k || kNext === i) {
+        continue;
+      }
+      const side1 = [vertices[i], vertices[iNext]];
+      const side2 = [vertices[k], vertices[kNext]];
+      if (intersects(side1, side2)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function vector(a, b) {
+  return ___default["default"].map(___default["default"].zip(a, b), function (pair) {
+    return pair[0] - pair[1];
+  });
+}
+function reverseVector(vector) {
+  return [-vector[0], -vector[1]];
+}
+
+// Returns whether connecting the given sequence of `points` forms a clockwise
+// path (assuming a closed loop, where the last point connects back to the
+// first).
+function clockwise(points) {
+  const segments = ___default["default"].zip(points, points.slice(1).concat(points.slice(0, 1)));
+  const areas = ___default["default"].map(segments, function (segment) {
+    const p1 = segment[0];
+    const p2 = segment[1];
+    return (p2[0] - p1[0]) * (p2[1] + p1[1]);
+  });
+  return kmath.sum(areas) > 0;
+}
+function magnitude(v) {
+  return Math.sqrt(___default["default"].reduce(v, function (memo, el) {
+    // @ts-expect-error - TS2345 - Argument of type 'Coord' is not assignable to parameter of type 'number'.
+    return memo + Math.pow(el, 2);
+  }, 0));
+}
+function dotProduct(a, b) {
+  return ___default["default"].reduce(___default["default"].zip(a, b), function (memo, pair) {
+    return memo + pair[0] * pair[1];
+  }, 0);
+}
+function sideLengths(coords) {
+  const segments = ___default["default"].zip(coords, rotate(coords));
+  return segments.map(function (segment) {
+    // @ts-expect-error - TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'readonly Coord[]'. | TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
+    return magnitude(vector(...segment));
+  });
+}
+
+// Based on http://math.stackexchange.com/a/151149
+function angleMeasures(coords) {
+  const triplets = ___default["default"].zip(rotate(coords, -1), coords, rotate(coords, 1));
+  const offsets = ___default["default"].map(triplets, function (triplet) {
+    const p = vector(triplet[1], triplet[0]);
+    const q = vector(triplet[2], triplet[1]);
+    // @ts-expect-error - TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'Coord'. | TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'readonly Coord[]'. | TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'readonly Coord[]'.
+    const raw = Math.acos(dotProduct(p, q) / (magnitude(p) * magnitude(q)));
+    // @ts-expect-error - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
+    return sign(ccw(...triplet)) > 0 ? raw : -raw;
+  });
+  const sum = ___default["default"].reduce(offsets, function (memo, arg) {
+    return memo + arg;
+  }, 0);
+  return ___default["default"].map(offsets, function (offset) {
+    return sum > 0 ? Math.PI - offset : Math.PI + offset;
+  });
+}
+
+// Whether two polygons are similar (or if specified, congruent)
+function similar(coords1, coords2, tolerance) {
+  if (coords1.length !== coords2.length) {
+    return false;
+  }
+  const n = coords1.length;
+  const angles1 = angleMeasures(coords1);
+  const angles2 = angleMeasures(coords2);
+  const sides1 = sideLengths(coords1);
+  const sides2 = sideLengths(coords2);
+  for (let i = 0; i < 2 * n; i++) {
+    let angles = angles2.slice();
+    let sides = sides2.slice();
+
+    // Reverse angles and sides to allow matching reflected polygons
+    if (i >= n) {
+      angles.reverse();
+      sides.reverse();
+      // Since sides are calculated from two coordinates,
+      // simply reversing results in an off by one error
+      // @ts-expect-error - TS4104 - The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
+      sides = rotate(sides, 1);
+    }
+
+    // @ts-expect-error - TS4104 - The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
+    angles = rotate(angles, i);
+    // @ts-expect-error - TS4104 - The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
+    sides = rotate(sides, i);
+    if (perseusCore.approximateDeepEqual(angles1, angles)) {
+      const sidePairs = ___default["default"].zip(sides1, sides);
+      const factors = ___default["default"].map(sidePairs, function (pair) {
+        return pair[0] / pair[1];
+      });
+      const same = ___default["default"].all(factors, function (factor) {
+        return perseusCore.approximateEqual(factors[0], factor);
+      });
+      const congruentEnough = ___default["default"].all(sidePairs, function (pair) {
+        return kmath.number.equal(pair[0], pair[1], tolerance);
+      });
+      if (same && congruentEnough) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// Given triangle with sides ABC return angle opposite side C in degrees
+function lawOfCosines(a, b, c) {
+  return Math.acos((a * a + b * b - c * c) / (2 * a * b)) * 180 / Math.PI;
+}
+function canonicalSineCoefficients(_ref) {
+  let [amplitude, angularFrequency, phase, verticalOffset] = _ref;
+  // For a curve of the form f(x) = a * Sin(b * x - c) + d,
+  // this function ensures that a, b > 0, and c is its
+  // smallest possible positive value.
+
+  // Guarantee a > 0
+  if (amplitude < 0) {
+    amplitude *= -1;
+    angularFrequency *= -1;
+    phase *= -1;
+  }
+  const period = 2 * Math.PI;
+  // Guarantee b > 0
+  if (angularFrequency < 0) {
+    angularFrequency *= -1;
+    phase *= -1;
+    phase += period / 2;
+  }
+
+  // Guarantee c is smallest possible positive value
+  while (phase > 0) {
+    phase -= period;
+  }
+  while (phase < 0) {
+    phase += period;
+  }
+  return [amplitude, angularFrequency, phase, verticalOffset];
+}
+
+// e.g. rotate([1, 2, 3]) -> [2, 3, 1]
+function rotate(array, n) {
+  n = typeof n === "undefined" ? 1 : n % array.length;
+  return array.slice(n).concat(array.slice(0, n));
+}
+function getLineEquation(first, second) {
+  if (perseusCore.approximateEqual(first[0], second[0])) {
+    return "x = " + first[0].toFixed(3);
+  }
+  const m = (second[1] - first[1]) / (second[0] - first[0]);
+  const b = first[1] - m * first[0];
+  return "y = " + m.toFixed(3) + "x + " + b.toFixed(3);
+}
+
+// Stolen from the wikipedia article
+// http://en.wikipedia.org/wiki/Line-line_intersection
+function getLineIntersection(
+// TODO(LP-10725): update these to be 2-tuples
+firstPoints, secondPoints) {
+  const x1 = firstPoints[0][0];
+  const y1 = firstPoints[0][1];
+  const x2 = firstPoints[1][0];
+  const y2 = firstPoints[1][1];
+  const x3 = secondPoints[0][0];
+  const y3 = secondPoints[0][1];
+  const x4 = secondPoints[1][0];
+  const y4 = secondPoints[1][1];
+  const determinant = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4);
+  if (Math.abs(determinant) < 1e-9) {
+    return "Lines are parallel";
+  }
+  const x = ((x1 * y2 - y1 * x2) * (x3 - x4) - (x1 - x2) * (x3 * y4 - y3 * x4)) / determinant;
+  const y = ((x1 * y2 - y1 * x2) * (y3 - y4) - (y1 - y2) * (x3 * y4 - y3 * x4)) / determinant;
+  return "Intersection: (" + x.toFixed(3) + ", " + y.toFixed(3) + ")";
+}
+
+var geometry = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    sign: sign,
+    ccw: ccw,
+    collinear: collinear,
+    intersects: intersects,
+    polygonSidesIntersect: polygonSidesIntersect,
+    vector: vector,
+    reverseVector: reverseVector,
+    clockwise: clockwise,
+    magnitude: magnitude,
+    angleMeasures: angleMeasures,
+    similar: similar,
+    lawOfCosines: lawOfCosines,
+    canonicalSineCoefficients: canonicalSineCoefficients,
+    rotate: rotate,
+    getLineEquation: getLineEquation,
+    getLineIntersection: getLineIntersection
+});
+
+// This file contains helper functions for working with angles.
+function convertDegreesToRadians(degrees) {
+  return degrees / 180 * Math.PI;
+}
+
+// Returns a value between -180 and 180, inclusive. The angle is measured
+// between the positive x-axis and the given vector.
+function calculateAngleInDegrees(_ref) {
+  let [x, y] = _ref;
+  return Math.atan2(y, x) * 180 / Math.PI;
+}
+
+// Converts polar coordinates to cartesian. The th(eta) parameter is in degrees.
+function polar(r, th) {
+  if (typeof r === "number") {
+    r = [r, r];
+  }
+  th = th * Math.PI / 180;
+  return [r[0] * Math.cos(th), r[1] * Math.sin(th)];
+}
+// This function calculates the angle between two points and an optional vertex.
+// If the vertex is not provided, the angle is measured between the two points.
+// This does not account for reflex angles or clockwise position.
+const getAngleFromVertex = (point, vertex) => {
+  const x = point[0] - vertex[0];
+  const y = point[1] - vertex[1];
+  if (!x && !y) {
+    return 0;
+  }
+  return (180 + Math.atan2(-y, -x) * 180 / Math.PI + 360) % 360;
+};
+
+// This function calculates the clockwise angle between three points,
+// and is used to generate the labels and equation strings of the
+// current angle for the interactive graph.
+const getClockwiseAngle = function (coords) {
+  let allowReflexAngles = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  const coordsCopy = [...coords];
+  // The coords are saved as [point1, vertex, point2] in the interactive graph
+  const areClockwise = clockwise([coordsCopy[0], coordsCopy[2], coordsCopy[1]]);
+
+  // We may need to reverse the coordinates if we allow
+  // reflex angles and the points are not in clockwise order.
+  const shouldReverseCoords = !areClockwise || allowReflexAngles;
+
+  // Reverse the coordinates accordingly to ensure the angle is calculated correctly
+  const clockwiseCoords = shouldReverseCoords ? coordsCopy.reverse() : coordsCopy;
+
+  // Calculate the angles between the two points and get the difference
+  // between the two angles to get the clockwise angle.
+  const startAngle = getAngleFromVertex(clockwiseCoords[0], clockwiseCoords[1]);
+  const endAngle = getAngleFromVertex(clockwiseCoords[2], clockwiseCoords[1]);
+  const angle = (startAngle + 360 - endAngle) % 360;
+  return angle;
+};
+
+var angles = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    convertDegreesToRadians: convertDegreesToRadians,
+    calculateAngleInDegrees: calculateAngleInDegrees,
+    polar: polar,
+    getAngleFromVertex: getAngleFromVertex,
+    getClockwiseAngle: getClockwiseAngle
+});
+
+// TODO: there's another, very similar getSinusoidCoefficients function
+// they should probably be merged
+function getSinusoidCoefficients(coords) {
+  // It's assumed that p1 is the root and p2 is the first peak
+  const p1 = coords[0];
+  const p2 = coords[1];
+
+  // Resulting coefficients are canonical for this sine curve
+  const amplitude = p2[1] - p1[1];
+  const angularFrequency = Math.PI / (2 * (p2[0] - p1[0]));
+  const phase = p1[0] * angularFrequency;
+  const verticalOffset = p1[1];
+  return [amplitude, angularFrequency, phase, verticalOffset];
+}
+// TODO: there's another, very similar getQuadraticCoefficients function
+// they should probably be merged
+function getQuadraticCoefficients(coords) {
+  const p1 = coords[0];
+  const p2 = coords[1];
+  const p3 = coords[2];
+  const denom = (p1[0] - p2[0]) * (p1[0] - p3[0]) * (p2[0] - p3[0]);
+  if (denom === 0) {
+    // Many of the callers assume that the return value is always defined.
+    // @ts-expect-error - TS2322 - Type 'undefined' is not assignable to type 'QuadraticCoefficient'.
+    return;
+  }
+  const a = (p3[0] * (p2[1] - p1[1]) + p2[0] * (p1[1] - p3[1]) + p1[0] * (p3[1] - p2[1])) / denom;
+  const b = (p3[0] * p3[0] * (p1[1] - p2[1]) + p2[0] * p2[0] * (p3[1] - p1[1]) + p1[0] * p1[0] * (p2[1] - p3[1])) / denom;
+  const c = (p2[0] * p3[0] * (p2[0] - p3[0]) * p1[1] + p3[0] * p1[0] * (p3[0] - p1[0]) * p2[1] + p1[0] * p2[0] * (p1[0] - p2[0]) * p3[1]) / denom;
+  return [a, b, c];
+}
+
+var coefficients = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    getSinusoidCoefficients: getSinusoidCoefficients,
+    getQuadraticCoefficients: getQuadraticCoefficients
+});
+
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
 var jquery = {exports: {}};
@@ -10548,11 +10919,14 @@ function add(a, b) {
 }
 
 exports.KhanMath = KhanMath;
+exports.angles = angles;
+exports.coefficients = coefficients;
+exports.geometry = geometry;
 exports.libVersion = libVersion;
 exports.line = line;
 exports.number = number;
 exports.point = point;
 exports.ray = ray;
 exports.sum = sum;
-exports.vector = vector;
+exports.vector = vector$1;
 //# sourceMappingURL=index.js.map