pts 0.12.8 → 1.0.0

package/src/Util.ts

@@ -0,0 +1,454 @@
+/*! Pts.js is licensed under Apache License 2.0. Copyright © 2017-current William Ngan and contributors. (https://github.com/williamngan/pts) */
+
+import type { CanvasSpace } from "./Canvas";
+import { Num } from "./Num";
+import { Group, Pt } from "./Pt";
+import { type WarningType, type PtLike, type PtLikeIterable } from "./Types";
+
+/**
+ * Various constant values for enumerations and calculations.
+ */
+export const Const = {
+  /** A string to indicate xy plane. */
+  xy: "xy",
+
+  /** A string to indicate yz plane. */
+  yz: "yz",
+
+  /** A string to indicate xz plane. */
+  xz: "xz",
+
+  /** A string to indicate xyz space. */
+  xyz: "xyz",
+
+  /** Represents horizontal direction. */
+  horizontal: 0,
+
+  /** Represents vertical direction. */
+  vertical: 1,
+
+  /** Represents identical point or value */
+  identical: 0,
+
+  /** Represents right position or direction */
+  right: 4,
+
+  /** Represents bottom right position or direction */
+  bottom_right: 5,
+
+  /** Represents bottom position or direction */
+  bottom: 6,
+
+  /** Represents bottom left position or direction */
+  bottom_left: 7,
+
+  /** Represents left position or direction */
+  left: 8,
+
+  /** Represents top left position or direction */
+  top_left: 1,
+
+  /** Represents top position or direction */
+  top: 2,
+
+  /** Represents top right position or direction */
+  top_right: 3,
+
+  /** Represents an arbitrary very small number. It is set as 0.0001 here. */
+  epsilon: 0.0001,
+
+  /** Represents Number.MAX_VALUE. Note: as a Float32 Pt value this overflows to Infinity. */
+  max: Number.MAX_VALUE,
+
+  /** Represents Number.MIN_VALUE, the smallest *positive* number (5e-324) — not the most negative number. Do not use it to initialize a running maximum; use -Infinity instead. As a Float32 Pt value this flushes to 0. */
+  min: Number.MIN_VALUE,
+
+  /** π radian (180 deg) */
+  pi: Math.PI,
+
+  /** Two π radian (360deg) */
+  two_pi: 6.283185307179586,
+
+  /** Half π radian (90deg) */
+  half_pi: 1.5707963267948966,
+
+  /** π/4 radian (45deg) */
+  quarter_pi: 0.7853981633974483,
+
+  /** π/180 or 1 degree in radian */
+  one_degree: 0.017453292519943295,
+
+  /** Multiply this constant with a radian to get a degree */
+  rad_to_deg: 57.29577951308232,
+
+  /** Multiply this constant with a degree to get a radian */
+  deg_to_rad: 0.017453292519943295,
+
+  /** Gravity acceleration (unit: m/s^2) and gravity force (unit: Newton) on 1kg of mass. */
+  gravity: 9.81,
+
+  /** 1 Newton: 0.10197 Kilogram-force */
+  newton: 0.10197,
+
+  /** Gaussian constant (1 / Math.sqrt(2 * Math.PI)) */
+  gaussian: 0.3989422804014327,
+};
+
+/**
+ * Util class provides static helper functions.
+ */
+export class Util {
+  static _warnLevel: WarningType = "mute";
+
+  /**
+   * Set a global warning level setting. If no parameter is passed, this will return the current warn-level. See [`Util.warn`](#link).
+   * @param lv a [`WarningType`](#link) option, where "error" will throw an error, "warn" will log in console, and "mute" will ignore the error.
+   */
+  static warnLevel(lv?: WarningType): WarningType {
+    if (lv) {
+      Util._warnLevel = lv;
+    }
+    return Util._warnLevel;
+  }
+
+  /**
+   * Convert different kinds of parameters (arguments, array, object) into an array of numbers.
+   * @param args can be either a list of numbers, an array, a Pt, or an object with {x,y,z,w} properties
+   */
+  static getArgs(args: any[]): Array<number> {
+    if (args.length < 1) return [];
+
+    let pos = [];
+
+    let isArray = Array.isArray(args[0]) || ArrayBuffer.isView(args[0]);
+
+    // positional arguments: x,y,z,w,...
+    if (typeof args[0] === "number") {
+      pos = Array.prototype.slice.call(args);
+
+      // as an object of {x, y?, z?, w?}
+    } else if (typeof args[0] === "object" && !isArray) {
+      let a = ["x", "y", "z", "w"];
+      let p = args[0];
+      for (let i = 0; i < a.length; i++) {
+        if ((p.length && i >= p.length) || !(a[i] in p)) break; // check for length and key exist
+        pos.push(p[a[i]]);
+      }
+
+      // as an array of values
+    } else if (isArray) {
+      pos = Util.toNumericArray(args[0]);
+    }
+
+    return pos;
+  }
+
+  /**
+   * Copy an array or typed array of numbers into a fresh plain array.
+   * @param a an array or typed array
+   */
+  static toNumericArray(a: ArrayLike<number>): number[] {
+    // native slice is a fast path for plain arrays, but `[].slice.call` on a
+    // typed array falls back to the generic per-element protocol
+    if (Array.isArray(a)) return a.slice();
+    const out = [];
+    for (let i = 0, len = a.length; i < len; i++) {
+      out.push(a[i]);
+    }
+    return out;
+  }
+
+  /**
+   * Like [`Util.getArgs`](#link), but avoids copying when the arguments are already
+   * a numeric array, a typed array (eg, a Pt), or a list of numbers. The result may be
+   * the caller's own object, so it must be treated as read-only.
+   * @param args can be either a list of numbers, an array, a Pt, or an object with {x,y,z,w} properties
+   */
+  static getPtLike(args: any[]): PtLike {
+    const a0 = args[0];
+    if (typeof a0 === "number") return args; // rest args are a fresh, private array
+    if (args.length === 1 && (Array.isArray(a0) || ArrayBuffer.isView(a0))) {
+      return a0 as PtLike;
+    }
+    return Util.getArgs(args);
+  }
+
+  /**
+   * Send a warning message based on [`Util.warnLevel`](#link) global setting. This allows you to dynamically set whether minor errors should be thrown or printed in console or muted.
+   * @param message any error or warning message
+   * @param defaultReturn optional return value
+   */
+  static warn(message: string = "error", defaultReturn: any = undefined): any {
+    if (Util.warnLevel() == "error") {
+      throw new Error(message);
+    } else if (Util.warnLevel() == "warn") {
+      console.warn(message);
+    }
+    return defaultReturn;
+  }
+
+  /**
+   * Get a random integer. This can be useful for selecting a random index in an array.
+   * @deprecated Use [`Num.randomRange`](#link) instead, for example `Math.floor( Num.randomRange( start, start + range ) )`.
+   * @param range value range
+   * @param start Optional starting value
+   */
+  static randomInt(range: number, start: number = 0) {
+    Util.warn("Util.randomInt is deprecated. Please use `Num.randomRange`");
+    return Math.floor(Num.random() * range) + start;
+  }
+
+  /**
+   * Split an array into chunks of sub-array.
+   * @param pts an array
+   * @param size chunk size, ie, number of items in a chunk
+   * @param stride optional parameter to "walk through" the array in steps
+   * @param loopBack if `true`, always go through the array till the end and loop back to the beginning to complete the segments if needed.
+   * @param matchSize if `true`, all chunks's length must match `size`.
+   */
+  static split(
+    pts: any[],
+    size: number,
+    stride?: number,
+    loopBack: boolean = false,
+    matchSize = true,
+  ): any[][] {
+    let chunks: any[] = [];
+    let part: any[] = [];
+    let st: number = stride || size;
+    let index: number = 0;
+    if (pts.length <= 0 || st <= 0) return [];
+
+    while (index < pts.length) {
+      part = [];
+      for (let k = 0; k < size; k++) {
+        if (loopBack) {
+          part.push(pts[(index + k) % pts.length]);
+        } else {
+          if (index + k >= pts.length) break;
+          part.push(pts[index + k]);
+        }
+      }
+      index += st;
+      if (!matchSize || (matchSize && part.length === size)) chunks.push(part);
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Flatten an array of arrays such as Group[] to a flat Array or Group.
+   * @param pts an array, usually an array of Groups
+   * @param flattenAsGroup a boolean to specify whether the return type should be a Group or Array. Default is `true` which returns a Group.
+   */
+  static flatten(pts: any[], flattenAsGroup: boolean = true): any {
+    // loop instead of concat.apply: spreading `pts` as arguments overflows
+    // the JS argument-count limit for very large inputs
+    const arr: unknown[] = flattenAsGroup ? new Group() : [];
+    for (let i = 0, len = pts.length; i < len; i++) {
+      const p = pts[i];
+      if (Array.isArray(p)) {
+        for (let k = 0, lenP = p.length; k < lenP; k++) arr.push(p[k]);
+      } else {
+        arr.push(p);
+      }
+    }
+    return arr;
+  }
+
+  /**
+   * Given two arrays of objects, and a function that operate on two objects, return an array. Objects must be of same type.
+   * @param a an array of object, eg `[Group, Group, ...]`
+   * @param b another array of object
+   * @param op a function that takes two parameters (a, b) and returns an object.
+   */
+  static combine<T>(a: T[], b: T[], op: (a: T, b: T) => T): T[] {
+    let result = [];
+    for (let i = 0, len = a.length; i < len; i++) {
+      for (let k = 0, lenB = b.length; k < lenB; k++) {
+        result.push(op(a[i], b[k]));
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Zip arrays. eg, `[[1,2],[3,4],[5,6]] => [[1,3,5],[2,4,6]]`.
+   * @param arrays an array of arrays
+   */
+  static zip(arrays: Array<any>[]) {
+    let z = [];
+    for (let i = 0, len = arrays[0].length; i < len; i++) {
+      let p = [];
+      for (let k = 0; k < arrays.length; k++) {
+        p.push(arrays[k][i]);
+      }
+      z.push(p);
+    }
+    return z;
+  }
+
+  /**
+   * Create a convenient stepper. This returns a function which you can call repeatedly to step a counter.
+   * @param max Maximum of the stepper range. The resulting stepper will return values within [min, max). Note that the first call returns `min + stride`, not `min`.
+   * @param min Minimum of the stepper range. Default is 0.
+   * @param stride Stride of the step. Default is 1.
+   * @param callback An optional callback function `fn( step )`, which will be called each time when stepper function is called.
+   * @example `let counter = stepper(100); let c = counter(); c = counter(); ...`
+   * @returns a function which will increment the stepper and return its value at each call.
+   */
+  static stepper(
+    max: number,
+    min: number = 0,
+    stride: number = 1,
+    callback?: (n: number) => void,
+  ): () => number {
+    let c = min;
+    return function () {
+      c += stride;
+      if (c >= max) {
+        // anchored modulo keeps c in [min, max) even when stride > max - min
+        c = min + ((c - min) % (max - min));
+      }
+      if (callback) callback(c);
+      return c;
+    };
+  }
+
+  /**
+   * A convenient way to step through a range. Same as `for (i=0; i<range; i++)`, except this also stores the resulting return values at each step and return them as an array.
+   * @param range a range to step through
+   * @param fn a callback function `fn(index)`. If this function returns a value, it will be stored at each step
+   * @returns an index-aligned array of returned values: entries sit at their step index, so with a non-zero `start` the positions below `start` are empty holes
+   */
+  static forRange(
+    fn: (index: number) => any,
+    range: number,
+    start: number = 0,
+    step: number = 1,
+  ): any[] {
+    let temp = [];
+    for (let i = start, len = range; i < len; i += step) {
+      temp[i] = fn(i);
+    }
+    return temp;
+  }
+
+  /**
+   * A helper function to load data from a url via XMLHttpRequest GET. Since the response passed into callback is a string, if you're loading json data, you may use standard `JSON.parse(response)` to get a JSON object. For csv, try using a javascript csv library like papaparse or vega/datalib.
+   * @param url the request url
+   * @param callback a function to capture the data. It receives two parameters: a `response` as string, and a `success` status as boolean.
+   */
+  static load(
+    url: string,
+    callback: (response: string, success: boolean) => void,
+  ) {
+    let request = new XMLHttpRequest();
+    request.open("GET", url, true);
+
+    request.onload = function () {
+      if (request.status >= 200 && request.status < 400) {
+        callback(request.responseText, true);
+      } else {
+        callback(
+          `Server error (${request.status}) when loading "${url}"`,
+          false,
+        );
+      }
+    };
+
+    request.onerror = function () {
+      callback(`Unknown network error`, false);
+    };
+
+    request.send();
+  }
+
+  /**
+   * Download the current `CanvasSpace` as an image (jpg/png/webp). Calling this function will automatically trigger a download.
+   * @param space an instance of `CanvasSpace`
+   * @param filename the name of the file, without the extension name.
+   * @param filetype the image type (jpg/png/webp)
+   * @param quality a value between 0 to 1, if filetype is either "jpg" or "png"
+   */
+  static download(
+    space: CanvasSpace,
+    filename: string = "pts_canvas_image",
+    filetype: "jpeg" | "jpg" | "png" | "webp" = "png",
+    quality: number = 1,
+  ) {
+    const ftype = filetype === "jpg" ? "jpeg" : filetype;
+    space.element.toBlob(
+      function (blob) {
+        const link = document.createElement("a");
+        // toBlob yields null on encoding failure; createObjectURL then throws
+        // a TypeError, same as it always has — kept, not silently swallowed
+        const url = URL.createObjectURL(blob!);
+        link.href = url;
+        link.download = `${filename}.${filetype}`;
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+        URL.revokeObjectURL(url);
+      },
+      `image/${ftype}`,
+      quality,
+    );
+  }
+
+  /**
+   * Estimate performance by checking how long it takes to render a frame
+   * @param avgFrames The number of frames used calculate to average
+   * @example `let perf = Util.performance(); perf();`
+   * @returns milliseconds per frame
+   */
+  static performance(avgFrames: number = 10): () => number {
+    let last = Date.now();
+    let avg = [];
+    return function () {
+      const now = Date.now();
+      avg.push(now - last);
+      if (avg.length > avgFrames) avg.shift();
+      last = now;
+      return Math.floor(avg.reduce((a, b) => a + b, 0) / avg.length);
+    };
+  }
+
+  /**
+   * Check number of items in a Group against a required number
+   * @param pts a Group or an Iterable<PtLike>
+   * @param minRequired minimum number of items required
+   */
+  static arrayCheck(pts: PtLikeIterable, minRequired: number = 2): boolean {
+    if (Array.isArray(pts) && pts.length < minRequired) {
+      Util.warn(`Requires ${minRequired} or more Pts in this Group.`);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Convert an iterable into an array
+   * @param it an iterable
+   */
+  static iterToArray(it: Iterable<any>): any[] {
+    return !Array.isArray(it) ? [...it] : it;
+  }
+
+  /**
+   * Check if accessing from a mobile device. Can be useful since some experimental features may not be availble in mobile browsers.
+   */
+  static isMobile() {
+    return /iPhone|iPad|Android/i.test(navigator.userAgent);
+  }
+
+  /**
+   * Generate a time-based unique ID or a crypto-based ID.
+   * @returns
+   */
+  static uniqueId(useCrypto = false) {
+    return useCrypto && typeof crypto !== "undefined" && crypto?.randomUUID
+      ? crypto.randomUUID()
+      : Date.now().toString(36) + Math.random().toString(36).substring(2);
+  }
+}

package/src/_module.ts

@@ -0,0 +1,18 @@
+export * from "./Canvas";
+export * from "./Create";
+export * from "./Form";
+export * from "./LinearAlgebra";
+export * from "./Num";
+export * from "./Op";
+export * from "./Pt";
+export * from "./Space";
+export * from "./Color";
+export * from "./Util";
+export * from "./Dom";
+export * from "./Svg";
+export * from "./Typography";
+export * from "./Physics";
+export * from "./Play";
+export * from "./UI";
+export * from "./Image";
+export * from "./Types";

package/src/_script.ts

@@ -0,0 +1,94 @@
+import * as Canvas from "./Canvas";
+import * as Create from "./Create";
+import * as Form from "./Form";
+import * as LinearAlgebra from "./LinearAlgebra";
+import * as Num from "./Num";
+import * as Op from "./Op";
+import * as Pt from "./Pt";
+import * as Space from "./Space";
+import * as Color from "./Color";
+import * as Util from "./Util";
+import * as Dom from "./Dom";
+import * as Svg from "./Svg";
+import * as Typography from "./Typography";
+import * as Physics from "./Physics";
+import * as UI from "./UI";
+import * as Play from "./Play";
+import * as Image from "./Image";
+import * as Types from "./Types";
+
+declare global {
+  // the browser bundle mounts the whole library on globalThis.Pts
+
+  var Pts: Record<string, any>;
+}
+
+globalThis.Pts = {
+  ...Canvas,
+  ...Create,
+  ...Form,
+  ...LinearAlgebra,
+  ...Num,
+  ...Op,
+  ...Pt,
+  ...Space,
+  ...Color,
+  ...Util,
+  ...Dom,
+  ...Svg,
+  ...Typography,
+  ...Physics,
+  ...UI,
+  ...Play,
+  ...Image,
+};
+
+// A function to switch scope for Pts library. eg, Pts.namespace( window );
+globalThis.Pts.namespace = (scope: any) => {
+  let lib = globalThis.Pts;
+  for (let k in lib) {
+    if (k != "namespace") {
+      scope[k] = lib[k];
+    }
+  }
+};
+
+globalThis.Pts.quickStart = (id: string | Element, bg: string = "#9ab") => {
+  if (!window) return;
+
+  let s: any = globalThis;
+  globalThis.Pts.namespace(s);
+
+  // pick the rendering backend from the mount element: an <svg> element (or a
+  // container holding one) gets an SVGSpace, anything else a CanvasSpace —
+  // so a sketch can swap renderers by changing only its HTML
+  // Preserve CanvasSpace's bare-ID shorthand for both rendering backends.
+  const mount =
+    typeof id === "string" && id[0] !== "#" && id[0] !== "." ? `#${id}` : id;
+  const elem =
+    typeof mount === "string" ? document.querySelector(mount) : mount;
+  const isSVG =
+    elem &&
+    ((elem as Element).nodeName.toLowerCase() === "svg" ||
+      !!(elem as Element).querySelector(":scope > svg"));
+
+  s.space = isSVG
+    ? new Svg.SVGSpace(mount).setup({ bgcolor: bg, resize: true })
+    : new Canvas.CanvasSpace(mount).setup({
+        bgcolor: bg,
+        resize: true,
+        retina: true,
+      });
+  s.form = s.space.getForm();
+
+  return function (animate = null, start = null, action = null, resize = null) {
+    s.space.add({
+      start: start,
+      animate: animate,
+      resize: resize,
+      action: action,
+    });
+
+    s.space.bindMouse().bindTouch().play();
+  };
+};