@js-draw/math 1.0.0

package/README.md

@@ -0,0 +1,3 @@
+# `@js-draw/math`
+
+A library with math utilities used by `js-draw`.

package/build-config.json

@@ -0,0 +1,4 @@
+{
+	"inDirectory": "./src",
+	"outDirectory": "./dist"
+}

package/dist/cjs/Color4.d.ts

@@ -0,0 +1,83 @@
+import Vec3 from './Vec3';
+/**
+ * Represents a color.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import { Color4 } from '@js-draw/math';
+ *
+ * console.log('Red:', Color4.fromString('#f00'));
+ * console.log('Also red:', Color4.ofRGB(1, 0, 0), Color4.red);
+ * console.log('Mixing red and blue:', Color4.red.mix(Color4.blue, 0.5));
+ * console.log('To string:', Color4.orange.toHexString());
+ * ```
+ */
+export default class Color4 {
+    /** Red component. Should be in the range [0, 1]. */
+    readonly r: number;
+    /** Green component. ${\tt g} \in [0, 1]$ */
+    readonly g: number;
+    /** Blue component. ${\tt b} \in [0, 1]$ */
+    readonly b: number;
+    /** Alpha/transparent component. ${\tt a} \in [0, 1]$. 0 = transparent */
+    readonly a: number;
+    private constructor();
+    /**
+     * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
+     *
+     * Each component should be in the range [0, 1].
+     */
+    static ofRGB(red: number, green: number, blue: number): Color4;
+    static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4;
+    static fromHex(hexString: string): Color4;
+    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    static fromString(text: string): Color4;
+    /** @returns true if `this` and `other` are approximately equal. */
+    eq(other: Color4 | null | undefined): boolean;
+    /**
+     * If `fractionTo` is not in the range $[0, 1]$, it will be clamped to the nearest number
+     * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
+     *
+     * @returns a color `fractionTo` of the way from this color to `other`.
+     *
+     * @example
+     * ```ts
+     * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
+     * ```
+     */
+    mix(other: Color4, fractionTo: number): Color4;
+    /**
+     * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
+     */
+    static average(colors: Color4[]): Color4;
+    /**
+     * Converts to (hue, saturation, value).
+     * See also https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+     *
+     * The resultant hue is represented in radians and is thus in $[0, 2\pi]$.
+     */
+    asHSV(): Vec3;
+    private hexString;
+    /**
+     * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
+     *
+     * @example
+     * ```
+     * Color4.red.toHexString(); // -> #ff0000ff
+     * ```
+     */
+    toHexString(): string;
+    toString(): string;
+    static transparent: Color4;
+    static red: Color4;
+    static orange: Color4;
+    static green: Color4;
+    static blue: Color4;
+    static purple: Color4;
+    static yellow: Color4;
+    static clay: Color4;
+    static black: Color4;
+    static gray: Color4;
+    static white: Color4;
+}
+export { Color4 };

package/dist/cjs/Color4.js

