@expofp/geometry 3.8.0

package/dist/lib/mesh.js

@@ -0,0 +1,162 @@
+import { Box } from './box.js';
+import { Point } from './point.js';
+/**
+ * A 3D triangle mesh: vertices carry an optional z coordinate, plus triangle index triplets.
+ * Immutable value object: readonly getters; transforms return a new instance unless a `target`
+ * is passed. For a planar triangulated polygon with area/containment use `Polygon` instead.
+ */
+export class Mesh {
+    /** Marker so callers can narrow the type at runtime. */
+    isMesh = true;
+    /** Internal mutable vertex array (3D). */
+    _vertices = [];
+    /** Internal triangle index array. */
+    _indices = [];
+    /** Cached axis-aligned bounding box (xy only). */
+    _bounds = new Box();
+    /**
+     * Constructs a mesh from a vertex list and triangle index triplets.
+     * @param vertices - source vertices; each is cloned into a {@link Point} (default `[]`)
+     * @param indices - triangle index triplets referencing positions in `vertices` (default `[]`)
+     */
+    constructor(vertices = [], indices = []) {
+        this.set(vertices, indices);
+    }
+    /**
+     * Readonly array of mesh vertices as {@link Point} instances.
+     * @returns the vertex array
+     */
+    get vertices() {
+        return this._vertices;
+    }
+    /**
+     * Readonly array of triangle index triplets.
+     * @returns the index array
+     */
+    get indices() {
+        return this._indices;
+    }
+    /**
+     * Cached axis-aligned bounding {@link Box} of this mesh (xy only, z ignored).
+     * @returns the bounding box
+     */
+    get bounds() {
+        return this._bounds;
+    }
+    /**
+     * Mutates this mesh in place, replacing vertices/indices and refreshing the cached bounds.
+     * Vertices are copied into fresh {@link Point}s — do not optimize this clone away; transform
+     * free functions rely on it to avoid aliasing shared vertices. Use only for hot-path reuse.
+     * @param vertices - new vertex list
+     * @param indices - new triangle index list
+     * @returns `this`
+     */
+    set(vertices, indices) {
+        this._vertices = vertices.map((v) => new Point(v.x, v.y, v.z ?? 0));
+        this._indices = indices;
+        this._bounds = meshBounds(this);
+        return this;
+    }
+    /**
+     * Merges two or more meshes into a single {@link Mesh}, offsetting each mesh's triangle indices
+     * by the cumulative vertex count so they remain valid. Forwards to {@link meshMerge}.
+     * @param meshes - meshes to merge
+     * @returns a new merged mesh
+     */
+    static merge(...meshes) {
+        return meshMerge(meshes);
+    }
+    /**
+     * Returns a new mesh translated by `offset`. Forwards to {@link meshTranslate}.
+     * @param offset - translation vector
+     * @param target - optional mesh to write into instead of allocating a new one
+     * @returns translated mesh
+     */
+    translate(offset, target) {
+        return meshTranslate(this, offset, target ?? new Mesh());
+    }
+    /**
+     * Returns a new mesh scaled by `factor` about `origin`. Forwards to {@link meshScale}.
+     * @param factor - uniform scale or per-axis `{ x, y }` scale
+     * @param origin - the fixed point of the scaling; defaults to the bounding-box center
+     * @param target - optional mesh to write into instead of allocating a new one
+     * @returns scaled mesh
+     */
+    scale(factor, origin = this._bounds.center, target) {
+        return meshScale(this, factor, origin, target ?? new Mesh());
+    }
+    /**
+     * Returns a new mesh rotated by `angle` radians about `origin`. Forwards to {@link meshRotate}.
+     * @param angle - rotation angle in radians (positive = clockwise in y-down space)
+     * @param origin - the pivot of the rotation; defaults to the bounding-box center
+     * @param target - optional mesh to write into instead of allocating a new one
+     * @returns rotated mesh
+     */
+    rotate(angle, origin = this._bounds.center, target) {
+        return meshRotate(this, angle, origin, target ?? new Mesh());
+    }
+}
+/**
+ * Computes the axis-aligned bounding {@link Box} of a mesh by sweeping all vertex xy coordinates.
+ * The z component is ignored — bounds are always in the xy plane.
+ * @param m - mesh or mesh-like object
+ * @returns the bounding box
+ */
+export function meshBounds(m) {
+    if (m.vertices.length === 0)
+        return new Box();
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const v of m.vertices) {
+        minX = Math.min(minX, v.x);
+        minY = Math.min(minY, v.y);
+        maxX = Math.max(maxX, v.x);
+        maxY = Math.max(maxY, v.y);
+    }
+    return Box.fromMinMax({ x: minX, y: minY }, { x: maxX, y: maxY });
+}
+export function meshMerge(meshes, target) {
+    const vertices = [];
+    const indices = [];
+    let offset = 0;
+    for (const m of meshes) {
+        for (const v of m.vertices)
+            vertices.push(v);
+        for (const [a, b, c] of m.indices)
+            indices.push([a + offset, b + offset, c + offset]);
+        offset += m.vertices.length;
+    }
+    return (target ?? new Mesh()).set(vertices, indices);
+}
+export function meshTranslate(m, offset, target) {
+    const dz = offset.z ?? 0;
+    const vertices = m.vertices.map((v) => ({
+        x: v.x + offset.x,
+        y: v.y + offset.y,
+        z: (v.z ?? 0) + dz,
+    }));
+    return (target ?? new Mesh()).set(vertices, m.indices);
+}
+export function meshScale(m, factor, origin = meshBounds(m).center, target) {
+    const fx = typeof factor === 'number' ? factor : factor.x;
+    const fy = typeof factor === 'number' ? factor : factor.y;
+    const vertices = m.vertices.map((v) => ({
+        x: origin.x + (v.x - origin.x) * fx,
+        y: origin.y + (v.y - origin.y) * fy,
+        z: v.z ?? 0,
+    }));
+    return (target ?? new Mesh()).set(vertices, m.indices);
+}
+export function meshRotate(m, angle, origin = meshBounds(m).center, target) {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const vertices = m.vertices.map((v) => {
+        const dx = v.x - origin.x;
+        const dy = v.y - origin.y;
+        return {
+            x: origin.x + dx * cos - dy * sin,
+            y: origin.y + dx * sin + dy * cos,
+            z: v.z ?? 0,
+        };
+    });
+    return (target ?? new Mesh()).set(vertices, m.indices);
+}

