@expofp/geometry 3.8.0

package/dist/lib/box.js

@@ -0,0 +1,362 @@
+import { intersectLineRect } from './intersections.js';
+import { Point } from './point.js';
+// Yields each box's two corners; lets fromUnion reuse the fromPoints sweep without allocating an array.
+function* boxUnionCorners(boxes) {
+    for (const b of boxes) {
+        yield b.min;
+        yield b.max;
+    }
+}
+/**
+ * Axis-aligned bounding box (AABB). Pure 2D, no elevation. Immutable value object: readonly getters;
+ * transforms return a new instance unless a method `target` is passed. For a rotated rectangle use
+ * {@link Rect}.
+ */
+export class Box {
+    /** Marker so callers can narrow the type at runtime. */
+    isBox = true;
+    /** Internal mutable backing for the minimum corner. */
+    _min = new Point();
+    /** Internal mutable backing for the maximum corner. */
+    _max = new Point();
+    /** Internal mutable backing for the center point. */
+    _center = new Point();
+    /** Internal mutable backing for the size vector (x = width, y = height). */
+    _size = new Point();
+    /**
+     * Creates a box from an origin and dimensions. Negative width/height are normalized so
+     * {@link Box.min} is always the lesser corner.
+     * @param x - left edge x coordinate (default 0)
+     * @param y - top edge y coordinate (default 0)
+     * @param w - width; may be negative (default 0)
+     * @param h - height; may be negative (default 0)
+     */
+    constructor(x = 0, y = 0, w = 0, h = 0) {
+        this.set(x, y, x + w, y + h);
+    }
+    /**
+     * The lesser corner of the box (minimum x and y).
+     * @returns a readonly `{ x, y }` view of the minimum corner
+     */
+    get min() {
+        return this._min;
+    }
+    /**
+     * The greater corner of the box (maximum x and y).
+     * @returns a readonly `{ x, y }` view of the maximum corner
+     */
+    get max() {
+        return this._max;
+    }
+    /**
+     * The geometric center of the box.
+     * @returns a readonly `{ x, y }` view of the center point
+     */
+    get center() {
+        return this._center;
+    }
+    /**
+     * The size of the box. `width` aliases `x` and `height` aliases `y`.
+     * @returns a readonly size view with `x`, `y`, `width`, and `height`
+     */
+    get size() {
+        return this._size;
+    }
+    /**
+     * Area of the box (`width × height`). Delegates to {@link boxArea}.
+     * @returns the area in square units
+     */
+    get area() {
+        return boxArea(this);
+    }
+    /**
+     * True when the box has zero extent in BOTH axes (collapsed to a point, or the
+     * default / `fromPoints([])` empty box). A degenerate line — extent in only one
+     * axis — is NOT considered empty. Delegates to {@link boxIsEmpty}.
+     * @returns true when `min === max` in both x and y
+     */
+    isEmpty() {
+        return boxIsEmpty(this);
+    }
+    /**
+     * Constructs a box from two arbitrary corners. Corners are normalized so
+     * {@link Box.min} is always the lesser corner regardless of argument order.
+     * @param min - one corner of the box
+     * @param max - the opposite corner of the box
+     * @returns a new normalized {@link Box}
+     */
+    static fromMinMax(min, max) {
+        return new Box(min.x, min.y, max.x - min.x, max.y - min.y);
+    }
+    /**
+     * Constructs a box centred on `center` with the given `size`.
+     * @param center - the desired center point of the box
+     * @param size - `{ x: width, y: height }` of the box
+     * @returns a new {@link Box} centred at `center`
+     */
+    static fromCenter(center, size) {
+        return new Box(center.x - size.x / 2, center.y - size.y / 2, size.x, size.y);
+    }
+    /**
+     * Constructs the smallest box that contains every box in `boxes`.
+     * Delegates to {@link Box.fromPoints} over each box's two corners so the
+     * min/max sweep lives in one place. Zero args returns `new Box()`.
+     * @param boxes - zero or more boxes to union
+     * @returns a new {@link Box} that is the axis-aligned union of all inputs
+     */
+    static fromUnion(...boxes) {
+        return Box.fromPoints(boxUnionCorners(boxes));
+    }
+    /**
+     * Constructs the smallest axis-aligned box that encloses every point in `points`.
+     * An empty iterable returns a zero-size box at the origin (equivalent to `new Box()`).
+     * @param points - iterable of `{ x, y }` points
+     * @returns a new {@link Box} that is the AABB of all inputs, or a zero box when `points` is empty
+     */
+    static fromPoints(points) {
+        let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+        for (const p of points) {
+            if (p.x < minX)
+                minX = p.x;
+            if (p.y < minY)
+                minY = p.y;
+            if (p.x > maxX)
+                maxX = p.x;
+            if (p.y > maxY)
+                maxY = p.y;
+        }
+        if (minX === Infinity)
+            return new Box();
+        return Box.fromMinMax({ x: minX, y: minY }, { x: maxX, y: maxY });
+    }
+    /**
+     * Constructs a box from an SVG `<rect>` or `<image>` element's base values.
+     * @param rect - the SVG element (or any {@link SvgRectLike}) to read dimensions from
+     * @returns a new {@link Box} matching the element's position and size
+     */
+    static fromSvg(rect) {
+        return new Box(rect.x.baseVal.value, rect.y.baseVal.value, rect.width.baseVal.value, rect.height.baseVal.value);
+    }
+    /**
+     * Returns true when this box overlaps `b`. Delegates to {@link boxIntersects}.
+     * @param b - the box to test intersection against
+     * @returns true when the boxes share at least one point
+     */
+    intersects(b) {
+        return boxIntersects(this, b);
+    }
+    /**
+     * Returns true when this box fully contains `b`. Delegates to {@link boxContains}.
+     * @param b - the box to test containment of
+     * @returns true when `b` lies entirely within this box
+     */
+    contains(b) {
+        return boxContains(this, b);
+    }
+    /**
+     * Returns true when `p` lies inside or on the boundary of this box.
+     * Delegates to {@link boxContainsPoint}.
+     * @param p - the point to test
+     * @returns true when `p` is within this box
+     */
+    containsPoint(p) {
+        return boxContainsPoint(this, p);
+    }
+    /**
+     * Returns true when this box has the same corners as `b`. Delegates to {@link boxEquals}.
+     * @param b - the box to compare against
+     * @returns true when both boxes share identical min and max corners
+     */
+    equals(b) {
+        return boxEquals(this, b);
+    }
+    /**
+     * Returns the intersection of this box and `b`, or `null` when they do not overlap.
+     * Delegates to {@link boxIntersection}.
+     * @param b - the box to intersect with
+     * @param target - optional box to write the result into; defaults to a new {@link Box}
+     * @returns the intersection box, or `null` if the boxes do not overlap
+     */
+    intersection(b, target) {
+        return boxIntersection(this, b, target);
+    }
+    /**
+     * Returns a copy of this box shifted by `offset`. Delegates to {@link boxTranslate}.
+     * @param offset - scalar (same shift on both axes) or `{ x, y }` amount to shift by
+     * @param target - optional box to write the result into; defaults to a new {@link Box}
+     * @returns the translated box
+     */
+    translate(offset, target) {
+        return boxTranslate(this, offset, target);
+    }
+    /**
+     * Returns a copy of this box expanded outward by `amount` on all sides.
+     * Delegates to {@link boxExpand}.
+     * @param amount - scalar or `{ x, y }` expansion per side
+     * @param target - optional box to write the result into; defaults to a new {@link Box}
+     * @returns the expanded box
+     */
+    expand(amount, target) {
+        return boxExpand(this, amount, target);
+    }
+    /**
+     * Returns a copy of this box scaled by `factor` about `origin`. Delegates to {@link boxScale}.
+     * @param factor - uniform scale or per-axis `{ x, y }` scale
+     * @param origin - the fixed point of the scaling; defaults to this box's center
+     * @param target - optional box to write the result into; defaults to a new {@link Box}
+     * @returns the scaled box
+     */
+    scale(factor, origin = this._center, target) {
+        return boxScale(this, factor, origin, target);
+    }
+    /**
+     * Points where `line` crosses this box. Delegates to {@link intersectLineRect}.
+     * @param line - the segment
+     * @returns the intersection points
+     */
+    intersectLine(line) {
+        return intersectLineRect(line, this);
+    }
+    /**
+     * Returns an independent copy of this box, or writes into `target` when provided.
+     * @param target - optional box to write the result into; defaults to a new {@link Box}
+     * @returns the cloned box
+     */
+    clone(target) {
+        return (target ?? new Box()).set(this._min.x, this._min.y, this._max.x, this._max.y);
+    }
+    /**
+     * Mutates this box in place, normalizing corners so {@link Box.min} is always the lesser corner,
+     * and refreshes the derived center and size. Prefer the immutable transforms; use this (or a
+     * transform `target`) only for hot-path reuse.
+     * @param x0 - x coordinate of the first corner
+     * @param y0 - y coordinate of the first corner
+     * @param x1 - x coordinate of the opposite corner
+     * @param y1 - y coordinate of the opposite corner
+     * @returns `this`
+     */
+    set(x0, y0, x1, y1) {
+        const minX = Math.min(x0, x1), minY = Math.min(y0, y1), maxX = Math.max(x0, x1), maxY = Math.max(y0, y1);
+        this._min.set(minX, minY);
+        this._max.set(maxX, maxY);
+        this._center.set((minX + maxX) / 2, (minY + maxY) / 2);
+        this._size.set(maxX - minX, maxY - minY);
+        return this;
+    }
+}
+/**
+ * Area of an axis-aligned box (`width × height`).
+ * @param b - the box to measure
+ * @returns the area in square units
+ */
+export function boxArea(b) {
+    return (b.max.x - b.min.x) * (b.max.y - b.min.y);
+}
+/**
+ * True when the box has zero extent in BOTH axes (collapsed to a point, or the
+ * default / `fromPoints([])` empty box). A degenerate line — extent in only one
+ * axis — is NOT empty.
+ * @param b - the box to test
+ * @returns true when `b.min === b.max` in both x and y
+ */
+export function boxIsEmpty(b) {
+    return b.min.x === b.max.x && b.min.y === b.max.y;
+}
+/**
+ * Returns true when boxes `a` and `b` share at least one point (edge-touching counts).
+ * @param a - first box
+ * @param b - second box
+ * @returns true when the boxes overlap or touch
+ */
+export function boxIntersects(a, b) {
+    return a.min.x <= b.max.x && a.max.x >= b.min.x && a.min.y <= b.max.y && a.max.y >= b.min.y;
+}
+/**
+ * Returns true when box `a` fully contains box `b` (boundary-inclusive).
+ * @param a - outer box
+ * @param b - inner box to test containment of
+ * @returns true when `b` lies entirely within `a`
+ */
+export function boxContains(a, b) {
+    return b.min.x >= a.min.x && b.max.x <= a.max.x && b.min.y >= a.min.y && b.max.y <= a.max.y;
+}
+/**
+ * Returns true when `p` lies inside or on the boundary of `b`.
+ * @param b - the box to test against
+ * @param p - the point to test
+ * @returns true when `p` is within `b`
+ */
+export function boxContainsPoint(b, p) {
+    return p.x >= b.min.x && p.x <= b.max.x && p.y >= b.min.y && p.y <= b.max.y;
+}
+/**
+ * Returns true when `a` and `b` have identical min and max corners.
+ * @param a - first box
+ * @param b - second box
+ * @returns true when both corners match exactly
+ */
+export function boxEquals(a, b) {
+    return a.min.x === b.min.x && a.min.y === b.min.y && a.max.x === b.max.x && a.max.y === b.max.y;
+}
+/**
+ * Returns the intersection of boxes `a` and `b`, or `null` when they do not overlap.
+ * @param a - first box
+ * @param b - second box
+ * @param target - optional box to write the result into; defaults to a new {@link Box}
+ * @returns the intersection box, or `null` if the boxes do not overlap
+ */
+export function boxIntersection(a, b, target) {
+    const minX = Math.max(a.min.x, b.min.x), minY = Math.max(a.min.y, b.min.y), maxX = Math.min(a.max.x, b.max.x), maxY = Math.min(a.max.y, b.max.y);
+    if (maxX < minX || maxY < minY)
+        return null;
+    return (target ?? new Box()).set(minX, minY, maxX, maxY);
+}
+/**
+ * Returns a copy of `b` shifted by `offset`. Pure — does not mutate `b`.
+ * @param b - source box
+ * @param offset - scalar (same shift on both axes) or `{ x, y }` translation vector
+ * @param target - optional box to write the result into; defaults to a new {@link Box}
+ * @returns the translated box
+ */
+export function boxTranslate(b, offset, target) {
+    const ox = typeof offset === 'number' ? offset : offset.x;
+    const oy = typeof offset === 'number' ? offset : offset.y;
+    return (target ?? new Box()).set(b.min.x + ox, b.min.y + oy, b.max.x + ox, b.max.y + oy);
+}
+/**
+ * Returns a copy of `b` expanded outward by `amount` on all sides. A positive amount grows the box;
+ * a negative amount shrinks it. Shrinking an axis past zero collapses it to its midpoint (clamped to
+ * zero size) rather than inverting.
+ * @param b - source box
+ * @param amount - scalar (broadcast to x/y) or `{ x, y }` expansion per side
+ * @param target - optional box to write the result into; defaults to a new {@link Box}
+ * @returns the expanded (or zero-clamped) box
+ */
+export function boxExpand(b, amount, target) {
+    const isNum = typeof amount === 'number';
+    const ex = isNum ? amount : amount.x;
+    const ey = isNum ? amount : amount.y;
+    let minX = b.min.x - ex;
+    let maxX = b.max.x + ex;
+    let minY = b.min.y - ey;
+    let maxY = b.max.y + ey;
+    // `set` would re-normalize an inverted span into a spurious positive size, so clamp here instead.
+    if (maxX < minX)
+        minX = maxX = (minX + maxX) / 2;
+    if (maxY < minY)
+        minY = maxY = (minY + maxY) / 2;
+    return (target ?? new Box()).set(minX, minY, maxX, maxY);
+}
+/**
+ * Returns a copy of `b` scaled by `factor` about `origin`.
+ * @param b - source box
+ * @param factor - uniform scale or per-axis `{ x, y }` scale
+ * @param origin - the fixed point of the scaling; defaults to `b`'s center
+ * @param target - optional box to write the result into; defaults to a new {@link Box}
+ * @returns the scaled box
+ */
+export function boxScale(b, factor, origin = { x: (b.min.x + b.max.x) / 2, y: (b.min.y + b.max.y) / 2 }, target) {
+    const fx = typeof factor === 'number' ? factor : factor.x;
+    const fy = typeof factor === 'number' ? factor : factor.y;
+    return (target ?? new Box()).set(origin.x + (b.min.x - origin.x) * fx, origin.y + (b.min.y - origin.y) * fy, origin.x + (b.max.x - origin.x) * fx, origin.y + (b.max.y - origin.y) * fy);
+}

