@aura3d/engine 1.4.5 → 1.5.1

package/dist/engine/agent-api/SceneQueries.js

@@ -0,0 +1,221 @@
+/**
+ * Reusable scene queries: raycasts, shape casts and ground probes.
+ *
+ * ## Why this exists
+ *
+ * The physics audit (`tests/reports/aura3d-physics-audit.json`) classified raycasts, shape
+ * casts, penetration resolution, friction, restitution, constraints and continuous
+ * collision detection as **unused**: implemented in `@aura3d/physics`, covered by its own
+ * suites, and unreachable from the public agent API. A route needing to answer "what is
+ * under this point" therefore had two options -- reach into a package's internals, or write
+ * the query by hand. Both are the same defect class as the hardcoded contact planes this
+ * remediation removed.
+ *
+ * `PhysicsWorld` already implements `raycast`, `raycastAll`, `sphereCast` and
+ * `sphereCastAll`. This module is the public surface over them, plus the pure
+ * scene-geometry queries a route usually actually wants: a downward ground probe, and a
+ * query against declarative scene nodes rather than a constructed physics world.
+ *
+ * The pure paths are dependency-free and unit-testable; the physics-backed path adapts a
+ * `PhysicsWorld` when a route has one.
+ */
+import { placedBounds } from "./SpatialAnchoring.js";
+/**
+ * Reduce declarative scene nodes to query targets.
+ *
+ * Only nodes with a resolvable position and scale participate. A model's bounds are its
+ * node scale, which is a conservative approximation: the caller is told so by
+ * {@link SceneQueryTarget}'s documentation rather than discovering it from a wrong result.
+ */
+export function sceneQueryTargets(nodes) {
+    const targets = [];
+    for (const node of nodes) {
+        if (node.kind !== "primitive" && node.kind !== "model")
+            continue;
+        const positioned = node;
+        const position = positioned.position;
+        if (!position)
+            continue;
+        const scale = positioned.scale;
+        const size = scale === undefined
+            ? [1, 1, 1]
+            : typeof scale === "number"
+                ? [scale, scale, scale]
+                : [scale[0], scale[1], scale[2]];
+        targets.push({
+            nodeName: node.name,
+            // Primitive nodes are centred on their position, so the placed bounds' floor is half
+            // a height below it.
+            bounds: placedBounds({
+                position: [position[0], position[1] - size[1] / 2, position[2]],
+                size,
+                floorY: position[1] - size[1] / 2
+            })
+        });
+    }
+    return targets;
+}
+/**
+ * Cast a ray against query targets, returning the nearest hit.
+ *
+ * Slab-method AABB intersection: exact for axis-aligned boxes and correct for the
+ * conservative bounds of other node kinds.
+ */
+export function raycastSceneTargets(targets, ray) {
+    return raycastSceneTargetsAll(targets, ray)[0];
+}
+/** Every hit along a ray, nearest first. */
+export function raycastSceneTargetsAll(targets, ray) {
+    const direction = normalize(ray.direction);
+    if (direction === undefined)
+        return [];
+    const maxDistance = ray.maxDistance ?? Number.POSITIVE_INFINITY;
+    const hits = [];
+    for (const target of targets) {
+        const hit = intersectAabb(ray.origin, direction, target.bounds, maxDistance);
+        if (!hit)
+            continue;
+        hits.push({ nodeName: target.nodeName, point: hit.point, normal: hit.normal, distance: hit.distance });
+    }
+    return hits.sort((a, b) => a.distance - b.distance);
+}
+/**
+ * Downward ground probe.
+ *
+ * The query a route asks most often, and the one that was previously answered by a frozen
+ * constant. Returns the surface height under a point, or `undefined` when nothing is below
+ * it -- which is a meaningful answer, not a reason to substitute zero.
+ */
+export function groundProbe(targets, x, z, options = {}) {
+    const fromHeight = options.fromHeight ?? 1e4;
+    const hit = raycastSceneTargets(targets, {
+        origin: [x, fromHeight, z],
+        direction: [0, -1, 0],
+        maxDistance: options.maxDistance ?? Number.POSITIVE_INFINITY
+    });
+    if (!hit)
+        return undefined;
+    return { height: hit.point[1], normal: hit.normal, nodeName: hit.nodeName };
+}
+/**
+ * Sphere cast against query targets.
+ *
+ * Implemented by inflating each target's bounds by the sphere radius, which is the standard
+ * conservative reduction of a sphere sweep to a ray test. Corners are therefore treated as
+ * rounded by radius rather than exactly; that over-reports contact slightly near an edge and
+ * never under-reports, which is the safe direction for a clearance query.
+ */
+export function sphereCastSceneTargets(targets, ray, radius) {
+    const inflated = targets.map((target) => ({
+        nodeName: target.nodeName,
+        bounds: inflateBounds(target.bounds, Math.max(0, radius))
+    }));
+    return raycastSceneTargets(inflated, ray);
+}
+/**
+ * Public raycast against a physics world.
+ *
+ * The adapter that makes `PhysicsWorld.raycast` reachable without a route importing
+ * `@aura3d/physics` directly. Returns the same {@link SceneQueryHit} shape as the pure
+ * paths, so a route can move between them without changing its call sites.
+ */
+export function raycastPhysicsWorld(world, ray) {
+    const direction = normalize(ray.direction);
+    if (direction === undefined)
+        return undefined;
+    const hit = world.raycast(ray.origin, direction, ray.maxDistance === undefined ? {} : { maxDistance: ray.maxDistance });
+    if (!hit)
+        return undefined;
+    return {
+        // A physics hit identifies a collider by id; the caller maps that to a name if it needs one.
+        nodeName: `collider-${hit.colliderId}`,
+        point: [hit.point[0], hit.point[1], hit.point[2]],
+        normal: [hit.normal[0], hit.normal[1], hit.normal[2]],
+        distance: hit.distance
+    };
+}
+/** Public sphere cast against a physics world, when the world supports one. */
+export function sphereCastPhysicsWorld(world, ray, radius) {
+    if (!world.sphereCast)
+        return undefined;
+    const direction = normalize(ray.direction);
+    if (direction === undefined)
+        return undefined;
+    const hit = world.sphereCast(ray.origin, radius, direction, ray.maxDistance === undefined ? {} : { maxDistance: ray.maxDistance });
+    if (!hit)
+        return undefined;
+    return {
+        nodeName: undefined,
+        point: [hit.point[0], hit.point[1], hit.point[2]],
+        normal: [hit.normal[0], hit.normal[1], hit.normal[2]],
+        distance: hit.distance
+    };
+}
+function inflateBounds(bounds, amount) {
+    return {
+        min: [bounds.min[0] - amount, bounds.min[1] - amount, bounds.min[2] - amount],
+        max: [bounds.max[0] + amount, bounds.max[1] + amount, bounds.max[2] + amount],
+        center: bounds.center,
+        size: [bounds.size[0] + amount * 2, bounds.size[1] + amount * 2, bounds.size[2] + amount * 2],
+        floorY: bounds.floorY - amount
+    };
+}
+/** Slab-method ray/AABB intersection. Returns the entry point and its face normal. */
+function intersectAabb(origin, direction, bounds, maxDistance) {
+    let tMin = 0;
+    let tMax = maxDistance;
+    let hitAxis = 0;
+    let hitSign = 1;
+    const min = bounds.min;
+    const max = bounds.max;
+    for (let axis = 0; axis < 3; axis += 1) {
+        const o = origin[axis];
+        const d = direction[axis];
+        if (Math.abs(d) < 1e-12) {
+            // Ray is parallel to this slab: it must already be inside it.
+            if (o < min[axis] || o > max[axis])
+                return undefined;
+            continue;
+        }
+        const inverse = 1 / d;
+        let near = (min[axis] - o) * inverse;
+        let far = (max[axis] - o) * inverse;
+        let sign = -1;
+        if (near > far) {
+            const swap = near;
+            near = far;
+            far = swap;
+            sign = 1;
+        }
+        if (near > tMin) {
+            tMin = near;
+            hitAxis = axis;
+            hitSign = sign;
+        }
+        if (far < tMax)
+            tMax = far;
+        if (tMin > tMax)
+            return undefined;
+    }
+    if (tMin > maxDistance)
+        return undefined;
+    const normal = [0, 0, 0];
+    const mutable = normal;
+    mutable[hitAxis] = hitSign;
+    return {
+        point: [
+            origin[0] + direction[0] * tMin,
+            origin[1] + direction[1] * tMin,
+            origin[2] + direction[2] * tMin
+        ],
+        normal,
+        distance: tMin
+    };
+}
+function normalize(vector) {
+    const length = Math.hypot(vector[0], vector[1], vector[2]);
+    if (!(length > 0) || !Number.isFinite(length))
+        return undefined;
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+//# sourceMappingURL=SceneQueries.js.map

package/dist/engine/agent-api/SceneQueries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneQueries.js","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/SceneQueries.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/SpatialAnchoring.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Asset-relative spatial layout and semantic anchoring.
+ *
+ * ## Why this exists
+ *
+ * Public routes placed helper geometry -- status markers, control stations,
+ * selection rings, callout panels, staging props -- at literal world
+ * coordinates chosen by eye against whatever asset was loaded that week. When
+ * the asset changed, or its bounds changed, the coordinates did not. The
+ * visible result is procedural boxes floating beside the scene rather than
+ * attached to the equipment they annotate.
+ *
+ * `CAR_SCENE_HEIGHT` was the same defect in a single constant: a value correct
+ * for one asset, frozen, then wrong. This module removes the reason to write
+ * such a constant. A route states intent -- "above this machine", "beside the
+ * workcell", "on the floor in front of the product" -- and reads back a world
+ * position derived from the asset's own placed bounds.
+ *
+ * Everything here is pure: no renderer, no asset loading, no DOM. Anchors are
+ * resolved from {@link PlacedBounds}, which a route obtains from typed asset
+ * bounds plus its intended scale via {@link placedBoundsFromAsset}.
+ */
+import { type SceneAssetLike, type SceneBounds, type Vec3 } from "./SceneGroundingUtils.js";
+/**
+ * Bounds of an asset as it actually sits in the scene.
+ *
+ * Distinct from {@link SceneBounds}, which is in raw asset-local units. Anchors
+ * must resolve against placed bounds or they reproduce the defect they exist to
+ * prevent: a correct-looking offset in local units lands in the wrong place
+ * once the renderer normalizes and scales the model.
+ */
+export interface PlacedBounds {
+    readonly min: Vec3;
+    readonly max: Vec3;
+    readonly center: Vec3;
+    readonly size: Vec3;
+    /** Y of the surface the subject rests on. */
+    readonly floorY: number;
+}
+/** Faces and corners of a placed bounding volume. */
+export type BoundsAnchor = "center" | "top" | "bottom" | "front" | "rear" | "left" | "right" | "top-front" | "top-rear" | "top-left" | "top-right" | "floor-front" | "floor-rear" | "floor-left" | "floor-right" | "corner-front-left" | "corner-front-right" | "corner-rear-left" | "corner-rear-right";
+export interface AnchorOptions {
+    /**
+     * Distance to push the anchor outward along its own face normal, in world
+     * units. Positive moves away from the subject.
+     */
+    readonly offset?: number | undefined;
+    /**
+     * Additional world-space nudge applied after the face offset. Reserved for
+     * genuine art direction; it is not a place to reintroduce asset-specific
+     * corrections.
+     */
+    readonly worldOffset?: Vec3 | undefined;
+    /**
+     * Keep the anchor at floor level regardless of the face chosen. Used for
+     * ground-standing props beside an asset.
+     */
+    readonly onFloor?: boolean | undefined;
+}
+export interface ResolvedAnchor {
+    readonly position: Vec3;
+    /** Outward normal of the face the anchor was taken from. */
+    readonly normal: Vec3;
+    readonly anchor: BoundsAnchor;
+    /** True when the anchor lies outside the subject's placed bounds. */
+    readonly outsideBounds: boolean;
+}
+/**
+ * Build placed bounds from a subject's world position, size and floor.
+ *
+ * `position` is the subject's floor contact point, matching how Aura3D's safe
+ * model renderer grounds a normalized model on its node origin.
+ */
+export declare function placedBounds(options: {
+    readonly position: Vec3;
+    readonly size: Vec3;
+    readonly floorY?: number | undefined;
+}): PlacedBounds;
+/**
+ * Placed bounds for a typed asset rendered with `model(asset)`.
+ *
+ * Mirrors the safe renderer: the asset is normalized to
+ * `normalizedMaxDimension`, multiplied by node scale, and grounded so its
+ * lowest point rests on `floorY`. A route therefore never needs the asset's raw
+ * dimensions to place something relative to it.
+ */
+export declare function placedBoundsFromAsset(asset: SceneAssetLike, options: {
+    readonly position?: Vec3 | undefined;
+    /** `targetMaxDimension` passed to `model(asset)`, in world units. */
+    readonly targetMaxDimension: number;
+    readonly floorY?: number | undefined;
+}): PlacedBounds;
+/** Placed bounds for a raw {@link SceneBounds} already expressed in world units. */
+export declare function placedBoundsFromWorldBounds(bounds: SceneBounds): PlacedBounds;
+/**
+ * Resolve a world position on or beside a subject's placed bounds.
+ *
+ * The returned position is on the named face at `offset` distance outward. This
+ * is the replacement for literal helper coordinates: it tracks the asset.
+ */
+export declare function resolveBoundsAnchor(bounds: PlacedBounds, anchor: BoundsAnchor, options?: AnchorOptions): ResolvedAnchor;
+/** True when a world point lies inside the placed bounds (inclusive). */
+export declare function containsPoint(bounds: PlacedBounds, point: Vec3, epsilon?: number): boolean;
+/**
+ * A named region inside a subject, expressed in normalized bounds space.
+ *
+ * This is how a route addresses "the assembly zone" or "the earcups" without
+ * hardcoding world coordinates. `u`/`v`/`w` run 0..1 across the subject's X/Y/Z
+ * extents, so the region follows the asset when its size or placement changes.
+ */
+export interface SemanticRegion {
+    readonly id: string;
+    readonly label?: string | undefined;
+    /** Normalized centre within the subject's bounds, each component 0..1. */
+    readonly u: number;
+    readonly v: number;
+    readonly w: number;
+    /** Normalized extents of the region, each component 0..1. Defaults to a point. */
+    readonly extent?: readonly [number, number, number] | undefined;
+}
+export interface ResolvedSemanticRegion {
+    readonly id: string;
+    readonly label: string | undefined;
+    readonly center: Vec3;
+    readonly size: Vec3;
+    readonly min: Vec3;
+    readonly max: Vec3;
+}
+/** Resolve a normalized semantic region to world-space bounds on the subject. */
+export declare function resolveSemanticRegion(bounds: PlacedBounds, region: SemanticRegion): ResolvedSemanticRegion;
+export interface DistributionOptions {
+    /** How many items to place. */
+    readonly count: number;
+    /** Minimum world-space gap between adjacent items. */
+    readonly minSpacing?: number | undefined;
+    /** Deterministic seed. Distribution is fully determined by this value. */
+    readonly seed?: number | undefined;
+    /** Keep every item on the floor plane. */
+    readonly onFloor?: boolean | undefined;
+    /** Jitter as a fraction of available spacing, 0..1. Defaults to 0 (exact grid). */
+    readonly jitter?: number | undefined;
+}
+export interface DistributedPlacement {
+    readonly index: number;
+    readonly position: Vec3;
+    /** Distance to the nearest other placement. */
+    readonly nearestNeighborDistance: number;
+}
+/**
+ * Distribute items evenly across a region, honouring a minimum spacing.
+ *
+ * Deterministic for a given seed so gameplay and evidence are reproducible.
+ * Used instead of `-0.45 + index * 0.17` style literals, which encode both the
+ * region and its spacing into one unexplained pair of numbers.
+ */
+export declare function distributeInRegion(region: {
+    readonly min: Vec3;
+    readonly max: Vec3;
+}, options: DistributionOptions): readonly DistributedPlacement[];
+/** Minimum-spacing check for a set of placements. */
+export declare function validateSpacing(placements: readonly DistributedPlacement[], minSpacing: number): {
+    readonly ok: boolean;
+    readonly violations: readonly {
+        readonly index: number;
+        readonly distance: number;
+    }[];
+};
+export interface RadialPlacementOptions {
+    readonly count: number;
+    /** Radius measured from the subject's bounds, not from the origin. */
+    readonly radius: number;
+    /** Starting angle in radians. Defaults to 0. */
+    readonly startAngle?: number | undefined;
+    /** Height above the floor. Defaults to the subject's vertical centre. */
+    readonly height?: number | undefined;
+    /** Sweep in radians. Defaults to a full circle. */
+    readonly sweep?: number | undefined;
+}
+/**
+ * Place items on a circle around a subject.
+ *
+ * The radius is added to the subject's own horizontal half-extent, so a ring of
+ * markers stays clear of the asset regardless of how large the asset is.
+ */
+export declare function distributeAroundBounds(bounds: PlacedBounds, options: RadialPlacementOptions): readonly DistributedPlacement[];
+/**
+ * Spatial invariant report for a set of helper placements.
+ *
+ * This is the machine-checkable form of "no floating procedural props". A route
+ * publishes it; a gate asserts on it. It replaces judging placement by eye or
+ * by counting coloured pixels.
+ */
+export interface SpatialInvariantReport {
+    readonly schema: "aura3d-spatial-invariants/1.0";
+    readonly subjectBounds: PlacedBounds;
+    readonly checks: readonly {
+        readonly id: string;
+        readonly description: string;
+        readonly passes: boolean;
+        readonly detail: string;
+    }[];
+    readonly passes: boolean;
+}
+export interface HelperPlacementClaim {
+    readonly id: string;
+    readonly position: Vec3;
+    /**
+     * Where this element is meant to sit relative to the subject.
+     * `inside`  -- within the subject's bounds (a selection ring on a part)
+     * `surface` -- on a bounds face, within one tolerance of it
+     * `outside` -- deliberately beside the subject (a control station, a panel)
+     */
+    readonly relation: "inside" | "surface" | "outside";
+    /** Maximum world distance from the subject's bounds for `outside` elements. */
+    readonly maxDistance?: number | undefined;
+}
+/**
+ * Verify that helper geometry is anchored to its subject.
+ *
+ * `outside` elements must remain within `maxDistance` of the bounds: that is
+ * what separates "a control station beside the workcell" from "a box floating in
+ * the void". The default of 2x the subject's largest extent is generous enough
+ * for staging and tight enough to catch the digital-twin defect class.
+ */
+export declare function checkSpatialInvariants(bounds: PlacedBounds, claims: readonly HelperPlacementClaim[], options?: {
+    readonly surfaceTolerance?: number | undefined;
+}): SpatialInvariantReport;
+/** Shortest distance from a point to the bounds surface (0 when on it). */
+export declare function distanceToBoundsSurface(bounds: PlacedBounds, point: Vec3): number;
+/** Distance from a point to the bounds volume; 0 when inside. */
+export declare function distanceOutsideBounds(bounds: PlacedBounds, point: Vec3): number;
+//# sourceMappingURL=SpatialAnchoring.d.ts.map

package/dist/engine/agent-api/SpatialAnchoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpatialAnchoring.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/SpatialAnchoring.ts"],"names":[],"mappings":"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"}