@expofp/geometry 3.8.0

package/dist/lib/intersections.js

@@ -0,0 +1,72 @@
+import { pointLerp } from './point.js';
+import { rectCorners } from './rect.js';
+/** Default tolerance for elevation comparison. */
+const DEFAULT_ELEVATION_TOLERANCE = 1e-3;
+/**
+ * Computes the crossing of lines `a` and `b` using the parametric form. Returns the crossing
+ * point plus flags indicating whether the crossing lies within each segment's `[0, 1]` parameter
+ * range. Returns `null` only when the lines are parallel (denominator is zero) or when both lines
+ * have a defined elevation and they differ by more than `elevationTolerance`.
+ * @param a - first line segment, defined by `p0` and `p1`
+ * @param b - second line segment, defined by `p0` and `p1`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @returns `{ point, onLine1, onLine2 }`, or `null` when the lines are parallel or elevation-incompatible
+ */
+export function lineIntersection(a, b, elevationTolerance = DEFAULT_ELEVATION_TOLERANCE) {
+    if (a.elevation != null &&
+        b.elevation != null &&
+        Math.abs(a.elevation - b.elevation) > elevationTolerance) {
+        return null;
+    }
+    const { x: x1, y: y1 } = a.p0, { x: x2, y: y2 } = a.p1;
+    const { x: x3, y: y3 } = b.p0, { x: x4, y: y4 } = b.p1;
+    const denom = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4);
+    if (denom === 0)
+        return null;
+    const t = ((x1 - x3) * (y3 - y4) - (y1 - y3) * (x3 - x4)) / denom;
+    const u = ((x1 - x3) * (y1 - y2) - (y1 - y3) * (x1 - x2)) / denom;
+    const point = pointLerp(a.p0, a.p1, t);
+    point.z = a.elevation ?? b.elevation ?? 0;
+    return { point, onLine1: t >= 0 && t <= 1, onLine2: u >= 0 && u <= 1 };
+}
+/**
+ * Returns the intersection point of two line segments `a` and `b`, or `null` when the segments
+ * do not cross. See `lineIntersection` for the full crossing result (includes out-of-segment
+ * flags). See `intersectLineRect` for the higher-level helper.
+ * @param a - first segment, defined by `p0` and `p1`
+ * @param b - second segment, defined by `p0` and `p1`
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @returns the intersection {@link Point}, or `null` if the segments are parallel or non-crossing
+ */
+function segmentIntersection(a, b, elevationTolerance) {
+    const r = lineIntersection(a, b, elevationTolerance);
+    return r?.onLine1 && r.onLine2 ? r.point : null;
+}
+/**
+ * Returns the points where a line segment crosses a rect's edges. Works for any `RectLike`,
+ * including a rotated rect or an unrotated `Box` (a `Box` satisfies `RectLike` and is treated
+ * as a rect with rotation 0). When both `line` and `rect` have a defined elevation that differs
+ * by more than `elevationTolerance`, returns an empty array.
+ * @param line - the segment, defined by `p0` and `p1`
+ * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
+ * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+ * @returns the intersection points (0–2 for a convex rect)
+ */
+export function intersectLineRect(line, rect, elevationTolerance = DEFAULT_ELEVATION_TOLERANCE) {
+    if (line.elevation != null &&
+        rect.elevation != null &&
+        Math.abs(line.elevation - rect.elevation) > elevationTolerance) {
+        return [];
+    }
+    const resultZ = line.elevation ?? rect.elevation ?? 0;
+    const corners = rectCorners(rect);
+    const hits = [];
+    for (let i = 0; i < 4; i++) {
+        const hit = segmentIntersection(line, { p0: corners[i], p1: corners[(i + 1) % 4] }, elevationTolerance);
+        if (hit) {
+            hit.z = resultZ;
+            hits.push(hit);
+        }
+    }
+    return hits;
+}

package/dist/lib/line.d.ts

