@matboks/utilities 0.0.1

package/dist/utilities/marching-squares.d.ts

@@ -0,0 +1,51 @@
+import * as MarchingSquares from "marching-squares";
+import { Vec2, Polygon, AABB } from "../geometry/index.js";
+type ContouringOptions = {
+    fn: (v: Vec2) => number;
+    extent: AABB;
+    resolution?: number | [number, number];
+    density?: number | [number, number];
+};
+type Interval = [number, number];
+type IsolineResult = {
+    isolines: Array<Polygon>;
+    level: number;
+};
+type Isoband = {
+    boundary: Polygon;
+    holes: Array<Polygon>;
+};
+type IsobandResult = {
+    isobands: Array<Isoband>;
+    interval: [number, number];
+};
+export declare class Contouring {
+    options: ContouringOptions;
+    surfaceFunction: (v: Vec2) => number;
+    extent: AABB;
+    cellSize: Vec2;
+    rows: number;
+    columns: number;
+    valueMatrix?: Array<Array<number>>;
+    quadTree?: MarchingSquares.QuadTree;
+    valueRange?: Interval;
+    constructor(options: ContouringOptions);
+    rowToYCoordinate(row: number): number;
+    columnToXCoordinate(column: number): number;
+    getValueMatrix(): number[][];
+    getValueRange(): Interval;
+    getQuadTree(): MarchingSquares.QuadTree;
+    rawPathToPolygon(rawVertices: Array<[number, number]>): Polygon;
+    createIntervals(options: CreateContouringIntervalsOptions): Array<Interval>;
+    isoline(levels: Array<number>): IsolineResult[];
+    isoband(intervals: Array<Interval>): IsobandResult[];
+}
+export type CreateContouringIntervalsOptions = {
+    n?: number;
+    density?: number;
+    lower?: number;
+    upper?: number;
+    overlap?: number;
+    padding?: number;
+};
+export {};

package/dist/utilities/marching-squares.js

