@metamesh/modeling 0.0.0-stage → 0.7.0

package/dist/geometry/profiles/shapes.js

@@ -0,0 +1,41 @@
+import { GeometryError } from "../errors.js";
+import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
+import { assertPrimitiveOptions } from "../primitive-resolvers.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
+/**
+ * Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling.
+ *
+ * @example Ellipse by full dimensions
+ * ```ts
+ * ellipseLoop({ size: [30, 20] });
+ * ```
+ */
+export function ellipseLoop(options) {
+    assertPrimitiveOptions(options, "ellipseLoop");
+    if ((options.radius === undefined) === (options.size === undefined)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Specify exactly one radius or size tuple.", {
+            operation: "ellipseLoop",
+        });
+    }
+    const dimensions = options.radius ?? options.size;
+    if (!Array.isArray(dimensions) || dimensions.length !== 2) {
+        throw new GeometryError("INVALID_ARGUMENT", "Ellipse dimensions must be an exact XY tuple.", {
+            operation: "ellipseLoop",
+        });
+    }
+    const factor = options.radius === undefined ? 0.5 : 1;
+    const radiusX = dimensions[0] * factor;
+    const radiusY = dimensions[1] * factor;
+    requireFiniteProfileValues([radiusX, radiusY], "ellipseLoop");
+    if (![radiusX, radiusY].every((value) => Number.isFinite(value) && value > 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Ellipse radii must be finite and positive.", {
+            operation: "ellipseLoop",
+        });
+    }
+    const segments = resolveCircularPrimitiveSegments(Math.max(radiusX, radiusY), options, "ellipseLoop");
+    requireProfileVertexCount(segments, 3, "ellipseLoop", options.limits);
+    return Object.freeze(Array.from({ length: segments }, (_, index) => {
+        const angle = (index * Math.PI * 2) / segments;
+        return Object.freeze([radiusX * Math.cos(angle), radiusY * Math.sin(angle)]);
+    }));
+}

package/dist/geometry/profiles/span-sampling.js

@@ -0,0 +1,28 @@
+import { CubicEvaluator, planarCubicControl } from "../curves/evaluation.js";
+/** @internal Samples validated profile spans, retaining exact cardinal arc endpoints. */
+export function createProfileSpanSampler(span) {
+    if (span.kind === "line")
+        return (t) => [
+            span.start[0] + (span.end[0] - span.start[0]) * t,
+            span.start[1] + (span.end[1] - span.start[1]) * t,
+        ];
+    if (span.kind === "arc")
+        return (t) => {
+            const angle = ((span.startDegrees + span.sweepDegrees * t) * Math.PI) / 180;
+            const snap = (value) => Math.abs(value) < 1e-14
+                ? 0
+                : Math.abs(Math.abs(value) - 1) < 1e-14
+                    ? Math.sign(value)
+                    : value;
+            return [
+                span.center[0] + span.radius * snap(Math.cos(angle)),
+                span.center[1] + span.radius * snap(Math.sin(angle)),
+            ];
+        };
+    const evaluator = new CubicEvaluator(planarCubicControl(span));
+    const point = [0, 0, 0];
+    return (t) => {
+        evaluator.point(t, point);
+        return [point[0], point[1]];
+    };
+}

package/dist/geometry/profiles/types.js

@@ -0,0 +1 @@
+export {};

package/dist/geometry/profiles/validation.js

@@ -0,0 +1,20 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+/** @internal Validates finite dimensions shared by the pure profile factories. */
+export function requireFiniteProfileValues(values, operation) {
+    if (!values.every(Number.isFinite)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Profile dimensions and angles must be finite.", {
+            operation,
+        });
+    }
+}
+/** @internal Checks an exact profile count before allocating vertices. */
+export function requireProfileVertexCount(count, minimum, operation, limits = {}) {
+    if (!Number.isSafeInteger(count) || count < minimum) {
+        throw new GeometryError("INVALID_ARGUMENT", `A profile needs at least ${minimum} samples.`, {
+            operation,
+            details: { count },
+        });
+    }
+    assertSamplingCount(count, operation, resolveGeometrySamplingLimits(limits).maxProfilePoints);
+}

package/dist/geometry/regions.js