@@ -0,0 +1,134 @@
+import { Point, type Point2Like } from './point.js';
+import type { RectLike } from './rect.js';
+/** Structural line segment with 2D endpoints and an optional planar elevation. */
+export interface LineLike {
+    /** Start point (2D). */
+    readonly p0: Point2Like;
+    /** End point (2D). */
+    readonly p1: Point2Like;
+    /** Planar elevation (z). When absent the segment is treated as elevation-agnostic (matches any). */
+    readonly elevation?: number;
+}
+/** A line segment between two 2D points at a given elevation. */
+export declare class Line {
+    /** Marker so callers can narrow the type at runtime. */
+    readonly isLine = true;
+    /** Internal mutable start point (2D). */
+    private _p0;
+    /** Internal mutable end point (2D). */
+    private _p1;
+    /** Internal mutable elevation (z). */
+    private _elevation;
+    /**
+     * @param p0 - start point (2D)
+     * @param p1 - end point (2D)
+     * @param elevation - planar elevation (z); defaults to 0
+     */
+    constructor(p0: Point2Like, p1: Point2Like, elevation?: number);
+    /**
+     * Start point (2D).
+     * @returns a readonly `{ x, y }` view of the start point
+     */
+    get p0(): Readonly<Point2Like>;
+    /**
+     * End point (2D).
+     * @returns a readonly `{ x, y }` view of the end point
+     */
+    get p1(): Readonly<Point2Like>;
+    /**
+     * Planar elevation (z coordinate of the segment's plane).
+     * @returns the current elevation
+     */
+    get elevation(): number;
+    /**
+     * Mutates this segment in place, replacing p0, p1, and optionally elevation. When `elevation`
+     * is omitted the current elevation is preserved. Prefer the constructor for one-off segments;
+     * use this only for hot-path reuse.
+     * @param p0 - new start point (2D); stored as a fresh `{ x, y }` copy
+     * @param p1 - new end point (2D); stored as a fresh `{ x, y }` copy
+     * @param elevation - new elevation; defaults to the current elevation when omitted
+     * @returns `this`
+     */
+    set(p0: Point2Like, p1: Point2Like, elevation?: number): this;
+    /**
+     * Length of this segment.
+     * @returns the distance between p0 and p1
+     */
+    length(): number;
+    /**
+     * Midpoint of this segment.
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the midpoint
+     */
+    center(target?: Point): Point;
+    /**
+     * Direction of this segment in radians.
+     * @returns the angle in radians
+     */
+    angle(): number;
+    /**
+     * Points where this line crosses `rect`.
+     * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @returns the intersection points
+     */
+    intersectRect(rect: RectLike, elevationTolerance?: number): Point[];
+    /**
+     * Nearest point on this segment to `point`, with parameter and distance.
+     * @param point - the point to project onto this segment
+     * @param target - optional point to write the projected position into; defaults to a new {@link Point}
+     * @returns `{ projected, t, distance }`
+     */
+    projectPoint(point: Point2Like, target?: Point): {
+        projected: Point;
+        t: number;
+        distance: number;
+    };
+    /**
+     * Intersection with another segment `other` on the infinite lines.
+     * @param other - the other segment
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @returns the crossing data, or `null` when the lines are parallel or elevations are incompatible
+     */
+    intersect(other: LineLike, elevationTolerance?: number): {
+        point: Point;
+        onLine1: boolean;
+        onLine2: boolean;
+    } | null;
+}
+/**
+ * Euclidean length of a line segment.
+ * @param line the segment
+ * @returns the distance between `line.p0` and `line.p1`
+ */
+export declare function lineLength(line: LineLike): number;
+/**
+ * Midpoint of a line segment.
+ * @param line the segment
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the midpoint
+ */
+export declare function lineCenter(line: LineLike, target?: Point): Point;
+/**
+ * Direction of the segment p0→p1 in radians.
+ * @param p0 start point
+ * @param p1 end point
+ * @returns the angle in radians
+ */
+export declare function lineAngle(p0: Point2Like, p1: Point2Like): number;
+/**
+ * Projects `point` onto the nearest position on segment `line`, returning the projected point,
+ * the normalized parameter `t` (clamped to `[0, 1]`), and the distance from `point` to the
+ * projection. For a zero-length segment, `t` is `0`, the projected point equals `line.p0`, and
+ * the distance is the distance from `point` to `p0`.
+ * @param line - the segment to project onto
+ * @param point - the point to project
+ * @param target - optional point to write the projected position into; defaults to a new {@link Point}
+ * @returns `{ projected, t, distance }` where `t ∈ [0, 1]`
+ */
+export declare function lineProjectPoint(line: LineLike, point: Point2Like, target?: Point): {
+    projected: Point;
+    t: number;
+    distance: number;
+};
+//# sourceMappingURL=line.d.ts.map

