@expofp/wayfinding-compiler 0.0.0-experimental.3b0db16 → 0.0.0-stage

package/dist/lib/compile-wayfinding.d.ts

@@ -1,90 +0,0 @@
-import { type Diagnostic } from './diagnostics.js';
-import type { RouteNetwork } from './graph-types.js';
-import { type Reachability } from './reachability.js';
-import { type CompileReport } from './report.js';
-import type { SourceDestination, WayfindingSource, WfV1Graph } from './types.js';
-import type { WalkableArea } from './walkable.js';
-/** Progress of a compile, reported as each stage finishes. */
-export interface CompileProgress {
-    /** The stage just finished. */
-    readonly stage: 'walkable' | 'network' | 'transitions';
-    /** The layer it belongs to; empty for whole-plan stages. */
-    readonly layer: string;
-    /** Stages completed so far, out of {@link total}. */
-    readonly done: number;
-    /** Stages this compile will run in all. */
-    readonly total: number;
-    /** True when the caller handed the stage its artifact and it did not run. */
-    readonly cached: boolean;
-}
-/** What a compile may be given besides the plan. */
-export interface CompileOptions {
-    /** Called as each stage finishes. */
-    readonly onProgress?: (progress: CompileProgress) => void;
-    /**
-     * Walkable areas to reuse, by layer id, from an earlier compile of the same geometry: only the
-     * route network is then built. A layer with no entry builds its own.
-     */
-    readonly walkable?: Readonly<Record<string, WalkableArea>>;
-}
-/** One layer's stage artifacts and raw inputs, as plain serializable data. */
-export interface LayerDebug {
-    /** Globally unique layer id. */
-    readonly layer: string;
-    /** The wall polylines as given (flat `[x0,y0,…]`). */
-    readonly rawWalls: readonly (readonly number[])[];
-    /** The destinations as the stages saw them, carved. */
-    readonly destinations: readonly SourceDestination[];
-    /** Walkable area. */
-    readonly walkable: WalkableArea;
-    /** Route network. */
-    readonly network: RouteNetwork;
-}
-/** What a compile returns: the graph and the report on it. Plain serializable data. */
-export interface CompileResult {
-    /** The emitted graph, lines not cut where they meet; empty, never null, when nothing was built. */
-    readonly graph: WfV1Graph;
-    /** Outcome, counts, and which POI are not connected and why. */
-    readonly report: CompileReport;
-}
-/**
- * `compileWayfinding(source, { debug: true })`: the result plus stage artifacts; JSON-serializable.
- */
-export interface WayfindingDebugResult extends CompileResult {
-    /** Per-layer stage artifacts. */
-    readonly layers: LayerDebug[];
-    /** What the emitted graph connects: its parts, and the part every POI is bound to. */
-    readonly reachability: Reachability;
-    /** Every technical fact of the compile, stage by stage. */
-    readonly diagnostics: readonly Diagnostic[];
-}
-/**
- * Compile plan geometry into a routing graph in the shape of the v1 format, with a report on the
- * result. Its lines are not cut where they meet: the converter that builds wf.data.js cuts them.
- *
- * Pure and deterministic. Per layer: walkable area, route network, v1 emit. A plan it cannot read
- * comes back `not-built` with the reason in the report; it never throws over the plan.
- * @param source Per-layer walls and destinations.
- * @param options What the compile may be given besides the plan.
- * @param options.onProgress Called as each stage finishes.
- * @param options.walkable Walkable areas by layer, to reuse instead of rebuilding.
- * @returns The compiled graph and its report.
- */
-export declare function compileWayfinding(source: WayfindingSource, options?: CompileOptions): CompileResult;
-/**
- * Debug mode: the same pass also returns {@link WayfindingDebugResult}.
- * @param source Per-layer walls and destinations.
- * @param options `debug: true` and the usual options.
- * @param options.debug Return the stage artifacts. `{ invariants: true }` also checks the emitted
- * graph against the geometric invariants (`graph-invariants.ts`) — a pairwise sweep that costs a
- * sizable share of the compile on a large plan, so it is opted into, not implied by `debug`.
- * @param options.onProgress Called as each stage finishes.
- * @param options.walkable Walkable areas by layer, to reuse instead of rebuilding.
- * @returns The compiled graph and its report, plus the stage artifacts and facts.
- */
-export declare function compileWayfinding(source: WayfindingSource, options: CompileOptions & {
-    debug: true | {
-        invariants?: boolean;
-    };
-}): WayfindingDebugResult;
-//# sourceMappingURL=compile-wayfinding.d.ts.map