@@ -0,0 +1,177 @@
+import * as MarchingSquares from "marching-squares";
+import { vec2, Polygon } from "../geometry/index.js";
+import { Resolution } from "./resolution.js";
+export class Contouring {
+    constructor(options) {
+        this.options = options;
+        const { extent, fn } = options;
+        const { width, height } = extent;
+        const { columns, rows } = computeResolution(options).toRowsAndColumns();
+        this.surfaceFunction = fn;
+        this.extent = extent;
+        this.columns = columns;
+        this.rows = rows;
+        this.cellSize = vec2(width / columns, height / rows);
+    }
+    rowToYCoordinate(row) {
+        const { cellSize, extent } = this;
+        return extent.yMin + (row + 0.5) * cellSize.y;
+    }
+    columnToXCoordinate(column) {
+        const { cellSize, extent } = this;
+        return extent.xMin + (column + 0.5) * cellSize.x;
+    }
+    getValueMatrix() {
+        if (this.valueMatrix)
+            return this.valueMatrix;
+        let minValue = Infinity, maxValue = -Infinity;
+        const { surfaceFunction, rows, columns } = this;
+        const values = [];
+        for (let row = 0; row < rows; row++) {
+            const rowValues = [];
+            const y = this.rowToYCoordinate(row);
+            for (let column = 0; column < columns; column++) {
+                const x = this.columnToXCoordinate(column);
+                const value = surfaceFunction(vec2(x, y));
+                rowValues.push(value);
+                if (value < minValue)
+                    minValue = value;
+                if (value > maxValue)
+                    maxValue = value;
+            }
+            values.push(rowValues);
+        }
+        this.valueMatrix = values;
+        this.valueRange = [minValue, maxValue];
+        return values;
+    }
+    getValueRange() {
+        if (!this.valueRange)
+            this.getValueMatrix();
+        return this.valueRange;
+    }
+    getQuadTree() {
+        return this.quadTree ?? (this.quadTree = new MarchingSquares.QuadTree(this.getValueMatrix()));
+    }
+    rawPathToPolygon(rawVertices) {
+        let vertices = [];
+        // First and last vertex are the same
+        for (let i = 0, n = rawVertices.length - 1; i < n; i++) {
+            const [column, row] = rawVertices[i];
+            vertices.push(vec2(this.columnToXCoordinate(column), this.rowToYCoordinate(row)));
+        }
+        return new Polygon(vertices);
+    }
+    createIntervals(options) {
+        const range = this.getValueRange();
+        let { n, density, lower = range[0], upper = range[1], overlap = 0, padding = 0 } = options;
+        if (n !== undefined && density !== undefined)
+            throw new Error("Either n or density must be specified");
+        let width = upper - lower;
+        if (padding > 0) {
+            lower += -0.5 * padding * width;
+            upper += 0.5 * padding * width;
+            width += padding * width;
+        }
+        const numThresholds = n ?? Math.round(density * width);
+        if (numThresholds < 2)
+            return [[lower, upper]];
+        const bandwidth = width / ((1 - overlap) * numThresholds + overlap);
+        const step = (width - bandwidth) / (numThresholds - 1);
+        let intervals = [];
+        for (let i = 0; i < numThresholds; i++) {
+            const intervalLower = lower + i * step;
+            intervals.push([intervalLower, intervalLower + bandwidth]);
+        }
+        return intervals;
+    }
+    isoline(levels) {
+        const quadTree = this.getQuadTree();
+        let results = [];
+        for (const level of levels) {
+            const [rings] = MarchingSquares.isoLines(quadTree, [level]);
+            const isolines = [];
+            for (const ring of rings)
+                isolines.push(this.rawPathToPolygon(ring));
+            results.push({ isolines, level });
+        }
+        return results;
+    }
+    isoband(intervals) {
+        const quadTree = this.getQuadTree();
+        let results = [];
+        for (const [lower, upper] of intervals) {
+            const [rings] = MarchingSquares.isoBands(quadTree, [lower], [upper - lower]);
+            const polygons = [];
+            for (const ring of rings)
+                polygons.push(this.rawPathToPolygon(ring));
+            results.push({ isobands: determineBoundariesAndHoles(polygons), interval: [lower, upper] });
+        }
+        return results;
+    }
+}
+function computeResolution(options) {
+    const { resolution, density, extent } = options;
+    if (resolution !== undefined && density !== undefined)
+        throw new Error("Only one of resolution and density must be specified");
+    if (resolution === undefined && density === undefined)
+        throw new Error("One of resolution and density must be specified");
+    const { width, height } = extent;
+    const aspectRatio = width / height;
+    let columns, rows;
+    if (density) {
+        const [columnDensity, rowDensity] = Array.isArray(density) ? density : [density, density];
+        columns = Math.round(columnDensity * width);
+        rows = Math.round(rowDensity * height);
+    }
+    else {
+        if (Array.isArray(resolution)) {
+            [columns, rows] = resolution;
+        }
+        else {
+            [columns, rows] = aspectRatio > 1 ?
+                [resolution, Math.round(resolution / aspectRatio)] :
+                [Math.round(resolution * aspectRatio), resolution];
+        }
+    }
+    return new Resolution(columns, rows);
+}
+function determineBoundariesAndHoles(polygons) {
+    const n = polygons.length;
+    let isobands = [];
+    const isIndexProcessedMap = {};
+    polygons.sort((a, b) => b.area() - a.area());
+    function helper(activeShape, isHole, index) {
+        let holes = [];
+        for (let i = index + 1; i < n; i++) {
+            if (isIndexProcessedMap[i])
+                continue;
+            const candidate = polygons[i];
+            // Enough to check if a single vertex is inside parent shape
+            const isContained = activeShape.aabb().contains(candidate.aabb()) &&
+                candidate.vertices.some((v) => activeShape.isPointInside(v));
+            if (isContained) {
+                helper(candidate, !isHole, i);
+                isIndexProcessedMap[i] = true;
+            }
+            else {
+                continue;
+            }
+            if (!isHole) {
+                candidate.makeClockwise();
+                holes.push(candidate);
+            }
+        }
+        if (isHole)
+            return;
+        activeShape.makeCounterClockwise();
+        isobands.push({ boundary: activeShape, holes });
+    }
+    for (let i = 0; i < n; i++) {
+        const boundary = polygons[i];
+        if (isIndexProcessedMap[i])
+            continue;
+        helper(boundary, false, i);
+    }
+    return isobands;
+}