package/dist/lib/line.js

@@ -0,0 +1,167 @@
+import { intersectLineRect, lineIntersection } from './intersections.js';
+import { Point, pointDistance, pointLerp } from './point.js';
+/** A line segment between two 2D points at a given elevation. */
+export class Line {
+    /** Marker so callers can narrow the type at runtime. */
+    isLine = true;
+    /** Internal mutable start point (2D). */
+    _p0;
+    /** Internal mutable end point (2D). */
+    _p1;
+    /** Internal mutable elevation (z). */
+    _elevation;
+    /**
+     * @param p0 - start point (2D)
+     * @param p1 - end point (2D)
+     * @param elevation - planar elevation (z); defaults to 0
+     */
+    constructor(p0, p1, elevation = 0) {
+        this._p0 = { x: p0.x, y: p0.y };
+        this._p1 = { x: p1.x, y: p1.y };
+        this._elevation = elevation;
+    }
+    /**
+     * Start point (2D).
+     * @returns a readonly `{ x, y }` view of the start point
+     */
+    get p0() {
+        return this._p0;
+    }
+    /**
+     * End point (2D).
+     * @returns a readonly `{ x, y }` view of the end point
+     */
+    get p1() {
+        return this._p1;
+    }
+    /**
+     * Planar elevation (z coordinate of the segment's plane).
+     * @returns the current elevation
+     */
+    get elevation() {
+        return this._elevation;
+    }
+    /**
+     * Mutates this segment in place, replacing p0, p1, and optionally elevation. When `elevation`
+     * is omitted the current elevation is preserved. Prefer the constructor for one-off segments;
+     * use this only for hot-path reuse.
+     * @param p0 - new start point (2D); stored as a fresh `{ x, y }` copy
+     * @param p1 - new end point (2D); stored as a fresh `{ x, y }` copy
+     * @param elevation - new elevation; defaults to the current elevation when omitted
+     * @returns `this`
+     */
+    set(p0, p1, elevation = this._elevation) {
+        this._p0 = { x: p0.x, y: p0.y };
+        this._p1 = { x: p1.x, y: p1.y };
+        this._elevation = elevation;
+        return this;
+    }
+    /**
+     * Length of this segment.
+     * @returns the distance between p0 and p1
+     */
+    length() {
+        return lineLength(this);
+    }
+    /**
+     * Midpoint of this segment.
+     * @param target - optional point to write into; defaults to a new {@link Point}
+     * @returns the midpoint
+     */
+    center(target) {
+        return lineCenter(this, target);
+    }
+    /**
+     * Direction of this segment in radians.
+     * @returns the angle in radians
+     */
+    angle() {
+        return lineAngle(this.p0, this.p1);
+    }
+    /**
+     * Points where this line crosses `rect`.
+     * @param rect - the rect (possibly rotated; a `Box` is accepted as an unrotated rect)
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @returns the intersection points
+     */
+    intersectRect(rect, elevationTolerance) {
+        return intersectLineRect(this, rect, elevationTolerance);
+    }
+    /**
+     * Nearest point on this segment to `point`, with parameter and distance.
+     * @param point - the point to project onto this segment
+     * @param target - optional point to write the projected position into; defaults to a new {@link Point}
+     * @returns `{ projected, t, distance }`
+     */
+    projectPoint(point, target) {
+        return lineProjectPoint(this, point, target);
+    }
+    /**
+     * Intersection with another segment `other` on the infinite lines.
+     * @param other - the other segment
+     * @param elevationTolerance - maximum elevation difference for a crossing to be reported; defaults to `1e-3`
+     * @returns the crossing data, or `null` when the lines are parallel or elevations are incompatible
+     */
+    intersect(other, elevationTolerance) {
+        return lineIntersection(this, other, elevationTolerance);
+    }
+}
+/**
+ * Euclidean length of a line segment.
+ * @param line the segment
+ * @returns the distance between `line.p0` and `line.p1`
+ */
+export function lineLength(line) {
+    return pointDistance(line.p0, line.p1);
+}
+/**
+ * Midpoint of a line segment.
+ * @param line the segment
+ * @param target optional point to write into; defaults to a new {@link Point}
+ * @returns the midpoint
+ */
+export function lineCenter(line, target) {
+    return pointLerp(line.p0, line.p1, 0.5, target);
+}
+/**
+ * Direction of the segment p0→p1 in radians.
+ * @param p0 start point
+ * @param p1 end point
+ * @returns the angle in radians
+ */
+export function lineAngle(p0, p1) {
+    return Math.atan2(p1.y - p0.y, p1.x - p0.x);
+}
+/**
+ * Projects `point` onto the nearest position on segment `line`, returning the projected point,
+ * the normalized parameter `t` (clamped to `[0, 1]`), and the distance from `point` to the
+ * projection. For a zero-length segment, `t` is `0`, the projected point equals `line.p0`, and
+ * the distance is the distance from `point` to `p0`.
+ * @param line - the segment to project onto
+ * @param point - the point to project
+ * @param target - optional point to write the projected position into; defaults to a new {@link Point}
+ * @returns `{ projected, t, distance }` where `t ∈ [0, 1]`
+ */
+export function lineProjectPoint(line, point, target) {
+    // Read inputs to locals — alias-safe even if `target` overlaps with `line` points.
+    const p0x = line.p0.x, p0y = line.p0.y;
+    const p1x = line.p1.x, p1y = line.p1.y;
+    const px = point.x, py = point.y;
+    const dx = p1x - p0x, dy = p1y - p0y;
+    const lenSq = dx * dx + dy * dy;
+    let t;
+    if (lenSq === 0) {
+        t = 0;
+    }
+    else {
+        const dot = (px - p0x) * dx + (py - p0y) * dy;
+        t = dot / lenSq;
+        t = t < 0 ? 0 : t > 1 ? 1 : t;
+    }
+    // Inline the lerp (avoid two transient {x,y} allocations on this hot path); `target` may alias an
+    // input, but all coords were copied to locals above. The distance uses the saved px/py snapshot so it
+    // stays correct even when `target === point`.
+    const projected = (target ?? new Point()).set(p0x + dx * t, p0y + dy * t, line.elevation ?? 0);
+    const distance = pointDistance({ x: px, y: py }, projected);
+    return { projected, t, distance };
+}

