plotboilerplate 1.24.0 → 1.26.0

package/src/ts/utils/datastructures/ColorGradient.ts

@@ -0,0 +1,196 @@
+/**
+ * A simple linear color gradient implementation.
+ *
+ * A color gradient is just an array of color objects paired with position values on the gradient.
+ *
+ * TODO: add `angle`
+ *
+ * @author  Ikaros Kappler
+ * @version 1.0.0
+ * @date    2025-08-05
+ */
+
+import { Color } from "./Color";
+
+const RAD_TO_DEG: number = 180.0 / Math.PI;
+
+export type ColorGradientRotation = number | `${number}deg` | `${number}turn` | `to top` | "to bottom" | "to left" | "to right";
+
+const DEFAULT_COLORSET: Array<ColorGradientItem> = [
+  { color: Color.Red, ratio: 0.0 },
+  { color: Color.Gold, ratio: 0.2 },
+  { color: Color.Yellow, ratio: 0.4 },
+  { color: Color.LimeGreen, ratio: 0.6 },
+  { color: Color.MediumBlue, ratio: 0.8 },
+  { color: Color.Purple, ratio: 1.0 }
+];
+
+export interface ColorGradientItem {
+  color: Color;
+  ratio: number; // Ideally a percentage value in [0.0 .. 1.0]
+}
+
+export class ColorGradient {
+  values: Array<ColorGradientItem>;
+  angle: ColorGradientRotation;
+
+  /**
+   * Creates a new ColorGradient with the given values. Please be sure that the values appear in the correct
+   * order regarding the `ratio` information. This will not be validated.
+   *
+   * @param {Array<ColorGradientItem>} values - The values to use.
+   * @param {number?} angle - (optional) An optional angle for the gradient; if no specified `PI/2.0` will be used (vertical from left to right).
+   */
+  constructor(values: Array<ColorGradientItem>, angle?: ColorGradientRotation) {
+    this.values = values;
+    // Default: left to right
+    this.angle = typeof angle === "undefined" ? Math.PI / 2.0 : angle;
+  }
+
+  /**
+   * Get a color gradient CSS value string from these gradient settings.
+   *
+   * @instance
+   * @memberof ColorGradientPicker
+   * @returns {string}
+   */
+  public toColorGradientString(): string {
+    // Example:
+    //    linear-gradient(90deg,rgba(42, 123, 155, 1) 0%, rgba(87, 199, 133, 1) 38%, rgba(161, 210, 108, 1) 68%, rgba(237, 221, 83, 1) 100%)
+
+    // const buffer: Array<string | undefined> = [`linear-gradient( ${RAD_TO_DEG * this.angle}deg, `];
+    const buffer: Array<string | undefined> = [
+      `linear-gradient( ${typeof this.angle === "number" ? `${this.angle * RAD_TO_DEG}deg` : this.angle}, `
+    ];
+
+    for (var i = 0; i < this.values.length; i++) {
+      if (i > 0) {
+        buffer.push(",");
+      }
+      const colorValue: string = this.values[i] ? this.values[i].color.cssRGBA() : null;
+      buffer.push(colorValue);
+      const percentage = this.values[i].ratio;
+      buffer.push(`${typeof percentage === "number" ? `${percentage * 100}%` : percentage}`);
+    }
+    buffer.push(")");
+
+    return buffer.join(" ");
+  }
+
+  /**
+   * Get the color at the specific relative position.
+   *
+   * @param {number} ratio - Any value between 0.0 and 1.0.
+   */
+  getColorAt(ratio: number): Color {
+    // Locate interval first
+    const intervalLocation: [number, ColorGradientItem] = this.locateClosestRatio(ratio);
+    const leftItem: ColorGradientItem = this.values[intervalLocation[0]];
+    const rightItem: ColorGradientItem = this.values[intervalLocation[0] + 1];
+    const relativeInnerIntervalPosition: number = (ratio - leftItem.ratio) / (rightItem.ratio - leftItem.ratio);
+    return leftItem.color.clone().interpolate(rightItem.color, relativeInnerIntervalPosition);
+  }
+
+  /**
+   * Find that gradient record (index) that's value is closest to the given relative value. The function will return
+   * the closest value and the left index, indicating the containing interval index.
+   *
+   * @param {number} ratio - The value to look for.
+   * @returns {[number,number]} A pair of left interval boundary index and closest value.
+   */
+  locateClosestRatio(ratio: number): [number, ColorGradientItem] {
+    if (this.values.length === 0) {
+      console.warn("[Warn] All slider values array is empty. This should not happen, cannot proceed.");
+      return [NaN, null]; // This should not happen: at least two values must be present in a gradient
+    }
+    // console.log("__locateClosestSliderValue", "allSliderValues", allSliderValues);
+    let leftSliderIndex: number = 0;
+    let closestSliderValue: ColorGradientItem = this.values[leftSliderIndex];
+    for (var i = 1; i < this.values.length; i++) {
+      const curVal: ColorGradientItem = this.values[i];
+      if (Math.abs(curVal.ratio - ratio) < Math.abs(closestSliderValue.ratio - ratio)) {
+        closestSliderValue = curVal;
+        if (curVal.ratio > ratio) {
+          leftSliderIndex = i - 1;
+        } else {
+          leftSliderIndex = i;
+        }
+      }
+    }
+    return [leftSliderIndex, closestSliderValue];
+  }
+
+  /**
+   * Try to convert the given anonymous item (usually and object) to a ColorGradient. This method should be used
+   * to restore items from JSON parse results to convert them into proper ColorGradient instances.
+   *
+   * @param {any} item
+   * @returns {ColorGradient}
+   */
+  public static fromObject(item: any): ColorGradient {
+    if (typeof item !== "object") {
+      throw new Error(`Cannot instantiate ColorGradient from item: must be an object. (${typeof item})`);
+    }
+    if (!item.hasOwnProperty("values")) {
+      throw new Error("Cannot instantiate ColorGradient from object: missing property 'values'.");
+    }
+    const valuesObj: Array<object> = item.values;
+    if (!Array.isArray(valuesObj)) {
+      throw new Error("Cannot instantiate ColorGradient from object: property 'values' is not an array.");
+    }
+    const values: Array<ColorGradientItem> = valuesObj.map((element: object, index: number) => {
+      if (typeof element !== "object") {
+        throw new Error(`Cannot instantiate ColorGradient from object: item at index ${index} is not an object.`);
+      }
+      if (!element.hasOwnProperty("color") || !element.hasOwnProperty("ratio")) {
+        throw new Error(
+          `Cannot instantiate ColorGradient from object: item at index ${index} is missing 'color' or 'ratio' property.`
+        );
+      }
+      const tmpElement = element as ColorGradientItem;
+      return { color: Color.makeRGB(tmpElement.color.r, tmpElement.color.g, tmpElement.color.b), ratio: tmpElement.ratio };
+    });
+    // More checks possible here ...
+    return new ColorGradient(values, item.angle);
+  }
+
+  /**
+   * Clone this linear color gradient. Returns a deep clone.
+   *
+   * @returns {ColorGradient}
+   */
+  public clone(): ColorGradient {
+    return new ColorGradient(
+      this.values.map((item: ColorGradientItem) => {
+        return { color: item.color, ratio: item.ratio };
+      }),
+      this.angle
+    );
+  }
+
+  /**
+   * Create a default color gradient with six color: red, orange, yellow, green, blue, purple.
+   * @returns
+   */
+  public static createDefault(): ColorGradient {
+    return new ColorGradient(DEFAULT_COLORSET.map((item: ColorGradientItem) => ({ color: item.color, ratio: item.ratio })));
+  }
+
+  /**
+   * Create a basic color gradient from only two colors.
+   *
+   * @param {Color} startColor - The leftmost color.
+   * @param {Color} endColor - The rightmost color.
+   * @param {number?} angleInRadians - (optional) An optional angle for the gradient; if no specified `PI/2.0` will be used (vertical from left to right).
+   * @returns
+   */
+  public static createFrom(startColor: Color, endColor: Color, angleInRadians?: number): ColorGradient {
+    return new ColorGradient(
+      [
+        { ratio: 0.0, color: startColor },
+        { ratio: 1.0, color: endColor }
+      ],
+      angleInRadians
+    );
+  }
+}

