@expofp/wayfinding-compiler 0.0.0-bootstrap.0

package/dist/lib/report.js

@@ -0,0 +1,374 @@
+import { poiKey } from './diagnostics.js';
+import { boundsOf } from './geom/primitives.js';
+import { ENTRANCE_REACH } from './openings.js';
+/** How many names a message spells out before it counts the rest. */
+const NAMES_SHOWN = 8;
+/** Why a floor has no floor, in words. */
+const FLOOR_CAUSES = {
+    'layer-no-walls': {
+        cause: 'no-walls',
+        text: 'the floor has no walls, so there is nothing to build routes inside',
+    },
+    'layer-no-outer-contour': {
+        cause: 'outline-open',
+        text: 'the outer walls do not close into a contour. Check the outer walls of this floor',
+    },
+    'floor-carved-away': {
+        cause: 'carved-away',
+        text: 'the walls and POI drawn on it cover it whole',
+    },
+    'floor-too-large': {
+        cause: 'too-large',
+        text: "it spans more than routes are built over. Check the plan's units, and any wall or POI drawn far from the hall",
+    },
+};
+/** Why a POI is not connected, in words — for one POI or for many. */
+const POI_CAUSES = {
+    'coordinate-not-finite': (one) => `${they(one)} ${one ? 'has' : 'have'} a coordinate that is not a number`,
+    'footprint-empty': (one) => `${they(one)} ${one ? 'has' : 'have'} no outline the plan can read`,
+    'dock-empty': () => 'the rectangle routes arrive at has no area',
+    'outside-building': (one) => `${they(one)} ${one ? 'stands' : 'stand'} outside the building outline; routes are built inside it only`,
+    'entrance-far-from-walls': (one) => `${they(one)} ${one ? 'stands' : 'stand'} more than ${ENTRANCE_REACH} m from the nearest wall; an entrance outside the building is connected only within ${ENTRANCE_REACH} m of a wall`,
+    'no-floor-behind-wall': (one) => `no wall near ${one ? 'it' : 'them'} opens onto floor; check that the building outline closes and that nothing stands right behind the wall`,
+    'no-floor-in-front': (one) => `there is no floor to stand on in front of ${one ? 'it' : 'them'}`,
+    'no-way-in': (one) => `${they(one)} ${one ? 'has' : 'have'} no open side and no doorway`,
+    'approach-blocked': () => 'a wall or another POI stands right in front of every way in',
+    'cut-off': (one) => `the floor in front of ${one ? 'it' : 'them'} is a pocket no route reaches`,
+    'lost-while-tidying': (one) => `${they(one)} ${one ? 'was' : 'were'} attached, then lost while the routes were tidied — reason unknown`,
+    unknown: () => 'reason unknown',
+};
+/**
+ * The pronoun for the POI a message is about.
+ * @param one True for a single POI.
+ * @returns `it` or `they`.
+ */
+function they(one) {
+    return one ? 'it' : 'they';
+}
+/** The network stage's reason, as the report's cause. */
+const REASON_CAUSE = {
+    'no-floor': 'no-floor-in-front',
+    'no-way-in': 'no-way-in',
+    'way-in-blocked': 'approach-blocked',
+    'cut-off': 'cut-off',
+    detached: 'lost-while-tidying',
+};
+/** The order problems are listed in: whole-plan first, then by what a designer fixes first. */
+const KIND_ORDER = [
+    'plan-invalid',
+    'nothing-to-build',
+    'floor-not-built',
+    'poi-not-connected',
+    'network-split',
+    'floors-not-connected',
+];
+/**
+ * A floor by the name the plan gave it.
+ * @param layer The layer id.
+ * @param start True at the start of a sentence.
+ * @returns `Floor "BG"`, or `the floor` for the one unnamed floor.
+ */
+function floorName(layer, start = true) {
+    const word = start ? 'Floor' : 'floor';
+    if (layer === '')
+        return start ? 'The floor' : 'the floor';
+    return `${word} "${layer}"`;
+}
+/**
+ * Names as a sentence tail: the first few in full, the rest counted.
+ * @param refs The POI.
+ * @returns `A, B and 3 more`.
+ */
+function names(refs) {
+    const shown = refs.slice(0, NAMES_SHOWN).map((ref) => (ref.id === '' ? 'unnamed POI' : ref.id));
+    const rest = refs.length - shown.length;
+    if (rest > 0)
+        return `${shown.join(', ')} and ${rest} more`;
+    return shown.join(', ');
+}
+/**
+ * Fold the compile's facts into what a designer reads: every problem is a diagnostic or a binding, grouped.
+ * @param diagnostics Every fact of the compile.
+ * @param reachability What the emitted graph connects.
+ * @param source The plan in plan units, for the outlines a problem points at.
+ * @returns The report.
+ */
+export function buildReport(diagnostics, reachability, source) {
+    const problems = [];
+    const has = (code) => diagnostics.filter((d) => d.code === code);
+    const outline = (ref) => {
+        const destination = source.layers.find((l) => l.layer === ref.layer)?.destinations[ref.index];
+        const ring = destination?.dock ?? destination?.polygon ?? [];
+        // A ring with a NaN vertex would put NaN bounds into serializable data.
+        if (!ring.length || !ring.every(([x, y]) => Number.isFinite(x) && Number.isFinite(y)))
+            return [];
+        const [x0, y0, x1, y1] = boundsOf(ring);
+        return [{ type: 'bounds', layer: ref.layer, box: [x0, y0, x1, y1] }];
+    };
+    // The plan cannot be read at all: an input error that names no layer poisons the whole of it.
+    for (const d of diagnostics.filter((f) => f.stage === 'input' && f.severity === 'error' && f.layer === undefined)) {
+        const messages = {
+            'units-per-meter-invalid': `The plan's units per meter is ${String(source.unitsPerMeter)}; it must be a positive number. Check the plan's units and map anchors.`,
+        };
+        problems.push({
+            kind: 'plan-invalid',
+            cause: d.code,
+            message: messages[d.code] ?? 'A floor has no id; the plan cannot be built.',
+            poi: [],
+            highlight: [],
+        });
+    }
+    const empty = source.layers.length === 0 ||
+        source.layers.every((l) => l.walls.length === 0 && l.destinations.length === 0);
+    if (!problems.length && empty)
+        problems.push({
+            kind: 'nothing-to-build',
+            cause: source.layers.length === 0 ? 'no-floors' : 'nothing-drawn',
+            message: source.layers.length === 0
+                ? 'Nothing to build: the plan has no floors.'
+                : 'Nothing to build: the plan has no walls and no POI.',
+            poi: [],
+            highlight: [],
+        });
+    // An unreadable or empty plan reports only that; everything after would repeat it.
+    if (problems.length)
+        return notBuilt(problems, source.layers.reduce((n, layer) => n + layer.destinations.length, 0));
+    // A floor that got no floor: one problem for the floor, none for each POI standing on it.
+    const unbuilt = new Set();
+    // A floor whose walls cannot be read as numbers is skipped whole; the rest of the plan compiles.
+    for (const d of diagnostics.filter((f) => f.stage === 'input' && f.severity === 'error' && f.layer !== undefined)) {
+        const layer = d.layer ?? '';
+        const messages = {
+            'wall-coordinate-not-finite': `${floorName(layer)}: a wall has a coordinate that is not a number; the floor is not built.`,
+        };
+        unbuilt.add(layer);
+        problems.push({
+            kind: 'plan-invalid',
+            layer,
+            cause: d.code,
+            message: messages[d.code] ?? `${floorName(layer)}: its data cannot be read; the floor is not built.`,
+            poi: [],
+            highlight: [],
+        });
+    }
+    for (const d of diagnostics.filter((f) => f.stage === 'walkable' && FLOOR_CAUSES[f.code])) {
+        const layer = d.layer ?? '';
+        const { cause, text } = FLOOR_CAUSES[d.code];
+        const count = Number(d.facts?.destinations ?? 0);
+        unbuilt.add(layer);
+        problems.push({
+            kind: 'floor-not-built',
+            layer,
+            cause,
+            message: `${floorName(layer)}: no floor could be built — ${text}.${count && cause === 'no-walls'
+                ? ` ${count} POI ${count === 1 ? 'stands' : 'stand'} on it.`
+                : ''}`,
+            poi: [],
+            highlight: [],
+        });
+    }
+    // POI bound to nothing, grouped by floor and their proven cause.
+    const flagged = (code) => new Set(has(code).map(({ ref }) => poiKey(ref?.layer ?? '', ref?.index ?? -1)));
+    const notFinite = flagged('destination-coordinate-not-finite');
+    const dockEmpty = flagged('destination-dock-empty');
+    const footprintEmpty = flagged('destination-footprint-empty');
+    // One pass over the network stage's facts: the proven cause, and the tip to point at.
+    const unreachedOf = new Map(has('destination-unreached').map(({ ref, facts, geometry }) => [
+        poiKey(ref?.layer ?? '', ref?.index ?? -1),
+        {
+            cause: facts?.reason === 'no-floor' && facts.outside === true
+                ? facts.floorBehind === false
+                    ? 'no-floor-behind-wall'
+                    : typeof facts.nearestWall === 'number'
+                        ? 'entrance-far-from-walls'
+                        : 'outside-building'
+                : (REASON_CAUSE[String(facts?.reason)] ?? 'unknown'),
+            geometry: geometry ?? [],
+        },
+    ]));
+    const unconnected = new Map();
+    for (const { ref, part } of reachability.poi) {
+        if (part >= 0 || unbuilt.has(ref.layer))
+            continue;
+        const at = poiKey(ref.layer, ref.index);
+        const cause = notFinite.has(at)
+            ? 'coordinate-not-finite'
+            : dockEmpty.has(at)
+                ? 'dock-empty'
+                : footprintEmpty.has(at)
+                    ? 'footprint-empty'
+                    : (unreachedOf.get(at)?.cause ?? 'unknown');
+        const group = `${ref.layer}\u0000${cause}`;
+        const entry = unconnected.get(group) ?? { layer: ref.layer, cause, poi: [] };
+        entry.poi.push(ref);
+        unconnected.set(group, entry);
+    }
+    for (const { layer, cause, poi } of unconnected.values()) {
+        const one = poi.length === 1;
+        problems.push({
+            kind: 'poi-not-connected',
+            layer,
+            cause,
+            message: `${floorName(layer)}: ${poi.length} POI ${one ? 'is' : 'are'} not connected to the routes — ${POI_CAUSES[cause](one)}: ${names(poi)}.`,
+            poi,
+            // The POI's own rectangle, and the stub tip where the failing way in ends, when one is known.
+            highlight: poi.flatMap((ref) => [
+                ...outline(ref),
+                ...(unreachedOf.get(poiKey(ref.layer, ref.index))?.geometry ?? []),
+            ]),
+        });
+    }
+    // POI on a part the main one does not reach, one problem per floor.
+    const detached = new Map();
+    const splits = [];
+    // Floors whose network stage proved the refusal: the ties tried every link and gave up.
+    const untied = new Set(has('network-pieces-untied').map(({ layer }) => layer));
+    for (const { ref, part } of reachability.poi)
+        if (part > 0) {
+            const list = detached.get(ref.layer);
+            if (list)
+                list.push(ref);
+            else
+                detached.set(ref.layer, [ref]);
+        }
+    for (const [layer, poi] of detached) {
+        const onFloor = reachability.parts.filter((part) => part.layers.includes(layer));
+        const others = reachability.parts.slice(1).filter((part) => part.layers.includes(layer));
+        const lines = [
+            { type: 'lines', layer, lines: others.flatMap((part) => part.lines) },
+        ];
+        // The main part never reaches this floor: its routes are whole, but no shaft joins them to the plan.
+        if (onFloor[0] !== reachability.parts[0]) {
+            problems.push({
+                kind: 'floors-not-connected',
+                layer,
+                cause: 'floor-detached',
+                message: `${floorName(layer)}: its routes are not connected to the rest of the plan; no transition joins them. ${poi.length} POI ${poi.length === 1 ? 'is' : 'are'} cut off: ${names(poi)}.`,
+                poi,
+                highlight: lines,
+            });
+            continue;
+        }
+        splits.push({ layer, parts: onFloor.length });
+        // The proven cause needs both facts: the stage recorded the refusal, and the emitted graph
+        // still falls apart here — later passes may have joined what the ties could not.
+        const proven = untied.has(layer);
+        problems.push({
+            kind: 'network-split',
+            layer,
+            cause: proven ? 'no-link-found' : 'unknown',
+            message: `${floorName(layer)}: the routes fall into ${onFloor.length} separate parts${proven ? ': the growth found no lawful link and no floor path between the parts' : ''}. ${poi.length} POI ${poi.length === 1 ? 'is' : 'are'} on parts not connected to the rest: ${names(poi)}.`,
+            poi,
+            highlight: lines,
+        });
+    }
+    // Shafts that do not join the floors they serve.
+    for (const d of [
+        ...has('transition-kind-missing'),
+        ...has('transition-coordinate-not-finite'),
+        ...has('transition-too-few-stops'),
+        ...has('transition-stop-unknown-layer'),
+        ...has('transition-stop-no-dock'),
+        ...has('transition-single-floor'),
+    ]) {
+        const id = d.ref?.id ?? '';
+        const name = id ? `Transition "${id}"` : 'A transition';
+        const layer = d.layer ?? '';
+        const whole = d.code === 'transition-kind-missing' ||
+            d.code === 'transition-coordinate-not-finite' ||
+            d.code === 'transition-too-few-stops';
+        const message = d.code === 'transition-kind-missing'
+            ? `${name} names no kind (stairs, escalator, elevator…) and is left out.`
+            : d.code === 'transition-coordinate-not-finite'
+                ? `${name} has a stop whose coordinate is not a number and is left out.`
+                : d.code === 'transition-too-few-stops'
+                    ? `${name} serves fewer than two floors.`
+                    : d.code === 'transition-stop-unknown-layer'
+                        ? `${name} names a floor the plan does not have: "${layer}".`
+                        : d.code === 'transition-single-floor'
+                            ? `${name} is connected to the routes of ${floorName(layer, false)} only, so it joins no floors.`
+                            : `${name} does not reach the routes of ${floorName(layer, false)}${d.facts?.pointId ? ` (stop "${String(d.facts.pointId)}")` : ''}.`;
+        problems.push({
+            kind: 'floors-not-connected',
+            ...(whole ? {} : { layer }),
+            cause: d.code,
+            message,
+            poi: [],
+            highlight: d.geometry ?? [],
+        });
+    }
+    const layerOrder = new Map(source.layers.map((l, index) => [l.layer, index]));
+    problems.sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind) ||
+        (layerOrder.get(a.layer ?? '') ?? -1) - (layerOrder.get(b.layer ?? '') ?? -1));
+    const total = reachability.poi.length;
+    const connected = reachability.poi.filter(({ part }) => part >= 0).length;
+    const counts = {
+        poi: total,
+        poiConnected: connected,
+        poiNotConnected: total - connected,
+        poiOnDetachedParts: reachability.poi.filter(({ part }) => part > 0).length,
+        networkParts: reachability.parts.length,
+        floorsWithoutFloor: unbuilt.size,
+    };
+    const built = reachability.parts.some((part) => part.lines.length > 0);
+    const outcome = !built ? 'not-built' : problems.length ? 'built-with-gaps' : 'built';
+    return { outcome, summary: summarize(outcome, problems, counts, splits), problems, counts };
+}
+/**
+ * The report of a plan that cannot be read or has nothing on it.
+ * @param problems The one reason, already worded.
+ * @param poi How many POI the source lists.
+ * @returns The report.
+ */
+function notBuilt(problems, poi) {
+    const counts = {
+        poi,
+        poiConnected: 0,
+        poiNotConnected: poi,
+        poiOnDetachedParts: 0,
+        networkParts: 0,
+        floorsWithoutFloor: 0,
+    };
+    return {
+        outcome: 'not-built',
+        summary: summarize('not-built', problems, counts, []),
+        problems,
+        counts,
+    };
+}
+/**
+ * One line for the whole plan.
+ * @param outcome What came of it.
+ * @param problems The grouped problems.
+ * @param counts The counts.
+ * @param splits The floors whose routes fall apart, with the number of parts on each.
+ * @returns The line.
+ */
+function summarize(outcome, problems, counts, splits) {
+    if (outcome === 'not-built') {
+        const first = problems[0];
+        if (!first)
+            return 'Routes are not built.';
+        if (first.kind === 'nothing-to-build')
+            return first.message;
+        if (first.kind === 'plan-invalid')
+            return `Routes are not built: ${first.message}`;
+        if (first.kind === 'floor-not-built')
+            return 'Routes are not built: no floor could be built.';
+        return `Routes are not built: none of the ${counts.poi} POI could be connected.`;
+    }
+    if (outcome === 'built')
+        return counts.poi
+            ? `Routes are built: all ${counts.poi} POI are connected.`
+            : 'Routes are built.';
+    const gaps = [];
+    if (counts.poiNotConnected)
+        gaps.push(`${counts.poiNotConnected} of ${counts.poi} POI are not connected`);
+    for (const { layer, parts } of splits)
+        gaps.push(`the routes on ${floorName(layer, false)} fall into ${parts} parts`);
+    if (counts.floorsWithoutFloor)
+        gaps.push(`${counts.floorsWithoutFloor} floor(s) could not be built`);
+    if (problems.some(({ kind }) => kind === 'floors-not-connected'))
+        gaps.push('some floors are not connected');
+    return `Routes are built, with gaps: ${gaps.join(', and ')}.`;
+}