package/dist/utilities/point-sampler.d.ts

@@ -0,0 +1,12 @@
+import { AABB } from "../geometry/aabb.js";
+import { Hollowgon } from "../geometry/hollowgon.js";
+import { Polygon } from "../geometry/polygon.js";
+import { RNG } from "./rng.js";
+export type PointSamplerStrategy = "uniform" | "poisson";
+export type PointSamplerOptions = {
+    size: number;
+    strategy: PointSamplerStrategy;
+    shape: Polygon | Hollowgon | AABB;
+    rng: RNG;
+};
+export declare function pointSampler(options: PointSamplerOptions): import("../index.js").Vec2[];

package/dist/utilities/point-sampler.js

@@ -0,0 +1,24 @@
+import { AABB } from "../geometry/aabb.js";
+import { Poissonnier } from "./poisson/poissonnier.js";
+export function pointSampler(options) {
+    const { size, strategy, shape, rng } = options;
+    const isAABB = shape instanceof AABB;
+    if (strategy === "poisson") {
+        // TODO polygon is approximate for now
+        const aabb = isAABB ? shape : shape.aabb();
+        const sampleSize = isAABB ? size : Math.ceil(size * aabb.area / shape.area());
+        const aabbSample = Poissonnier.generateFixedSizeSample({
+            extent: shape instanceof AABB ? shape : shape.aabb(),
+            sampleSize,
+            rng
+        });
+        return isAABB ? aabbSample : aabbSample.filter((v) => shape.isPointInside(v));
+    }
+    else if (strategy === "uniform") {
+        const sampler = isAABB ? () => rng.pointInAABB(shape) : () => rng.pointInPolygon(shape);
+        return Array(size).fill(null).map(sampler);
+    }
+    else {
+        throw new Error(`Invalid strategy ${strategy}`);
+    }
+}

package/dist/utilities/poisson/grid.d.ts

@@ -0,0 +1,21 @@
+import { AABB, Vec2 } from "../../geometry/index.js";
+type GridResolution = {
+    columns: number;
+    rows: number;
+};
+export declare class LookupGrid {
+    extent: AABB;
+    minimumDistance: number;
+    isVariable: boolean;
+    resolution: GridResolution;
+    cellSize: Vec2;
+    occupied: Array<Vec2>;
+    constructor(extent: AABB, minimumDistance: number, isVariable: boolean);
+    computeGridPosition(p: Vec2): {
+        column: number;
+        row: number;
+    };
+    validatePosition(p: Vec2, radius: number): boolean;
+    addToGrid(p: Vec2): void;
+}
+export {};

package/dist/utilities/poisson/grid.js

@@ -0,0 +1,51 @@
+import { vec2 } from "../../geometry/index.js";
+const { ceil, max, min } = Math;
+export class LookupGrid {
+    constructor(extent, minimumDistance, isVariable) {
+        this.extent = extent;
+        this.isVariable = isVariable;
+        this.minimumDistance = minimumDistance;
+        const { xMin, xMax, yMin, yMax } = extent;
+        const gridSize = minimumDistance / 2 ** 0.5;
+        const width = xMax - xMin;
+        const height = yMax - yMin;
+        const rows = ceil(height / gridSize);
+        const columns = ceil(width / gridSize);
+        this.resolution = { columns, rows };
+        this.occupied = [];
+        this.cellSize = vec2(width / columns, height / rows);
+    }
+    computeGridPosition(p) {
+        const { extent, cellSize } = this;
+        const column = (p.x - extent.xMin) / cellSize.x | 0;
+        const row = (p.y - extent.yMin) / cellSize.y | 0;
+        return { column, row };
+    }
+    validatePosition(p, radius) {
+        const { extent, resolution: { columns, rows }, cellSize } = this;
+        if (!extent.isPointInside(p))
+            return false;
+        const radius2 = radius ** 2;
+        const { column, row } = this.computeGridPosition(p);
+        let dX = 1;
+        let dY = 1;
+        if (this.isVariable) {
+            dX = ((radius / cellSize.x) | 0) + 1;
+            dY = ((radius / cellSize.y) | 0) + 1;
+        }
+        let i0 = max(0, row - dY), i1 = min(rows - 1, row + dY), j0 = max(0, column - dX), j1 = min(columns - 1, column + dX);
+        for (let i = i0; i <= i1; i++) {
+            for (let j = j0; j <= j1; j++) {
+                const existingPoint = this.occupied[i * columns + j];
+                if (existingPoint && p.distanceSquared(existingPoint) < radius2)
+                    return false;
+            }
+        }
+        return true;
+    }
+    addToGrid(p) {
+        const { resolution: { columns } } = this;
+        const { column, row } = this.computeGridPosition(p);
+        this.occupied[row * columns + column] = p;
+    }
+}

