summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/seeing/candidates.js

@@ -0,0 +1,282 @@
+/**
+ * Smart framing, part 1: candidate camera poses per shot type. Pure and
+ * engine-free — the engine only measures what these poses would see
+ * (assets/seeing/seeing_probe.gd "measure"); scoring.ts ranks the result.
+ *
+ * Every candidate sits at the distance where the subject fills the shot
+ * type's target share of the frame (fitDistance), on a ring or hemisphere
+ * around the subject, or along a corridor's free line. Low angles follow the
+ * low-angle rule (closer + wider instead of buried in the ground).
+ */
+import { aabbCenter, aabbCorners, aabbMax, add, applyLowAngleRule, directionFromAngles, fitDistance, lerp, normalize, rotateY, scale, sub, thirdsYawOffset, } from "./math.js";
+export const SHOT_TYPES = ["establishing", "eye_level", "low_angle", "detail", "corridor"];
+export const SHOT_DEFAULTS = {
+    establishing: { fov: 55, fill: 0.78 },
+    eye_level: { fov: 70, fill: 0.5 },
+    low_angle: { fov: 60, fill: 0.85 },
+    detail: { fov: 40, fill: 0.7 },
+    corridor: { fov: 65, fill: 0 },
+};
+export const LOW_ANGLE_CLEARANCE = 0.35;
+export const DEFAULT_CLEARANCE = 0.3;
+export const MAX_FOV = 100;
+export const DEFAULT_EYE_HEIGHT = 1.6;
+/** A standing eye without an explicit eye_height: 1.5-1.8 m above the walkable
+ *  surface under the camera. */
+export const EYE_BAND = [1.5, 1.8];
+/** The eye band: exactly eye_height when given, else EYE_BAND. */
+export function eyeBand(eyeHeight) {
+    return eyeHeight !== undefined ? [eyeHeight, eyeHeight] : [EYE_BAND[0], EYE_BAND[1]];
+}
+/** Nine points the thick sweep aims at: the center plus the eight corners
+ *  pulled 40% toward it, so a subject standing on the ground still offers
+ *  points above the ground plane. */
+export function subjectSamples(box) {
+    const c = aabbCenter(box);
+    return [c, ...aabbCorners(box).map((corner) => lerp(c, corner, 0.6))];
+}
+const AZIMUTHS_12 = Array.from({ length: 12 }, (_, i) => i * 30);
+const AZIMUTHS_16 = Array.from({ length: 16 }, (_, i) => i * 22.5);
+function ringCandidates(prefix, box, lookAt, elevations, fov, fill, aspect, options) {
+    const out = [];
+    const samples = subjectSamples(box);
+    for (const elevation of elevations) {
+        for (const azimuth of AZIMUTHS_12) {
+            const toCamera = directionFromAngles(azimuth, elevation);
+            const dist = fitDistance(box, lookAt, toCamera, fov, aspect, fill);
+            let position = add(lookAt, scale(toCamera, dist));
+            let camFov = fov;
+            let note;
+            if (options.lowAngle && options.minY !== undefined) {
+                const rule = applyLowAngleRule(lookAt, toCamera, dist, fov, options.minY, MAX_FOV);
+                if (rule.impossible)
+                    continue;
+                position = rule.position;
+                camFov = rule.fov;
+                if (rule.adjusted)
+                    note = `low-angle rule: ${dist.toFixed(1)} m -> ${rule.distance.toFixed(1)} m, fov ${fov} -> ${rule.fov.toFixed(1)}`;
+            }
+            out.push({
+                id: `${prefix}_az${String(azimuth).padStart(3, "0")}_el${elevation}`,
+                position,
+                look_at: lookAt,
+                fov: Math.round(camFov * 100) / 100,
+                samples,
+                min_clearance: options.clearance,
+                low_angle_rule: options.lowAngle === true,
+                ...(note ? { note } : {}),
+            });
+        }
+    }
+    return out;
+}
+function eyeOf(ctx) {
+    const spawn = ctx.spawn;
+    if (ctx.eyeHeight === undefined && spawn.camera)
+        return { eye: spawn.camera.position, source: `camera ${spawn.camera.path}` };
+    const h = ctx.eyeHeight ?? DEFAULT_EYE_HEIGHT;
+    return { eye: add(spawn.origin, [0, h, 0]), source: `${h} m above the walkable surface at ${spawn.path}` };
+}
+function eyeLevelCandidates(ctx, fovDefault) {
+    const { eye, source } = eyeOf(ctx);
+    const [min, max] = eyeBand(ctx.eyeHeight);
+    // The engine stands the eye on the walkable surface under it: eye_height
+    // (or 1.6 m) above it, or a spawn camera's own height clamped into
+    // 1.5-1.8 m. Never higher.
+    const ownCamera = ctx.eyeHeight === undefined && ctx.spawn.camera !== undefined;
+    const eyeSpec = { min, max, ...(ownCamera ? {} : { target: ctx.eyeHeight ?? DEFAULT_EYE_HEIGHT }), stand: [...ctx.spawn.origin] };
+    const out = [];
+    const fovs = ctx.fov !== undefined ? [ctx.fov] : [fovDefault - 10, fovDefault + 5];
+    if (ctx.subject) {
+        const c = aabbCenter(ctx.subject);
+        const flat = normalize([c[0] - eye[0], 0, c[2] - eye[2]]);
+        const horizontal = Math.hypot(c[0] - eye[0], c[2] - eye[2]);
+        const samples = subjectSamples(ctx.subject);
+        for (const fov of fovs) {
+            const yawStep = thirdsYawOffset(fov, ctx.aspect);
+            for (const [tag, yaw] of [["c", 0], ["l3", yawStep], ["r3", -yawStep]]) {
+                for (const [ptag, aimed] of [["level", false], ["aim", true]]) {
+                    const dir = rotateY(flat, yaw);
+                    // Eye level means a level camera; "aim" tilts at most 12 degrees
+                    // toward the subject's center, the way a player glances up.
+                    const rise = aimed ? Math.max(-0.21, Math.min(0.21, (c[1] - eye[1]) / Math.max(horizontal, 0.1))) : 0;
+                    out.push({
+                        id: `eye_${tag}_${ptag}_fov${fov}`,
+                        position: eye,
+                        look_at: add(eye, scale(normalize([dir[0], rise, dir[2]]), 10)),
+                        fov,
+                        samples,
+                        min_clearance: 0,
+                        low_angle_rule: false,
+                        eye: eyeSpec,
+                        note: `eye ${source}`,
+                    });
+                }
+            }
+        }
+        return out;
+    }
+    const fov = ctx.fov ?? fovDefault;
+    const forward = normalize([ctx.spawn.camera?.forward[0] ?? ctx.spawn.forward[0], 0, ctx.spawn.camera?.forward[2] ?? ctx.spawn.forward[2]]);
+    out.push({ id: "eye_spawn_forward", position: eye, look_at: add(eye, scale(forward, 10)), fov, samples: [], min_clearance: 0, low_angle_rule: false, eye: eyeSpec, note: `eye ${source}` });
+    for (const azimuth of AZIMUTHS_16) {
+        const dir = directionFromAngles(azimuth, 0);
+        out.push({
+            id: `eye_az${String(azimuth).padStart(5, "0")}`,
+            position: eye,
+            look_at: add(eye, scale(dir, 10)),
+            fov,
+            samples: [],
+            min_clearance: 0,
+            low_angle_rule: false,
+            eye: eyeSpec,
+            note: `eye ${source}`,
+        });
+    }
+    return out;
+}
+/** Where a ray from `origin` along `dir` leaves `box` (slab test), or Infinity. */
+export function exitDistance(box, origin, dir) {
+    const lo = box.position;
+    const hi = aabbMax(box);
+    let tExit = Infinity;
+    for (let k = 0; k < 3; k++) {
+        const d = dir[k];
+        if (Math.abs(d) < 1e-9)
+            continue;
+        const t1 = (lo[k] - origin[k]) / d;
+        const t2 = (hi[k] - origin[k]) / d;
+        tExit = Math.min(tExit, Math.max(t1, t2));
+    }
+    return Math.max(0, tExit);
+}
+/**
+ * Pick the corridor axis from the engine's free-run scan: the longest free
+ * line (clipped to the subject bounds + 2 m on each end) that is also narrow
+ * enough to read as a corridor and wide enough to walk.
+ */
+export function chooseCorridorAxis(runs, box) {
+    const scored = [];
+    for (const run of runs) {
+        const exitFwd = exitDistance(box, run.seed, run.dir);
+        const exitBack = exitDistance(box, run.seed, scale(run.dir, -1));
+        const usableFwd = Math.min(run.fwd, exitFwd + 2);
+        const usableBack = Math.min(run.back, exitBack + 2);
+        const total = usableFwd + usableBack;
+        const width = run.left + run.right;
+        if (total < 4 || width < 1)
+            continue;
+        const slenderness = total / Math.max(width, 0.5);
+        const score = total * Math.min(1, slenderness / 3);
+        scored.push({ ...run, usableFwd, usableBack, width, score, openFwd: run.fwd > exitFwd + 0.5, openBack: run.back > exitBack + 0.5 });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    // Distinct axes only: drop near-duplicates (same direction, nearby seed).
+    const distinct = [];
+    for (const axis of scored) {
+        const dup = distinct.some((d) => Math.abs(d.dir[0] * axis.dir[0] + d.dir[2] * axis.dir[2]) > 0.95 && Math.hypot(d.seed[0] - axis.seed[0], d.seed[2] - axis.seed[2]) < Math.max(2, d.width));
+        if (!dup)
+            distinct.push(axis);
+        if (distinct.length >= 3)
+            break;
+    }
+    return distinct;
+}
+/** The walkable floor along a corridor axis: the scan put its seed at eye
+ *  height above the floor it found there. */
+export function corridorFloorY(axis, eyeHeight) {
+    return axis.seed[1] - (eyeHeight ?? DEFAULT_EYE_HEIGHT);
+}
+function corridorCandidates(ctx, fovDefault) {
+    const axis = ctx.corridor;
+    // The floor under the corridor line (the scan's seed), not the subject's
+    // lowest point: walls sunk into the ground or a backing plane below the
+    // floor would put every camera too low or, after the ground check, high.
+    const floorY = corridorFloorY(axis, ctx.eyeHeight);
+    const height = ctx.eyeHeight ?? DEFAULT_EYE_HEIGHT;
+    const [min, max] = eyeBand(ctx.eyeHeight);
+    const eyeSpec = { min, max, target: height, stand: [...axis.seed] };
+    const dir = normalize([axis.dir[0], 0, axis.dir[2]]);
+    const perp = [dir[2], 0, -dir[0]];
+    const halfWidth = Math.min(axis.left, axis.right, axis.width / 2);
+    const fovs = ctx.fov !== undefined ? [ctx.fov] : [fovDefault - 5, fovDefault + 10];
+    const out = [];
+    // "ab" starts at the back end and looks toward the forward end.
+    const intoOf = (fromOpen, toOpen) => (fromOpen === toOpen ? 0.5 : fromOpen ? 1 : 0);
+    const intoAb = intoOf(axis.openBack, axis.openFwd);
+    // A corridor shot is about walking it: every camera stands at eye height.
+    // The alternatives are horizontal only (how far in from the end, how far
+    // off the centre line), never a raised eye.
+    for (const reach of [0.92, 0.75]) {
+        const endB = add(axis.seed, scale(dir, axis.usableFwd * reach));
+        const endA = add(axis.seed, scale(dir, -axis.usableBack * reach));
+        for (const [tag, from, to] of [["ab", endA, endB], ["ba", endB, endA]]) {
+            const into = tag === "ab" ? intoAb : 1 - intoAb;
+            const far = [to[0], floorY + height, to[2]];
+            const samples = [0.3, 0.55, 0.8, 1].map((t) => {
+                const p = lerp(from, to, t);
+                return [p[0], floorY + height, p[2]];
+            });
+            const mid = lerp(from, to, 0.55);
+            for (const side of [-0.3, 0.3]) {
+                const lat = scale(perp, side * halfWidth);
+                samples.push([mid[0] + lat[0], floorY + height, mid[2] + lat[2]]);
+            }
+            for (const lateral of [-0.3, 0, 0.3]) {
+                const offset = scale(perp, lateral * halfWidth);
+                const position = [from[0] + offset[0], floorY + height, from[2] + offset[2]];
+                for (const fov of fovs) {
+                    out.push({
+                        id: `corridor_${tag}_r${reach}_x${lateral}_fov${fov}`,
+                        position,
+                        look_at: far,
+                        fov,
+                        samples,
+                        min_clearance: DEFAULT_CLEARANCE,
+                        low_angle_rule: false,
+                        eye: eyeSpec,
+                        into,
+                        ...(into === 1 ? { note: "looks in from the open end" } : into === 0 ? { note: "looks out from the dead end" } : {}),
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+export function generateCandidates(ctx) {
+    const defaults = SHOT_DEFAULTS[ctx.shot];
+    const fov = ctx.fov ?? defaults.fov;
+    switch (ctx.shot) {
+        case "establishing": {
+            const box = ctx.subject;
+            return ringCandidates("wide", box, aabbCenter(box), [12, 25, 40], fov, defaults.fill, ctx.aspect, { clearance: DEFAULT_CLEARANCE });
+        }
+        case "detail": {
+            const box = ctx.subject;
+            return ringCandidates("detail", box, aabbCenter(box), [8, 22, 38], fov, defaults.fill, ctx.aspect, { clearance: DEFAULT_CLEARANCE });
+        }
+        case "low_angle": {
+            const box = ctx.subject;
+            const ground = ctx.groundY ?? box.position[1];
+            return ringCandidates("low", box, aabbCenter(box), [-6, -14, -24], fov, defaults.fill, ctx.aspect, {
+                minY: ground + LOW_ANGLE_CLEARANCE,
+                lowAngle: true,
+                clearance: LOW_ANGLE_CLEARANCE,
+            });
+        }
+        case "eye_level":
+            return eyeLevelCandidates(ctx, defaults.fov);
+        case "corridor":
+            return corridorCandidates(ctx, defaults.fov);
+    }
+}
+/** Corridor "subject" box used for frame metrics: the free line it looks down. */
+export function corridorBox(axis, floorY) {
+    const dir = normalize([axis.dir[0], 0, axis.dir[2]]);
+    const a = add(axis.seed, scale(dir, -axis.usableBack));
+    const b = add(axis.seed, scale(dir, axis.usableFwd));
+    const lo = [Math.min(a[0], b[0]) - 0.5, floorY, Math.min(a[2], b[2]) - 0.5];
+    const hi = [Math.max(a[0], b[0]) + 0.5, floorY + 2.5, Math.max(a[2], b[2]) + 0.5];
+    return { position: lo, size: sub(hi, lo) };
+}

package/dist/core/capabilities/seeing/math.d.ts

@@ -0,0 +1,134 @@
+export type Vec3 = readonly [number, number, number];
+export interface Aabb {
+    position: Vec3;
+    size: Vec3;
+}
+export interface CameraPose {
+    position: Vec3;
+    look_at: Vec3;
+    /** Vertical field of view, degrees. */
+    fov: number;
+}
+export declare const add: (a: Vec3, b: Vec3) => Vec3;
+export declare const sub: (a: Vec3, b: Vec3) => Vec3;
+export declare const scale: (a: Vec3, s: number) => Vec3;
+export declare const dot: (a: Vec3, b: Vec3) => number;
+export declare const cross: (a: Vec3, b: Vec3) => Vec3;
+export declare const length: (a: Vec3) => number;
+export declare const distance: (a: Vec3, b: Vec3) => number;
+export declare const lerp: (a: Vec3, b: Vec3, t: number) => Vec3;
+export declare const deg: (rad: number) => number;
+export declare const rad: (degrees: number) => number;
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+export declare function normalize(a: Vec3): Vec3;
+export declare function aabbCenter(box: Aabb): Vec3;
+export declare function aabbMax(box: Aabb): Vec3;
+export declare function aabbCorners(box: Aabb): Vec3[];
+export declare function mergeAabbs(boxes: readonly Aabb[]): Aabb;
+/** Camera basis as three column vectors (x right, y up, z back) — Basis.looking_at. */
+export interface Basis3 {
+    x: Vec3;
+    y: Vec3;
+    z: Vec3;
+}
+export declare function lookAtBasis(position: Vec3, target: Vec3): Basis3;
+export interface Projected {
+    u: number;
+    v: number;
+    /** Distance along the view direction; <= 0 means behind the lens. */
+    depth: number;
+}
+export declare function project(pose: CameraPose, aspect: number, point: Vec3): Projected;
+/** World direction of the ray through screen point (u, v). */
+export declare function rayDirection(pose: CameraPose, aspect: number, u: number, v: number): Vec3;
+export interface ScreenBox {
+    /** Clipped to the frame, normalized 0..1. */
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    /** Unclipped extent (may exceed 0..1); NaN when a corner is behind the lens. */
+    rawWidth: number;
+    rawHeight: number;
+    /** Fraction of the 8 corners that land inside the frame. */
+    cornersInFrame: number;
+    anyBehind: boolean;
+}
+export declare function screenBox(pose: CameraPose, aspect: number, box: Aabb): ScreenBox;
+/** How much of the frame the box spans along its limiting dimension
+ *  (max of width and height fractions). Infinity when a corner is behind. */
+export declare function frameFill(pose: CameraPose, aspect: number, box: Aabb): number;
+/** Unit vector from azimuth (0 = +Z, 90 = +X) and elevation (degrees, + = up). */
+export declare function directionFromAngles(azimuthDeg: number, elevationDeg: number): Vec3;
+/**
+ * Distance from `lookAt` along `toCamera` (unit) at which the box fills
+ * `fill` of the frame along its limiting dimension. Binary search: fill falls
+ * monotonically as the camera backs away once every corner is in front.
+ */
+export declare function fitDistance(box: Aabb, lookAt: Vec3, toCamera: Vec3, fov: number, aspect: number, fill: number): number;
+/** Direction presets the screenshot tool uses (direction FROM the subject TO
+ *  the camera). "iso" matches ScenePreview's 3/4 view (camera at -X, +Y, -Z). */
+export declare const DIRECTION_PRESETS: {
+    readonly front: readonly [0, 0, 1];
+    readonly back: readonly [0, 0, -1];
+    readonly left: readonly [-1, 0, 0];
+    readonly right: readonly [1, 0, 0];
+    readonly top: readonly [0, 1, 0];
+    readonly iso: readonly [-1, 0.7, -1];
+};
+export type DirectionPreset = keyof typeof DIRECTION_PRESETS;
+export declare const DIRECTION_PRESET_NAMES: readonly ["front", "back", "left", "right", "top", "iso"];
+/** Parse a Godot "Vector3(x, y, z)" literal; throws ToolInputError (nothing sent). */
+export declare function parseVector3(literal: string, label: string): Vec3;
+/** "Vector3(x, y, z)" with 3 decimals — the literal the engine echoes. */
+export declare function formatVector3(v: Vec3): string;
+export declare function roundVec(v: Vec3, digits?: number): Vec3;
+/** Rotate `v` about +Y by `degrees` (counter-clockwise seen from above). */
+export declare function rotateY(v: Vec3, degrees: number): Vec3;
+/** Horizontal angle (degrees) that moves a centered subject to a vertical
+ *  third line for this fov/aspect. */
+export declare function thirdsYawOffset(fov: number, aspect: number): number;
+/** Horizon line position (v, 0 = top) for a level camera pitched by `pitchDeg`
+ *  (+ = looking up); null when the horizon is outside the frame. */
+export declare function horizonV(pitchDeg: number, fov: number): number | null;
+export declare function pitchOf(pose: CameraPose): number;
+/**
+ * The low-angle rule (camera-collision-avoidance): a camera that would sit
+ * below `minY` on its line of sight to `lookAt` moves CLOSER along that line
+ * and widens its FOV so the subject keeps its size in frame, instead of being
+ * buried in the ground or pushed up out of the low angle.
+ */
+export declare function applyLowAngleRule(lookAt: Vec3, toCamera: Vec3, dist: number, fov: number, minY: number, maxFov: number): {
+    position: Vec3;
+    distance: number;
+    fov: number;
+    adjusted: boolean;
+    impossible?: boolean;
+};
+/**
+ * The zoom window for a region of a reference frame, honoured EXACTLY: the
+ * region plus `pad` of its size on each side, clipped to the frame — never
+ * grown to an aspect ratio. `widenedBecause` names anything that made the
+ * window larger than the region asked for (only the pad can).
+ */
+export declare function exactCrop(rect: {
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+}, pad?: number): {
+    crop: [number, number, number, number];
+    widenedBecause: string[];
+    clipped: boolean;
+};
+/**
+ * Lay a window of pixel aspect `regionAspect` into an output image whose
+ * longest edge is `maxEdge`. The image takes the window's own aspect, clamped
+ * to minAspect..maxAspect; past the clamp the window is centred with dark bars
+ * (letterbox / pillarbox) instead of being stretched or widened.
+ */
+export declare function letterbox(regionAspect: number, maxEdge: number, minAspect?: number, maxAspect?: number): {
+    canvas: [number, number];
+    rect: [number, number, number, number];
+    letterboxed: boolean;
+};

package/dist/core/capabilities/seeing/math.js

@@ -0,0 +1,269 @@
+/**
+ * Camera math for the seeing tools — pure, engine-free, unit-tested.
+ *
+ * Conventions match the engine (Godot 4): right-handed, +Y up, a camera looks
+ * down its local -Z, `lookAtBasis` mirrors Basis.looking_at, and the vertical
+ * field of view is fixed (Camera3D KEEP_HEIGHT), so the horizontal extent
+ * scales with the aspect ratio. Screen coordinates are normalized: u,v in 0..1
+ * with v = 0 at the TOP of the image.
+ */
+import { ToolInputError } from "../../tool-errors.js";
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+];
+export const length = (a) => Math.sqrt(dot(a, a));
+export const distance = (a, b) => length(sub(a, b));
+export const lerp = (a, b, t) => add(a, scale(sub(b, a), t));
+export const deg = (rad) => (rad * 180) / Math.PI;
+export const rad = (degrees) => (degrees * Math.PI) / 180;
+export const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+export function normalize(a) {
+    const l = length(a);
+    if (l < 1e-9)
+        return [0, 0, 0];
+    return [a[0] / l, a[1] / l, a[2] / l];
+}
+export function aabbCenter(box) {
+    return add(box.position, scale(box.size, 0.5));
+}
+export function aabbMax(box) {
+    return add(box.position, box.size);
+}
+export function aabbCorners(box) {
+    const [x0, y0, z0] = box.position;
+    const [x1, y1, z1] = aabbMax(box);
+    return [
+        [x0, y0, z0], [x1, y0, z0], [x0, y1, z0], [x1, y1, z0],
+        [x0, y0, z1], [x1, y0, z1], [x0, y1, z1], [x1, y1, z1],
+    ];
+}
+export function mergeAabbs(boxes) {
+    if (!boxes.length)
+        throw new Error("mergeAabbs needs at least one box");
+    let lo = boxes[0].position;
+    let hi = aabbMax(boxes[0]);
+    for (const box of boxes.slice(1)) {
+        const bmax = aabbMax(box);
+        lo = [Math.min(lo[0], box.position[0]), Math.min(lo[1], box.position[1]), Math.min(lo[2], box.position[2])];
+        hi = [Math.max(hi[0], bmax[0]), Math.max(hi[1], bmax[1]), Math.max(hi[2], bmax[2])];
+    }
+    return { position: lo, size: sub(hi, lo) };
+}
+export function lookAtBasis(position, target) {
+    const forward = normalize(sub(target, position));
+    // Same guard as the engine: looking_at refuses an up parallel to the view.
+    const up = Math.abs(dot(forward, [0, 1, 0])) > 0.999 ? [0, 0, -1] : [0, 1, 0];
+    const z = scale(forward, -1);
+    const x = normalize(cross(up, z));
+    const y = cross(z, x);
+    return { x, y, z };
+}
+export function project(pose, aspect, point) {
+    const basis = lookAtBasis(pose.position, pose.look_at);
+    const rel = sub(point, pose.position);
+    const cx = dot(rel, basis.x);
+    const cy = dot(rel, basis.y);
+    const cz = dot(rel, basis.z);
+    const depth = -cz;
+    const tanV = Math.tan(rad(pose.fov) / 2);
+    const tanH = tanV * aspect;
+    if (depth <= 1e-6)
+        return { u: Number.NaN, v: Number.NaN, depth };
+    const xNdc = cx / (depth * tanH);
+    const yNdc = cy / (depth * tanV);
+    return { u: (xNdc + 1) / 2, v: (1 - yNdc) / 2, depth };
+}
+/** World direction of the ray through screen point (u, v). */
+export function rayDirection(pose, aspect, u, v) {
+    const basis = lookAtBasis(pose.position, pose.look_at);
+    const tanV = Math.tan(rad(pose.fov) / 2);
+    const x = (u * 2 - 1) * tanV * aspect;
+    const y = (1 - v * 2) * tanV;
+    return normalize(add(add(scale(basis.x, x), scale(basis.y, y)), scale(basis.z, -1)));
+}
+export function screenBox(pose, aspect, box) {
+    let u0 = Infinity;
+    let v0 = Infinity;
+    let u1 = -Infinity;
+    let v1 = -Infinity;
+    let inside = 0;
+    let behind = false;
+    const corners = aabbCorners(box);
+    for (const corner of corners) {
+        const p = project(pose, aspect, corner);
+        if (p.depth <= 1e-6) {
+            behind = true;
+            continue;
+        }
+        u0 = Math.min(u0, p.u);
+        v0 = Math.min(v0, p.v);
+        u1 = Math.max(u1, p.u);
+        v1 = Math.max(v1, p.v);
+        if (p.u >= 0 && p.u <= 1 && p.v >= 0 && p.v <= 1)
+            inside += 1;
+    }
+    if (!Number.isFinite(u0)) {
+        return { u0: 0, v0: 0, u1: 0, v1: 0, rawWidth: Number.NaN, rawHeight: Number.NaN, cornersInFrame: 0, anyBehind: true };
+    }
+    return {
+        u0: clamp(u0, 0, 1),
+        v0: clamp(v0, 0, 1),
+        u1: clamp(u1, 0, 1),
+        v1: clamp(v1, 0, 1),
+        rawWidth: behind ? Number.NaN : u1 - u0,
+        rawHeight: behind ? Number.NaN : v1 - v0,
+        cornersInFrame: inside / corners.length,
+        anyBehind: behind,
+    };
+}
+/** How much of the frame the box spans along its limiting dimension
+ *  (max of width and height fractions). Infinity when a corner is behind. */
+export function frameFill(pose, aspect, box) {
+    const s = screenBox(pose, aspect, box);
+    if (s.anyBehind || !Number.isFinite(s.rawWidth))
+        return Infinity;
+    return Math.max(s.rawWidth, s.rawHeight);
+}
+/** Unit vector from azimuth (0 = +Z, 90 = +X) and elevation (degrees, + = up). */
+export function directionFromAngles(azimuthDeg, elevationDeg) {
+    const az = rad(azimuthDeg);
+    const el = rad(elevationDeg);
+    return [Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az)];
+}
+/**
+ * Distance from `lookAt` along `toCamera` (unit) at which the box fills
+ * `fill` of the frame along its limiting dimension. Binary search: fill falls
+ * monotonically as the camera backs away once every corner is in front.
+ */
+export function fitDistance(box, lookAt, toCamera, fov, aspect, fill) {
+    const dir = normalize(toCamera);
+    const radius = Math.max(0.05, length(box.size) / 2);
+    let lo = 0.05;
+    let hi = Math.max(1, radius / Math.tan(rad(Math.min(fov, fov * aspect)) / 2) * 50);
+    const fillAt = (d) => frameFill({ position: add(lookAt, scale(dir, d)), look_at: lookAt, fov }, aspect, box);
+    if (fillAt(hi) > fill)
+        return hi;
+    for (let i = 0; i < 60; i++) {
+        const mid = (lo + hi) / 2;
+        if (fillAt(mid) > fill)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return hi;
+}
+/** Direction presets the screenshot tool uses (direction FROM the subject TO
+ *  the camera). "iso" matches ScenePreview's 3/4 view (camera at -X, +Y, -Z). */
+export const DIRECTION_PRESETS = {
+    front: [0, 0, 1],
+    back: [0, 0, -1],
+    left: [-1, 0, 0],
+    right: [1, 0, 0],
+    top: [0, 1, 0],
+    iso: [-1, 0.7, -1],
+};
+export const DIRECTION_PRESET_NAMES = ["front", "back", "left", "right", "top", "iso"];
+const NUM = "[-+]?(?:\\d+\\.?\\d*|\\.\\d+)(?:[eE][-+]?\\d+)?";
+const VECTOR3_LITERAL = new RegExp(`^\\s*Vector3\\s*\\(\\s*(${NUM})\\s*,\\s*(${NUM})\\s*,\\s*(${NUM})\\s*\\)\\s*$`);
+/** Parse a Godot "Vector3(x, y, z)" literal; throws ToolInputError (nothing sent). */
+export function parseVector3(literal, label) {
+    const match = VECTOR3_LITERAL.exec(literal);
+    if (!match) {
+        throw new ToolInputError(`${label} must be a Godot literal like "Vector3(0, 5, 12)" (got ${JSON.stringify(literal)}). Nothing was sent.`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** "Vector3(x, y, z)" with 3 decimals — the literal the engine echoes. */
+export function formatVector3(v) {
+    const f = (n) => {
+        const r = Math.round(n * 1000) / 1000;
+        return Object.is(r, -0) ? "0" : String(r);
+    };
+    return `Vector3(${f(v[0])}, ${f(v[1])}, ${f(v[2])})`;
+}
+export function roundVec(v, digits = 3) {
+    const k = 10 ** digits;
+    return [Math.round(v[0] * k) / k, Math.round(v[1] * k) / k, Math.round(v[2] * k) / k];
+}
+/** Rotate `v` about +Y by `degrees` (counter-clockwise seen from above). */
+export function rotateY(v, degrees) {
+    const a = rad(degrees);
+    const c = Math.cos(a);
+    const s = Math.sin(a);
+    return [v[0] * c + v[2] * s, v[1], -v[0] * s + v[2] * c];
+}
+/** Horizontal angle (degrees) that moves a centered subject to a vertical
+ *  third line for this fov/aspect. */
+export function thirdsYawOffset(fov, aspect) {
+    const tanH = Math.tan(rad(fov) / 2) * aspect;
+    return deg(Math.atan(tanH / 3));
+}
+/** Horizon line position (v, 0 = top) for a level camera pitched by `pitchDeg`
+ *  (+ = looking up); null when the horizon is outside the frame. */
+export function horizonV(pitchDeg, fov) {
+    const v = 0.5 + Math.tan(rad(pitchDeg)) / (2 * Math.tan(rad(fov) / 2));
+    return v >= 0 && v <= 1 ? v : null;
+}
+export function pitchOf(pose) {
+    const f = normalize(sub(pose.look_at, pose.position));
+    return deg(Math.asin(clamp(f[1], -1, 1)));
+}
+/**
+ * The low-angle rule (camera-collision-avoidance): a camera that would sit
+ * below `minY` on its line of sight to `lookAt` moves CLOSER along that line
+ * and widens its FOV so the subject keeps its size in frame, instead of being
+ * buried in the ground or pushed up out of the low angle.
+ */
+export function applyLowAngleRule(lookAt, toCamera, dist, fov, minY, maxFov) {
+    const dir = normalize(toCamera);
+    const position = add(lookAt, scale(dir, dist));
+    if (position[1] >= minY || dir[1] >= -0.02)
+        return { position, distance: dist, fov, adjusted: false };
+    const d2 = (minY - lookAt[1]) / dir[1];
+    if (!(d2 >= 0.5))
+        return { position, distance: dist, fov, adjusted: false, impossible: true };
+    const fov2 = clamp(deg(2 * Math.atan((Math.tan(rad(fov) / 2) * dist) / d2)), fov, maxFov);
+    return { position: add(lookAt, scale(dir, d2)), distance: d2, fov: fov2, adjusted: true };
+}
+/**
+ * The zoom window for a region of a reference frame, honoured EXACTLY: the
+ * region plus `pad` of its size on each side, clipped to the frame — never
+ * grown to an aspect ratio. `widenedBecause` names anything that made the
+ * window larger than the region asked for (only the pad can).
+ */
+export function exactCrop(rect, pad = 0) {
+    const w = Math.max(1e-4, rect.u1 - rect.u0);
+    const h = Math.max(1e-4, rect.v1 - rect.v0);
+    const raw = [rect.u0 - w * pad, rect.v0 - h * pad, rect.u1 + w * pad, rect.v1 + h * pad];
+    const crop = [clamp(raw[0], 0, 1), clamp(raw[1], 0, 1), clamp(raw[2], 0, 1), clamp(raw[3], 0, 1)];
+    const clipped = crop.some((v, i) => Math.abs(v - raw[i]) > 1e-9);
+    return { crop, widenedBecause: pad > 0 ? [`pad ${pad} of the region's size added on each side`] : [], clipped };
+}
+/**
+ * Lay a window of pixel aspect `regionAspect` into an output image whose
+ * longest edge is `maxEdge`. The image takes the window's own aspect, clamped
+ * to minAspect..maxAspect; past the clamp the window is centred with dark bars
+ * (letterbox / pillarbox) instead of being stretched or widened.
+ */
+export function letterbox(regionAspect, maxEdge, minAspect = 0.5, maxAspect = 3.2) {
+    const even = (n) => Math.max(16, Math.round(n / 2) * 2);
+    const canvasAspect = clamp(regionAspect, minAspect, maxAspect);
+    const canvas = canvasAspect >= 1 ? [even(maxEdge), even(maxEdge / canvasAspect)] : [even(maxEdge * canvasAspect), even(maxEdge)];
+    let w = canvas[0];
+    let h = Math.round(w / regionAspect);
+    if (h > canvas[1]) {
+        h = canvas[1];
+        w = Math.round(h * regionAspect);
+    }
+    w = Math.max(16, Math.min(canvas[0], w));
+    h = Math.max(16, Math.min(canvas[1], h));
+    const x = Math.floor((canvas[0] - w) / 2);
+    const y = Math.floor((canvas[1] - h) / 2);
+    return { canvas, rect: [x, y, w, h], letterboxed: w < canvas[0] - 1 || h < canvas[1] - 1 };
+}