package/dist/lib/mesh.d.ts

@@ -0,0 +1,166 @@
+import { Box } from './box.js';
+import { Point, type Point2Like, type PointLike } from './point.js';
+import type { Polygon } from './polygon.js';
+/** A triplet of vertex indices forming a triangle. */
+export type TriangleIndex = readonly [number, number, number];
+/** Structural mesh: vertices plus triangle indices. */
+export interface MeshLike {
+    /** Mesh vertices (may carry a z coordinate). */
+    readonly vertices: readonly PointLike[];
+    /** Triangle index triplets. */
+    readonly indices: readonly TriangleIndex[];
+}
+/**
+ * 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 declare class Mesh {
+    /** Marker so callers can narrow the type at runtime. */
+    readonly isMesh = true;
+    /** Internal mutable vertex array (3D). */
+    private _vertices;
+    /** Internal triangle index array. */
+    private _indices;
+    /** Cached axis-aligned bounding box (xy only). */
+    private _bounds;
+    /**
+     * 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?: readonly PointLike[], indices?: readonly TriangleIndex[]);
+    /**
+     * Readonly array of mesh vertices as {@link Point} instances.
+     * @returns the vertex array
+     */
+    get vertices(): readonly Point[];
+    /**
+     * Readonly array of triangle index triplets.
+     * @returns the index array
+     */
+    get indices(): readonly TriangleIndex[];
+    /**
+     * Cached axis-aligned bounding {@link Box} of this mesh (xy only, z ignored).
+     * @returns the bounding box
+     */
+    get bounds(): Box;
+    /**
+     * 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: readonly PointLike[], indices: readonly TriangleIndex[]): 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: MeshLike[]): Mesh;
+    /**
+     * 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: PointLike, target?: Mesh): 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: number | Point2Like, origin?: Point2Like, target?: Mesh): 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: number, origin?: Point2Like, target?: Mesh): 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 declare function meshBounds(m: MeshLike): Box;
+/**
+ * Merges two or more meshes into a single mesh, offsetting each mesh's triangle indices by the
+ * cumulative vertex count so they remain valid. When `target` is provided the result is written
+ * into it, preserving the target's concrete type (e.g. a `Polygon` target stays a `Polygon`).
+ * @param meshes - meshes to merge
+ * @param target - mesh to write into; receives the merged vertices and indices
+ * @returns `target` with the merged data
+ */
+export declare function meshMerge<T extends Mesh | Polygon>(meshes: readonly MeshLike[], target: T): T;
+/**
+ * Merges two or more meshes into a single new {@link Mesh}, offsetting each mesh's triangle
+ * indices by the cumulative vertex count so they remain valid.
+ * @param meshes - meshes to merge
+ * @returns a new merged mesh
+ */
+export declare function meshMerge(meshes: readonly MeshLike[]): Mesh;
+/**
+ * Returns a new mesh whose vertices are translated by `offset`. Writes into `target` when
+ * provided, preserving the target's concrete type (e.g. a `Polygon` target stays a `Polygon`).
+ * @param m - source mesh
+ * @param offset - translation vector; `z` defaults to 0
+ * @param target - mesh to write into; receives the translated vertices in place
+ * @returns `target` with updated vertices
+ */
+export declare function meshTranslate<T extends Mesh | Polygon>(m: MeshLike, offset: PointLike, target: T): T;
+/**
+ * Returns a new {@link Mesh} whose vertices are translated by `offset`. Does not mutate `m`.
+ * @param m - source mesh
+ * @param offset - translation vector; `z` defaults to 0
+ * @returns new translated mesh
+ */
+export declare function meshTranslate(m: MeshLike, offset: PointLike): Mesh;
+/**
+ * Returns a new mesh whose vertices are scaled by `factor` about `origin`. The xy coordinates
+ * are scaled; z is preserved unchanged. Writes into `target` when provided.
+ * @param m - source mesh
+ * @param factor - uniform scale or per-axis `{ x, y }` scale
+ * @param origin - the fixed point of the scaling; defaults to the mesh's bounding-box center
+ * @param target - mesh to write into; receives the scaled vertices in place
+ * @returns `target` with updated vertices
+ */
+export declare function meshScale<T extends Mesh | Polygon>(m: MeshLike, factor: number | Point2Like, origin: Point2Like, target: T): T;
+/**
+ * Returns a new {@link Mesh} whose vertices are scaled by `factor` about `origin`. Does not
+ * mutate `m`.
+ * @param m - source mesh
+ * @param factor - uniform scale or per-axis `{ x, y }` scale
+ * @param origin - the fixed point of the scaling; defaults to the mesh's bounding-box center
+ * @returns new scaled mesh
+ */
+export declare function meshScale(m: MeshLike, factor: number | Point2Like, origin?: Point2Like): Mesh;
+/**
+ * Returns a new mesh whose vertices are rotated by `angle` radians about `origin`. The xy
+ * coordinates are rotated; z is preserved unchanged. Positive angles rotate clockwise in
+ * y-down coordinate space. Writes into `target` when provided.
+ * @param m - source mesh
+ * @param angle - rotation angle in radians (positive = clockwise in y-down space)
+ * @param origin - the pivot of the rotation; defaults to the mesh's bounding-box center
+ * @param target - mesh to write into; receives the rotated vertices in place
+ * @returns `target` with updated vertices
+ */
+export declare function meshRotate<T extends Mesh | Polygon>(m: MeshLike, angle: number, origin: Point2Like, target: T): T;
+/**
+ * Returns a new {@link Mesh} whose vertices are rotated by `angle` radians about `origin`. Does
+ * not mutate `m`.
+ * @param m - source mesh
+ * @param angle - rotation angle in radians (positive = clockwise in y-down space)
+ * @param origin - the pivot of the rotation; defaults to the mesh's bounding-box center
+ * @returns new rotated mesh
+ */
+export declare function meshRotate(m: MeshLike, angle: number, origin?: Point2Like): Mesh;
+//# sourceMappingURL=mesh.d.ts.map