package/dist/utilities/poisson/poissonnier.d.ts

@@ -0,0 +1,50 @@
+import { AABB, Vec2 } from "../../geometry/index.js";
+import { RNG } from "../rng.js";
+import { LookupGrid } from "./grid.js";
+export type PoissonnierOptions = {
+    extent: AABB;
+    minDistance: number;
+    distanceFunction?: (v: Vec2) => number;
+    maxScale?: number;
+    attempts?: number;
+    rng: RNG;
+};
+export type PointData = {
+    point: Vec2;
+    value: number;
+    distance: number;
+};
+export declare class Poissonnier {
+    extent: AABB;
+    minDistance: number;
+    distanceRange: number;
+    distanceFunction?: (v: Vec2) => number;
+    attempts: number;
+    rng: RNG;
+    grid: LookupGrid;
+    sampleData: Array<PointData>;
+    activeIndex: number;
+    private activeGenerator;
+    constructor(options: PoissonnierOptions);
+    static generateFixedSizeSample(options: GenerateFixedSizeSampleOptions): Vec2[];
+    private initialize;
+    addPoint(point: Vec2): {
+        point: Vec2;
+        value: number;
+        distance: number;
+    };
+    private internalAddPoint;
+    private createGenerator;
+    getNext(): PointData | undefined;
+    getAll(): PointData[];
+    private sampleCandidate;
+    [Symbol.iterator](): {
+        next: () => IteratorResult<PointData, undefined>;
+    };
+}
+export type GenerateFixedSizeSampleOptions = {
+    extent: AABB;
+    sampleSize: number;
+    rng: RNG;
+    padding?: number;
+};

package/dist/utilities/poisson/poissonnier.js