package/dist/lib/compile-wayfinding.js

@@ -1,203 +0,0 @@
-import { CellsRefusedError } from './cell-array.js';
-import { compileLayer, inCanonicalOrder } from './compile-layer.js';
-import { fromEmit, fromGraphInvariants, fromNetwork, fromNormalize, fromOversize, fromReachability, fromScale, fromSourceIssues, fromStops, fromTransitions, fromWalkable, } from './diagnostics.js';
-import { emitLayerV1 } from './emit-v1.js';
-import { createClipper2Ops } from './geom/clipper2-ops.js';
-import { boundsOf } from './geom/primitives.js';
-import { checkGraphInvariants } from './graph-invariants.js';
-import { NETWORK_SIZES } from './network-sizes.js';
-import { readReachability } from './reachability.js';
-import { buildReport } from './report.js';
-import { destinationsInPlanUnits, graphInPlanUnits, networkInPlanUnits, orphansInPlanUnits, sourceInMeters, walkableScaled, } from './scale.js';
-import { emitTransitionEdges, planTransitions } from './transitions.js';
-import { destinationFinite, validateWayfindingSource, wallsFinite } from './validate-source.js';
-/**
- * Most raster cells a floor's extent may take: six times the largest plan known, and well short of
- * what a browser tab holds. A larger floor is drawn in the wrong units or holds a stray drawing.
- */
-const MAX_FLOOR_CELLS = 40e6;
-/**
- * The box a layer's drawing spans: walls and every destination ring.
- * @param layer One layer, in meters.
- * @returns Its bounds; infinite when nothing is drawn.
- */
-function extentOf(layer) {
-    const points = [];
-    for (const run of layer.walls)
-        for (let i = 0; i + 1 < run.length; i += 2)
-            points.push([run[i], run[i + 1]]);
-    for (const d of layer.destinations)
-        points.push(...d.polygon, ...(d.parts ?? []).flat(), ...(d.dock ?? []));
-    return boundsOf(points);
-}
-/**
- * A layer's destinations in canonical order, each under an id no other one on the layer shares: a blank
- * or repeated id gets its rank among its namesakes, so every destination docks by its own geometry.
- * @param destinations The layer's destinations, in source order.
- * @returns The destinations in canonical order, and the id each source position compiles under.
- */
-function uniquelyNamed(destinations) {
-    const sorted = inCanonicalOrder(destinations);
-    const count = new Map();
-    const rank = new Map();
-    const idOf = new Map();
-    for (const d of destinations)
-        count.set(d.id, (count.get(d.id) ?? 0) + 1);
-    for (const d of sorted) {
-        const n = rank.get(d.id) ?? 0;
-        rank.set(d.id, n + 1);
-        idOf.set(d, d.id && count.get(d.id) === 1 ? d.id : `${d.id}\u0000${n}`);
-    }
-    return {
-        destinations: sorted.map((d) => ({ ...d, id: idOf.get(d) })),
-        ids: destinations.map((d) => idOf.get(d)),
-    };
-}
-/**
- * Shared implementation of both overloads.
- * @param source Per-layer walls and destinations.
- * @param options Compile options.
- * @param options.debug Return the stage artifacts; `{ invariants: true }` also checks the graph.
- * @param options.onProgress Called as each stage finishes.
- * @param options.walkable Walkable areas by layer, to reuse instead of rebuilding.
- * @returns The compiled graph and its report, plus the stage artifacts and facts in debug mode.
- */
-export function compileWayfinding(source, options) {
-    const issues = validateWayfindingSource(source);
-    const input = [...fromSourceIssues(issues), ...fromScale(source.unitsPerMeter)];
-    // An unreadable plan is reported, not thrown. An error naming a layer stops that floor alone.
-    if (issues.some(({ severity, layer }) => severity === 'error' && layer === undefined)) {
-        const graph = { lines: [], lineEnds: [] };
-        const reachability = { parts: [], poi: [], unownedEnds: [], sharedEnds: [] };
-        const report = buildReport(input, reachability, source);
-        return options?.debug
-            ? { graph, report, layers: [], reachability, diagnostics: input }
-            : { graph, report };
-    }
-    // What the input stage proved unreadable is left out and stays in the report as the input fact:
-    // a broken wall skips its floor, a broken destination or transition is dropped alone. Keyed by
-    // position, not id — two layers may share an id, and only the broken one is touched.
-    const layerBroken = source.layers.map((layer) => !wallsFinite(layer.walls));
-    const poiBroken = source.layers.map((layer) => layer.destinations.flatMap((d, index) => (destinationFinite(d) ? [] : [index])));
-    const brokenTransitions = new Set(issues.flatMap(({ code, index }) => code === 'transition-coordinate-not-finite' && index !== undefined ? [index] : []));
-    const ops = createClipper2Ops();
-    const graph = { lines: [], lineEnds: [] };
-    const layers = [];
-    // Stages work in meters: one conversion in here, one back to plan units on the way out.
-    const unit = source.unitsPerMeter ?? 1;
-    // Canonical order and unique ids before transition stops resolve: a stop takes the smallest
-    // destination it stands in, the first of equals.
-    const scaled = sourceInMeters(source, unit);
-    const named = scaled.layers.map((layer) => uniquelyNamed(layer.destinations));
-    const metric = {
-        ...scaled,
-        ...(scaled.transitions && {
-            transitions: scaled.transitions.filter((_, index) => !brokenTransitions.has(index)),
-        }),
-        layers: scaled.layers.map((layer, index) => {
-            const broken = poiBroken[index];
-            if (!broken.length)
-                return { ...layer, destinations: named[index].destinations };
-            const left = new Set(broken.map((at) => named[index].ids[at]));
-            return {
-                ...layer,
-                destinations: named[index].destinations.filter(({ id }) => !left.has(id)),
-            };
-        }),
-    };
-    // Stops resolve to footprints before the layers compile: a stop in the open gets a pad to dock
-    // from.
-    const plan = planTransitions(metric);
-    const networks = new Map();
-    const stages = [];
-    // Two stages per layer plus the transition pass.
-    const total = plan.layers.length * 2 + 1;
-    let done = 0;
-    const progress = (stage, layer, cached) => {
-        done++;
-        options?.onProgress?.({ stage, layer, done, total, cached });
-    };
-    for (const [index, layerSource] of plan.layers.entries()) {
-        // Counted against the plan's own POI, without transition pads; the plan's layers come in order.
-        const own = source.layers[index];
-        // A wall coordinate that is not a number: the input fact carries the reason, the floor is skipped.
-        if (layerBroken[index]) {
-            progress('walkable', layerSource.layer, false);
-            progress('network', layerSource.layer, false);
-            continue;
-        }
-        const [x0, y0, x1, y1] = extentOf(layerSource);
-        const cells = ((x1 - x0 + 2) / NETWORK_SIZES.cs) * ((y1 - y0 + 2) / NETWORK_SIZES.cs);
-        // Too large to rasterize: reported and skipped, as a floor with no floor is.
-        if (Number.isFinite(cells) && cells > MAX_FLOOR_CELLS) {
-            stages.push(...fromOversize(layerSource.layer, x1 - x0, y1 - y0, own.destinations.length));
-            progress('walkable', layerSource.layer, false);
-            progress('network', layerSource.layer, false);
-            continue;
-        }
-        // A caller's walkable area is in plan units.
-        const cached = options?.walkable?.[layerSource.layer];
-        const reported = new Set();
-        let compiled;
-        try {
-            compiled = compileLayer(layerSource, ops, {
-                ...(cached && { walkable: walkableScaled(cached, 1 / unit, false) }),
-                onStage: (stage, ready) => {
-                    reported.add(stage);
-                    progress(stage, layerSource.layer, ready);
-                },
-            });
-        }
-        catch (error) {
-            if (!(error instanceof CellsRefusedError))
-                throw error;
-            // Under the cell limit, yet more than this device holds: reported like any floor too large.
-            stages.push(...fromOversize(layerSource.layer, x1 - x0, y1 - y0, own.destinations.length));
-            for (const stage of ['walkable', 'network'])
-                if (!reported.has(stage))
-                    progress(stage, layerSource.layer, false);
-            continue;
-        }
-        const collapsed = emitLayerV1(compiled.network, compiled.layer, graph);
-        networks.set(compiled.layer, compiled.network);
-        stages.push(...fromNormalize(own, compiled.facts, named[index].ids, unit), ...fromWalkable(compiled.layer, compiled.walkable.stats, own.destinations.length), ...fromNetwork(own, compiled.network.stats, unit, named[index].ids), ...fromEmit(own, collapsed, named[index].ids));
-        if (options?.debug) {
-            layers.push({
-                layer: compiled.layer,
-                rawWalls: own.walls,
-                destinations: destinationsInPlanUnits(compiled.destinations, unit),
-                walkable: walkableScaled(compiled.walkable, unit, true),
-                network: networkInPlanUnits(compiled.network, unit),
-            });
-        }
-    }
-    const shafts = emitTransitionEdges(plan, networks, graph);
-    // Orphans in plan units, like everything emitted.
-    const transitionOrphans = orphansInPlanUnits([...plan.orphans, ...shafts.orphans], unit);
-    progress('transitions', '', false);
-    const emitted = graphInPlanUnits(graph, unit);
-    // Read off the emitted graph and the plan as given, in plan units, as they are handed out.
-    const reachability = readReachability(emitted, source);
-    const diagnostics = [
-        ...input,
-        ...stages,
-        ...fromStops(plan, unit),
-        ...fromTransitions(transitionOrphans, shafts.singleFloor, unit),
-        ...fromReachability(reachability, [...input, ...stages]),
-    ];
-    // The report folds the compile's facts; the graph invariants are debug-only and stay out of it.
-    const report = buildReport(diagnostics, reachability, source);
-    if (!options?.debug)
-        return { graph: emitted, report };
-    // The pairwise sweep costs a sizable share of the compile on a large plan: opted into alone.
-    const invariants = typeof options.debug === 'object' && options.debug.invariants
-        ? fromGraphInvariants(checkGraphInvariants(emitted, layers))
-        : [];
-    return {
-        graph: emitted,
-        report,
-        layers,
-        reachability,
-        diagnostics: [...diagnostics, ...invariants],
-    };
-}

