@hatiolab/figure-model 0.9.5 → 0.9.6

package/dist/authoring-occupancy.js

@@ -6,12 +6,13 @@
  */
 import { upgradeFigurePlacement, figurePlacementOf } from "./asset.js";
 import { compileFigureGraph } from "./graph.js";
+import { figureShapeDescriptionOf } from "./shape-ops.js";
 import { FigureContractError } from "./contract.js";
 import { AXES } from "./words.js";
 import { FIGURE_PLACEMENTS } from "./asset-types.js";
 import { FIGURE_FACES } from "./authoring-types.js";
 import { fail, nodeById, writerOf, throughSums, rowHolding, partOf, namer, constantOf, dropIfUnused, parentOf, round6, stringsIn } from "./authoring-nodes.js";
-import { isReach, sizeRefsOf, occupiedExtentsOf, angleOf, turnMatrix, mul3, standingRefsOf, half, IDENTITY } from "./authoring-geometry.js";
+import { isReach, sizeRefsOf, occupiedExtentsOf, angleOf, turnMatrix, mul3, standingRefsOf, half, axisTurn, offCentreEndsOf, IDENTITY } from "./authoring-geometry.js";
 /** A figure as one value, for saying "this is the figure I read". The declaration itself is left out of it. */
 function fingerprintOf(asset) {
     /*
@@ -133,7 +134,7 @@ function poseTurnOf(m, asset, part) {
 const seatTurned = (m, asset, part) => (nodeById(m, `${part}.seat.rigid`)?.args.slice(3, 6) ?? []).some((ref) => angleOf(m, asset, ref) !== 0);
 /**
  * Whether a part, or anything carrying it, turns on a joint, stands turned by other than quarter turns, or is seated
- * turned: a box cannot follow it, a ball about the point it turns at can (`reachOf`).
+ * turned: a box cannot follow it, its reach about the point it turns at can (`reachOf`).
  */
 function carriedByATurn(m, asset, id) {
     for (let part = id; part; part = parentOf(m, part)) {
@@ -258,8 +259,9 @@ function sizeValue(m, ref, seen = 0) {
     if (seen > 64)
         return false;
     const input = m.inputs.find((i) => i.id === ref);
+    /* The instance size is never below zero, its smallest end given or not (ADR-0087 decision 6). */
     if (input)
-        return input.role !== 'state' && input.min >= 0;
+        return input.role !== 'state' && (/^size\.[xyz]$/.test(input.id) || input.min >= 0);
     const w = writerOf(m, ref);
     const positive = (r) => (m.constants.find((c) => c.id === r)?.value ?? -1) > 0;
     if (w?.op === 'geomean@1')
@@ -413,14 +415,111 @@ function boundedSides(m, low, high) {
         high[axis] = high[axis].flatMap(l => boundsOf(m, l, true));
     }
 }
+const transposedTimes = (r, d) => [0, 1, 2].map(j => r[0][j] * d[0] + r[1][j] * d[1] + r[2][j] * d[2]);
+/** A turn as `rigid@1` writes it, in degrees about X, Y and Z: Rx·Ry·Rz, at any angle (`turnMatrix` takes quarter turns). */
+const rigidTurnOf = ([x, y, z]) => mul3(mul3(axisTurn('x', x), axisTurn('y', y)), axisTurn('z', z));
+/** The directions seen from a frame turned by `r` from this one (a point there is r·x here). */
+function turnedBy(d, r) {
+    if ('one' in d)
+        return { one: transposedTimes(r, d.one) };
+    return { most: [0, 1, 2].map(j => Math.min(1, d.most.reduce((sum, v, i) => sum + Math.abs(r[i][j]) * v, 0))) };
+}
+/** The largest |a + b cos t + c sin t| for t from lo to hi, in radians; all the way round without a range. */
+function largestOver(a, b, c, range) {
+    if (!range)
+        return Math.abs(a) + Math.hypot(b, c);
+    const [lo, hi] = range;
+    const at = (t) => Math.abs(a + b * Math.cos(t) + c * Math.sin(t));
+    let most = Math.max(at(lo), at(hi));
+    /* Where its slope is zero: t = atan2(c, b) and half a turn from it, every whole turn over. */
+    const turn = 2 * Math.PI;
+    for (const t0 of [Math.atan2(c, b), Math.atan2(c, b) + Math.PI])
+        for (let t = t0 + Math.ceil((lo - t0) / turn) * turn; t <= hi; t += turn)
+            most = Math.max(most, at(t));
+    return most;
+}
+/**
+ * The directions seen from a frame turned about the unit axis `u` by any angle in `range` (radians; null all the way
+ * round): R(t) = u uᵀ + (I − u uᵀ) cos t + [u]× sin t, each entry a + b cos t + c sin t.
+ */
+function sweptBy(d, u, range) {
+    const K = [
+        [0, -u[2], u[1]],
+        [u[2], 0, -u[0]],
+        [-u[1], u[0], 0]
+    ];
+    const A = (i, j) => u[i] * u[j];
+    const B = (i, j) => (i === j ? 1 : 0) - u[i] * u[j];
+    const C = (i, j) => K[i][j];
+    if (range && Math.abs(range[1] - range[0]) < 1e-12) {
+        const t = range[0];
+        return turnedBy(d, [0, 1, 2].map(i => [0, 1, 2].map(j => A(i, j) + B(i, j) * Math.cos(t) + C(i, j) * Math.sin(t))));
+    }
+    if ('one' in d) {
+        const v = d.one;
+        const sum = (f, j) => [0, 1, 2].reduce((s, i) => s + f(i, j) * v[i], 0);
+        const parts = [0, 1, 2].map(j => [sum(A, j), sum(B, j), sum(C, j)]);
+        /* Along the axis it is turned about, a direction does not move. */
+        if (parts.every(([, b, c]) => Math.abs(b) < 1e-12 && Math.abs(c) < 1e-12))
+            return d;
+        return { most: parts.map(([a, b, c]) => Math.min(1, largestOver(a, b, c, range))) };
+    }
+    return {
+        most: [0, 1, 2].map(j => Math.min(1, d.most.reduce((s, v, i) => s + largestOver(A(i, j), B(i, j), C(i, j), range) * v, 0)))
+    };
+}
+/**
+ * The angles a turn's control can give it, in degrees: its limits, scaled and moved as the angle is written from it.
+ * Null -- all the way round -- for a control without limits or that turns a whole turn, and for an angle written any
+ * other way.
+ */
+function angleRangeOf(m, ref, depth = 0) {
+    if (depth > 64)
+        return null;
+    const constant = m.constants.find((c) => c.id === ref);
+    if (constant)
+        return constant.unit === 'deg' ? [constant.value, constant.value] : null;
+    const input = m.inputs.find((i) => i.id === ref);
+    if (input) {
+        if (input.role !== 'state' || input.unit !== 'deg')
+            return null;
+        const { min, max } = input;
+        return Number.isFinite(min) && Number.isFinite(max) && max - min < 360 ? [min, max] : null;
+    }
+    const w = writerOf(m, ref);
+    if (w?.op === 'add@1') {
+        let lo = 0, hi = 0;
+        for (const arg of w.args) {
+            const r = angleRangeOf(m, arg, depth + 1);
+            if (!r)
+                return null;
+            lo += r[0];
+            hi += r[1];
+        }
+        return hi - lo < 360 ? [lo, hi] : null;
+    }
+    if (w?.op === 'mul@1' && w.args.length === 2) {
+        const factor = (arg) => m.constants.find((c) => c.id === arg && c.unit === 'ratio')?.value;
+        const [a, b] = w.args;
+        const k = factor(a) ?? factor(b);
+        const r = factor(a) !== undefined ? angleRangeOf(m, b, depth + 1) : factor(b) !== undefined ? angleRangeOf(m, a, depth + 1) : null;
+        if (k === undefined || !r)
+            return null;
+        const ends = [r[0] * k, r[1] * k].sort((x, y) => x - y);
+        return ends[1] - ends[0] < 360 ? ends : null;
+    }
+    return null;
+}
 /**
- * Where a part carried by a turn can reach: a ball about the point the first turn above it turns about, as wide as
- * every step from there to the part laid end to end, plus the part's own half size on each axis (the triangle
- * inequality -- it holds at every angle and every design size, so it is a bound, not a sample). As a box, that
- * ball is the pivot plus and minus its radius on each axis. Read by the proposal; the release gate still checks
- * the parts against it.
+ * Where a part carried by a turn can reach, on each side of each axis, from the point the first turn above it turns
+ * about (ADR-0087, amendments 2026-10-21). Down the chain from there each step adds what it can add that way: while
+ * the directions are one, what it adds, sign included; once a joint has turned them through its range, each axis's
+ * largest times the size of that coordinate -- no more than its length, when its coordinates are numbers. The part
+ * adds its own half size the same way. Each step's largest taken on its own (the triangle inequality), it holds at
+ * every angle the joints can reach and every design size: a bound, not a sample. Read by the proposal; the release
+ * gate still checks the parts against it.
  */
-function reachOf(m, asset, id, ends, freezeless = true) {
+function reachOf(m, asset, id, ends) {
     const chain = [];
     for (let part = id; part; part = parentOf(m, part))
         chain.push(part);
@@ -432,56 +531,149 @@ function reachOf(m, asset, id, ends, freezeless = true) {
         : found, -1);
     if (top < 0)
         return `${id} is carried by no turn`;
-    let radius = { terms: [], c: 0 };
-    const grow = (lin, what) => {
-        const size = lin && magnitudeOf(m, lin);
-        if (!size)
-            return `${what} is not a sum of sizes, so how far it reaches cannot be bounded`;
-        radius = linAdd(radius, size);
-        return null;
-    };
-    /* Its half size on every axis of its own, whichever way it stands: the ball holds it at any angle. */
+    const pivotPart = chain[top];
+    const parent = parentOf(m, pivotPart);
+    /* Above the pivot every part stands in quarter turns: the frame it turns in is a signed axis permutation. */
+    const frame = parent ? worldTurnOf(m, asset, parent) : IDENTITY;
+    if (!frame)
+        return `${pivotPart} is carried by a part turned by other than quarter turns`;
     const sizes = sizeRefsOf(m, id, id);
-    void freezeless;
-    for (const axis of AXES) {
-        const bad = grow({ terms: [{ ref: sizes[axis].ref, k: 0.5 * sizes[axis].k }], c: 0 }, `${id}'s size`);
-        if (bad)
-            return bad;
-    }
-    for (let i = 0; i <= top; i++) {
-        const part = chain[i];
-        const pose = nodeById(m, `${part}.pose`);
-        if (!pose)
-            return `${part} has no pose this command can read`;
-        for (const ref of pose.args.slice(0, 3)) {
-            const bad = grow(linOf(m, ref), `${part}'s place`);
-            if (bad)
-                return bad;
-        }
-        if (i < top) {
-            const seat = nodeById(m, `${part}.seat.rigid`);
-            for (const ref of seat?.args.slice(0, 3) ?? []) {
-                const bad = grow(linOf(m, ref), `where ${part} is fastened`);
-                if (bad)
-                    return bad;
+    const { shape } = partOf(m, id, id);
+    const faces = figureShapeDescriptionOf(shape)?.faces;
+    const offCentre = Object.fromEntries(AXES.map(axis => [axis, offCentreEndsOf(shape, faces, axis)]));
+    const constants = (refs) => refs.map(r => m.constants.find((c) => c.id === r)?.value);
+    const angles = (refs) => refs.map(r => angleOf(m, asset, r));
+    const reachToward = (e) => {
+        let d = { one: transposedTimes(frame, e) };
+        let out = { terms: [], c: 0 };
+        const most = (dir) => ('one' in dir ? dir.one.map(Math.abs) : dir.most);
+        /* A step of three coordinates, in the frame the directions are seen from. */
+        const step = (refs, what) => {
+            if ('one' in d) {
+                const v = d.one;
+                refs.forEach((ref, i) => {
+                    if (Math.abs(v[i]) > 1e-12)
+                        out = linAdd(out, linOf(m, ref), v[i]);
+                });
+                return null;
             }
-            const motion = nodeById(m, `${part}.motion`);
-            if (motion?.op === 'axis-slide@1')
-                for (const end of ['min', 'max']) {
-                    const bad = grow(travelAt(m, asset, motion, end), `${part}'s travel`);
+            const w = d.most;
+            const numbers = constants(refs);
+            if (numbers.every(n => n !== undefined)) {
+                const across = numbers.reduce((s, n, i) => s + w[i] * Math.abs(n), 0);
+                const length = Math.hypot(...numbers.map((n, i) => (w[i] > 0 ? n : 0)));
+                out = linAdd(out, { terms: [], c: Math.min(across, length) });
+                return null;
+            }
+            for (const [i, ref] of refs.entries()) {
+                if (!w[i])
+                    continue;
+                const size = magnitudeOf(m, linOf(m, ref));
+                if (!size)
+                    return `${what} is not a sum of sizes, so how far it reaches cannot be bounded`;
+                out = linAdd(out, size, w[i]);
+            }
+            return null;
+        };
+        const turnTo = (refs) => {
+            const a = angles(refs);
+            if (a.every(t => t === 0))
+                return;
+            d = a.every(t => t !== null && Number.isFinite(t))
+                ? turnedBy(d, rigidTurnOf(a))
+                : { most: [0, 1, 2].map(() => Math.min(1, most(d).reduce((s, v) => s + v, 0))) };
+        };
+        for (let i = top; i >= 0; i--) {
+            const part = chain[i];
+            const seat = nodeById(m, `${part}.seat.rigid`);
+            if (seat) {
+                /* The pivot's own seat is where it turns: it is the centre, not a step. */
+                if (i < top) {
+                    const bad = step(seat.args.slice(0, 3), `where ${part} is fastened`);
                     if (bad)
                         return bad;
                 }
+                turnTo(seat.args.slice(3, 6));
+            }
+            const motion = nodeById(m, `${part}.motion`);
+            if (motion) {
+                const unit = constants(motion.args.slice(0, 3));
+                if (unit.some(u => u === undefined))
+                    return `${part}'s ${motion.op === 'axis-turn@1' ? 'turn' : 'slide'} axis is not a constant`;
+                const n = Math.hypot(...unit);
+                const u = unit.map(v => v / n);
+                if (motion.op === 'axis-turn@1') {
+                    const range = angleRangeOf(m, motion.args[3]);
+                    d = sweptBy(d, u, range && [(range[0] * Math.PI) / 180, (range[1] * Math.PI) / 180]);
+                }
+                else if (motion.op === 'axis-slide@1') {
+                    const along = most(d).reduce((s, v, k) => s + v * Math.abs(u[k]), 0);
+                    for (const end of ['min', 'max']) {
+                        const travel = travelAt(m, asset, motion, end);
+                        const size = travel && magnitudeOf(m, travel);
+                        if (!size)
+                            return `${part}'s travel is not a sum of sizes, so how far it reaches cannot be bounded`;
+                        out = linAdd(out, size, along);
+                    }
+                }
+                else
+                    return `${part} moves by ${motion.op}, which this command does not add up`;
+            }
+            const pose = nodeById(m, `${part}.pose`);
+            if (!pose)
+                return `${part} has no pose this command can read`;
+            const bad = step(pose.args.slice(0, 3), `${part}'s place`);
+            if (bad)
+                return bad;
+            turnTo(pose.args.slice(3, 6));
         }
+        /*
+          Its own extent on every axis, as far as the directions reach across it: half its size either way about its
+          origin, or from face to face where they do not sit about it (a portal stands on 0, `offCentreEndsOf`).
+        */
+        const w = most(d);
+        for (const [i, axis] of AXES.entries()) {
+            if (!w[i])
+                continue;
+            const ends = offCentre[axis];
+            if (ends && 'one' in d) {
+                const e = d.one[i] > 0 ? ends[1] : ends[0];
+                out = linAdd(out, { terms: [{ ref: e.ref, k: e.k * d.one[i] }], c: 0 });
+                continue;
+            }
+            const reach = ends
+                ? ends.reduce((sum, e) => {
+                    const size = sum && magnitudeOf(m, { terms: [{ ref: e.ref, k: e.k }], c: 0 });
+                    return size && sum && linAtLeast(sum, size);
+                }, { terms: [], c: 0 })
+                : magnitudeOf(m, { terms: [{ ref: sizes[axis].ref, k: 0.5 * sizes[axis].k }], c: 0 });
+            if (!reach)
+                return `${id}'s size is not a sum of sizes, so how far it reaches cannot be bounded`;
+            out = linAdd(out, reach, w[i]);
+        }
+        return linNorm(out);
+    };
+    const up = {};
+    const down = {};
+    for (const [i, axis] of AXES.entries()) {
+        const e = [0, 0, 0];
+        e[i] = 1;
+        const high = reachToward(e);
+        if (typeof high === 'string')
+            return high;
+        e[i] = -1;
+        const low = reachToward(e);
+        if (typeof low === 'string')
+            return low;
+        up[axis] = high;
+        down[axis] = low;
     }
     /*
       The pivot: where the topmost turn is fastened, and everything above it. Above it nothing turns, but a slide may
       carry it -- the telescopic conveyor's nose turns at the end of its third stage -- so the pivot is read at each
-      end of the controls, a ball at each: a slide is a straight line, so the balls at its two ends bound it all the
-      way (it had been refused, and the nose left out of the room).
+      end of the controls, a reach from each: a slide is a straight line, so the reaches from its two ends bound it all
+      the way (it had been refused, and the nose left out of the room).
     */
-    const pivotPart = chain[top];
-    const parent = parentOf(m, pivotPart);
     const seat = nodeById(m, `${pivotPart}.seat.rigid`);
     const seatAt = Object.fromEntries(AXES.map((a, i) => [a, seat ? linOf(m, seat.args[i]) : { terms: [], c: 0 }]));
     const centres = [];
@@ -492,7 +684,7 @@ function reachOf(m, asset, id, ends, freezeless = true) {
             return at;
         centres.push(at);
     }
-    return { centres, radius };
+    return { centres, up, down };
 }
 /** The bounds the parts come to, as sums, with what could not be read named. */
 function occupancyLins(asset, over) {
@@ -502,8 +694,28 @@ function occupancyLins(asset, over) {
     const bounded = [];
     const low = { x: [], y: [], z: [] };
     const high = { x: [], y: [], z: [] };
-    /* Parts carried by the same turn share one ball: its radius the larger of theirs, term by term. */
-    const balls = new Map();
+    /*
+      Parts carried by the same turn each bound their own reach about its pivot, and the room takes the largest when the
+      graph is evaluated (ADR-0087, 2026-10-21). One ball per pivot, its radius the larger of theirs term by term, was
+      every branch added up: each part's sizes and places are values of its own, and a humanoid's torso, head and two arms
+      under its waist came to 8210 mm across for a body 300 mm wide. A reach that another one passes at every size -- by a
+      number and sizes, never below zero -- is left out.
+    */
+    const reaches = {
+        low: { x: [], y: [], z: [] },
+        high: { x: [], y: [], z: [] }
+    };
+    const atLeast = (a, b) => {
+        const gap = linNorm(linAdd(a, b, -1));
+        return gap.c >= -1e-9 && gap.terms.every(t => t.k > 0 && sizeValue(m, t.ref));
+    };
+    const addReach = (side, axis, lin) => {
+        const list = reaches[side][axis];
+        const further = (a, b) => (side === 'high' ? atLeast(a, b) : atLeast(b, a));
+        if (list.some(o => further(o, lin)))
+            return;
+        reaches[side][axis] = [...list.filter(o => !further(lin, o)), lin];
+    };
     /* A row's template stands for its copies (`repeatPart`): leaving it out left a conveyor's rollers out of its room. */
     const rowOf = (id) => nodeById(m, `${id}.repeat`);
     const ends = over === 'rest' ? ['start'] : ['min', 'max'];
@@ -630,14 +842,14 @@ function occupancyLins(asset, over) {
                 */
                 for (const { run } of rows) {
                     for (const l of run.lows)
-                        low[run.axis].push(linAdd(l, reach.radius, -1));
+                        low[run.axis].push(linAdd(l, reach.down[run.axis], -1));
                     for (const h of run.highs)
-                        high[run.axis].push(linAdd(h, reach.radius, 1));
+                        high[run.axis].push(linAdd(h, reach.up[run.axis], 1));
                 }
                 for (const at of reach.centres)
                     for (const axis of AXES.filter(a => !rowAxes.has(a))) {
-                        const lo = linAdd(at[axis], reach.radius, -1);
-                        const hi = linAdd(at[axis], reach.radius, 1);
+                        const lo = linAdd(at[axis], reach.down[axis], -1);
+                        const hi = linAdd(at[axis], reach.up[axis], 1);
                         low[axis].push(lo);
                         high[axis].push(hi);
                         climbed(lo, -1, low, axis);
@@ -645,12 +857,11 @@ function occupancyLins(asset, over) {
                     }
                 continue;
             }
-            for (const at of reach.centres) {
-                const centre = Object.fromEntries(AXES.map(a => [a, linNorm(at[a])]));
-                const key = JSON.stringify(centre);
-                const ball = balls.get(key);
-                balls.set(key, { centre, radius: ball ? linAtLeast(ball.radius, reach.radius) : linNorm(reach.radius) });
-            }
+            for (const at of reach.centres)
+                for (const axis of AXES) {
+                    addReach('low', axis, linNorm(linAdd(at[axis], reach.down[axis], -1)));
+                    addReach('high', axis, linNorm(linAdd(at[axis], reach.up[axis], 1)));
+                }
             continue;
         }
         /*
@@ -743,7 +954,7 @@ function occupancyLins(asset, over) {
     for (const part of parts)
         if (boundsUnder(m, part).length)
             bounded.push(part);
-    return { parts, skipped, bounded, low, high, balls: [...balls.values()] };
+    return { parts, skipped, bounded, low, high, reaches };
 }
 const valueOfLin = (values, l) => l.terms.reduce((s, t) => s + t.k * (values[t.ref] ?? NaN), l.c);
 /** What the parts come to, and what a person is being asked to confirm. Reads the asset; changes nothing. */
@@ -753,12 +964,11 @@ export function proposeFigureOccupancy(asset, options = {}) {
     if (over !== 'rest' && over !== 'range')
         fail('SCHEMA', 'over', `${String(over)} is neither rest nor range`);
     const source = structuredClone(asset);
-    const { parts, skipped, bounded, low, high, balls } = occupancyLins(source, over);
-    for (const ball of balls)
-        for (const axis of AXES) {
-            low[axis].push(linAdd(ball.centre[axis], ball.radius, -1));
-            high[axis].push(linAdd(ball.centre[axis], ball.radius, 1));
-        }
+    const { parts, skipped, bounded, low, high, reaches } = occupancyLins(source, over);
+    for (const axis of AXES) {
+        low[axis].push(...reaches.low[axis]);
+        high[axis].push(...reaches.high[axis]);
+    }
     boundedSides(source.document.model, low, high);
     if (!parts.length)
         fail('OCCUPANCY_NO_PARTS', 'occupancy', `no part could be measured${skipped.length ? `: ${skipped.map(s => `${s.part} — ${s.reason}`).join('; ')}` : ''}`);
@@ -814,13 +1024,12 @@ export function declareOccupancy(asset, a) {
             fail('OCCUPANCY_PADDING', `occupancy.${axis}`, `padding is millimetres, zero or more; got ${String(pad)}`);
         padding[axis] = pad;
     }
-    const { parts, low, high, balls } = occupancyLins(asset, a.proposal.over);
-    /* A turning chain's ball, its reach either way about its pivot on each axis. */
-    for (const ball of balls)
-        for (const axis of AXES) {
-            low[axis].push(linAdd(ball.centre[axis], ball.radius, -1));
-            high[axis].push(linAdd(ball.centre[axis], ball.radius, 1));
-        }
+    const { parts, low, high, reaches } = occupancyLins(asset, a.proposal.over);
+    /* What the parts carried by a turn reach either way about their pivots, on each axis. */
+    for (const axis of AXES) {
+        low[axis].push(...reaches.low[axis]);
+        high[axis].push(...reaches.high[axis]);
+    }
     boundedSides(m, low, high);
     for (const axis of AXES) {
         if (!padding[axis])