@khanacademy/kmath 0.0.0-PR971-20240207180432 → 0.0.0-PR973-20240207194831

package/src/__tests__/vector.test.ts

@@ -0,0 +1,145 @@
+import * as vector from "../vector";
+
+describe("kvector", function () {
+    it("vector.zip should return empty given empty", function () {
+        expect(vector.zip([], [])).toEqual([]);
+    });
+
+    it("vector.zip should create vectors from x and y coords", function () {
+        expect(vector.zip([1, 2], [3, 4])).toEqual([
+            [1, 3],
+            [2, 4],
+        ]);
+    });
+
+    it("vector.zip should ignore extra xs", function () {
+        expect(vector.zip([1, 2, 9], [3, 4])).toEqual([
+            [1, 3],
+            [2, 4],
+        ]);
+    });
+
+    it("vector.zip should ignore extra ys", function () {
+        expect(vector.zip([1, 2], [3, 4, 9])).toEqual([
+            [1, 3],
+            [2, 4],
+        ]);
+    });
+
+    it("vector.map should transform a 2D vector", function () {
+        const double = (x) => x * 2;
+        expect(vector.map([3, 4], double)).toEqual([6, 8]);
+    });
+
+    it("vector.map should pass the index of each element to the callback", function () {
+        expect(vector.map([3, 4], (_, i) => i)).toEqual([0, 1]);
+    });
+
+    it("vector.add should add two 2D vectors", function () {
+        const result = vector.add([1, 2], [3, 4]);
+        expect(result).toStrictEqual([4, 6]);
+    });
+
+    it("vector.add should add two 3D vectors", function () {
+        const result = vector.add([1, 2, 3], [4, 5, 6]);
+        expect(result).toStrictEqual([5, 7, 9]);
+    });
+
+    it("vector.add should add three 2D vectors", function () {
+        const result = vector.add([1, 2], [3, 4], [5, 6]);
+        expect(result).toStrictEqual([9, 12]);
+    });
+
+    it("vector.subtract should subtract two 2D vectors", function () {
+        const result = vector.subtract([1, 2], [3, 4]);
+        expect(result).toStrictEqual([-2, -2]);
+    });
+
+    it("vector.subtract should subtract two 3D vectors", function () {
+        const result = vector.subtract([1, 2, 3], [4, 5, 6]);
+        expect(result).toStrictEqual([-3, -3, -3]);
+    });
+
+    it("vector.dot should take the dot product of 2 2D vectors", function () {
+        const result = vector.dot([1, 2], [3, 4]);
+        expect(result).toBe(3 + 8);
+    });
+
+    it("vector.dot should take the dot product of 2 3D vectors", function () {
+        const result = vector.dot([1, 2, 3], [4, 5, 6]);
+        expect(result).toBe(4 + 10 + 18);
+    });
+
+    it("vector.scale should scale a 2D vector", function () {
+        const result = vector.scale([4, 2], 0.5);
+        expect(result).toStrictEqual([2, 1]);
+    });
+
+    it("vector.scale should scale a 3D vector", function () {
+        const result = vector.scale([1, 2, 3], 2);
+        expect(result).toStrictEqual([2, 4, 6]);
+    });
+
+    it("vector.length should take the length of a 2D vector", function () {
+        const result = vector.length([3, 4]);
+        expect(result).toBe(5);
+    });
+
+    it("vector.length should take the length of a 3D vector", function () {
+        const result = vector.length([4, 0, 3]);
+        expect(result).toBe(5);
+    });
+
+    it("vector.equal should return true on two equal 3D vectors", function () {
+        const result = vector.equal([6, 3, 4], [6, 3, 4]);
+        expect(result).toBe(true);
+    });
+
+    it("vector.equal should return false on two inequal 3D vectors", function () {
+        const result = vector.equal([6, 3, 4], [6, 4, 4]);
+        expect(result).toBe(false);
+    });
+
+    it("vector.equal should return false on a 2D and 3D vector", function () {
+        const result = vector.equal([6, 4], [6, 4, 4]);
+        expect(result).toBe(false);
+    });
+
+    it("vector.equal should return false on a 2D and 3D vector", function () {
+        const result = vector.equal([6, 3, 4], [6, 3]);
+        expect(result).toBe(false);
+    });
+
+    it("vector.equal should return false on a 2D and 3D vector with a trailing 0", function () {
+        const result = vector.equal([6, 3, 0], [6, 3]);
+        expect(result).toBe(false);
+    });
+
+    it(
+        "vector.collinear should return true on two collinear vectors of " +
+            "the same magnitude but different direction",
+        function () {
+            const result = vector.collinear([3, 3], [-3, -3]);
+            expect(result).toBe(true);
+        },
+    );
+
+    it(
+        "vector.collinear should return true on two collinear vectors of " +
+            "different magnitudes",
+        function () {
+            const result = vector.collinear([2, 1], [6, 3]);
+            expect(result).toBe(true);
+        },
+    );
+
+    it("vector.collinear should return false on non-collinear vectors", function () {
+        const result = vector.collinear([1, 2], [-1, 2]);
+        expect(result).toBe(false);
+    });
+
+    it("vector.negate of [-2, 2] is [2, -2]", function () {
+        const result = vector.negate([-2, 2]);
+        expect(result).toStrictEqual([2, -2]);
+    });
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+export {libVersion} from "./version";
+
+export * as number from "./number";
+export * as vector from "./vector";
+export * as point from "./point";
+export * as line from "./line";
+export * as ray from "./ray";

package/src/line.ts

@@ -0,0 +1,42 @@
+/**
+ * Line Utils
+ * A line is an array of two points e.g. [[-5, 0], [5, 0]].
+ */
+
+import * as kpoint from "./point";
+import * as kvector from "./vector";
+
+import type {Point} from "./point";
+
+export type Line = [Point, Point];
+
+export function distanceToPoint(line: Line, point: Point): number {
+    return kpoint.distanceToLine(point, line);
+}
+
+export function reflectPoint(line: Line, point: Point): Point {
+    return kpoint.reflectOverLine(point, line);
+}
+
+export function midpoint(line: Line): Point {
+    return [(line[0][0] + line[1][0]) / 2, (line[0][1] + line[1][1]) / 2];
+}
+
+export function equal(line1: Line, line2: Line, tolerance?: number): boolean {
+    // TODO: A nicer implementation might just check collinearity of
+    // vectors using underscore magick
+    // Compare the directions of the lines
+    const v1 = kvector.subtract(line1[1], line1[0]);
+    const v2 = kvector.subtract(line2[1], line2[0]);
+    if (!kvector.collinear(v1, v2, tolerance)) {
+        return false;
+    }
+    // If the start point is the same for the two lines, then they are the same
+    if (kpoint.equal(line1[0], line2[0])) {
+        return true;
+    }
+    // Make sure that the direction to get from line1 to
+    // line2 is the same as the direction of the lines
+    const line1ToLine2Vector = kvector.subtract(line2[0], line1[0]);
+    return kvector.collinear(v1, line1ToLine2Vector, tolerance);
+}

package/src/logo.ts

@@ -0,0 +1,39 @@
+/* eslint-disable import/no-default-export */
+// This file describes the graphie source code of the kmath logo
+// currently used on khan.github.io.
+//
+// Also located at http://ka-perseus-graphie.s3.amazonaws.com/42ef3cbadc3e6464124533191728c3c5c55c7355.svg
+
+declare let init: any;
+declare let ellipse: any;
+declare let line: any;
+
+const GREEN = "#28AE7B";
+
+export default () => {
+    init({
+        range: [
+            [0, 10],
+            [0, 10],
+        ],
+        scale: 40,
+    });
+
+    ellipse(5, 5, 5, {
+        stroke: null,
+        fill: GREEN,
+    });
+
+    line([2, 5], [8.5, 5], {
+        stroke: "WHITE",
+        fill: "WHITE",
+        strokeWidth: 25,
+        arrows: "->",
+    });
+
+    line([5, 2], [5, 8], {
+        stroke: "WHITE",
+        fill: "WHITE",
+        strokeWidth: 25,
+    });
+};

package/src/number.ts

@@ -0,0 +1,104 @@
+/**
+ * Number Utils
+ * A number is a js-number, e.g. 5.12
+ */
+
+import _ from "underscore";
+
+export const DEFAULT_TOLERANCE = 1e-9;
+
+// TODO: Should this just be Number.Epsilon
+export const EPSILON: number = Math.pow(2, -42);
+
+export function is(x: any): boolean {
+    return _.isNumber(x) && !_.isNaN(x);
+}
+
+export function equal(x: number, y: number, tolerance?: number): boolean {
+    // Checking for undefined makes this function behave nicely
+    // with vectors of different lengths that are _.zip'd together
+    if (x == null || y == null) {
+        return x === y;
+    }
+    // We check === here so that +/-Infinity comparisons work correctly
+    if (x === y) {
+        return true;
+    }
+    if (tolerance == null) {
+        tolerance = DEFAULT_TOLERANCE;
+    }
+    return Math.abs(x - y) < tolerance;
+}
+
+export function sign(
+    x: number,
+    tolerance?: number,
+): number /* Should be: 0 | 1 | -1 */ {
+    return equal(x, 0, tolerance) ? 0 : Math.abs(x) / x;
+}
+
+export function isInteger(num: number, tolerance?: number): boolean {
+    return equal(Math.round(num), num, tolerance);
+}
+
+// Round a number to a certain number of decimal places
+export function round(num: number, precision: number): number {
+    const factor = Math.pow(10, precision);
+    return Math.round(num * factor) / factor;
+}
+
+// Round num to the nearest multiple of increment
+// i.e. roundTo(83, 5) -> 85
+export function roundTo(num: number, increment: number): number {
+    return Math.round(num / increment) * increment;
+}
+
+export function floorTo(num: number, increment: number): number {
+    return Math.floor(num / increment) * increment;
+}
+
+export function ceilTo(num: number, increment: number): number {
+    return Math.ceil(num / increment) * increment;
+}
+
+/**
+ * toFraction
+ *
+ * Returns a [numerator, denominator] array rational representation
+ * of `decimal`
+ *
+ * See http://en.wikipedia.org/wiki/Continued_fraction for implementation
+ * details
+ *
+ * toFraction(4/8) => [1, 2]
+ * toFraction(0.66) => [33, 50]
+ * toFraction(0.66, 0.01) => [2/3]
+ * toFraction(283 + 1/3) => [850, 3]
+ */
+export function toFraction(
+    decimal: number,
+    // can't be 0
+    tolerance: number = EPSILON,
+    maxDenominator = 1000,
+): [number, number] {
+    // Initialize everything to compute successive terms of
+    // continued-fraction approximations via recurrence relation
+    let n = [1, 0];
+    let d = [0, 1];
+    let a = Math.floor(decimal);
+    let rem = decimal - a;
+
+    while (d[0] <= maxDenominator) {
+        if (equal(n[0] / d[0], decimal, tolerance)) {
+            return [n[0], d[0]];
+        }
+        n = [a * n[0] + n[1], n[0]];
+        d = [a * d[0] + d[1], d[0]];
+        a = Math.floor(1 / rem);
+        rem = 1 / rem - a;
+    }
+
+    // We failed to find a nice rational representation,
+    // so return an irrational "fraction"
+    return [decimal, 1];
+}

package/src/point.ts

@@ -0,0 +1,102 @@
+/**
+ * Point Utils
+ * A point is an array of two numbers e.g. [0, 0].
+ */
+
+import * as knumber from "./number";
+import * as kvector from "./vector";
+
+// A point, in 2D, 3D, or nD space.
+export type Point = ReadonlyArray<number>;
+
+// Rotate point (around origin unless a center is specified)
+export function rotateRad(point: Point, theta: number, center?: Point): Point {
+    if (center === undefined) {
+        return kvector.rotateRad(point, theta);
+    } else {
+        return kvector.add(
+            center,
+            kvector.rotateRad(kvector.subtract(point, center), theta),
+        );
+    }
+}
+
+export function rotateDeg(point: Point, theta: number, center?: Point): Point {
+    if (center === undefined) {
+        return kvector.rotateDeg(point, theta);
+    } else {
+        return kvector.add(
+            center,
+            kvector.rotateDeg(kvector.subtract(point, center), theta),
+        );
+    }
+}
+
+// Distance between two points
+export function distanceToPoint(point1: Point, point2: Point): number {
+    return kvector.length(kvector.subtract(point1, point2));
+}
+
+// Distance between point and line
+export function distanceToLine(point: Point, line: [Point, Point]): number {
+    const lv = kvector.subtract(line[1], line[0]);
+    const pv = kvector.subtract(point, line[0]);
+    const projectedPv = kvector.projection(pv, lv);
+    const distancePv = kvector.subtract(projectedPv, pv);
+    return kvector.length(distancePv);
+}
+
+// Reflect point over line
+export function reflectOverLine<P extends Point>(point: P, line: [P, P]): P {
+    const lv = kvector.subtract(line[1], line[0]);
+    const pv = kvector.subtract(point, line[0]);
+    const projectedPv = kvector.projection(pv, lv);
+    const reflectedPv = kvector.subtract(kvector.scale(projectedPv, 2), pv);
+    return kvector.add(line[0], reflectedPv);
+}
+
+/**
+ * Compares two points, returning -1, 0, or 1, for use with
+ * Array.prototype.sort
+ *
+ * Note: This technically doesn't satisfy the total-ordering
+ * requirements of Array.prototype.sort unless equalityTolerance
+ * is 0. In some cases very close points that compare within a
+ * few equalityTolerances could appear in the wrong order.
+ */
+export function compare(
+    point1: Point,
+    point2: Point,
+    equalityTolerance?: number,
+): number /* TODO: convert to -1 | 0 | 1 type */ {
+    if (point1.length !== point2.length) {
+        return point1.length - point2.length;
+    }
+    for (let i = 0; i < point1.length; i++) {
+        if (!knumber.equal(point1[i], point2[i], equalityTolerance)) {
+            return point1[i] - point2[i];
+        }
+    }
+    return 0;
+}
+
+// Check if a value is a point
+export const is = kvector.is;
+
+// Add and subtract vector(s)
+export const addVector = kvector.add;
+export const addVectors = kvector.add;
+export const subtractVector = kvector.subtract;
+export const equal = kvector.equal;
+
+// Convert from cartesian to polar and back
+export const polarRadFromCart = kvector.polarRadFromCart;
+export const polarDegFromCart = kvector.polarDegFromCart;
+export const cartFromPolarRad = kvector.cartFromPolarRad;
+export const cartFromPolarDeg = kvector.cartFromPolarDeg;
+
+// Rounding
+export const round = kvector.round;
+export const roundTo = kvector.roundTo;
+export const floorTo = kvector.floorTo;
+export const ceilTo = kvector.ceilTo;

package/src/ray.ts

@@ -0,0 +1,24 @@
+/**
+ * Ray Utils
+ * A ray (→) is an array of an endpoint and another point along the ray.
+ * For example, [[0, 0], [1, 0]] is the ray starting at the origin and
+ * traveling along the positive x-axis.
+ */
+
+import * as kpoint from "./point";
+import * as kvector from "./vector";
+
+import type {Point} from "./point";
+
+export type Ray = [Point, Point];
+
+export function equal(ray1: Ray, ray2: Ray, tolerance?: number): boolean {
+    // Compare the directions of the rays
+    const v1 = kvector.subtract(ray1[1], ray1[0]);
+    const v2 = kvector.subtract(ray2[1], ray2[0]);
+
+    const sameOrigin = kpoint.equal(ray1[0], ray2[0]);
+    const codirectional = kvector.codirectional(v1, v2, tolerance);
+
+    return sameOrigin && codirectional;
+}