@khanacademy/kmath 0.2.0 → 0.3.0

package/dist/angles.d.ts

@@ -0,0 +1,6 @@
+import type { Coord } from "@khanacademy/perseus-core";
+export declare function convertDegreesToRadians(degrees: number): number;
+export declare function calculateAngleInDegrees([x, y]: Coord): number;
+export declare function polar(r: number | Coord, th: number): Coord;
+export declare const getAngleFromVertex: (point: Coord, vertex: Coord) => number;
+export declare const getClockwiseAngle: (coords: [Coord, Coord, Coord], allowReflexAngles?: boolean) => number;

package/dist/coefficients.d.ts

@@ -0,0 +1,11 @@
+import type { SineCoefficient } from "./geometry";
+import type { Coord } from "@khanacademy/perseus-core";
+export type NamedSineCoefficient = {
+    amplitude: number;
+    angularFrequency: number;
+    phase: number;
+    verticalOffset: number;
+};
+export declare function getSinusoidCoefficients(coords: ReadonlyArray<Coord>): SineCoefficient;
+export type QuadraticCoefficient = [number, number, number];
+export declare function getQuadraticCoefficients(coords: ReadonlyArray<Coord>): QuadraticCoefficient;

package/dist/es/index.js

@@ -1,10 +1,10 @@
-import { addLibraryVersionToPerseusDebug } from '@khanacademy/perseus-core';
+import { addLibraryVersionToPerseusDebug, approximateEqual, approximateDeepEqual } from '@khanacademy/perseus-core';
 import _ from 'underscore';
-import { number as number$1 } from '@khanacademy/kmath';
+import { point as point$1, sum as sum$1, number as number$1 } from '@khanacademy/kmath';
 
 // 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.0";
 addLibraryVersionToPerseusDebug(libName, libVersion);
 
 /**
@@ -33,7 +33,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) {
@@ -102,7 +102,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,
@@ -209,7 +209,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);
 }
 
@@ -298,7 +298,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,
@@ -312,7 +312,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,
@@ -458,7 +458,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
@@ -468,7 +468,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({
@@ -499,6 +499,374 @@ 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 (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 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 = _.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 (point$1.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 _.map(_.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 = _.zip(points, points.slice(1).concat(points.slice(0, 1)));
+  const areas = _.map(segments, function (segment) {
+    const p1 = segment[0];
+    const p2 = segment[1];
+    return (p2[0] - p1[0]) * (p2[1] + p1[1]);
+  });
+  return sum$1(areas) > 0;
+}
+function magnitude(v) {
+  return Math.sqrt(_.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 _.reduce(_.zip(a, b), function (memo, pair) {
+    return memo + pair[0] * pair[1];
+  }, 0);
+}
+function sideLengths(coords) {
+  const segments = _.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 = _.zip(rotate(coords, -1), coords, rotate(coords, 1));
+  const offsets = _.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 = _.reduce(offsets, function (memo, arg) {
+    return memo + arg;
+  }, 0);
+  return _.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 (approximateDeepEqual(angles1, angles)) {
+      const sidePairs = _.zip(sides1, sides);
+      const factors = _.map(sidePairs, function (pair) {
+        return pair[0] / pair[1];
+      });
+      const same = _.all(factors, function (factor) {
+        return approximateEqual(factors[0], factor);
+      });
+      const congruentEnough = _.all(sidePairs, function (pair) {
+        return number$1.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([amplitude, angularFrequency, phase, verticalOffset]) {
+  // 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 (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([x, y]) {
+  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 = (coords, allowReflexAngles = 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: {}};
@@ -10534,5 +10902,5 @@ function add(a, b) {
   return a + b;
 }
 
-export { KhanMath, libVersion, line, number, point, ray, sum, vector };
+export { KhanMath, angles, coefficients, geometry, libVersion, line, number, point, ray, sum, vector$1 as vector };
 //# sourceMappingURL=index.js.map