@@ -0,0 +1,118 @@
+import { EPS } from "../../constants.js";
+import { AABB, Vec2, vec2 } from "../../geometry/index.js";
+import { LookupGrid } from "./grid.js";
+const { sin, cos, PI, sqrt, max } = Math;
+const TWO_PI = 2 * PI;
+// add padding (make extent smaller)
+// periodicity (lets columns and rows wrap around)
+export class Poissonnier {
+    constructor(options) {
+        this.sampleData = []; // Stores points accepted into the grid
+        this.activeIndex = 0;
+        const { extent, minDistance, maxScale = 2, distanceFunction, attempts = 20, rng } = options;
+        if (maxScale < 1)
+            throw new Error("maxScale can not be less than 1");
+        this.extent = extent;
+        this.minDistance = minDistance;
+        this.distanceRange = distanceFunction ? (maxScale * minDistance - minDistance) : 0;
+        this.distanceFunction = distanceFunction;
+        this.rng = rng;
+        this.grid = new LookupGrid(extent, minDistance, distanceFunction !== undefined);
+        this.attempts = attempts;
+        this.activeGenerator = this.createGenerator();
+    }
+    static generateFixedSizeSample(options) {
+        return generateFixedSizeSample(options);
+    }
+    initialize() {
+        const { extent, rng, grid, minDistance, distanceRange } = this;
+        const paddedExtent = extent.clone().grow(-2 * (minDistance + distanceRange));
+        const startPoint = rng.pointInAABB(paddedExtent);
+        grid.addToGrid(startPoint);
+        return this.internalAddPoint(startPoint);
+    }
+    addPoint(point) {
+        return this.internalAddPoint(point, true);
+    }
+    internalAddPoint(point, ensureInside = false) {
+        const { distanceFunction, distanceRange, minDistance } = this;
+        if (ensureInside && !this.extent.isPointInside(point))
+            throw new Error(`Added point is outside extent ${this.extent}`);
+        this.grid.addToGrid(point);
+        const value = distanceFunction?.(point) ?? 0;
+        const distance = minDistance + distanceRange * value;
+        const data = { point, value, distance };
+        this.sampleData.push(data);
+        return data;
+    }
+    *createGenerator() {
+        if (this.sampleData.length === 0)
+            yield this.initialize();
+        while (this.activeIndex < this.sampleData.length) {
+            let { point, distance } = this.sampleData[this.activeIndex];
+            // Add eps to ensure that distance check only fails when the distance is actually larger than threshold
+            const candidateDistance = distance + EPS;
+            for (let candidateIndex = 0, n = this.attempts; candidateIndex < n; candidateIndex++) {
+                const candidate = this.sampleCandidate(point, candidateDistance);
+                const isValid = this.grid.validatePosition(candidate, distance);
+                if (!isValid)
+                    continue;
+                yield this.internalAddPoint(candidate);
+            }
+            this.activeIndex++;
+        }
+        return undefined;
+    }
+    getNext() {
+        const { value } = this.activeGenerator.next();
+        return value;
+    }
+    getAll() {
+        while (this.getNext()) { }
+        return this.sampleData;
+    }
+    sampleCandidate(origin, distance) {
+        const theta = TWO_PI * this.rng();
+        return vec2(origin.x + distance * cos(theta), origin.y + distance * sin(theta));
+    }
+    [Symbol.iterator]() {
+        return {
+            next: () => this.activeGenerator.next()
+        };
+    }
+}
+// Idea: Generate sample for slightly larger extent,
+// using the heuristic distance = constant * sqrt(area / sampleSize)
+// where constant is roughly 0.82 for typical setups.
+// Then pick out sampleSize points and rescale to fill the original extent
+// Does not work well for extreme aspect ratios
+function generateFixedSizeSample(options) {
+    const { extent, sampleSize, rng, padding = 0.5 } = options;
+    const { width, height, center, aspectRatio, area } = extent;
+    const distance = 0.95 * sqrt(area / sampleSize);
+    const paddedExtent = extent.clone().grow(vec2(width, height).times(0.05));
+    let sample;
+    while (true) {
+        sample = new Poissonnier({
+            extent: paddedExtent, minDistance: distance, rng
+        }).getAll();
+        if (sample.length >= sampleSize)
+            break;
+    }
+    const sortData = sample.map(({ point }) => {
+        const diff = Vec2.subtract(point, center).absolute();
+        const value = max(diff.x, aspectRatio * diff.y);
+        return { point, value };
+    });
+    sortData.sort((a, b) => a.value - b.value);
+    let points = [];
+    const candidatesAABB = AABB.placeholder();
+    for (let i = 0; i < sampleSize; i++) {
+        const { point } = sortData[i];
+        candidatesAABB.update(point);
+        points.push(point);
+    }
+    const paddingAmount = padding * distance;
+    candidatesAABB.grow(rng(-paddingAmount, 0), rng(0, paddingAmount), rng(-paddingAmount, 0), rng(0, paddingAmount));
+    return points.map((p) => extent.mapFromUV(candidatesAABB.mapToUV(p)));
+}

package/dist/utilities/resolution.d.ts

@@ -0,0 +1,10 @@
+export declare class Resolution {
+    width: number;
+    height: number;
+    constructor(width: number, height: number);
+    toRowsAndColumns(): {
+        columns: number;
+        rows: number;
+    };
+    toVec2(): import("../geometry/vec2.js").Vec2;
+}

package/dist/utilities/resolution.js

@@ -0,0 +1,14 @@
+import { vec2 } from "../geometry/vec2.js";
+export class Resolution {
+    constructor(width, height) {
+        this.width = width;
+        this.height = height;
+    }
+    toRowsAndColumns() {
+        const { width, height } = this;
+        return { columns: width, rows: height };
+    }
+    toVec2() {
+        return vec2(this.width, this.height);
+    }
+}

package/dist/utilities/rng.d.ts