package/dist/lib/point.d.ts

@@ -0,0 +1,206 @@
+/** A 2D point/vector `{ x, y }`. */
+export interface Point2Like {
+    /** Horizontal coordinate. */
+    readonly x: number;
+    /** Vertical coordinate. */
+    readonly y: number;
+}
+/** A 3D point/vector `{ x, y, z }`. */
+export interface Point3Like {
+    /** Horizontal coordinate. */
+    readonly x: number;
+    /** Vertical coordinate. */
+    readonly y: number;
+    /** Depth coordinate. */
+    readonly z: number;
+}
+/** Any structural point — `z` optional. */
+export interface PointLike {
+    /** Horizontal coordinate. */
+    readonly x: number;
+    /** Vertical coordinate. */
+    readonly y: number;
+    /** Depth coordinate (optional). */
+    readonly z?: number;
+}
+/**
+ * A readonly 2D vector that also exposes `width`/`height` aliases of `x`/`y` — the return type of the
+ * `size` getter on {@link Box} and {@link Rect}. Backed by a {@link Point} (which provides the
+ * aliases), so `size.x`/`size.width` and `size.y`/`size.height` both read the same value.
+ */
+export type SizeLike = Readonly<Point2Like> & {
+    readonly width: number;
+    readonly height: number;
+};
+/**
+ * Mutable point/vector — the low-level building block other primitives and the point free functions
+ * write into. `width`/`height` alias `x`/`y` so a point used as a size reads naturally.
+ */
+export declare class Point {
+    /** Marker so callers can narrow the type at runtime. */
+    readonly isPoint = true;
+    /** Horizontal coordinate. */
+    x: number;
+    /** Vertical coordinate. */
+    y: number;
+    /** Depth coordinate. */
+    z: number;
+    /**
+     * @param x - horizontal coordinate (default 0)
+     * @param y - vertical coordinate (default 0)
+     * @param z - depth coordinate (default 0)
+     */
+    constructor(x?: number, y?: number, z?: number);
+    /**
+     * Alias of {@link Point.x}.
+     * @returns the x coordinate
+     */
+    get width(): number;
+    /**
+     * Alias of {@link Point.y}.
+     * @returns the y coordinate
+     */
+    get height(): number;
+    /**
+     * Sets coordinates in place.
+     * @param x - horizontal coordinate
+     * @param y - vertical coordinate
+     * @param z - depth coordinate (defaults to the current z)
+     * @returns this
+     */
+    set(x: number, y: number, z?: number): this;
+    /**
+     * Copies from another point in place.
+     * @param p - source point to copy coordinates from
+     * @returns this
+     */
+    copy(p: PointLike): this;
+    /**
+     * Returns an independent copy, or writes into `target` if provided. See {@link pointLerp} for the
+     * underlying free function.
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the copy
+     */
+    clone(target?: Point): Point;
+    /**
+     * True when `p` has the same coordinates.
+     * @param p - point to compare against
+     * @returns true when all coordinates are equal
+     */
+    equals(p: PointLike): boolean;
+    /**
+     * Distance to `p`. See {@link pointDistance} for the underlying free function.
+     * @param p - target point
+     * @returns the distance
+     */
+    distanceTo(p: PointLike): number;
+    /**
+     * Interpolate toward `p` by `t`. See {@link pointLerp} for the underlying free function.
+     * @param p - target point
+     * @param t - interpolation factor (0 = this, 1 = p)
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    lerp(p: PointLike, t: number, target?: Point): Point;
+    /**
+     * Rotate by `angle` radians around `origin`. See {@link pointRotate} for the underlying free
+     * function.
+     * @param angle - radians to rotate (positive = clockwise, y-down)
+     * @param origin - rotation pivot point
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    rotate(angle: number, origin: Point2Like, target?: Point): Point;
+    /**
+     * Shift by `length` along `angle` radians. See {@link pointShift} for the underlying free function.
+     * @param length - distance to shift
+     * @param angle - direction in radians
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    shift(length: number, angle: number, target?: Point): Point;
+    /**
+     * Angle (radians) at this point between rays to `a` and `b`. See {@link pointAngleBetween} for
+     * the underlying free function.
+     * @param a - first ray endpoint
+     * @param b - second ray endpoint
+     * @returns the signed angle in radians (positive = clockwise, y-down)
+     */
+    angleBetween(a: Point2Like, b: Point2Like): number;
+    /**
+     * Add a scalar (broadcast to x/y) or another point. See {@link pointAdd} for the underlying free
+     * function.
+     * @param b - scalar or point to add
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    add(b: number | PointLike, target?: Point): Point;
+    /**
+     * Multiply by a scalar (x/y) or componentwise by another point. See {@link pointMultiply} for
+     * the underlying free function.
+     * @param b - scalar or point factor
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    multiply(b: number | PointLike, target?: Point): Point;
+}
+/**
+ * Euclidean distance between two points (XY plane).
+ * @param a first point
+ * @param b second point
+ * @returns the distance
+ */
+export declare function pointDistance(a: PointLike, b: PointLike): number;
+/**
+ * Linear interpolation from `a` to `b` by `t`.
+ * @param a start point
+ * @param b end point
+ * @param t factor (0 = a, 1 = b)
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the interpolated point
+ */
+export declare function pointLerp(a: PointLike, b: PointLike, t: number, target?: Point): Point;
+/**
+ * Adds a scalar (broadcast to x/y) or another point (componentwise) to `a`.
+ * @param a base point
+ * @param b scalar or point to add
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the sum
+ */
+export declare function pointAdd(a: PointLike, b: number | PointLike, target?: Point): Point;
+/**
+ * Multiplies `a` by a scalar (x/y) or by another point (componentwise).
+ * @param a base point
+ * @param b scalar or point factor
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the product
+ */
+export declare function pointMultiply(a: PointLike, b: number | PointLike, target?: Point): Point;
+/**
+ * Rotates `point` by `angle` radians around `origin` in the XY plane.
+ * @param point point to rotate
+ * @param angle radians (positive = clockwise, y-down)
+ * @param origin rotation pivot point
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the rotated point, preserving the input depth (`z`)
+ */
+export declare function pointRotate(point: PointLike, angle: number, origin: Point2Like, target?: Point): Point;
+/**
+ * Shifts `point` by `length` along `angle` radians.
+ * @param point origin
+ * @param length distance
+ * @param angle direction in radians
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the shifted point
+ */
+export declare function pointShift(point: PointLike, length: number, angle: number, target?: Point): Point;
+/**
+ * Angle (radians) at `center` between the rays to `a` and `b`. The result is signed — positive means
+ * clockwise (screen y-down convention), matching the winding used by {@link pointRotate}.
+ * @param center vertex
+ * @param a first ray endpoint
+ * @param b second ray endpoint
+ * @returns signed angle in radians (positive = clockwise, y-down)
+ */
+export declare function pointAngleBetween(center: Point2Like, a: Point2Like, b: Point2Like): number;
+//# sourceMappingURL=point.d.ts.map

package/dist/lib/point.js

@@ -0,0 +1,237 @@
+import { fromPolar } from './angles.js';
+/**
+ * Mutable point/vector — the low-level building block other primitives and the point free functions
+ * write into. `width`/`height` alias `x`/`y` so a point used as a size reads naturally.
+ */
+export class Point {
+    /** Marker so callers can narrow the type at runtime. */
+    isPoint = true;
+    /** Horizontal coordinate. */
+    x;
+    /** Vertical coordinate. */
+    y;
+    /** Depth coordinate. */
+    z;
+    /**
+     * @param x - horizontal coordinate (default 0)
+     * @param y - vertical coordinate (default 0)
+     * @param z - depth coordinate (default 0)
+     */
+    constructor(x = 0, y = 0, z = 0) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+    }
+    /**
+     * Alias of {@link Point.x}.
+     * @returns the x coordinate
+     */
+    get width() {
+        return this.x;
+    }
+    /**
+     * Alias of {@link Point.y}.
+     * @returns the y coordinate
+     */
+    get height() {
+        return this.y;
+    }
+    /**
+     * Sets coordinates in place.
+     * @param x - horizontal coordinate
+     * @param y - vertical coordinate
+     * @param z - depth coordinate (defaults to the current z)
+     * @returns this
+     */
+    set(x, y, z = this.z) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        return this;
+    }
+    /**
+     * Copies from another point in place.
+     * @param p - source point to copy coordinates from
+     * @returns this
+     */
+    copy(p) {
+        return this.set(p.x, p.y, p.z ?? 0);
+    }
+    /**
+     * Returns an independent copy, or writes into `target` if provided. See {@link pointLerp} for the
+     * underlying free function.
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the copy
+     */
+    clone(target) {
+        return (target ?? new Point()).set(this.x, this.y, this.z);
+    }
+    /**
+     * True when `p` has the same coordinates.
+     * @param p - point to compare against
+     * @returns true when all coordinates are equal
+     */
+    equals(p) {
+        return this.x === p.x && this.y === p.y && this.z === (p.z ?? 0);
+    }
+    /**
+     * Distance to `p`. See {@link pointDistance} for the underlying free function.
+     * @param p - target point
+     * @returns the distance
+     */
+    distanceTo(p) {
+        return pointDistance(this, p);
+    }
+    /**
+     * Interpolate toward `p` by `t`. See {@link pointLerp} for the underlying free function.
+     * @param p - target point
+     * @param t - interpolation factor (0 = this, 1 = p)
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    lerp(p, t, target) {
+        return pointLerp(this, p, t, target);
+    }
+    /**
+     * Rotate by `angle` radians around `origin`. See {@link pointRotate} for the underlying free
+     * function.
+     * @param angle - radians to rotate (positive = clockwise, y-down)
+     * @param origin - rotation pivot point
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    rotate(angle, origin, target) {
+        return pointRotate(this, angle, origin, target);
+    }
+    /**
+     * Shift by `length` along `angle` radians. See {@link pointShift} for the underlying free function.
+     * @param length - distance to shift
+     * @param angle - direction in radians
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    shift(length, angle, target) {
+        return pointShift(this, length, angle, target);
+    }
+    /**
+     * Angle (radians) at this point between rays to `a` and `b`. See {@link pointAngleBetween} for
+     * the underlying free function.
+     * @param a - first ray endpoint
+     * @param b - second ray endpoint
+     * @returns the signed angle in radians (positive = clockwise, y-down)
+     */
+    angleBetween(a, b) {
+        return pointAngleBetween(this, a, b);
+    }
+    /**
+     * Add a scalar (broadcast to x/y) or another point. See {@link pointAdd} for the underlying free
+     * function.
+     * @param b - scalar or point to add
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    add(b, target) {
+        return pointAdd(this, b, target);
+    }
+    /**
+     * Multiply by a scalar (x/y) or componentwise by another point. See {@link pointMultiply} for
+     * the underlying free function.
+     * @param b - scalar or point factor
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the resulting point
+     */
+    multiply(b, target) {
+        return pointMultiply(this, b, target);
+    }
+}
+/**
+ * Euclidean distance between two points (XY plane).
+ * @param a first point
+ * @param b second point
+ * @returns the distance
+ */
+export function pointDistance(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * Linear interpolation from `a` to `b` by `t`.
+ * @param a start point
+ * @param b end point
+ * @param t factor (0 = a, 1 = b)
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the interpolated point
+ */
+export function pointLerp(a, b, t, target) {
+    const az = a.z ?? 0;
+    const bz = b.z ?? 0;
+    return (target ?? new Point()).set(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, az + (bz - az) * t);
+}
+/**
+ * Adds a scalar (broadcast to x/y) or another point (componentwise) to `a`.
+ * @param a base point
+ * @param b scalar or point to add
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the sum
+ */
+export function pointAdd(a, b, target) {
+    const isNum = typeof b === 'number';
+    const bx = isNum ? b : b.x;
+    const by = isNum ? b : b.y;
+    const bz = isNum ? 0 : (b.z ?? 0);
+    return (target ?? new Point()).set(a.x + bx, a.y + by, (a.z ?? 0) + bz);
+}
+/**
+ * Multiplies `a` by a scalar (x/y) or by another point (componentwise).
+ * @param a base point
+ * @param b scalar or point factor
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the product
+ */
+export function pointMultiply(a, b, target) {
+    const isNum = typeof b === 'number';
+    const bx = isNum ? b : b.x;
+    const by = isNum ? b : b.y;
+    const bz = isNum ? 1 : (b.z ?? 1);
+    return (target ?? new Point()).set(a.x * bx, a.y * by, (a.z ?? 0) * bz);
+}
+/**
+ * Rotates `point` by `angle` radians around `origin` in the XY plane.
+ * @param point point to rotate
+ * @param angle radians (positive = clockwise, y-down)
+ * @param origin rotation pivot point
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the rotated point, preserving the input depth (`z`)
+ */
+export function pointRotate(point, angle, origin, target) {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const dx = point.x - origin.x;
+    const dy = point.y - origin.y;
+    return (target ?? new Point()).set(origin.x + dx * cos - dy * sin, origin.y + dx * sin + dy * cos, point.z ?? 0);
+}
+/**
+ * Shifts `point` by `length` along `angle` radians.
+ * @param point origin
+ * @param length distance
+ * @param angle direction in radians
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the shifted point
+ */
+export function pointShift(point, length, angle, target) {
+    return pointAdd(point, fromPolar(length, angle), target);
+}
+/**
+ * Angle (radians) at `center` between the rays to `a` and `b`. The result is signed — positive means
+ * clockwise (screen y-down convention), matching the winding used by {@link pointRotate}.
+ * @param center vertex
+ * @param a first ray endpoint
+ * @param b second ray endpoint
+ * @returns signed angle in radians (positive = clockwise, y-down)
+ */
+export function pointAngleBetween(center, a, b) {
+    const aa = Math.atan2(a.y - center.y, a.x - center.x);
+    const bb = Math.atan2(b.y - center.y, b.x - center.x);
+    return bb - aa;
+}