@allyhub/sdk 0.1.0-alpha.8 → 0.2.0-next.1

package/node_modules/@allyhub-next/scenery/dist/report.d.ts

@@ -0,0 +1,677 @@
+import { type CameraState } from "./camera.js";
+import type { FieldOfView, LensFrame } from "./lens.js";
+import type { Vec3 } from "./vec.js";
+/** A box along the world axes. */
+export interface AxisBox {
+    min: Vec3;
+    max: Vec3;
+    size: Vec3;
+    center: Vec3;
+}
+/** A box along an object's own axes: its geometry's bounds under its matrixWorld. */
+export interface OwnBox {
+    center: Vec3;
+    /** Along its own x, y and z, m. */
+    size: Vec3;
+    /** Its own x, y and z in world space, unit. */
+    axes: readonly [Vec3, Vec3, Vec3];
+}
+/** The smallest rectangle round an object seen from above, with its height. */
+export interface UprightBox {
+    center: Vec3;
+    /** Its longer side on the floor, m. */
+    length: number;
+    /** Its shorter side on the floor, m. */
+    width: number;
+    /** From its lowest point to its highest, m. */
+    height: number;
+    /** Degrees about +Y from +X to its longer side, in [0, 180). */
+    angle: number;
+    /** Its corners on the floor at its lowest height, x and z. */
+    footprint: readonly (readonly [number, number])[];
+    /** Its lowest and highest y. */
+    bottom: number;
+    top: number;
+}
+/** One object of a scenery, as `allyhub scenery` prints it. */
+export interface SceneryObject {
+    /** Names from the scene down, an unnamed one as Type[index among its siblings]. */
+    path: string;
+    /** Its own name; "" for none. */
+    name: string;
+    /** three.js's type: Mesh, Group, InstancedMesh… */
+    type: string;
+    depth: number;
+    /** Visible itself and through every parent. */
+    visible: boolean;
+    /** Its origin in world space. */
+    position: Vec3;
+    /** Its own +Z in world space (a glTF model's front), unit. */
+    front: Vec3;
+    /** Triangles drawn for it and everything under it. */
+    triangles: number;
+    /** Meshes in it and under it. */
+    meshes: number;
+    /** Its own materials' names, or types where unnamed. */
+    materials: string[];
+    /** Boxes of it and everything under it, from the vertices as posed; none without geometry. */
+    box?: AxisBox;
+    own?: OwnBox;
+    upright?: UprightBox;
+}
+export interface SceneryLight {
+    path: string;
+    name: string;
+    type: string;
+    position: Vec3;
+    /** Where a directional or spot light points, when it has a target. */
+    target?: Vec3;
+    /** Its colour as #rrggbb. */
+    color: string;
+    /** three.js's intensity: candela for point and spot lights, lux for directional. */
+    intensity: number;
+    castShadow: boolean;
+    /** Shadow map size, when it casts shadows. */
+    shadowMap?: number;
+    distance?: number;
+    /** A spot's cone, degrees. */
+    angle?: number;
+}
+export interface SceneryInventory {
+    /** Scenery time it was posed at, s. */
+    t: number;
+    objects: SceneryObject[];
+    lights: SceneryLight[];
+    /** The scenery's named cameras and moves. */
+    cameras: Record<string, CameraState>;
+    moves: string[];
+    totals: {
+        objects: number;
+        meshes: number;
+        triangles: number;
+        drawCalls: number;
+        textures: number;
+        /** Bytes the textures take with their mipmaps, an estimate from their sizes. */
+        textureBytes: number;
+        /** One frame drawn at the size asked, ms, from a camera at (0, 1.6, 5); the first draw at that size makes what later frames reuse and is not counted. */
+        frameMs: number;
+        frameSize: readonly [number, number];
+        /**
+         * Objects with a transmissive material (transmission, diffuse
+         * transmission), for which three.js draws the scene once more at the
+         * frame's size, and the same frame drawn without them, ms.
+         */
+        transmission?: {
+            objects: string[];
+            withoutMs: number;
+        };
+    };
+    /** Objects with no name of their own. */
+    unnamed: number;
+    /** Names given to more than one object, with how many. */
+    repeated: Record<string, number>;
+    /** What draws: the WebGL renderer string, three.js's revision, the renderer kind. */
+    renderer: {
+        gl: string;
+        three: string;
+        kind: "webgl" | "webgpu";
+    };
+}
+/** A camera as it was drawn: its state resolved for the frame. */
+export interface DrawnCamera {
+    position: Vec3;
+    /** The point it looked at, when it had a target. */
+    target?: Vec3;
+    /** Its target's name, when it was given one. */
+    targetName?: string;
+    forward: Vec3;
+    up: Vec3;
+    fov: FieldOfView;
+    /** The lens in the diagonal convention, mm. */
+    lens: number;
+    lensFrame?: LensFrame;
+    yaw: number;
+    pitch: number;
+    roll: number;
+    near: number;
+    far: number;
+    /** With an aperture: its f-number, the focus's distance along the view (m) and the lens they go with (mm). */
+    dof?: {
+        aperture: number;
+        focus: number;
+        lens: number;
+    };
+    /** With an exposure: its EV at ISO 100. */
+    ev?: number;
+}
+/** Where a camera comes from in a view request. */
+export type CameraSource = {
+    state: CameraState;
+} | {
+    name: string;
+} | {
+    move: string;
+} | {
+    around: string;
+    side: Side;
+    lens?: number;
+    fill?: number;
+};
+/** The named directions of `--around`, looking at an object. */
+export type Side = "front" | "back" | "left" | "right" | "top" | "three-quarter";
+/** A camera that frames an object from one of its sides: its lens, and how far toward the frame's edges the object reaches (0–1). */
+export declare const AROUND_DEFAULTS: {
+    lens: number;
+    fill: number;
+};
+export declare const SIDES: readonly Side[];
+export interface ViewTile {
+    camera: CameraSource;
+    /** Scenery time, s. */
+    t: number;
+    /** What the caption calls it, before its numbers. */
+    label?: string;
+}
+export interface ViewRequest {
+    /** Seconds of scenery time for the word and anchor references moves are timed by ("@turn": 3.2). */
+    times?: Readonly<Record<string, number>>;
+    tiles: ViewTile[];
+    /** Each tile's picture, px. */
+    width: number;
+    height: number;
+    /** Tiles per row; default as square a sheet as fits. */
+    columns?: number;
+    /** Names, boxes, the floor grid and axes over each picture. */
+    overlay?: boolean;
+    /**
+     * Which named objects the overlay labels: "top" (default), those with no
+     * named object above them (what the scenery's code named; a model's own
+     * part names stay inside), or "all".
+     */
+    labels?: "top" | "all";
+    /** Objects not drawn, by name. */
+    hide?: string[];
+    /** The only objects drawn, by name (with what is under them). */
+    only?: string[];
+    /** A colour, or null for transparent; default the scenery's own background. */
+    background?: string | null;
+    /** How the sheet is encoded: a PNG (default), or a WebP to look at. */
+    picture?: "png" | "webp";
+}
+/** A named object's share of a picture, from the ID passes. */
+export interface Seen {
+    name: string;
+    path: string;
+    /** Pixels it shows, and the share of the frame. */
+    pixels: number;
+    share: number;
+    /** Share of it hidden by other objects (0–1): pixels it would show alone, less those it shows. */
+    hidden: number;
+    /** What hides it, each as a share of the pixels it would show alone. */
+    by?: {
+        name: string;
+        path: string;
+        share: number;
+    }[];
+    /** Share of it the frame's edges cut (0–1), measured with a frame twice as wide and high. */
+    cut?: number;
+    /** From the camera to its nearest surface, m. */
+    distance?: number;
+    /** The centre of its visible pixels, px from the top left. */
+    centroid?: readonly [number, number];
+    /** The box round its visible pixels, px: left, top, right, bottom. */
+    box?: readonly [number, number, number, number];
+}
+export interface ViewTileResult {
+    t: number;
+    label: string;
+    camera: DrawnCamera;
+    /** The named objects it shows, with --overlay. */
+    seen?: Seen[];
+}
+export interface ViewResult {
+    /** The sheet as a data URL: a PNG, or a WebP when the request asked (`picture`). */
+    png: string;
+    width: number;
+    height: number;
+    columns: number;
+    tiles: ViewTileResult[];
+}
+export type MapView = "top" | "front" | "side";
+export declare const MAP_VIEWS: readonly MapView[];
+/** A map's grid spacing, m, and a mark on each move every so many seconds (`allyhub scenery map`). */
+export declare const MAP_DEFAULTS: {
+    readonly grid: 0.5;
+    readonly tick: 1;
+};
+/** A point of the scenery by name: an object's box centre, or a place on a screen's face. */
+export type PointRef = {
+    object: string;
+}
+/** `at`: shares of the screen's content from its top left, [0, 0] to [1, 1]. */
+ | {
+    screen: string;
+    at: readonly [number, number];
+};
+/** Where named points are at a moment of scenery time. */
+export interface PointsRequest {
+    t: number;
+    refs: PointRef[];
+    /** Seconds of scenery time for the references the scenery's update is timed by ("@turn": 3.2). */
+    times?: Readonly<Record<string, number>>;
+}
+export interface MapRequest {
+    /** Seconds of scenery time for the word and anchor references moves are timed by ("@turn": 3.2). */
+    times?: Readonly<Record<string, number>>;
+    views: MapView[];
+    /** Scenery time the scenery is posed at, s. */
+    t: number;
+    /** The frame the cameras drawn are aimed for, width over height; default 9/16. */
+    aspect?: number;
+    /** The stretch of scenery time the moves are drawn over, s. */
+    from: number;
+    to: number;
+    /** The longer side of each view, px. */
+    size: number;
+    /** Grid spacing, m. */
+    grid: number;
+    /** Moves to draw, by name, with a tick every `tick` s. */
+    moves: string[];
+    tick: number;
+    /** Extra cameras to draw (a camera given on the command line). */
+    cameras?: Record<string, CameraState>;
+    hide?: string[];
+    only?: string[];
+    /** How each view is encoded: a PNG (default), or a WebP to look at. */
+    picture?: "png" | "webp";
+    /** Also each named object inside a model or group (default: those with no named object above them). */
+    nested?: boolean;
+}
+/** An object's place on the floor, as the map's JSON gives it. */
+export interface Footprint {
+    name: string;
+    path: string;
+    /** The upright rectangle's corners, x and z, m. */
+    corners: readonly (readonly [number, number])[];
+    bottom: number;
+    top: number;
+    /** Yaw of its own +Z, degrees: 0 faces +Z, 90 faces +X. */
+    facing: number;
+}
+export interface MapPath {
+    name: string;
+    points: {
+        t: number;
+        position: Vec3;
+    }[];
+}
+export interface MapViewResult {
+    view: MapView;
+    /** The view as a data URL: a PNG, or a WebP when the request asked (`picture`). */
+    png: string;
+    width: number;
+    height: number;
+    /** Pixels per metre. */
+    scale: number;
+    /** The world box the view covers, m. */
+    bounds: AxisBox;
+}
+export interface MapResult {
+    views: MapViewResult[];
+    footprints: Footprint[];
+    paths: MapPath[];
+    /** Moves that could not be drawn, and why (one timed by references, with no --times). */
+    left?: {
+        move: string;
+        why: string;
+    }[];
+}
+/** Whether an object's surface is closed, and what is wrong with it. */
+export interface MeshHealth {
+    path: string;
+    name: string;
+    triangles: number;
+    /** No open and no non-manifold edges. */
+    closed: boolean;
+    /**
+     * A closed surface's volume, m³, signed by which way its faces turn:
+     * over 0 a solid (inside it means something), under 0 its faces turn
+     * in, as a room's walls do (it encloses space, it is not a solid).
+     */
+    volume?: number;
+    /** Edges of one triangle. */
+    openEdges: number;
+    /** Edges of more than two triangles. */
+    nonManifoldEdges: number;
+    /** Triangles with no area. */
+    degenerate: number;
+    /** Pairs of its triangles that cross without sharing a vertex; null above the limit, not counted. */
+    selfIntersections: number | null;
+    /** The count stopped at its limit: there are at least that many. */
+    selfIntersectionsAtLeast?: boolean;
+}
+/** Two objects against each other. */
+export interface Contact {
+    a: string;
+    b: string;
+    /** Their surfaces cut each other. */
+    crossing: boolean;
+    /** Not crossing, and within the tolerance (faces in one plane, or a gap under it). */
+    touching: boolean;
+    /** Not crossing: the closest distance between their surfaces, m. */
+    gap?: number;
+    /** Faces in one plane within the tolerance: the area they share, m². */
+    area?: number;
+    /** Where they cross: the curve's length (m), its segments and its box. */
+    curve?: {
+        length: number;
+        segments: number;
+        min: Vec3;
+        max: Vec3;
+    };
+    /** One is inside the other without their surfaces crossing. */
+    within?: "a in b" | "b in a";
+    /** How deep, a lower bound: the deepest sample of each inside the other, m. */
+    depth?: {
+        aInB?: number;
+        aInBMissing?: string;
+        bInA?: number;
+        bInAMissing?: string;
+        /** Surface samples per object (their vertices besides). */
+        samples: number;
+    };
+    /**
+     * The least move of a along `direction` after which they neither cross
+     * nor hold one another, and the least move of b along it, m: of a laptop
+     * set on a desk, moving the laptop up clears them at once, the desk only
+     * once it is past the laptop.
+     */
+    lift?: {
+        direction: Vec3;
+        a: number;
+        b: number;
+    };
+    /** The volume both fill, m³; only where both are closed. */
+    volume?: number;
+    volumeMissing?: string;
+    /** The pair could not be measured, and why (crossing and touching are then unknown, given as false). */
+    missing?: string;
+}
+/** What an object rests on, by columns over its upright footprint. */
+export interface Support {
+    path: string;
+    name: string;
+    /** Its lowest y. */
+    bottom: number;
+    /** Grid columns across its footprint that met its surface. */
+    columns: number;
+    /** Columns at its lowest points (legs, a base), besides the grid. */
+    feet?: number;
+    /** What is below, nearest first: the columns over it, their share, the least gap. */
+    on: {
+        path: string;
+        name: string;
+        columns: number;
+        share: number;
+        gap: number;
+    }[];
+    /** The least gap below any column, m; negative when sunk; null with nothing below. */
+    gap: number | null;
+    /** The deepest it is sunk into what holds it, m. */
+    sunk: number;
+    /** Share of its columns within the tolerance of what is below. */
+    footprintShare: number;
+    /** The largest angle between its faces and those below where they touch, degrees. */
+    angle?: number;
+    /** The area in contact, m²: the columns in contact as shares of its footprint's rectangle. */
+    contactArea?: number;
+    /** How far its centre of mass, seen from above, is inside the hull of the contact columns, m (negative outside). */
+    margin?: number;
+    /** Columns with nothing below. */
+    nothingBelow: number;
+}
+export interface Sight {
+    a: string;
+    b: string;
+    rays: number;
+    /** Share of rays between them that nothing else stops. */
+    clear: number;
+    blockedBy: {
+        path: string;
+        share: number;
+    }[];
+}
+export interface ClearAhead {
+    path: string;
+    /** Its own +Z, the way the rays run. */
+    front: Vec3;
+    rays: number;
+    /** Rays that met nothing within `far` m. */
+    open: number;
+    far: number;
+    least?: number;
+    median?: number;
+    most?: number;
+}
+export interface FreeFloor {
+    floor: string;
+    radius: number;
+    height: number;
+    cell: number;
+    /** The floor's top in cells, m². */
+    floorArea: number;
+    /** Its upright rectangle's area, m². */
+    floorRect?: number;
+    /** Cells a radius from anything standing on it, m². */
+    freeArea: number;
+    /** Of those, the area connected to `from` (or the largest connected area), m². */
+    connected: number;
+    from?: string;
+    /** Whether each object can be reached from there: a connected cell within the radius of its box. */
+    reach: {
+        path: string;
+        reached: boolean;
+    }[];
+}
+/** What `allyhub scenery measure` measures with. */
+export declare const MEASURE_DEFAULTS: {
+    /** Pairs closer than this are measured, m. */
+    near: number;
+    /** What counts as touching, m. */
+    tolerance: number;
+    /** Surface samples per object for how deep one is in another. */
+    samples: number;
+    /** Support columns along each side of a footprint. */
+    grid: number;
+    /** The direction a lift to clear moves either object of a pair. */
+    lift: Vec3;
+    /** Measure the volume crossing pairs share where both are closed. */
+    volume: boolean;
+};
+/** The free floor: its cells so far from anything standing (m), what stands lower than `height` (m) taking the floor under it, the cells' side (m). */
+export declare const FLOOR_DEFAULTS: {
+    readonly radius: 0.3;
+    readonly height: 1.8;
+    readonly cell: 0.05;
+};
+/** Samples a second a camera's motion is measured at. */
+export declare const MOTION_DEFAULTS: {
+    readonly fps: 30;
+};
+/** The frame a scenery's inventory measures one frame's drawing time at, px. */
+export declare const INVENTORY_FRAME: readonly [number, number];
+export interface MeasureRequest {
+    t: number;
+    /** Seconds of scenery time for the references the scenery's update is timed by ("@turn": 3.2). */
+    times?: Readonly<Record<string, number>>;
+    /** The named objects measured; default every named object. */
+    objects?: string[];
+    /** Also each named object inside a model or group (default: only those with no named object above them, each counted once with all it holds). */
+    nested?: boolean;
+    near: number;
+    tolerance: number;
+    samples: number;
+    /** Every pair, not only those closer than `near`. */
+    all: boolean;
+    /** The direction a lift to clear moves either object of a pair; default up. */
+    lift?: Vec3;
+    /** Measure this pair whatever the distance. */
+    between?: [string, string];
+    /** Columns across each side of a footprint, for support. */
+    grid: number;
+    volume: boolean;
+    sight?: [string, string];
+    clear?: string;
+    floor?: {
+        name: string;
+        radius: number;
+        height: number;
+        cell: number;
+        from?: string;
+    };
+}
+export interface MeasureResult {
+    t: number;
+    /** The objects measured, by path. */
+    objects: string[];
+    health: MeshHealth[];
+    contacts: Contact[];
+    support: Support[];
+    sight?: Sight;
+    clear?: ClearAhead;
+    floor?: FreeFloor;
+}
+/** The camera itself at a moment: what it is inside, how near a surface, what the near plane cuts. */
+export interface CameraClearance {
+    /** Closed objects it is inside, and open ones where a vote says inside (marked). */
+    inside: {
+        path: string;
+        closed: boolean;
+    }[];
+    /** The nearest surface and how far, m. */
+    nearest?: {
+        path: string;
+        distance: number;
+    };
+    /** Objects whose surface crosses the near plane inside the frame. */
+    nearCut: string[];
+}
+/** A drawn picture's levels. */
+export interface Levels {
+    /** Mean luminance, 0–1. */
+    mean: number;
+    /** Shares of pixels at 0 and at 255 on any channel. */
+    black: number;
+    white: number;
+    /** Luminance in 16 bins, shares. */
+    histogram: number[];
+}
+export interface SeeRequest {
+    /** Seconds of scenery time for the word and anchor references moves are timed by ("@turn": 3.2). */
+    times?: Readonly<Record<string, number>>;
+    tiles: ViewTile[];
+    width: number;
+    height: number;
+    hide?: string[];
+    only?: string[];
+    /** A pixel to ask what is under, px from the top left. */
+    pick?: readonly [number, number];
+}
+export interface SeeTile {
+    t: number;
+    label: string;
+    camera: DrawnCamera;
+    objects: Seen[];
+    clearance: CameraClearance;
+    levels: Levels;
+    pick?: {
+        x: number;
+        y: number;
+        path?: string;
+        name?: string;
+        point?: Vec3;
+        distance?: number;
+    };
+}
+export interface SeeResult {
+    width: number;
+    height: number;
+    tiles: SeeTile[];
+}
+/** One motion channel over a move: its largest magnitude and when, and its mean magnitude. */
+export interface Channel {
+    peak: number;
+    at: number;
+    mean: number;
+}
+export interface MotionRequest {
+    /** Seconds of scenery time for the word and anchor references moves are timed by ("@turn": 3.2). */
+    times?: Readonly<Record<string, number>>;
+    camera: CameraSource;
+    from: number;
+    to: number;
+    /** Samples per second. */
+    fps: number;
+    width: number;
+    height: number;
+    /** Named objects whose place on the frame is followed; default every named object in view. */
+    objects?: string[];
+}
+export interface Motion {
+    from: number;
+    to: number;
+    fps: number;
+    samples: number;
+    /** The camera's path, m. */
+    length: number;
+    /** In the camera's own frame (CameraBench's names: channels, not labels). */
+    truck: Channel;
+    pedestal: Channel;
+    dolly: Channel;
+    /** Degrees per second. */
+    pan: Channel;
+    tilt: Channel;
+    roll: Channel;
+    /** Stops per second: log2 of the lens's change. */
+    zoom: Channel;
+    /** Degrees per second about its target, when it has one. */
+    arc?: Channel;
+    speed: Channel;
+    /** How fast its view turns, degrees per second. */
+    turn: Channel;
+    acceleration: Channel;
+    jerk: Channel;
+    /** Log dimensionless jerk (more negative: less smooth); null when it does not move. */
+    smoothness: number | null;
+    /** The largest step between samples: in place (m) and in view (degrees), and when. */
+    step: {
+        distance: number;
+        angle: number;
+        at: number;
+    };
+    /** The least distance to any surface over the move, m, and when. */
+    clearance?: {
+        distance: number;
+        path: string;
+        at: number;
+    };
+    /** Each followed object's speed on the frame (px per sample) and how fast its size on the frame changes (share per second). */
+    objects: {
+        path: string;
+        screen: Channel;
+        growth: Channel;
+        inView: number;
+    }[];
+    /** The camera's cuts (shots()): what is measured stops at each. */
+    cuts?: number[];
+}
+/**
+ * The objects with no named object above them, in the inventory's order
+ * (depth first): what the agent placed, each model and group once, not
+ * the parts a model was made of.
+ */
+export declare function topObjects<T extends {
+    name: string;
+    depth: number;
+}>(objects: readonly T[]): T[];
+//# sourceMappingURL=report.d.ts.map

package/node_modules/@allyhub-next/scenery/dist/report.js

@@ -0,0 +1,2 @@
+/*! AllyHub. Copyright (c) 2026 AllyHub, Inc. All rights reserved. Use is subject to LICENSE.md. */
+import{CAMERA_DEFAULTS as n}from"./camera.js";export const AROUND_DEFAULTS={lens:n.lens,fill:.9},SIDES=["front","back","left","right","top","three-quarter"],MAP_VIEWS=["top","front","side"],MAP_DEFAULTS={grid:.5,tick:1},MEASURE_DEFAULTS={near:.05,tolerance:.001,samples:2e3,grid:7,lift:[0,1,0],volume:!0},FLOOR_DEFAULTS={radius:.3,height:1.8,cell:.05},MOTION_DEFAULTS={fps:30},INVENTORY_FRAME=[1080,1920];export function topObjects(r){const e=[],o=[];for(const t of r)o.length=t.depth,o.some(Boolean)||e.push(t),o[t.depth]=t.name!=="";return e}