@@ -0,0 +1,13 @@
+import { AABB, Hollowgon, Polygon, Vec2 } from "../geometry/index.js";
+export declare function hash(value: number, seed: number): number;
+export type RNG = ReturnType<typeof createRNG>;
+export declare function createRNG(seed: number | (() => number)): ((min?: number, max?: number) => number) & {
+    integer: (lower: number, upper?: number) => number;
+    sample: <T>(array: Array<T>) => T;
+    sampleWeighted: <const E extends readonly (readonly [any, number])[]>(entries: E) => E[number][0];
+    shuffle: <T extends Array<any>>(array: T) => T;
+    pointInPolygon: (polygon: Polygon | Hollowgon) => Vec2;
+    pointInDisk: (center: Vec2, radius: number) => Vec2;
+    pointInAABB: (aabb: AABB) => Vec2;
+    reset: () => void;
+};

package/dist/utilities/rng.js

@@ -0,0 +1,80 @@
+import { Vec2, vec2 } from "../geometry/index.js";
+const { imul, floor, sqrt, PI } = Math;
+const MAGIC_NUMBER = 0x9E3779B9;
+export function hash(value, seed) {
+    value = (value + MAGIC_NUMBER * seed) | 0;
+    value += 0x7ED55D16;
+    value ^= value >>> 12;
+    value = imul(value, 0xC761C23C);
+    value ^= value >>> 19;
+    return value >>> 0;
+}
+export function createRNG(seed) {
+    const initialState = typeof seed === "function" ? floor(MAGIC_NUMBER * seed()) : seed;
+    let state = initialState;
+    function next() {
+        state = hash(state, 0);
+        return state / 4294967296;
+    }
+    const rng = (min, max) => {
+        if (min === undefined || max === undefined)
+            [min, max] = [0, 1];
+        return min + (max - min) * next();
+    };
+    const integer = (lower, upper) => {
+        [lower, upper] = upper === undefined ? [0, lower] : [lower, upper];
+        return lower + floor((upper - lower + 1) * next());
+    };
+    const sample = (array) => {
+        return array[integer(0, array.length - 1)];
+    };
+    const sampleWeighted = (entries) => {
+        let weightSum = 0;
+        for (const entry of entries)
+            weightSum += entry[1];
+        const value = rng() * weightSum;
+        let cumulativeWeight = 0;
+        for (const [data, weight] of entries) {
+            cumulativeWeight += weight;
+            if (value < cumulativeWeight)
+                return data;
+        }
+        return entries[entries.length - 1][0];
+    };
+    const shuffle = (array) => {
+        const n = array.length;
+        for (let i = n - 1; i > 0; i--) {
+            const j = integer(0, i);
+            [array[i], array[j]] = [array[j], array[i]];
+        }
+        return array;
+    };
+    const pointInDisk = (center, radius) => {
+        return Vec2.fromPolar(radius * sqrt(rng()), rng(0, 2 * PI)).plus(center);
+    };
+    const pointInPolygon = (polygon) => {
+        const { xMin, xMax, yMin, yMax } = polygon.aabb();
+        while (true) {
+            const point = vec2(rng(xMin, xMax), rng(yMin, yMax));
+            if (polygon.isPointInside(point))
+                return point;
+        }
+    };
+    const pointInAABB = (aabb) => {
+        const { xMin, xMax, yMin, yMax } = aabb;
+        return vec2(rng(xMin, xMax), rng(yMin, yMax));
+    };
+    const reset = () => {
+        state = initialState;
+    };
+    return Object.assign(rng, {
+        integer,
+        sample,
+        sampleWeighted,
+        shuffle,
+        pointInPolygon,
+        pointInDisk,
+        pointInAABB,
+        reset
+    });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@matboks/utilities",
+  "version": "0.0.1",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "author": "",
+  "type": "module",
+  "license": "MIT",
+  "description": "",
+  "dependencies": {
+    "d3-delaunay": "^6.0.4",
+    "earcut": "^3.0.2",
+    "glsl-modules": "^0.5.0",
+    "marching-squares": "^1.0.0",
+    "polyclip-ts": "^0.16.8"
+  },
+  "devDependencies": {
+    "@types/d3-delaunay": "^6.0.4",
+    "@types/earcut": "^3.0.0",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}