package/dist/lib/connect.d.ts

@@ -1,35 +0,0 @@
-import type { Segment } from './geom/types.js';
-import type { NetworkSizes } from './network-sizes.js';
-import type { NetworkStore } from './network-store.js';
-import { type LayPath, type TipTarget } from './place-path.js';
-import type { Router } from './router.js';
-import type { Placement } from './runs.js';
-/** Lays raster paths into the network and grows the pieces together. */
-export interface Connector {
-    /** Adds a segment and claims the cells it passes. */
-    add(seg: Segment): void;
-    /** 1 for each router cell a network line passes: where a raster path may end. */
-    readonly onNetwork: Uint8Array;
-    /** Lays a path of cells, `head` first, its ends tied to what stands at them. */
-    readonly layPath: LayPath;
-    /**
-     * One growth from the largest piece to every other piece and every lone tip the floor connects
-     * to it; what the largest piece cannot reach grows a tree of its own.
-     * @param tips Tips no line stands at yet.
-     * @returns How many pieces the growth and the ties could not join: the pieces left beyond the
-     * first, 0 when all are one.
-     */
-    connect(tips: readonly TipTarget[]): {
-        untied: number;
-    };
-}
-/**
- * Builds the connector.
- * @param store The network.
- * @param router The raster router.
- * @param cfg Network sizes.
- * @param place What the runs are laid on.
- * @returns The connector.
- */
-export declare function createConnector(store: NetworkStore, router: Router, cfg: NetworkSizes, place: Placement): Connector;
-//# sourceMappingURL=connect.d.ts.map