@@ -0,0 +1,371 @@
+import { GeometryError } from "./errors.js";
+import { resolveGeometryTolerance } from "./tolerance.js";
+// Only our deeply frozen, canonical outputs enter these registries. Object.isFrozen alone
+// cannot establish validation provenance, and caller-owned inputs must never be cached.
+const normalizedLoops = new WeakMap();
+const normalizedPolygons = new WeakMap();
+const normalizedRegions = new WeakMap();
+const samePolicy = (a, b) => a !== undefined &&
+    a.absolute === b.absolute &&
+    a.relative === b.relative &&
+    a.angular === b.angular;
+const reusableLoop = (loop, counterClockwise, policy) => {
+    const known = normalizedLoops.get(loop);
+    return known?.counterClockwise === counterClockwise && samePolicy(known.policy, policy);
+};
+const cross2 = (a, b, c) => (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+const distanceSquared = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2;
+const coordinateScale = (loop) => {
+    if (loop.length === 0)
+        return 0;
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const [x, y] of loop) {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    }
+    return Math.max(maxX - minX, maxY - minY);
+};
+/** Returns the signed area of a non-duplicated loop; positive means CCW. */
+export function signedAreaLoop2(loop) {
+    if (loop.length === 0)
+        return 0;
+    const origin = loop[0];
+    let twiceArea = 0, correction = 0;
+    for (let index = 0; index < loop.length; index += 1) {
+        const current = loop[index];
+        const next = loop[(index + 1) % loop.length];
+        const contribution = (current[0] - origin[0]) * (next[1] - origin[1]) -
+            (next[0] - origin[0]) * (current[1] - origin[1]);
+        const nextArea = twiceArea + contribution;
+        correction +=
+            Math.abs(twiceArea) >= Math.abs(contribution)
+                ? twiceArea - nextArea + contribution
+                : contribution - nextArea + twiceArea;
+        twiceArea = nextArea;
+    }
+    return (twiceArea + correction) / 2;
+}
+/** Returns true when a point lies inside or on the boundary of a loop. */
+export function loopContainsPoint(loop, point) {
+    let inside = false;
+    for (let index = 0, previous = loop.length - 1; index < loop.length; previous = index++) {
+        const a = loop[index];
+        const b = loop[previous];
+        const edgeCross = cross2(a, b, point);
+        if (Math.abs(edgeCross) <= Number.EPSILON &&
+            point[0] >= Math.min(a[0], b[0]) &&
+            point[0] <= Math.max(a[0], b[0]) &&
+            point[1] >= Math.min(a[1], b[1]) &&
+            point[1] <= Math.max(a[1], b[1])) {
+            return true;
+        }
+        if (a[1] > point[1] !== b[1] > point[1] &&
+            point[0] < ((b[0] - a[0]) * (point[1] - a[1])) / (b[1] - a[1]) + a[0]) {
+            inside = !inside;
+        }
+    }
+    return inside;
+}
+const orientation = (a, b, c, epsilon) => {
+    const value = cross2(a, b, c);
+    // A cross product is an area: a distance tolerance must be multiplied by edge length.
+    const areaTolerance = epsilon * Math.hypot(b[0] - a[0], b[1] - a[1]);
+    return Math.abs(value) <= areaTolerance ? 0 : value > 0 ? 1 : -1;
+};
+const onSegment = (a, b, point, epsilon) => point[0] >= Math.min(a[0], b[0]) - epsilon &&
+    point[0] <= Math.max(a[0], b[0]) + epsilon &&
+    point[1] >= Math.min(a[1], b[1]) - epsilon &&
+    point[1] <= Math.max(a[1], b[1]) + epsilon;
+const segmentsIntersect = (a, b, c, d, epsilon) => {
+    const abC = orientation(a, b, c, epsilon);
+    const abD = orientation(a, b, d, epsilon);
+    const cdA = orientation(c, d, a, epsilon);
+    const cdB = orientation(c, d, b, epsilon);
+    if (abC * abD < 0 && cdA * cdB < 0)
+        return true;
+    return ((abC === 0 && onSegment(a, b, c, epsilon)) ||
+        (abD === 0 && onSegment(a, b, d, epsilon)) ||
+        (cdA === 0 && onSegment(c, d, a, epsilon)) ||
+        (cdB === 0 && onSegment(c, d, b, epsilon)));
+};
+const MAX_INTERSECTION_CANDIDATES = 2_000_000;
+// This private helper only receives the immutable loops produced by normalization.
+const normalizedLoopBounds = new WeakMap();
+const loopBounds = (loop) => {
+    const known = normalizedLoopBounds.get(loop);
+    if (known !== undefined)
+        return known;
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const [x, y] of loop) {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    }
+    const result = { minX, minY, maxX, maxY };
+    normalizedLoopBounds.set(loop, result);
+    return result;
+};
+const boundsOverlap = (a, b, epsilon) => a.maxX + epsilon >= b.minX &&
+    b.maxX + epsilon >= a.minX &&
+    a.maxY + epsilon >= b.minY &&
+    b.maxY + epsilon >= a.minY;
+const boundedSegments = (loop, epsilon) => loop.map((a, index) => {
+    const b = loop[(index + 1) % loop.length];
+    return {
+        a,
+        b,
+        index,
+        loop,
+        minX: Math.min(a[0], b[0]) - epsilon,
+        maxX: Math.max(a[0], b[0]) + epsilon,
+        minY: Math.min(a[1], b[1]) - epsilon,
+        maxY: Math.max(a[1], b[1]) + epsilon,
+    };
+});
+const consumeIntersectionCandidate = (budget) => {
+    budget.candidates += 1;
+    if (budget.candidates > MAX_INTERSECTION_CANDIDATES) {
+        throw new GeometryError("COMPLEXITY_LIMIT", "Region validation exceeds the 2000000 intersection-candidate work limit.", { operation: "normalizeRegion2", details: { maximumCandidates: MAX_INTERSECTION_CANDIDATES } });
+    }
+};
+const boundedIntersections = (segments, epsilon, budget, sameLoop) => {
+    segments.sort((a, b) => a.minX - b.minX || a.minY - b.minY || a.index - b.index);
+    const firstLoop = segments[0]?.loop;
+    const active = [[], []];
+    for (const current of segments) {
+        const ownGroup = sameLoop || current.loop === firstLoop ? 0 : 1;
+        const candidates = active[sameLoop ? 0 : 1 - ownGroup];
+        let retained = 0;
+        for (const candidate of candidates) {
+            if (candidate.maxX < current.minX)
+                continue;
+            candidates[retained++] = candidate;
+            consumeIntersectionCandidate(budget);
+            if (candidate.maxY < current.minY || current.maxY < candidate.minY)
+                continue;
+            if (sameLoop) {
+                if ((candidate.index + 1) % current.loop.length === current.index ||
+                    (current.index + 1) % current.loop.length === candidate.index)
+                    continue;
+            }
+            if (segmentsIntersect(candidate.a, candidate.b, current.a, current.b, epsilon))
+                return true;
+        }
+        candidates.length = retained;
+        active[ownGroup].push(current);
+    }
+    return false;
+};
+const loopsIntersect = (a, b, epsilon, budget) => a === b ||
+    (boundsOverlap(loopBounds(a), loopBounds(b), 2 * epsilon) &&
+        boundedIntersections([...boundedSegments(a, epsilon), ...boundedSegments(b, epsilon)], epsilon, budget, false));
+/**
+ * Cleans and validates one closed loop.
+ *
+ * Adjacent duplicates and a repeated seam point are removed. Coordinates must
+ * be finite, the effective loop must contain at least three points, and the
+ * result must be simple and have non-zero area. Previously validated immutable results may be
+ * returned unchanged when their winding and tolerance policy match.
+ */
+export function normalizeLoop2(input, counterClockwise, tolerance = {}) {
+    return normalizeLoopWithBudget(input, counterClockwise, tolerance, { candidates: 0 });
+}
+const normalizeLoopWithBudget = (input, counterClockwise, tolerance, budget) => {
+    const policy = resolveGeometryTolerance(1, tolerance);
+    if (reusableLoop(input, counterClockwise, policy))
+        return input;
+    if (!input.every((point) => Number.isFinite(point[0]) && Number.isFinite(point[1]) && point.every(Number.isFinite))) {
+        throw new GeometryError("NON_FINITE_VALUE", "Loop coordinates must be finite.");
+    }
+    const scale = coordinateScale(input);
+    const resolved = resolveGeometryTolerance(scale, policy);
+    const epsilonSquared = resolved.linear ** 2;
+    const cleaned = [];
+    for (const point of input) {
+        const copied = Object.freeze([point[0], point[1]]);
+        if (cleaned.length === 0 || distanceSquared(cleaned.at(-1), copied) > epsilonSquared) {
+            cleaned.push(copied);
+        }
+    }
+    while (cleaned.length > 1 && distanceSquared(cleaned[0], cleaned.at(-1)) <= epsilonSquared) {
+        cleaned.pop();
+    }
+    if (cleaned.length < 3) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "A loop needs at least three distinct points.");
+    }
+    if (boundedIntersections(boundedSegments(cleaned, resolved.linear), resolved.linear, budget, true)) {
+        throw new GeometryError("SELF_INTERSECTION", "A loop must not self-intersect.");
+    }
+    const area = signedAreaLoop2(cleaned);
+    if (!Number.isFinite(area)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Loop area must be finite.");
+    }
+    if (Math.abs(area) <= resolved.area) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "A loop must have non-zero area.");
+    }
+    const ordered = area > 0 === counterClockwise ? cleaned : [...cleaned].reverse();
+    const result = Object.freeze(ordered);
+    // Cleanup can change the scale used by relative tolerances, or expose another short seam.
+    // Such outputs must take the ordinary path on the next call until normalization is stable.
+    if (resolveGeometryTolerance(coordinateScale(result), policy).linear === resolved.linear &&
+        distanceSquared(result[0], result.at(-1)) > epsilonSquared) {
+        normalizedLoops.set(result, { policy, counterClockwise });
+    }
+    return result;
+};
+/**
+ * Validates explicit polygon topology and normalizes its winding.
+ *
+ * Exteriors become CCW and holes clockwise. Every hole must lie strictly
+ * within its exterior and boundaries may not intersect. Previously validated immutable results
+ * may be returned unchanged under the same tolerance policy.
+ */
+export function normalizePolygon2(polygon, tolerance = {}) {
+    return normalizePolygonWithBudget(polygon, tolerance, { candidates: 0 });
+}
+const normalizePolygonWithBudget = (polygon, tolerance, budget) => {
+    const policy = resolveGeometryTolerance(1, tolerance);
+    if (samePolicy(normalizedPolygons.get(polygon), policy))
+        return polygon;
+    const outer = normalizeLoopWithBudget(polygon.outer, true, policy, budget);
+    const holes = polygon.holes.map((hole) => normalizeLoopWithBudget(hole, false, policy, budget));
+    const scale = coordinateScale(outer);
+    const epsilon = resolveGeometryTolerance(scale, policy).linear;
+    for (let index = 0; index < holes.length; index += 1) {
+        const hole = holes[index];
+        if (!loopContainsPoint(outer, hole[0]) || loopsIntersect(outer, hole, epsilon, budget)) {
+            throw new GeometryError("INVALID_TOPOLOGY", "Every hole must lie inside its exterior.");
+        }
+    }
+    const boundedHoles = holes
+        .map((loop, index) => ({ loop, index, ...loopBounds(loop) }))
+        .sort((a, b) => a.minX - b.minX || a.minY - b.minY || a.index - b.index);
+    const activeHoles = [];
+    for (const current of boundedHoles) {
+        let retained = 0;
+        for (const previous of activeHoles) {
+            if (previous.maxX + 2 * epsilon < current.minX)
+                continue;
+            activeHoles[retained++] = previous;
+            consumeIntersectionCandidate(budget);
+            if (!boundsOverlap(previous, current, 2 * epsilon))
+                continue;
+            if (loopsIntersect(previous.loop, current.loop, epsilon, budget) ||
+                loopContainsPoint(previous.loop, current.loop[0]) ||
+                loopContainsPoint(current.loop, previous.loop[0])) {
+                throw new GeometryError("INVALID_TOPOLOGY", "Polygon holes must be disjoint.");
+            }
+        }
+        activeHoles.length = retained;
+        activeHoles.push(current);
+    }
+    const result = Object.freeze({ holes: Object.freeze(holes), outer });
+    if (reusableLoop(outer, true, policy) &&
+        holes.every((hole) => reusableLoop(hole, false, policy))) {
+        normalizedPolygons.set(result, policy);
+    }
+    return result;
+};
+/**
+ * Validates a disjoint explicit region and returns immutable normalized data.
+ * Previously validated immutable results may be returned unchanged under the same tolerance policy.
+ */
+export function normalizeRegion2(region, tolerance = {}) {
+    const policy = resolveGeometryTolerance(1, tolerance);
+    if (samePolicy(normalizedRegions.get(region), policy))
+        return region;
+    for (let index = 0; index < region.length; index += 1) {
+        if (!Object.hasOwn(region, index)) {
+            throw new GeometryError("INVALID_TOPOLOGY", "Region polygons must not contain missing entries.");
+        }
+    }
+    const budget = { candidates: 0 };
+    const polygons = region.map((polygon) => normalizePolygonWithBudget(polygon, policy, budget));
+    const containsFilledPoint = (polygon, point) => loopContainsPoint(polygon.outer, point) &&
+        !polygon.holes.some((hole) => loopContainsPoint(hole, point));
+    // Broad phase preserves exact contact semantics while avoiding pairwise loop
+    // walks for separated polygons (for example many disconnected QR modules).
+    const bounded = polygons
+        .map((polygon) => {
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        for (const [x, y] of polygon.outer) {
+            minX = Math.min(minX, x);
+            minY = Math.min(minY, y);
+            maxX = Math.max(maxX, x);
+            maxY = Math.max(maxY, y);
+        }
+        return { polygon, minX, minY, maxX, maxY };
+    })
+        .sort((a, b) => a.minX - b.minX);
+    const active = [];
+    for (const current of bounded) {
+        let retained = 0;
+        for (const candidate of active) {
+            if (candidate.maxX < current.minX)
+                continue;
+            active[retained++] = candidate;
+            consumeIntersectionCandidate(budget);
+            if (candidate.maxY < current.minY || current.maxY < candidate.minY)
+                continue;
+            const a = current.polygon.outer;
+            const b = candidate.polygon.outer;
+            if (loopsIntersect(a, b, 0, budget) ||
+                current.polygon.holes.some((hole) => loopsIntersect(hole, b, 0, budget)) ||
+                candidate.polygon.holes.some((hole) => loopsIntersect(a, hole, 0, budget)) ||
+                containsFilledPoint(current.polygon, b[0]) ||
+                containsFilledPoint(candidate.polygon, a[0])) {
+                throw new GeometryError("INVALID_TOPOLOGY", "Region polygons must be disjoint.");
+            }
+        }
+        active.length = retained;
+        active.push(current);
+    }
+    const result = Object.freeze(polygons);
+    if (polygons.every((polygon) => samePolicy(normalizedPolygons.get(polygon), policy))) {
+        normalizedRegions.set(result, policy);
+    }
+    return result;
+}
+/**
+ * Returns the total filled area of a normalized region in square millimetres.
+ *
+ * Each polygon contributes its outer-loop area minus the areas of its holes. An empty region has
+ * zero area. Call {@link normalizeRegion2} first when input winding or topology is not already
+ * canonical.
+ *
+ * @param region - Normalized disjoint polygons with CCW outers and clockwise holes.
+ * @returns Total filled area in square millimetres.
+ */
+export function regionArea(region) {
+    return region.reduce((total, polygon) => total +
+        Math.abs(signedAreaLoop2(polygon.outer)) -
+        polygon.holes.reduce((holeTotal, hole) => holeTotal + Math.abs(signedAreaLoop2(hole)), 0), 0);
+}
+/** Returns finite axis-aligned bounds for a non-empty region. */
+export function regionBounds(region) {
+    if (region.length === 0) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "An empty region has no bounds.");
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const polygon of region) {
+        for (const [x, y] of polygon.outer) {
+            minX = Math.min(minX, x);
+            minY = Math.min(minY, y);
+            maxX = Math.max(maxX, x);
+            maxY = Math.max(maxY, y);
+        }
+    }
+    return Object.freeze({
+        max: Object.freeze([maxX, maxY]),
+        min: Object.freeze([minX, minY]),
+    });
+}