package/dist/lib/router.d.ts

@@ -0,0 +1,111 @@
+import { type Frame } from './geom/frames.js';
+import type { Segment, Vec2 } from './geom/types.js';
+import type { MaskCtx } from './mask.js';
+import { type NetworkSizes } from './network-sizes.js';
+/** The floor read along one direction: its frame and the mask in frame coordinates. */
+export interface Grid {
+    /** The direction. */
+    readonly frame: Frame;
+    /** Mask in the frame's coordinates. */
+    readonly ctx: MaskCtx;
+}
+/**
+ * Four-heading walk over the grids, cells numbered through all of them; stepping onto the same spot of
+ * another grid costs a turn.
+ */
+export interface Router {
+    /** Cell count over all grids. */
+    readonly cells: number;
+    /** 1 for a walkable cell. */
+    readonly ok: Uint8Array;
+    /** Cell size, meters. */
+    readonly pitch: number;
+    /**
+     * Cheapest path from any seed to any target.
+     * @param seeds Start cells.
+     * @param isTarget 1 for each target cell.
+     * @returns Cells from the target back to its seed, or null.
+     */
+    route(seeds: Iterable<number>, isTarget: Uint8Array): number[] | null;
+    /**
+     * One growing search: each reached target group joins the tree and the search continues from it.
+     * @param seeds Initial tree cells; may be empty.
+     * @param group Target group per cell, -1 for none; the reached cell is cleared here.
+     * @param reseed Cells to start a new tree from once nothing is reachable; null to stop.
+     * @param onJoin Gets the path (target first) and the group; returns other cells joining with it, their
+     *   `group` cleared. Must not search the router (shared state).
+     * @returns Every cell of every tree.
+     */
+    grow(seeds: Iterable<number>, group: Int32Array, reseed: () => Iterable<number> | null, onJoin: (cells: number[], group: number) => Iterable<number>): Set<number>;
+    /**
+     * Neighbor of `c` in direction `nd` on its grid.
+     * @param c The cell.
+     * @param nd Direction, 0…3.
+     * @returns The neighbor, or -1 when blocked or off the grid.
+     */
+    stepTo(c: number, nd: number): number;
+    /**
+     * A point's cell on each grid that covers it.
+     * @param x Point x.
+     * @param y Point y.
+     * @returns The cells.
+     */
+    cellsOf(x: number, y: number): number[];
+    /**
+     * A point's cell on the grid nearest a direction.
+     * @param x Point x.
+     * @param y Point y.
+     * @param dx Direction x.
+     * @param dy Direction y.
+     * @returns The cell, or -1 off that grid.
+     */
+    cellOf(x: number, y: number, dx: number, dy: number): number;
+    /**
+     * A point's cell on a grid of a frame.
+     * @param x Point x.
+     * @param y Point y.
+     * @param frame One of the grids' frames.
+     * @returns The cell, or -1 off every grid of that frame.
+     */
+    cellIn(x: number, y: number, frame: Frame): number;
+    /**
+     * Frame of a cell's grid.
+     * @param c The cell.
+     * @returns Its frame.
+     */
+    frameOf(c: number): Frame;
+    /**
+     * Center of a cell.
+     * @param c The cell.
+     * @returns The center, rounded to centimeters.
+     */
+    worldOf(c: number): Vec2;
+    /**
+     * Cells a segment passes through, on every grid or only on its own direction's (every grid when its
+     * own does not reach it).
+     * @param x0 Start x.
+     * @param y0 Start y.
+     * @param x1 End x.
+     * @param y1 End y.
+     * @param own Only the segment's own direction.
+     * @returns The cells, grid by grid, in order along the segment.
+     */
+    cellsAlong(x0: number, y0: number, x1: number, y1: number, own?: boolean): number[];
+    /**
+     * A cell path as segments between centers. A step between grids is laid through the corner where the
+     * arriving and leaving lines meet, when the floor there is free.
+     * @param cells The path.
+     * @returns Segments in path order, each at least a centimeter.
+     */
+    segmentsAlong(cells: readonly number[]): Segment[];
+}
+/**
+ * Build the router. Per grid: coarse cells free when any mask cell is, seam flags so a thin wall still
+ * blocks a step, and a cost that keeps off walls. A roomy cell may step onto another grid at the cost of a
+ * turn; along an aisle its own grid runs straight while the others zigzag, so the walk picks it naturally.
+ * @param grids The floor per direction, plan axes first; a direction may have several grids.
+ * @param cfg Network sizes.
+ * @returns The router.
+ */
+export declare function makeRouter(grids: readonly Grid[], cfg: NetworkSizes): Router;
+//# sourceMappingURL=router.d.ts.map