package/dist/lib/geo.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @module geo
+ *
+ * Pure geodetic math — geographic coordinate types and algorithms on the WGS-84
+ * sphere. This module is deliberately **firewalled** from the planar primitives:
+ *
+ * - **Coordinates are in DEGREES** (not radians).
+ * - **`lat` is north-positive, `lng` is east-positive.**
+ * - **Bearings use compass convention: 0 = North, increasing clockwise** (90 = East,
+ *   180 = South, 270 = West). This is the opposite of the planar convention in this
+ *   package, where angles are in radians and positive = clockwise in a y-down screen
+ *   system starting from the +x axis.
+ * - **Distances are in metres** on a WGS-84 mean-radius sphere (R = 6 371 000 m).
+ *
+ * The only deliberate bridge between planar and geographic space is
+ * {@link projectLocalToGps} / {@link projectGpsToLocal}, which map between a
+ * `Point2Like` local coordinate system and geographic `LatLng` coordinates via two
+ * {@link GeoAnchor} correspondences. Callers are responsible for building validated
+ * `GeoAnchor` / `LatLng` values and passing them in — no floorplan-domain logic
+ * enters this module.
+ */
+import type { Point2Like } from './point.js';
+/** A geographic coordinate pair in decimal degrees. */
+export interface LatLng {
+    /** Latitude in decimal degrees. North is positive. */
+    readonly lat: number;
+    /** Longitude in decimal degrees. East is positive. */
+    readonly lng: number;
+}
+/**
+ * A correspondence between a local 2D coordinate and a geographic position.
+ * Used to define the affine bridge between a planar coordinate system (e.g.
+ * SVG floorplan units) and geographic coordinates.
+ */
+export interface GeoAnchor {
+    /** Local planar coordinate (e.g. SVG pixels or metres). */
+    readonly local: Point2Like;
+    /** Geographic position corresponding to the local coordinate. */
+    readonly geo: LatLng;
+}
+/**
+ * Great-circle distance between two geographic points using the Haversine formula.
+ * @param a - first point (degrees)
+ * @param b - second point (degrees)
+ * @returns distance in metres
+ */
+export declare function haversineDistance(a: LatLng, b: LatLng): number;
+/**
+ * Initial compass bearing from `from` to `to`.
+ *
+ * Compass convention: **0 = North, 90 = East, 180 = South, 270 = West**, result
+ * in `[0, 360)`.
+ * @param from - origin point (degrees)
+ * @param to - destination point (degrees)
+ * @returns bearing in degrees `[0, 360)`
+ */
+export declare function bearing(from: LatLng, to: LatLng): number;
+/**
+ * Destination point given an origin, distance, and compass bearing.
+ * @param from - starting point (degrees)
+ * @param distanceM - distance in metres
+ * @param bearingDeg - initial compass bearing in degrees (0 = North, CW)
+ * @returns the destination {@link LatLng}
+ */
+export declare function destinationPoint(from: LatLng, distanceM: number, bearingDeg: number): LatLng;
+/**
+ * Projects a local 2D point to geographic coordinates using two anchor
+ * correspondences. The projection uses a polar-coordinate affine transform:
+ * it measures the local point's distance and angular offset relative to the
+ * anchor baseline vector, then applies that same distance ratio and angular
+ * offset in geographic space starting from anchor `a`.
+ *
+ * The projection is an **affine similarity transform** (scale + rotation +
+ * translation), valid when the local→geo mapping is approximately uniform
+ * scale and rotation over the region of interest (true for convention-centre
+ * scale floorplans).
+ * @param point - local 2D point to project
+ * @param a - first anchor (local origin of the baseline)
+ * @param b - second anchor (local end of the baseline)
+ * @returns the geographic position corresponding to `point`
+ */
+export declare function projectLocalToGps(point: Point2Like, a: GeoAnchor, b: GeoAnchor): LatLng;
+/**
+ * Projects a geographic point to local 2D coordinates using two anchor
+ * correspondences. This is the inverse of {@link projectLocalToGps}.
+ *
+ * It measures the geographic point's great-circle distance and compass-bearing
+ * offset relative to the anchor baseline (anchor A → anchor B), then reproduces
+ * that same distance ratio and angular offset in local planar space — inverting
+ * the affine similarity (scale + rotation + translation) bridge. Like the forward
+ * transform, it assumes an approximately uniform scale and rotation over the region.
+ * @param geo - geographic point to project
+ * @param a - first anchor (local origin of the baseline)
+ * @param b - second anchor (local end of the baseline)
+ * @returns the local 2D point corresponding to `geo`
+ */
+export declare function projectGpsToLocal(geo: LatLng, a: GeoAnchor, b: GeoAnchor): Point2Like;
+//# sourceMappingURL=geo.d.ts.map