@@ -0,0 +1,277 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Color4 = void 0;
+const Vec3_1 = __importDefault(require("./Vec3"));
+/**
+ * Represents a color.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import { Color4 } from '@js-draw/math';
+ *
+ * console.log('Red:', Color4.fromString('#f00'));
+ * console.log('Also red:', Color4.ofRGB(1, 0, 0), Color4.red);
+ * console.log('Mixing red and blue:', Color4.red.mix(Color4.blue, 0.5));
+ * console.log('To string:', Color4.orange.toHexString());
+ * ```
+ */
+class Color4 {
+    constructor(
+    /** Red component. Should be in the range [0, 1]. */
+    r, 
+    /** Green component. ${\tt g} \in [0, 1]$ */
+    g, 
+    /** Blue component. ${\tt b} \in [0, 1]$ */
+    b, 
+    /** Alpha/transparent component. ${\tt a} \in [0, 1]$. 0 = transparent */
+    a) {
+        this.r = r;
+        this.g = g;
+        this.b = b;
+        this.a = a;
+        this.hexString = null;
+    }
+    /**
+     * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
+     *
+     * Each component should be in the range [0, 1].
+     */
+    static ofRGB(red, green, blue) {
+        return Color4.ofRGBA(red, green, blue, 1.0);
+    }
+    static ofRGBA(red, green, blue, alpha) {
+        red = Math.max(0, Math.min(red, 1));
+        green = Math.max(0, Math.min(green, 1));
+        blue = Math.max(0, Math.min(blue, 1));
+        alpha = Math.max(0, Math.min(alpha, 1));
+        return new Color4(red, green, blue, alpha);
+    }
+    static fromHex(hexString) {
+        // Remove starting '#' (if present)
+        hexString = (hexString.match(/^[#]?(.*)$/) ?? [])[1];
+        hexString = hexString.toUpperCase();
+        if (!hexString.match(/^[0-9A-F]+$/)) {
+            throw new Error(`${hexString} is not in a valid format.`);
+        }
+        // RGBA or RGB
+        if (hexString.length === 3 || hexString.length === 4) {
+            // Each character is a component
+            const components = hexString.split('');
+            // Convert to RRGGBBAA or RRGGBB format
+            hexString = components.map(component => `${component}0`).join('');
+        }
+        if (hexString.length === 6) {
+            // Alpha component
+            hexString += 'FF';
+        }
+        const components = [];
+        for (let i = 2; i <= hexString.length; i += 2) {
+            const chunk = hexString.substring(i - 2, i);
+            components.push(parseInt(chunk, 16) / 255);
+        }
+        if (components.length !== 4) {
+            throw new Error(`Unable to parse ${hexString}: Wrong number of components.`);
+        }
+        return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
+    }
+    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    static fromString(text) {
+        if (text.startsWith('#')) {
+            return Color4.fromHex(text);
+        }
+        if (text === 'none' || text === 'transparent') {
+            return Color4.transparent;
+        }
+        // rgba?: Match both rgb and rgba strings.
+        // ([,0-9.]+): Match any string of only numeric, '.' and ',' characters.
+        const rgbRegex = /^rgba?\(([,0-9.]+)\)$/i;
+        const rgbMatch = text.replace(/\s*/g, '').match(rgbRegex);
+        if (rgbMatch) {
+            const componentsListStr = rgbMatch[1];
+            const componentsList = JSON.parse(`[ ${componentsListStr} ]`);
+            if (componentsList.length === 3) {
+                return Color4.ofRGB(componentsList[0] / 255, componentsList[1] / 255, componentsList[2] / 255);
+            }
+            else if (componentsList.length === 4) {
+                return Color4.ofRGBA(componentsList[0] / 255, componentsList[1] / 255, componentsList[2] / 255, componentsList[3]);
+            }
+            else {
+                throw new Error(`RGB string, ${text}, has wrong number of components: ${componentsList.length}`);
+            }
+        }
+        // Otherwise, try to use an HTMLCanvasElement to determine the color.
+        // Note: We may be unable to create an HTMLCanvasElement if running as a unit test.
+        const canvas = document.createElement('canvas');
+        canvas.width = 1;
+        canvas.height = 1;
+        const ctx = canvas.getContext('2d');
+        ctx.fillStyle = text;
+        ctx.fillRect(0, 0, 1, 1);
+        const data = ctx.getImageData(0, 0, 1, 1);
+        const red = data.data[0] / 255;
+        const green = data.data[1] / 255;
+        const blue = data.data[2] / 255;
+        const alpha = data.data[3] / 255;
+        return Color4.ofRGBA(red, green, blue, alpha);
+    }
+    /** @returns true if `this` and `other` are approximately equal. */
+    eq(other) {
+        if (other == null) {
+            return false;
+        }
+        // If both completely transparent,
+        if (this.a === 0 && other.a === 0) {
+            return true;
+        }
+        return this.toHexString() === other.toHexString();
+    }
+    /**
+     * If `fractionTo` is not in the range $[0, 1]$, it will be clamped to the nearest number
+     * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
+     *
+     * @returns a color `fractionTo` of the way from this color to `other`.
+     *
+     * @example
+     * ```ts
+     * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
+     * ```
+     */
+    mix(other, fractionTo) {
+        fractionTo = Math.min(Math.max(fractionTo, 0), 1);
+        const fractionOfThis = 1 - fractionTo;
+        return new Color4(this.r * fractionOfThis + other.r * fractionTo, this.g * fractionOfThis + other.g * fractionTo, this.b * fractionOfThis + other.b * fractionTo, this.a * fractionOfThis + other.a * fractionTo);
+    }
+    /**
+     * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
+     */
+    static average(colors) {
+        let averageA = 0;
+        let averageR = 0;
+        let averageG = 0;
+        let averageB = 0;
+        for (const color of colors) {
+            averageA += color.a;
+            averageR += color.r;
+            averageG += color.g;
+            averageB += color.b;
+        }
+        if (colors.length > 0) {
+            averageA /= colors.length;
+            averageR /= colors.length;
+            averageG /= colors.length;
+            averageB /= colors.length;
+        }
+        return new Color4(averageR, averageG, averageB, averageA);
+    }
+    /**
+     * Converts to (hue, saturation, value).
+     * See also https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+     *
+     * The resultant hue is represented in radians and is thus in $[0, 2\pi]$.
+     */
+    asHSV() {
+        // Ref: https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+        //
+        // HUE:
+        // First, consider the unit cube. Rotate it such that one vertex is at the origin
+        // of a plane and its three neighboring vertices are equidistant from that plane:
+        //
+        //         /\
+        //       /  | \
+        //   2 /    3   \ 1
+        //     \    |   /
+        //       \  | /
+        //   .     \/      .
+        //
+        //        .
+        //
+        // Let z be up and (x, y, 0) be in the plane.
+        //
+        // Label vectors 1,2,3 with R, G, and B, respectively. Let R's projection into the plane
+        // lie along the x axis.
+        //
+        // Because R is a unit vector and R, G, B are equidistant from the plane, they must
+        // form 30-60-90 triangles, which have side lengths proportional to (1, √3, 2)
+        //
+        //       /|
+        //    1/  | (√3)/2
+        //    /   |
+        //      1/2
+        //
+        const minComponent = Math.min(this.r, this.g, this.b);
+        const maxComponent = Math.max(this.r, this.g, this.b);
+        const chroma = maxComponent - minComponent;
+        let hue;
+        // See https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+        if (chroma === 0) {
+            hue = 0;
+        }
+        else if (this.r >= this.g && this.r >= this.b) {
+            hue = ((this.g - this.b) / chroma) % 6;
+        }
+        else if (this.g >= this.r && this.g >= this.b) {
+            hue = (this.b - this.r) / chroma + 2;
+        }
+        else {
+            hue = (this.r - this.g) / chroma + 4;
+        }
+        // Convert to degree representation, then to radians.
+        hue *= 60;
+        hue *= Math.PI / 180;
+        // Ensure positivity.
+        if (hue < 0) {
+            hue += Math.PI * 2;
+        }
+        const value = maxComponent;
+        const saturation = value > 0 ? chroma / value : 0;
+        return Vec3_1.default.of(hue, saturation, value);
+    }
+    /**
+     * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
+     *
+     * @example
+     * ```
+     * Color4.red.toHexString(); // -> #ff0000ff
+     * ```
+     */
+    toHexString() {
+        if (this.hexString) {
+            return this.hexString;
+        }
+        const componentToHex = (component) => {
+            const res = Math.round(255 * component).toString(16);
+            if (res.length === 1) {
+                return `0${res}`;
+            }
+            return res;
+        };
+        const alpha = componentToHex(this.a);
+        const red = componentToHex(this.r);
+        const green = componentToHex(this.g);
+        const blue = componentToHex(this.b);
+        if (alpha === 'ff') {
+            return `#${red}${green}${blue}`;
+        }
+        this.hexString = `#${red}${green}${blue}${alpha}`;
+        return this.hexString;
+    }
+    toString() {
+        return this.toHexString();
+    }
+}
+exports.Color4 = Color4;
+Color4.transparent = Color4.ofRGBA(0, 0, 0, 0);
+Color4.red = Color4.ofRGB(1.0, 0.0, 0.0);
+Color4.orange = Color4.ofRGB(1.0, 0.65, 0.0);
+Color4.green = Color4.ofRGB(0.0, 1.0, 0.0);
+Color4.blue = Color4.ofRGB(0.0, 0.0, 1.0);
+Color4.purple = Color4.ofRGB(0.5, 0.2, 0.5);
+Color4.yellow = Color4.ofRGB(1, 1, 0.1);
+Color4.clay = Color4.ofRGB(0.8, 0.4, 0.2);
+Color4.black = Color4.ofRGB(0, 0, 0);
+Color4.gray = Color4.ofRGB(0.5, 0.5, 0.5);
+Color4.white = Color4.ofRGB(1, 1, 1);
+exports.default = Color4;

package/dist/cjs/Mat33.d.ts

@@ -0,0 +1,131 @@
+import { Point2, Vec2 } from './Vec2';
+import Vec3 from './Vec3';
+export type Mat33Array = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/**
+ * Represents a three dimensional linear transformation or
+ * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
+ * **and** translates while a linear transformation just scales/rotates/shears).
+ */
+export declare class Mat33 {
+    readonly a1: number;
+    readonly a2: number;
+    readonly a3: number;
+    readonly b1: number;
+    readonly b2: number;
+    readonly b3: number;
+    readonly c1: number;
+    readonly c2: number;
+    readonly c3: number;
+    private readonly rows;
+    /**
+     * Creates a matrix from inputs in the form,
+     * $$
+     * \begin{bmatrix}
+     *   a1 & a2 & a3 \\
+     *   b1 & b2 & b3 \\
+     *   c1 & c2 & c3
+     * \end{bmatrix}
+     * $$
+     */
+    constructor(a1: number, a2: number, a3: number, b1: number, b2: number, b3: number, c1: number, c2: number, c3: number);
+    /**
+     * Creates a matrix from the given rows:
+     * $$
+     * \begin{bmatrix}
+     *  \texttt{r1.x} & \texttt{r1.y} & \texttt{r1.z}\\
+     *  \texttt{r2.x} & \texttt{r2.y} & \texttt{r2.z}\\
+     *  \texttt{r3.x} & \texttt{r3.y} & \texttt{r3.z}\\
+     * \end{bmatrix}
+     * $$
+     */
+    static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33;
+    static identity: Mat33;
+    /**
+     * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
+     * returns Mat33.identity.
+     *
+     * This may cache the computed inverse and return the cached version instead of recomputing
+     * it.
+     */
+    inverse(): Mat33;
+    invertable(): boolean;
+    private cachedInverse;
+    private computeInverse;
+    transposed(): Mat33;
+    rightMul(other: Mat33): Mat33;
+    /**
+     * Applies this as an **affine** transformation to the given vector.
+     * Returns a transformed version of `other`.
+     *
+     * Unlike {@link transformVec3}, this **does** translate the given vector.
+     */
+    transformVec2(other: Vec2): Vec2;
+    /**
+     * Applies this as a linear transformation to the given vector (doesn't translate).
+     * This is the standard way of transforming vectors in ℝ³.
+     */
+    transformVec3(other: Vec3): Vec3;
+    /** @returns true iff this is the identity matrix. */
+    isIdentity(): boolean;
+    /** Returns true iff this = other ± fuzz */
+    eq(other: Mat33, fuzz?: number): boolean;
+    toString(): string;
+    /**
+     * ```
+     * result[0] = top left element
+     * result[1] = element at row zero, column 1
+     * ...
+     * ```
+     */
+    toArray(): Mat33Array;
+    /**
+     * Returns a new `Mat33` where each entry is the output of the function
+     * `mapping`.
+     *
+     * @example
+     * ```
+     * new Mat33(
+     *  1, 2, 3,
+     *  4, 5, 6,
+     *  7, 8, 9,
+     * ).mapEntries(component => component - 1);
+     * // → ⎡ 0, 1, 2 ⎤
+     * //   ⎢ 3, 4, 5 ⎥
+     * //   ⎣ 6, 7, 8 ⎦
+     * ```
+     */
+    mapEntries(mapping: (component: number, rowcol: [number, number]) => number): Mat33;
+    /** Estimate the scale factor of this matrix (based on the first row). */
+    getScaleFactor(): number;
+    /**
+     * Constructs a 3x3 translation matrix (for translating `Vec2`s) using
+     * **transformVec2**.
+     */
+    static translation(amount: Vec2): Mat33;
+    static zRotation(radians: number, center?: Point2): Mat33;
+    static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
+    /** @see {@link fromCSSMatrix} */
+    toCSSMatrix(): string;
+    /**
+     * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
+     *
+     * Note that such a matrix has the form,
+     * ```
+     * ⎡ a c e ⎤
+     * ⎢ b d f ⎥
+     * ⎣ 0 0 1 ⎦
+     * ```
+     */
+    static fromCSSMatrix(cssString: string): Mat33;
+}
+export default Mat33;