@khanacademy/kmath 0.0.3

package/src/point.js

@@ -0,0 +1,108 @@
+// @flow
+/**
+ * Point Utils
+ * A point is an array of two numbers e.g. [0, 0].
+ */
+
+import _ from "underscore";
+
+import * as kvector from "./vector.js";
+import * as knumber from "./number.js";
+
+// 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(
+    point: Point,
+    line: [Point, Point],
+): $ReadOnlyArray<number> /* TODO: convert to Point */ {
+    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.js

@@ -0,0 +1,25 @@
+// @flow
+/**
+ * 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 kvector from "./vector.js";
+import * as kpoint from "./point.js";
+
+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;
+}

package/src/vector.js

@@ -0,0 +1,267 @@
+// @flow
+/**
+ * Vector Utils
+ * A vector is an array of numbers e.g. [0, 3, 4].
+ */
+
+import _ from "underscore";
+import * as knumber from "./number.js";
+
+function arraySum(array: $ReadOnlyArray<number>): number {
+    return array.reduce((memo, arg) => memo + arg, 0);
+}
+
+function arrayProduct(array: $ReadOnlyArray<number>): number {
+    return array.reduce((memo, arg) => memo * arg, 1);
+}
+
+export function is<T>(vec: $ReadOnlyArray<T>, dimension: number): boolean {
+    if (!_.isArray(vec)) {
+        return false;
+    }
+    if (dimension !== undefined && vec.length !== dimension) {
+        return false;
+    }
+    return vec.every(knumber.is);
+}
+
+// Normalize to a unit vector
+export function normalize(v: $ReadOnlyArray<number>): $ReadOnlyArray<number> {
+    return scale(v, 1 / length(v));
+}
+
+// Length/magnitude of a vector
+export function length(v: $ReadOnlyArray<number>): number {
+    return Math.sqrt(dot(v, v));
+}
+// Dot product of two vectors
+export function dot(
+    a: $ReadOnlyArray<number>,
+    b: $ReadOnlyArray<number>,
+): number {
+    // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
+    const zipped = _.zip(a, b);
+    const multiplied = zipped.map(arrayProduct);
+    return arraySum(multiplied);
+}
+
+/* vector-add multiple [x, y] coords/vectors
+ *
+ * add([1, 2], [3, 4]) -> [4, 6]
+ */
+export function add(
+    ...vecs: $ReadOnlyArray<$ReadOnlyArray<number>>
+): $ReadOnlyArray<number> {
+    // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
+    const zipped = _.zip(...vecs);
+    return zipped.map(arraySum);
+}
+
+export function subtract(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+): $ReadOnlyArray<number> {
+    // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
+    return _.zip(v1, v2).map((dim) => dim[0] - dim[1]);
+}
+
+export function negate(v: $ReadOnlyArray<number>): $ReadOnlyArray<number> {
+    return v.map((x) => {
+        return -x;
+    });
+}
+
+// Scale a vector
+export function scale(
+    v1: $ReadOnlyArray<number>,
+    scalar: number,
+): $ReadOnlyArray<number> {
+    return v1.map((x) => {
+        return x * scalar;
+    });
+}
+
+export function equal(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+    tolerance?: number,
+): boolean {
+    // _.zip will nicely deal with the lengths, going through
+    // the length of the longest vector. knumber.equal then
+    // returns false for any number compared to the undefined
+    // passed in if one of the vectors is shorter.
+    // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
+    return _.zip(v1, v2).every((pair) =>
+        knumber.equal(pair[0], pair[1], tolerance),
+    );
+}
+
+export function codirectional(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+    tolerance?: number,
+): boolean {
+    // The origin is trivially codirectional with all other vectors.
+    // This gives nice semantics for codirectionality between points when
+    // comparing their difference vectors.
+    if (
+        knumber.equal(length(v1), 0, tolerance) ||
+        knumber.equal(length(v2), 0, tolerance)
+    ) {
+        return true;
+    }
+
+    v1 = normalize(v1);
+    v2 = normalize(v2);
+
+    return equal(v1, v2, tolerance);
+}
+
+export function collinear(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+    tolerance?: number,
+): boolean {
+    return (
+        codirectional(v1, v2, tolerance) ||
+        codirectional(v1, negate(v2), tolerance)
+    );
+}
+
+// Convert a cartesian coordinate into a radian polar coordinate
+export function polarRadFromCart(
+    v: $ReadOnlyArray<number>,
+): $ReadOnlyArray<number> {
+    const radius = length(v);
+    let theta = Math.atan2(v[1], v[0]);
+
+    // Convert angle range from [-pi, pi] to [0, 2pi]
+    if (theta < 0) {
+        theta += 2 * Math.PI;
+    }
+
+    return [radius, theta];
+}
+
+// Converts a cartesian coordinate into a degree polar coordinate
+export function polarDegFromCart(
+    v: $ReadOnlyArray<number>,
+): $ReadOnlyArray<number> /* TODO: convert to tuple/Point */ {
+    const polar = polarRadFromCart(v);
+    return [polar[0], (polar[1] * 180) / Math.PI];
+}
+
+/* Convert a polar coordinate into a cartesian coordinate
+ *
+ * Examples:
+ * cartFromPolarRad(5, Math.PI)
+ * cartFromPolarRad([5, Math.PI])
+ */
+export function cartFromPolarRad(
+    radius: number,
+    theta?: number = 0,
+): $ReadOnlyArray<number> /* TODO: convert to tuple/Point */ {
+    return [radius * Math.cos(theta), radius * Math.sin(theta)];
+}
+
+/* Convert a polar coordinate into a cartesian coordinate
+ *
+ * Examples:
+ * cartFromPolarDeg(5, 30)
+ * cartFromPolarDeg([5, 30])
+ */
+export function cartFromPolarDeg(
+    radius: number,
+    theta?: number = 0,
+): $ReadOnlyArray<number> {
+    return cartFromPolarRad(radius, (theta * Math.PI) / 180);
+}
+
+// Rotate vector
+export function rotateRad(
+    v: $ReadOnlyArray<number>,
+    theta: number,
+): $ReadOnlyArray<number> {
+    const polar = polarRadFromCart(v);
+    const angle = polar[1] + theta;
+    return cartFromPolarRad(polar[0], angle);
+}
+
+export function rotateDeg(
+    v: $ReadOnlyArray<number>,
+    theta: number,
+): $ReadOnlyArray<number> {
+    const polar = polarDegFromCart(v);
+    const angle = polar[1] + theta;
+    return cartFromPolarDeg(polar[0], angle);
+}
+
+// Angle between two vectors
+export function angleRad(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+): number {
+    return Math.acos(dot(v1, v2) / (length(v1) * length(v2)));
+}
+
+export function angleDeg(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+): number {
+    return (angleRad(v1, v2) * 180) / Math.PI;
+}
+
+// Vector projection of v1 onto v2
+export function projection(
+    v1: $ReadOnlyArray<number>,
+    v2: $ReadOnlyArray<number>,
+): $ReadOnlyArray<number> {
+    const scalar = dot(v1, v2) / dot(v2, v2);
+    return scale(v2, scalar);
+}
+
+// Round each number to a certain number of decimal places
+export function round(
+    vec: $ReadOnlyArray<number>,
+    precision: $ReadOnlyArray<number> | number,
+): $ReadOnlyArray<number> {
+    return vec.map((elem, i) =>
+        // $FlowFixMe[prop-missing]
+        // $FlowFixMe[incompatible-call]
+        knumber.round(elem, precision[i] || precision),
+    );
+}
+
+// Round each number to the nearest increment
+export function roundTo(
+    vec: $ReadOnlyArray<number>,
+    increment: $ReadOnlyArray<number> | number,
+): $ReadOnlyArray<number> {
+    return vec.map((elem, i) =>
+        // $FlowFixMe[prop-missing]
+        // $FlowFixMe[incompatible-call]
+        knumber.roundTo(elem, increment[i] || increment),
+    );
+}
+
+export function floorTo(
+    vec: $ReadOnlyArray<number>,
+    increment: $ReadOnlyArray<number> | number,
+): $ReadOnlyArray<number> {
+    return vec.map((elem, i) =>
+        // $FlowFixMe[prop-missing]
+        // $FlowFixMe[incompatible-call]
+        knumber.floorTo(elem, increment[i] || increment),
+    );
+}
+
+export function ceilTo(
+    vec: $ReadOnlyArray<number>,
+    increment: $ReadOnlyArray<number> | number,
+): $ReadOnlyArray<number> {
+    return vec.map((elem, i) =>
+        // $FlowFixMe[prop-missing]
+        // $FlowFixMe[incompatible-call]
+        knumber.ceilTo(elem, increment[i] || increment),
+    );
+}