package/dist/lib/geo.js

@@ -0,0 +1,159 @@
+/**
+ * @module geo
+ *
+ * Pure geodetic math — geographic coordinate types and algorithms on the WGS-84
+ * sphere. This module is deliberately **firewalled** from the planar primitives:
+ *
+ * - **Coordinates are in DEGREES** (not radians).
+ * - **`lat` is north-positive, `lng` is east-positive.**
+ * - **Bearings use compass convention: 0 = North, increasing clockwise** (90 = East,
+ *   180 = South, 270 = West). This is the opposite of the planar convention in this
+ *   package, where angles are in radians and positive = clockwise in a y-down screen
+ *   system starting from the +x axis.
+ * - **Distances are in metres** on a WGS-84 mean-radius sphere (R = 6 371 000 m).
+ *
+ * The only deliberate bridge between planar and geographic space is
+ * {@link projectLocalToGps} / {@link projectGpsToLocal}, which map between a
+ * `Point2Like` local coordinate system and geographic `LatLng` coordinates via two
+ * {@link GeoAnchor} correspondences. Callers are responsible for building validated
+ * `GeoAnchor` / `LatLng` values and passing them in — no floorplan-domain logic
+ * enters this module.
+ */
+import { degToRad, fromPolar, normalizeAngle, radToDeg } from './angles.js';
+/** WGS-84 mean Earth radius in metres. Matches the value used by all existing callers. */
+const EARTH_RADIUS_METERS = 6_371_000;
+// ---------------------------------------------------------------------------
+// Geodetic algorithms
+// ---------------------------------------------------------------------------
+/**
+ * Great-circle distance between two geographic points using the Haversine formula.
+ * @param a - first point (degrees)
+ * @param b - second point (degrees)
+ * @returns distance in metres
+ */
+export function haversineDistance(a, b) {
+    const phi1 = degToRad(a.lat);
+    const phi2 = degToRad(b.lat);
+    const deltaPhi = degToRad(b.lat - a.lat);
+    const deltaLambda = degToRad(b.lng - a.lng);
+    const s = Math.sin(deltaPhi / 2) * Math.sin(deltaPhi / 2) +
+        Math.cos(phi1) * Math.cos(phi2) * Math.sin(deltaLambda / 2) * Math.sin(deltaLambda / 2);
+    const c = 2 * Math.atan2(Math.sqrt(s), Math.sqrt(1 - s));
+    return EARTH_RADIUS_METERS * c;
+}
+/**
+ * Initial compass bearing from `from` to `to`.
+ *
+ * Compass convention: **0 = North, 90 = East, 180 = South, 270 = West**, result
+ * in `[0, 360)`.
+ * @param from - origin point (degrees)
+ * @param to - destination point (degrees)
+ * @returns bearing in degrees `[0, 360)`
+ */
+export function bearing(from, to) {
+    const phi1 = degToRad(from.lat);
+    const phi2 = degToRad(to.lat);
+    const deltaLambda = degToRad(to.lng - from.lng);
+    const y = Math.sin(deltaLambda) * Math.cos(phi2);
+    const x = Math.cos(phi1) * Math.sin(phi2) - Math.sin(phi1) * Math.cos(phi2) * Math.cos(deltaLambda);
+    return (radToDeg(Math.atan2(y, x)) + 360) % 360;
+}
+/**
+ * Destination point given an origin, distance, and compass bearing.
+ * @param from - starting point (degrees)
+ * @param distanceM - distance in metres
+ * @param bearingDeg - initial compass bearing in degrees (0 = North, CW)
+ * @returns the destination {@link LatLng}
+ */
+export function destinationPoint(from, distanceM, bearingDeg) {
+    const delta = distanceM / EARTH_RADIUS_METERS;
+    const theta = degToRad(bearingDeg);
+    const phi1 = degToRad(from.lat);
+    const lambda1 = degToRad(from.lng);
+    const phi2 = Math.asin(Math.sin(phi1) * Math.cos(delta) + Math.cos(phi1) * Math.sin(delta) * Math.cos(theta));
+    const lambda2 = lambda1 +
+        Math.atan2(Math.sin(theta) * Math.sin(delta) * Math.cos(phi1), Math.cos(delta) - Math.sin(phi1) * Math.sin(phi2));
+    // Wrap longitude into (-180, 180] so results past the antemeridian stay canonical
+    // (parity with the floorplan `gps.ts` source being consolidated). `lambda2` is in
+    // radians, so `normalizeAngle` is exactly the longitude wrap.
+    return { lat: radToDeg(phi2), lng: radToDeg(normalizeAngle(lambda2)) };
+}
+// ---------------------------------------------------------------------------
+// Planar ↔ geographic projection (two-anchor affine bridge)
+// ---------------------------------------------------------------------------
+/**
+ * Projects a local 2D point to geographic coordinates using two anchor
+ * correspondences. The projection uses a polar-coordinate affine transform:
+ * it measures the local point's distance and angular offset relative to the
+ * anchor baseline vector, then applies that same distance ratio and angular
+ * offset in geographic space starting from anchor `a`.
+ *
+ * The projection is an **affine similarity transform** (scale + rotation +
+ * translation), valid when the local→geo mapping is approximately uniform
+ * scale and rotation over the region of interest (true for convention-centre
+ * scale floorplans).
+ * @param point - local 2D point to project
+ * @param a - first anchor (local origin of the baseline)
+ * @param b - second anchor (local end of the baseline)
+ * @returns the geographic position corresponding to `point`
+ */
+export function projectLocalToGps(point, a, b) {
+    // Baseline vector in local space (anchor A → anchor B)
+    const baseDx = b.local.x - a.local.x;
+    const baseDy = b.local.y - a.local.y;
+    const baseLen = Math.sqrt(baseDx * baseDx + baseDy * baseDy);
+    // Vector from anchor A to the query point in local space
+    const pointDx = point.x - a.local.x;
+    const pointDy = point.y - a.local.y;
+    const pointLen = Math.sqrt(pointDx * pointDx + pointDy * pointDy);
+    // Angular offset of point from the baseline, in degrees
+    const baseAngleDeg = radToDeg(Math.atan2(baseDy, baseDx));
+    const pointAngleDeg = radToDeg(Math.atan2(pointDy, pointDx));
+    const deltaAngleDeg = pointAngleDeg - baseAngleDeg;
+    // Scale factor and geographic distance
+    const distanceRatio = baseLen === 0 ? 0 : pointLen / baseLen;
+    const fullGeoDistM = haversineDistance(a.geo, b.geo);
+    const pointDistM = distanceRatio * fullGeoDistM;
+    // Compass bearing of the baseline in geographic space
+    const baseBearingDeg = bearing(a.geo, b.geo);
+    // Apply: start from anchor A, go pointDistM along (baseBearing + angularOffset)
+    return destinationPoint(a.geo, pointDistM, baseBearingDeg + deltaAngleDeg);
+}
+/**
+ * Projects a geographic point to local 2D coordinates using two anchor
+ * correspondences. This is the inverse of {@link projectLocalToGps}.
+ *
+ * It measures the geographic point's great-circle distance and compass-bearing
+ * offset relative to the anchor baseline (anchor A → anchor B), then reproduces
+ * that same distance ratio and angular offset in local planar space — inverting
+ * the affine similarity (scale + rotation + translation) bridge. Like the forward
+ * transform, it assumes an approximately uniform scale and rotation over the region.
+ * @param geo - geographic point to project
+ * @param a - first anchor (local origin of the baseline)
+ * @param b - second anchor (local end of the baseline)
+ * @returns the local 2D point corresponding to `geo`
+ */
+export function projectGpsToLocal(geo, a, b) {
+    // Geographic distances and bearings from anchor A
+    const fullGeoDistM = haversineDistance(a.geo, b.geo);
+    const baseBearingDeg = bearing(a.geo, b.geo);
+    const pointDistM = haversineDistance(a.geo, geo);
+    const pointBearingDeg = bearing(a.geo, geo);
+    // Angular offset in geographic space
+    const deltaAngleDeg = pointBearingDeg - baseBearingDeg;
+    // Scale factor
+    const distanceRatio = fullGeoDistM === 0 ? 0 : pointDistM / fullGeoDistM;
+    // Baseline vector in local space
+    const baseDx = b.local.x - a.local.x;
+    const baseDy = b.local.y - a.local.y;
+    const baseLen = Math.sqrt(baseDx * baseDx + baseDy * baseDy);
+    // Direction angle of baseline in local space (planar radians)
+    const baseAngleRad = Math.atan2(baseDy, baseDx);
+    // Shift from anchor A along baseline direction by scaled distance,
+    // then rotate by the angular offset
+    const shiftLen = baseLen * distanceRatio;
+    const shiftAngleRad = baseAngleRad + degToRad(deltaAngleDeg);
+    // Polar → cartesian in local planar space, offset from anchor A.
+    const offset = fromPolar(shiftLen, shiftAngleRad);
+    return { x: a.local.x + offset.x, y: a.local.y + offset.y };
+}

package/dist/lib/intersections.d.ts

@@ -0,0 +1,30 @@
+import type { LineLike } from './line.js';
+import { type Point } from './point.js';
+import { type RectLike } from './rect.js';
+/**
+ * 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 declare function lineIntersection(a: LineLike, b: LineLike, elevationTolerance?: number): {
+    point: Point;
+    onLine1: boolean;
+    onLine2: boolean;
+} | 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 declare function intersectLineRect(line: LineLike, rect: RectLike, elevationTolerance?: number): Point[];
+//# sourceMappingURL=intersections.d.ts.map