summer-engine 3.0.0 → 3.2.0

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

@@ -0,0 +1,233 @@
+import { type CapabilityAdvertisingClient } from "../../capability-skew.js";
+import { type SceneMark, type SceneMarksSummary } from "../camera-view.js";
+import { type Aabb, type CameraPose, type DirectionPreset, type Vec3 } from "./math.js";
+import { type ShotType } from "./candidates.js";
+import { type Measurement, type ViewProblem } from "./scoring.js";
+import { type ProbeClient } from "./probe.js";
+export declare const VIEW_MODES: readonly ["beauty", "lighting", "unshaded", "normals", "overdraw", "wireframe"];
+export type ViewMode = (typeof VIEW_MODES)[number];
+export declare const SEEING_FALLBACK = "render explicit poses with summer_screenshot target:\"scene\" framing:\"free\" (camera_position + camera_look_at), one image per call";
+export interface SeeingClient extends ProbeClient, CapabilityAdvertisingClient {
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getProjectRoot?(): string | undefined;
+}
+export interface SeeingImage {
+    base64: string;
+    mime: string;
+    width?: number;
+    height?: number;
+}
+export interface SeeingSuccess {
+    ok: true;
+    image: SeeingImage | null;
+    /** Compact, model-facing text (labels, poses, scores, mark->path map). */
+    caption: string;
+    /** Structured receipt for the CLI face and tests. */
+    receipt: Record<string, unknown>;
+}
+export interface SeeingFailure {
+    ok: false;
+    failure_reason: string;
+    error: string;
+    hint?: string;
+    detail?: Record<string, unknown>;
+}
+export type SeeingResult = SeeingSuccess | SeeingFailure;
+export interface PoseArgs {
+    bookmark_name?: string;
+    camera_position?: string;
+    camera_look_at?: string;
+    fov?: number;
+}
+export interface OccluderArgs {
+    hard?: string[];
+    soft?: string[];
+    ignore?: string[];
+    hard_layers?: number;
+    soft_layers?: number;
+}
+export declare const MAX_IMAGE_EDGE = 4096;
+export declare function validateScenePath(path: string): string;
+export declare function validateNodePath(path: string, label: string): string;
+export declare function validateLabel(label: string): string;
+export declare function validateBookmarkName(name: string, label?: string): string;
+export interface BookmarkInfo {
+    pose: CameraPose;
+    created?: string;
+}
+export interface GridLayout {
+    cols: number;
+    rows: number;
+    tile: [number, number];
+    canvas: [number, number];
+    rects: Array<[number, number, number, number]>;
+}
+/** Same-size tiles in a grid whose longest edge is `maxEdge`. */
+export declare function layoutGrid(count: number, aspect: number, maxEdge: number, forcedCols?: number): GridLayout;
+/**
+ * The compare baseline rule, ONE copy for every renderer of a bookmark: a
+ * bookmark's previous-image slot is replaced only by a compare_previous render
+ * (the comparison is done, this render is the next baseline), by an explicit
+ * update_previous:true, or by a call that (re)defines the bookmark's pose
+ * (summer_frame_nodes / summer_frame_shot saving it: the old image is of a
+ * different viewpoint). Any other render of the bookmark creates the slot only
+ * when it does not exist yet and otherwise leaves the baseline alone, so a
+ * plain sheet, debug view or screenshot never silently resets a comparison.
+ */
+export type SlotPolicy = "replace" | "create_if_missing";
+export declare function slotPolicy(options: {
+    comparePrevious?: boolean;
+    updatePrevious?: boolean;
+    definesPose?: boolean;
+}): SlotPolicy;
+/** Keep the native render of a bookmark as its before/after slot when it is
+ *  clean (no marks), within the stored-shot edge and allowed by the policy.
+ *  Returns caption notes. */
+export declare function rememberBookmarkRender(projectRoot: string | undefined, bookmark: string, image: {
+    base64: string;
+    width?: number;
+    height?: number;
+}, marks: boolean, policy?: SlotPolicy): Promise<string[]>;
+export interface FrameNodesArgs {
+    scenePath?: string;
+    nodes: string[];
+    direction?: DirectionPreset;
+    from?: string;
+    fill?: number;
+    fov?: number;
+    max_size?: number;
+    aspect?: number;
+    marks?: boolean;
+    max_marks?: number;
+    bookmark_name?: string;
+}
+export declare function frameNodes(client: SeeingClient, args: FrameNodesArgs): Promise<SeeingResult>;
+export interface ViewOption {
+    /** How the option differs from the request ("as requested", "fov 65", "turned 30 deg left"...). */
+    tag: string;
+    from: Vec3;
+    fov: number;
+    /** Closeness to the request: degrees turned + half the fov added. */
+    cost: number;
+    pose: CameraPose;
+}
+/**
+ * The requested view first, then the nearby alternatives a caller can pass
+ * straight back to summer_frame_nodes (`from` + `fov`): the same direction
+ * with a wider lens (the camera fits closer, in front of what it stood
+ * behind), the direction turned around the nodes, and raised or lowered.
+ */
+export declare function viewOptions(box: Aabb, center: Vec3, toCamera: Vec3, fov: number, aspect: number, fill: number): ViewOption[];
+export interface ViewCheck {
+    problem: ViewProblem | null;
+    requestedSummary: string;
+    requestedFov: number;
+    alternative?: ViewOption;
+    checked: number;
+}
+export declare function judgeViewOptions(options: ViewOption[], measurements: Measurement[]): ViewCheck;
+export interface MarkVisibility {
+    id: number;
+    path: string;
+    /** Points of the node's 5 (centre + 4 across the face it shows) the camera sees. */
+    visible?: number;
+    samples?: number;
+    /** First opaque surface in front of a hidden point. */
+    blocker?: string;
+    /** Points met only on the node's own back faces (not drawn). */
+    own_back?: number;
+    missing?: boolean;
+}
+export declare function readOcclusion(result: Record<string, unknown> | null | undefined): Map<number, MarkVisibility>;
+/** "" when the node is mostly visible; else a short phrase for its label. */
+export declare function markOcclusionNote(v: MarkVisibility): string;
+export declare function isHiddenMark(v: MarkVisibility | undefined): boolean;
+/** formatSceneMarks plus a "(hidden ...)" note per hidden label and one line
+ *  saying what the occlusion test found. */
+export declare function formatMarksWithOcclusion(summary: SceneMarksSummary, occlusion: Map<number, MarkVisibility>): string[];
+/**
+ * The occlusion test on its own (summer_screenshot marks): one analyze pass.
+ * Never throws; a failure becomes a caption note, the screenshot stands.
+ */
+export declare function checkMarkOcclusion(client: SeeingClient, scenePath: string | undefined, position: Vec3, marks: SceneMark[]): Promise<{
+    occlusion: Map<number, MarkVisibility>;
+    note?: string;
+}>;
+export interface ShotSheetShot extends PoseArgs {
+    label?: string;
+}
+export interface ShotSheetArgs {
+    scenePath?: string;
+    shots: ShotSheetShot[];
+    view?: ViewMode;
+    compare_previous?: boolean;
+    /** Replace each bookmark's previous image with this render even without
+     *  compare_previous (default: only a missing slot is created). */
+    update_previous?: boolean;
+    max_size?: number;
+    aspect?: number;
+    save_to?: string;
+}
+export declare function shotSheet(client: SeeingClient, args: ShotSheetArgs): Promise<SeeingResult>;
+export interface DebugViewsArgs extends PoseArgs {
+    scenePath?: string;
+    views?: ViewMode[];
+    /** Replace the bookmark's previous image with this beauty tile (default:
+     *  only a missing slot is created). */
+    update_previous?: boolean;
+    max_size?: number;
+    aspect?: number;
+    save_to?: string;
+}
+export declare const VIEW_NOTES: Record<ViewMode, string>;
+export declare function debugViews(client: SeeingClient, args: DebugViewsArgs): Promise<SeeingResult>;
+export interface ZoomArgs extends PoseArgs {
+    scenePath?: string;
+    /** [x, y, w, h]; length is checked at call time. */
+    region?: number[];
+    mark?: number;
+    /** [width, height]; length is checked at call time. */
+    reference_size?: number[];
+    pad?: number;
+    view?: ViewMode;
+    max_size?: number;
+    save_to?: string;
+}
+export declare function zoom(client: SeeingClient, args: ZoomArgs): Promise<SeeingResult>;
+export interface FrameShotArgs {
+    scenePath?: string;
+    shot: ShotType;
+    subject?: string[];
+    spawn?: string;
+    eye_height?: number;
+    fov?: number;
+    aspect?: number;
+    occluders?: OccluderArgs;
+    max_soft_fraction?: number;
+    bookmark_name?: string;
+    save_bookmark?: boolean;
+    render?: "sheet" | "best" | "none";
+    max_size?: number;
+}
+/**
+ * The real camera height, said explicitly: the absolute y of the camera and
+ * its height above the first solid surface straight below it (the walkable
+ * surface for eye-level and corridor poses; for a high camera that can be a
+ * roof). `short` is for tile labels.
+ */
+export declare function cameraHeightText(pose: CameraPose, groundY: number | null | undefined, short?: boolean): string;
+/** Where the corridor scan seeded: the walkable floor it found inside the
+ *  subject, or (declared) the subject's lowest point. */
+export interface CorridorScanFloor {
+    floor_y: number;
+    /** "walkable" (downward rays found it), "lowest_point" (none found), "caller". */
+    floor_source: string;
+    floor_hits?: number;
+    floor_rays?: number;
+}
+export declare function scanFloorText(floor: CorridorScanFloor, subject: Aabb): string;
+export declare function frameShot(client: SeeingClient, args: FrameShotArgs): Promise<SeeingResult>;
+export declare const SHOT_TYPE_DEFAULTS: Record<"detail" | "establishing" | "eye_level" | "low_angle" | "corridor", import("./candidates.js").ShotDefaults>;