package/dist/lib/connect.js

@@ -1,206 +0,0 @@
-// Growth: one search over the raster from the largest piece of the network to every other piece and
-// every lone tip the floor connects to it, reseeded from what it cannot reach, so islands the main
-// network cannot reach still meet. Every path is laid on the lines its place defines
-// (`place-path.ts`); a piece the router cannot reach is tied by an elbow from one of its nodes, else
-// by a raster path from its own cells.
-import { cellArray } from './cell-array.js';
-import { linkOnto, nearestFrame } from './geom/frames.js';
-import { pointKey } from './geom/point-key.js';
-import { createPathPlacer } from './place-path.js';
-/**
- * Builds the connector.
- * @param store The network.
- * @param router The raster router.
- * @param cfg Network sizes.
- * @param place What the runs are laid on.
- * @returns The connector.
- */
-export function createConnector(store, router, cfg, place) {
-    const { frames, mayLay } = place;
-    /** The segment claiming each cell: what a path ending there ties to. */
-    const carrier = new Map();
-    /** The tip standing at a cell a path may end at. */
-    const tipAt = new Map();
-    const onNetwork = cellArray(Uint8Array, router.cells);
-    const claim = (seg, cells = router.cellsAlong(...seg, true)) => {
-        for (const c of cells) {
-            if (!carrier.has(c))
-                carrier.set(c, seg);
-            onNetwork[c] = 1;
-        }
-    };
-    const add = (seg) => {
-        if (store.add(seg[0], seg[1], seg[2], seg[3]) >= 0)
-            claim(seg);
-    };
-    const layPath = createPathPlacer({ store, router, cfg, place, tipAt, onNetwork, add, claim });
-    const connect = (tips) => {
-        const labels = store.components();
-        const size = new Map();
-        for (const label of labels.values())
-            size.set(label, (size.get(label) ?? 0) + 1);
-        // Largest piece first, then by label: the order the trees are started in.
-        const order = [...size.entries()]
-            .sort((a, b) => b[1] - a[1] || a[0] - b[0])
-            .map(([label]) => label);
-        const group = cellArray(Int32Array, router.cells).fill(-1);
-        const cellsOf = new Map();
-        carrier.clear();
-        onNetwork.fill(0);
-        store.forEach((id, x0, y0, x1, y1) => {
-            const label = labels.get(id);
-            const seg = [x0, y0, x1, y1];
-            for (const c of router.cellsAlong(x0, y0, x1, y1, true)) {
-                onNetwork[c] = 1;
-                if (carrier.has(c))
-                    continue;
-                carrier.set(c, seg);
-                // Only a cell the router walks can be reached.
-                if (!router.ok[c])
-                    continue;
-                group[c] = label;
-                const list = cellsOf.get(label);
-                if (list)
-                    list.push(c);
-                else
-                    cellsOf.set(label, [c]);
-            }
-        });
-        // Each lone tip is a target of its own, on its direction's grid; one whose cell a line claims
-        // is joined by its stub later.
-        const tipTargets = [];
-        for (const tip of tips) {
-            let cell = router.cellIn(tip.at[0], tip.at[1], tip.frame);
-            if (cell < 0 || !router.ok[cell])
-                cell = router.cellIn(tip.at[0], tip.at[1], frames[0]);
-            if (cell < 0 || !router.ok[cell] || carrier.has(cell) || tipAt.has(cell))
-                continue;
-            tipAt.set(cell, tip);
-            tipTargets.push({ tip, cell });
-        }
-        // Nothing to join: an empty network with no tip standing off it.
-        if (!order.length && !tipTargets.length)
-            return { untied: 0 };
-        const firstTip = order.length ? Math.max(...order) + 1 : 0;
-        tipTargets.forEach(({ cell }, i) => (group[cell] = firstTip + i));
-        const take = (label) => {
-            if (label >= firstTip) {
-                const { cell } = tipTargets[label - firstTip];
-                group[cell] = -1;
-                return [cell];
-            }
-            const cells = cellsOf.get(label) ?? [];
-            for (const c of cells)
-                group[c] = -1;
-            cellsOf.delete(label);
-            return cells;
-        };
-        let next = 0;
-        let nextTip = 0;
-        router.grow(take(order[0] ?? firstTip), group, () => {
-            while (next < order.length && !cellsOf.has(order[next]))
-                next++;
-            if (next < order.length)
-                return take(order[next]);
-            while (nextTip < tipTargets.length && group[tipTargets[nextTip].cell] < 0)
-                nextTip++;
-            return nextTip < tipTargets.length ? take(firstTip + nextTip) : null;
-        }, (cells, label) => {
-            const head = label >= firstTip ? tipTargets[label - firstTip].tip : null;
-            if (cells.length > 1)
-                layPath(cells, head);
-            return take(label);
-        });
-        const remaining = tieStranded();
-        // Later passes move tips: a remembered snapshot would tie to where a tip once stood.
-        tipAt.clear();
-        return { untied: Math.max(0, remaining - 1) };
-    };
-    /**
-     * Ties the pieces the growth never reached — their cells too tight for the router, or already
-     * claimed by another piece — to the nearest line of another piece a free elbow reaches, smallest
-     * piece first, until no piece can be tied.
-     * @returns How many pieces the network is left in.
-     */
-    const tieStranded = () => {
-        let pieces = Infinity;
-        for (;;) {
-            const labels = store.components();
-            const size = new Map();
-            for (const label of labels.values())
-                size.set(label, (size.get(label) ?? 0) + 1);
-            // A tie that merged nothing would repeat itself: the pieces must shrink every round.
-            if (size.size <= 1 || size.size >= pieces)
-                return size.size;
-            pieces = size.size;
-            const ranked = [...size.entries()].sort((a, b) => a[1] - b[1] || a[0] - b[0]);
-            // The largest piece is what the others come to.
-            const strays = ranked.slice(0, -1).map(([label]) => label);
-            let tied = false;
-            for (const label of strays) {
-                const nodes = [];
-                const seen = new Set();
-                store.forEach((id, x0, y0, x1, y1) => {
-                    if (labels.get(id) !== label)
-                        return;
-                    for (const p of [
-                        [x0, y0],
-                        [x1, y1],
-                    ]) {
-                        const key = pointKey(p[0], p[1]);
-                        if (seen.has(key))
-                            continue;
-                        seen.add(key);
-                        nodes.push(p);
-                    }
-                });
-                for (const node of nodes) {
-                    const found = store.nearestLawful(node[0], node[1], (id, qx, qy) => labels.get(id) !== label && mayLay([node[0], node[1], qx, qy]));
-                    if (!found)
-                        continue;
-                    const { id: index, at } = found;
-                    const held = store.coords(index);
-                    const [hx0, hy0, hx1, hy1] = held;
-                    const link = linkOnto(frames[nearestFrame(frames, hx1 - hx0, hy1 - hy0)], node, held, at, mayLay);
-                    if (!link)
-                        continue;
-                    store.splitAt(index, link.at[0], link.at[1]);
-                    for (const leg of link.legs)
-                        add(leg);
-                    tied = true;
-                    break;
-                }
-                if (tied)
-                    break;
-                // No free elbow: a raster path from the piece's cells to any other piece's.
-                const own = new Set();
-                const seeds = [];
-                store.forEach((id, x0, y0, x1, y1) => {
-                    if (labels.get(id) !== label)
-                        return;
-                    for (const c of router.cellsAlong(x0, y0, x1, y1)) {
-                        own.add(c);
-                        if (router.ok[c])
-                            seeds.push(c);
-                    }
-                });
-                const isTarget = cellArray(Uint8Array, router.cells);
-                store.forEach((id, x0, y0, x1, y1) => {
-                    if (labels.get(id) === label)
-                        return;
-                    for (const c of router.cellsAlong(x0, y0, x1, y1))
-                        if (!own.has(c))
-                            isTarget[c] = 1;
-                });
-                const cells = router.route(seeds, isTarget);
-                if (cells && cells.length > 1 && layPath(cells.reverse(), null)) {
-                    tied = true;
-                    break;
-                }
-            }
-            if (!tied)
-                return size.size;
-        }
-    };
-    return { add, onNetwork, layPath, connect };
-}