package/src/ts/utils/datastructures/DataGrid2d.ts

@@ -18,6 +18,13 @@
 
 export type DataGridFace4<T> = [[T | null, T | null], [T | null, T | null]];
 
+export type RasterPosition = {
+  xIndex: number;
+  yIndex: number;
+  xRel?: number;
+  yRel?: number;
+};
+
 export interface IDataGrid2d<T> {
   readonly xSegmentCount: number;
 

package/src/ts/utils/datastructures/DataGrid2dArrayMatrix.ts

@@ -0,0 +1,182 @@
+/**
+ * A DataGrid2d implementation on 2 dimensional arrays.
+ *
+ * @author   Ikaros Kappler
+ * @date     2025-10-16
+ * @modified 2025-10-28 Added `DataGrid2dArrayMatrix.setAll(function)`.
+ * @modified 2025-10-28 Fixed a bug in the `DataGrid2dArrayMatrix.toString()` method.
+ * @version  1.0.0
+ **/
+
+import { arrayFill } from "../algorithms/arrayFill";
+import { DataGridFace4, IDataGrid2d, RasterPosition } from "./DataGrid2d";
+
+export class DataGrid2dArrayMatrix<T> implements IDataGrid2d<T> {
+  /**
+   * @override
+   */
+  readonly xSegmentCount: number;
+
+  /**
+   * @override
+   */
+  readonly ySegmentCount: number;
+
+  // This is not really useful here ...
+  minDataValue: T;
+  maxDataValue: T;
+
+  private _matrix: Array<Array<T>>;
+
+  /**
+   * Create a new DataGrid2d from the given
+   * @throws Error if xSegmentCount*ySegmentCount is larger than the capacity of the array/list.
+   * @param list
+   * @param xSegmentCount
+   * @param ySegmentCount
+   */
+  constructor(xSegmentCount: number, ySegmentCount: number, initialValue: T) {
+    if (xSegmentCount <= 0) {
+      throw `Cannot create DataGrid2dArray, xSegmentCount (${xSegmentCount}) must be > 0.`;
+    }
+    if (ySegmentCount <= 0) {
+      throw `Cannot create DataGrid2dArray, ySegmentCount (${ySegmentCount}) must be > 0.`;
+    }
+
+    // this.canvas = document.getElementById(canvasId);
+    this.xSegmentCount = xSegmentCount;
+    this.ySegmentCount = ySegmentCount;
+
+    this._matrix = [];
+    for (var i = 0; i < ySegmentCount; i++) {
+      this._matrix.push(arrayFill(xSegmentCount, initialValue));
+    }
+  }
+
+  /**
+   * Set the matrix value at the given (x,y) position to a new value.
+   *
+   * @param {number} xIndex - The horizontal matrix position to set.
+   * @param {number} yIndex - The vertical matrix position to set.
+   * @param {T} value - The new value.
+   */
+  public set(xIndex: number, yIndex: number, value: T) {
+    this._matrix[yIndex][xIndex] = value;
+  }
+
+  /**
+   * Getthe matrix value at the given (x,y) position.
+   *
+   * @param {number} xIndex - The horizontal matrix position to set.
+   * @param {number} yIndex - The vertical matrix position to set.
+   * @return {T} value - The new value.
+   */
+  public get(xIndex: number, yIndex: number): T {
+    return this.getDataValueAt(xIndex, yIndex);
+  }
+
+  /**
+   * Set all matrix values. The passed factory function must accept respective (x,y) positions.
+   *
+   * @param {Function} factory - The factory function to determine the new values to set.
+   * @return {DataGrid2dArrayMatrix<T>} this - for chaning.
+   */
+  public setAll(factory: (xIndex: number, yIndex: number) => T): DataGrid2dArrayMatrix<T> {
+    for (var x = 0; x < this.xSegmentCount; x++) {
+      for (var y = 0; y < this.ySegmentCount; y++) {
+        this.set(x, y, factory(x, y));
+      }
+    }
+    return this;
+  }
+
+  public find(
+    condition: (value: T, xIndex: number, yIndex: number, sourceMatrix: DataGrid2dArrayMatrix<T>) => boolean
+  ): RasterPosition {
+    for (var x = 0; x < this.xSegmentCount; x++) {
+      for (var y = 0; y < this.ySegmentCount; y++) {
+        if (condition(this.get(x, y), x, y, this)) {
+          return {
+            xIndex: x,
+            yIndex: y,
+            xRel: x / this.xSegmentCount,
+            yRel: y / this.ySegmentCount
+          };
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * @override
+   */
+  getMinDataValue(): T {
+    return this.minDataValue;
+  }
+
+  /**
+   * @override
+   */
+  getMaxDataValue(): T {
+    return this.maxDataValue;
+  }
+
+  /**
+   * @override
+   */
+  getDataValueAt(xIndex: number, yIndex: number, isDebug?: boolean): T | null {
+    return this._matrix[yIndex][xIndex];
+  }
+
+  /**
+   * @override
+   */
+  getDataFace4At(xIndex: number, yIndex: number, buffer: DataGridFace4<T>) {
+    // buffer: array[2][2]
+    buffer[0][0] = this.getDataValueAt(xIndex, yIndex);
+    buffer[1][0] = this.getDataValueAt(xIndex + 1, yIndex);
+    buffer[1][1] = this.getDataValueAt(xIndex + 1, yIndex + 1);
+    buffer[0][1] = this.getDataValueAt(xIndex, yIndex + 1);
+  }
+
+  /**
+   * A helper method to convert a boolean matrix to a parsable string.
+   *
+   * @param {DataGrid2dArrayMatrix<boolean>} matrix
+   * @returns {string}
+   */
+  static toString(matrix: DataGrid2dArrayMatrix<boolean>): string {
+    const buffer: Array<string> = [];
+    for (var y = 0; y < matrix.ySegmentCount; y++) {
+      for (var x = 0; x < matrix.xSegmentCount; x++) {
+        buffer.push(matrix.get(x, y) ? "X" : ".");
+      }
+      buffer.push("\n");
+    }
+    return buffer.join("");
+  }
+
+  /**
+   * Simple way to parse a data matrix from a string. `false` should be coded as '.' character,
+   * `true` must be coded as 'X' character.
+   *
+   * @param {string} str - The input string.
+   * @param {number} width - The desired width of the matrix (xSegmentCount).
+   * @param {number} height - The desired height of the matrix (ySegmentCount).
+   * @returns {DataGrid2dArrayMatrix<boolean>}
+   */
+  static parseBooleanMatrix(str: string, width: number, height: number): DataGrid2dArrayMatrix<boolean> {
+    const matrix = new DataGrid2dArrayMatrix<boolean>(width, height, false);
+    const lines: String[] = str.trim().split("\n");
+    for (var y = 0; y < lines.length && y < height; y++) {
+      lines[y] = lines[y].trim();
+      for (var x = 0; x < lines[y].length && x < width; x++) {
+        if (y < height && x < width && lines[y].charAt(x) === "X") {
+          matrix.set(x, y, true);
+        }
+      }
+    }
+    return matrix;
+  }
+}

package/src/ts/utils/datastructures/DataGrid2dListAdapter.ts

@@ -7,7 +7,7 @@
  * @version  1.0.0
  **/
 
-import { DataGridFace4, IDataGrid2d } from "./DataGrid2d";
+import { DataGridFace4, IDataGrid2d, RasterPosition } from "./DataGrid2d";
 
 type Triplet<T> = {
   x: T;
@@ -15,13 +15,6 @@ type Triplet<T> = {
   z: T;
 };
 
-type RasterPosition = {
-  xIndex: number;
-  yIndex: number;
-  xRel?: number;
-  yRel?: number;
-};
-
 export class DataGrid2dListAdapter<T> implements IDataGrid2d<T> {
   /**
    * @override
@@ -96,9 +89,9 @@ export class DataGrid2dListAdapter<T> implements IDataGrid2d<T> {
   getDataValueAt(xIndex: number, yIndex: number, isDebug?: boolean): T | null {
     // var bufferIndex = yIndex * this.xSegmentCount + xIndex;
     var bufferIndex = this.coordinateIndicesToBufferIndex(xIndex, yIndex);
-    if (isDebug) {
-      console.log("xIndex", xIndex, "yIndex", yIndex, "bufferIndex", bufferIndex);
-    }
+    // if (isDebug) {
+    //   console.log("xIndex", xIndex, "yIndex", yIndex, "bufferIndex", bufferIndex);
+    // }
     if (bufferIndex > this._dataList.length) {
       console.error("ERR buffer index is out of bounds! xIndex", xIndex, "yIndex", yIndex, "bufferIndex", bufferIndex);
     }

package/src/ts/utils/datastructures/GeometryMesh.ts

@@ -0,0 +1,79 @@
+/**
+ * Adapted from the 3D geometry datastuctured from demo-33 (depth mesh).
+ *
+ * Refactored the strucure into a class.
+ *
+ * @author   Ikaros Kappler
+ * @date     2025-11-14
+ * @modified 2025-11-17 Moved `getBounds` and `normalizeGeometry` from helper functions to this class.
+ * @version  1.0.0
+ */
+
+export type Vertex2 = { x: number; y: number };
+export type Vertex3 = { x: number; y: number; z: number };
+
+export class GeometryMesh<T extends Vertex2 | Vertex3> {
+  /**
+   * A set (array) of vertices (points) used in this mesh. Can be 2d or 3d.
+   *
+   * @member {Array<T>}
+   * @memberof GeometryMesh
+   * @type {Array<T>}
+   * @instance
+   */
+  vertices: Array<T>;
+
+  /**
+   * A set (array) of edges used in this mesh.
+   * Each edge consist of two indices indicating the vertex position.
+   *
+   * @member {Array<T>}
+   * @memberof GeometryMesh
+   * @type {Array<T>}
+   * @instance
+   */
+  edges: Array<[number, number]>;
+
+  constructor(vertices?: Array<T>, edges?: Array<[number, number]>) {
+    this.vertices = vertices || [];
+    this.edges = edges || [];
+  }
+
+  normalize() {
+    // Desired bounds is a max bounding box. The object will be scaled keeping aspect ratio
+    // in that way that the largest axis size touches the desired bounds.
+    var desiredBounds = { min: { x: -1, y: -1, z: -1 }, max: { x: 1, y: 1, z: 1 } };
+    var bounds = this.getGeometryBounds();
+    var sizeX = bounds.max.x - bounds.min.x;
+    var sizeY = bounds.max.y - bounds.min.y;
+    var sizeZ = bounds.max.z - bounds.min.z;
+    // Scale uniform so the dimension with the max expansion fits into [-1,1]
+    var maxDimension = Math.max(sizeX, sizeY, sizeZ);
+    var desiredSizeX = (desiredBounds.max.x - desiredBounds.min.x) / maxDimension;
+    var desiredSizeY = (desiredBounds.max.y - desiredBounds.min.y) / maxDimension;
+    var desiredSizeZ = (desiredBounds.max.z - desiredBounds.min.z) / maxDimension;
+    for (var i in this.vertices) {
+      var vert = this.vertices[i] as Vertex3; // TODO: Check if this is safe
+      vert.x = desiredBounds.min.x + (bounds.max.x - vert.x) * desiredSizeX;
+      vert.y = desiredBounds.min.y + (bounds.max.y - vert.y) * desiredSizeY;
+      vert.z = desiredBounds.min.z + (bounds.max.z - vert.z) * desiredSizeZ;
+    }
+  }
+
+  getGeometryBounds(): { min: Vertex3; max: Vertex3; width: number; height: number; depth: number } {
+    // var min = new Vert3(Number.MAX_VALUE, Number.MAX_VALUE, Number.MAX_VALUE);
+    // var max = new Vert3(Number.MIN_VALUE, Number.MIN_VALUE, Number.MIN_VALUE);
+    var min = { x: Number.MAX_VALUE, y: Number.MAX_VALUE, z: Number.MAX_VALUE };
+    var max = { x: Number.MIN_VALUE, y: Number.MIN_VALUE, z: Number.MIN_VALUE };
+    for (var i in this.vertices) {
+      var vert = this.vertices[i] as Vertex3;
+      min.x = Math.min(vert.x, min.x);
+      min.y = Math.min(vert.y, min.y);
+      min.z = Math.min(vert.z, min.z);
+      max.x = Math.max(vert.x, max.x);
+      max.y = Math.max(vert.y, max.y);
+      max.z = Math.max(vert.z, max.z);
+    }
+    return { min: min, max: max, width: max.x - min.x, height: max.y - min.y, depth: max.z - min.z };
+  }
+}

package/src/ts/utils/detectDarkMode.ts

@@ -9,20 +9,29 @@
  */
 
 export const detectDarkMode = (GUP?: Record<string, string>): boolean => {
+  var isDarkmode: boolean = false;
   // Respect overrides
   if (typeof GUP !== "undefined" && GUP.hasOwnProperty("darkmode") && GUP["darkmode"]) {
     // const overrideValue = PlotBoilerplate.utils.fetch.bool(GUP, "darkmode", null);
     const overrideValue = !!JSON.parse(GUP["darkmode"]);
     if (overrideValue !== null) {
-      return overrideValue;
+      isDarkmode = overrideValue;
     }
-  }
-  if (globalThis.matchMedia && globalThis.matchMedia("(prefers-color-scheme: dark)").matches) {
+  } else if (globalThis.matchMedia && globalThis.matchMedia("(prefers-color-scheme: dark)").matches) {
     // dark mode by system
-    return true;
+    isDarkmode = true;
+  } else {
+    // else: dark mode by daytime
+    const hours = new Date().getHours();
+    const isDayTime = hours > 6 && hours < 18;
+    isDarkmode = !isDayTime;
+  }
+
+  // console.log("Adding darkmode to <body>", isDarkmode);
+  if (isDarkmode && document.body) {
+    // Add darkmode class to <body> tag
+    document.body.classList.add("darkmode");
   }
-  // else: dark mode by daytime
-  const hours = new Date().getHours();
-  const isDayTime = hours > 6 && hours < 18;
-  return !isDayTime;
+
+  return isDarkmode;
 };