@pascal-app/core 1.0.3 → 1.0.5

package/dist/agent-operations/node-patch.js

@@ -0,0 +1,114 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { parseMaterialColor } from '../material-library.js';
+import { parseNode } from '../schema/compiled-node-parsers.js';
+import { finishSurface, requireMaterialRef } from './material-refs.js';
+/**
+ * An agent's edit of a node checked so it does what it says, the same on the MCP's apply_patch
+ * and the chat's update_node. A pier once took five attempts: `material: {color}`
+ * reported "applied" and stored `{}` (the schema drops unknown keys), `materialPreset: null` was
+ * refused (no way to clear), an unknown preset rendered grey, and a `material` under a set preset
+ * never showed. Returns the data to write: `null` (or an empty material ref) as `undefined`, which
+ * the store reads as "remove the field". Free-form records (metadata, slots) keep every key, so they
+ * pass as sent.
+ */
+/** The pairs where the first, set, hides the second: the renderer reads a preset before a material. */
+const HIDES = [
+    ['materialPreset', 'material'],
+    ['topMaterialPreset', 'topMaterial'],
+    ['edgeMaterialPreset', 'edgeMaterial'],
+    ['wallMaterialPreset', 'wallMaterial'],
+];
+const isPreset = (key) => key === 'materialPreset' || key.endsWith('MaterialPreset');
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** The paths of `sent` the parsed node does not keep as sent: dropped, or changed (a value coerced). */
+function lostPaths(sent, kept, path) {
+    if (isRecord(sent)) {
+        if (!isRecord(kept))
+            return [path];
+        return Object.entries(sent).flatMap(([key, value]) => value === undefined
+            ? []
+            : key in kept
+                ? lostPaths(value, kept[key], `${path}.${key}`)
+                : [`${path}.${key}`]);
+    }
+    if (Array.isArray(sent))
+        return Array.isArray(kept) && kept.length === sent.length
+            ? sent.flatMap((value, i) => lostPaths(value, kept[i], `${path}[${i}]`))
+            : [path];
+    return typeof sent === 'string' && sent !== kept
+        ? [`${path} (stored as ${JSON.stringify(kept)})`]
+        : [];
+}
+/** Material refs the patch writes: a preset field, a slot, a region's or a room's finish. */
+function materialRefs(data) {
+    const refs = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (isPreset(key) && typeof value === 'string')
+            refs.push([key, value]);
+        if (key === 'slots' && isRecord(value))
+            for (const [slot, ref] of Object.entries(value))
+                if (typeof ref === 'string')
+                    refs.push([`slots.${slot}`, ref]);
+        if (key === 'faceRegions' && Array.isArray(value))
+            value.forEach((region, i) => {
+                if (isRecord(region) && typeof region.finish === 'string')
+                    refs.push([`faceRegions[${i}].finish`, region.finish]);
+            });
+    }
+    return refs;
+}
+/** The node's current value at a field materialRefs names (a preset, `slots.<id>`, a region). */
+function valueAt(node, field) {
+    const record = node;
+    const slot = /^slots\.(.+)$/.exec(field);
+    if (slot)
+        return isRecord(record.slots) ? record.slots[slot[1]] : undefined;
+    const region = /^faceRegions\[(\d+)\]\.finish$/.exec(field);
+    if (region) {
+        const regions = record.faceRegions;
+        const entry = Array.isArray(regions) ? regions[Number(region[1])] : undefined;
+        return isRecord(entry) ? entry.finish : undefined;
+    }
+    return record[field];
+}
+export function honestNodePatch(current, data) {
+    const sent = {};
+    for (const [key, value] of Object.entries(data))
+        sent[key] = value === null || (isPreset(key) && value === '') ? undefined : value;
+    const merged = { ...current, ...sent };
+    for (const [key, value] of Object.entries(sent))
+        if (value === undefined)
+            delete merged[key];
+    const parsed = parseNode(merged);
+    if (!parsed.success) {
+        const required = parsed.error.issues
+            .map((issue) => String(issue.path[0] ?? ''))
+            .find((key) => key in sent && sent[key] === undefined);
+        if (required)
+            refuse('field_required', `${current.type} ${current.id} needs ${required}: it cannot be cleared.`, {
+                field: required,
+            });
+        // Any other schema failure is the caller's own refusal.
+        return sent;
+    }
+    const lost = Object.entries(sent).flatMap(([key, value]) => value === undefined ? [] : lostPaths(value, parsed.data[key], key));
+    if (lost.length)
+        refuse('unknown_field', `${current.type} ${current.id} would not keep ${lost.join(', ')}: the patch would report it applied and drop it.${lost.some((path) => /(^|\.)color\b/.test(path))
+            ? ' A colour goes in material.properties.color.'
+            : ''}`, { fields: lost });
+    for (const [field, ref] of materialRefs(sent)) {
+        // Restating the node's own value passes, so an older node's bad value never blocks an edit;
+        // a slot also takes a plain colour (as unknownMaterialPresetRefusal reads them).
+        if (valueAt(current, field) === ref)
+            continue;
+        if (field.startsWith('slots.') && parseMaterialColor(ref))
+            continue;
+        requireMaterialRef(ref, field, finishSurface(current.type, field));
+    }
+    for (const [preset, material] of HIDES) {
+        const hider = merged[preset];
+        if (sent[material] !== undefined && typeof hider === 'string' && hider)
+            refuse('shadowed_field', `${material} would not show: ${preset} (${hider}) is read first. Clear it in the same patch (${preset}: null).`, { field: material, hiddenBy: preset });
+    }
+    return sent;
+}

package/dist/agent-operations/paint.d.ts

@@ -0,0 +1,22 @@
+import { type MaterialSchema } from '../schema/index.js';
+import type { AgentOperation } from './types.js';
+/**
+ * `paint`: a finish in one call, as the editor's Paint gives it. Through patches an agent once took
+ * five tries to paint a pier grey: `material: {color}` was stored as `{}`, `materialPreset: null`
+ * was refused and an unknown preset fell back to grey. A colour is the nearest of the library's
+ * flat colours, said with how near; a native material is kept as a scene material. Slots are
+ * written as the editor's slot paint writes them, a wall's faces through its paint plan, a roof's
+ * role through its role field, on the roof: a roof shows one finish per surface, so a segment's
+ * finish goes on its roof.
+ */
+type PaintInput = {
+    targets: string[];
+    role?: string;
+    color?: string;
+    material?: string | MaterialSchema;
+    materialName?: string;
+    erase?: true;
+};
+export declare const paint: AgentOperation<PaintInput>;
+export {};
+//# sourceMappingURL=paint.d.ts.map

package/dist/agent-operations/paint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/paint.ts"],"names":[],"mappings":"AAKA,OAAO,EAKL,KAAK,cAAc,EAOpB,MAAM,WAAW,CAAA;AAMlB,OAAO,KAAK,EAAgB,cAAc,EAAc,MAAM,SAAS,CAAA;AAEvE;;;;;;;;GAQG;AAEH,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,CAAA;IAClC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,IAAI,CAAA;CACb,CAAA;AAsKD,eAAO,MAAM,KAAK,EAAE,cAAc,CAAC,UAAU,CA8M5C,CAAA"}

package/dist/agent-operations/paint.js

@@ -0,0 +1,329 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { wallFaceScriptPaintRefusal } from '../lib/wall-face-script.js';
+import { GLAZED_ROOF_SLOTS, nodeSlotDeclarations } from '../node-slots/index.js';
+import { nearestLibraryColorRef } from '../procedural-items/library-colors.js';
+import { getEffectiveSegmentSurfaceMaterial, getWallTrimSlotId, isGlazedRoofSegment, } from '../schema/index.js';
+import { buildWallFinishLayout, getWallLevelZones } from '../systems/wall/wall-finish.js';
+import { planWallPaint } from '../systems/wall/wall-paint-plan.js';
+import { roomFaceCover } from '../systems/wall/wall-room-sides.js';
+import { finishSurface, requireMaterialRef } from './material-refs.js';
+import { resolveInlinePaintMaterial } from './scene-materials.js';
+const WALL_TRIMS = ['skirting', 'crown', 'chairRail'];
+const ROOF_ROLES = ['top', 'edge', 'wall', 'fascia'];
+/** The surfaces the roof itself holds; its fascia is held by each of its segments. */
+const SHELL_ROLES = ['top', 'edge', 'wall'];
+/** The surfaces painted when no role is named: what "paint the column" means. */
+const DEFAULT_ROLES = {
+    wall: ['a', 'b', 'curtain-frame', 'curtain-solid'],
+    column: ['shaft'],
+    slab: ['surface'],
+    ceiling: ['surface'],
+    fence: ['posts', 'infill', 'base', 'rail'],
+    door: ['panel', 'frame'],
+    window: ['frame'],
+    'roof-segment': ['glazing-frame', 'glazing-solid'],
+    block: ['body'],
+};
+/** The roles painted without one named: the kind's defaults, or the one surface it has. */
+function defaultRoles(type, ids) {
+    const defaults = DEFAULT_ROLES[type];
+    if (defaults)
+        return defaults.filter((role) => ids.includes(role));
+    return ids.length === 1 ? [...ids] : [];
+}
+/** The finish asked for, as the ref it writes; refused when it is unknown. */
+function finishOf(input, surface, context) {
+    const given = [input.color, input.material, input.erase].filter((value) => value !== undefined);
+    if (given.length !== 1)
+        refuse('finish_required', 'Give one finish: color (#rrggbb), material (a library or scene ref, or a native material), or erase: true.');
+    if (input.materialName !== undefined && typeof input.material !== 'object')
+        refuse('invalid_material_name', 'materialName names a native material only.');
+    if (input.erase)
+        return { ref: undefined };
+    if (input.color) {
+        const match = nearestLibraryColorRef(input.color);
+        if (!match)
+            refuse('invalid_color', `${input.color} is no colour: give #rrggbb.`);
+        return {
+            ref: match.ref,
+            note: `${input.color}: nearest library colour ${match.name} (${match.color}), ΔE ${Math.round(match.distance)}.`,
+        };
+    }
+    if (typeof input.material === 'object')
+        return resolveInlinePaintMaterial(context.materials, input.material, input.materialName);
+    const ref = requireMaterialRef(input.material, undefined, surface, {
+        paint: true,
+        materials: context.materials,
+    });
+    const sceneMaterial = context.materials
+        ? Object.values(context.materials).find((entry) => `scene:${entry.id}` === ref)
+        : undefined;
+    return { ref, ...(sceneMaterial ? { sceneMaterial } : {}) };
+}
+/** A node's data for an update: what changed, and `undefined` for the fields it lost. */
+function changedData(before, after) {
+    const data = {};
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const [a, b] = [
+            before[key],
+            after[key],
+        ];
+        if (JSON.stringify(a) !== JSON.stringify(b))
+            data[key] = b;
+    }
+    return data;
+}
+/** A node's role written as `<role>MaterialPreset`, its inline material for that role gone with it. */
+function paintRoleField(node, role, ref) {
+    const next = { ...node };
+    delete next[`${role}Material`];
+    if (ref)
+        next[`${role}MaterialPreset`] = ref;
+    else
+        delete next[`${role}MaterialPreset`];
+    return next;
+}
+/**
+ * A segment without a finish of its own for a role, so its roof's shows there. A catch-all finish
+ * (`material`, `materialPreset`) goes too, written on the segment's other roles, which keep it.
+ */
+function withoutOwnRole(segment, role) {
+    const next = { ...segment };
+    if (segment.material !== undefined || segment.materialPreset !== undefined) {
+        for (const other of SHELL_ROLES) {
+            if (other === role)
+                continue;
+            const shown = getEffectiveSegmentSurfaceMaterial(segment, other);
+            next[`${other}Material`] = shown.material;
+            next[`${other}MaterialPreset`] = shown.materialPreset;
+        }
+        delete next.material;
+        delete next.materialPreset;
+    }
+    delete next[`${role}Material`];
+    delete next[`${role}MaterialPreset`];
+    for (const key of Object.keys(next))
+        if (next[key] === undefined)
+            delete next[key];
+    return next;
+}
+/**
+ * A wall face painted whole, as the editor's Paint paints each part of it: the face's own finish,
+ * and the finish of each room it is turned to, which shows over the face's own. Painted parts
+ * (regions) stay on top, as they do under a room's paint.
+ */
+function paintWallFace(nodes, wall, face, ref) {
+    const plan = planWallPaint(nodes, wall, { kind: 'slot', slotId: face }, ref);
+    const rooms = buildWallFinishLayout(wall, getWallLevelZones(wall, nodes)).spans[face];
+    for (const zoneId of new Set(rooms.map((span) => span.zoneId))) {
+        const scene = { ...nodes, ...plan };
+        Object.assign(plan, planWallPaint(scene, scene[wall.id], { kind: 'room-face', zoneId, face }, ref));
+    }
+    return plan;
+}
+/**
+ * The faces of a wall turned out of its rooms, or into them: by the rooms on its sides, else by
+ * the sides it keeps (`frontSide` and `backSide`, as a generator or the room structure wrote
+ * them). A partition, with a room on each face, is interior on both. A face rooms stand on only in
+ * part (a wall running on past its rooms, into a garden) is both: it is refused, so the caller
+ * names the face to paint whole.
+ */
+function wallFacesTurned(scene, wall, side) {
+    const cover = roomFaceCover(scene, wall.id);
+    const faces = ['a', 'b'];
+    const part = faces.find((face) => cover[face] === 'part');
+    if (part)
+        refuse('side_unknown', `Wall ${wall.id}'s face ${part} is in a room for part of its length and outside for the rest: name the face to paint whole, a or b.`, { target: wall.id });
+    if (cover.a === 'none' && cover.b === 'none')
+        return faces.filter((face) => (face === 'a' ? wall.frontSide : wall.backSide) === side);
+    return faces.filter((face) => (cover[face] === 'whole') === (side === 'interior'));
+}
+export const paint = (nodes, input, context) => {
+    // A refused material's nearest are the first target's kind: a roof is offered roofing.
+    const first = input.targets[0] ? nodes[input.targets[0]] : undefined;
+    const finish = finishOf(input, first && finishSurface(first.type, input.role), context);
+    const { ref } = finish;
+    const written = {};
+    const current = (id) => (written[id] ?? nodes[id]);
+    const scene = () => ({ ...nodes, ...written });
+    const painted = [];
+    const keptParts = [];
+    const throughRoof = [];
+    const modelRoles = [];
+    // A roof with glazed segments: its roles go on the roof for its standard segments, its glazing's
+    // on each glazed segment; a role only one kind has paints that kind.
+    const targets = [
+        ...new Set(input.targets.flatMap((id) => {
+            const node = nodes[id];
+            if (node?.type !== 'roof')
+                return [id];
+            const segments = node.children
+                .map((childId) => nodes[childId])
+                .filter((child) => child?.type === 'roof-segment');
+            const glazed = segments.filter(isGlazedRoofSegment).map((segment) => segment.id);
+            if (!glazed.length)
+                return [id];
+            const standard = glazed.length < segments.length;
+            const roles = [...(standard ? ROOF_ROLES : []), ...GLAZED_ROOF_SLOTS];
+            if (input.role !== undefined && !roles.includes(input.role))
+                refuse('unknown_role', `Roof ${id}'s roles are ${roles.join(', ')}.`, {
+                    target: id,
+                    roles,
+                });
+            const roofRole = input.role === undefined || ROOF_ROLES.includes(input.role);
+            return [...(standard && roofRole ? [id] : []), ...(roofRole && input.role ? [] : glazed)];
+        })),
+    ];
+    for (const id of targets) {
+        const node = current(id);
+        if (!node)
+            refuse('target_not_found', `Nothing to paint: ${id} is not in the scene (a room edit may have replaced its walls: read the scene again). Nothing was painted.`, { target: id });
+        if (node.type === 'roof' || (node.type === 'roof-segment' && !isGlazedRoofSegment(node))) {
+            const role = (input.role ?? 'top');
+            if (!ROOF_ROLES.includes(role))
+                refuse('unknown_role', `A roof's roles are ${ROOF_ROLES.join(', ')}.`, {
+                    target: id,
+                    roles: [...ROOF_ROLES],
+                });
+            const roof = node.type === 'roof' ? node : current(node.parentId ?? '');
+            if (roof?.type !== 'roof')
+                refuse('not_paintable', `Roof segment ${id} has no roof to paint.`, { target: id });
+            if (node.type === 'roof-segment')
+                throughRoof.push(id);
+            if (painted.some((entry) => entry.id === roof.id && entry.roles.includes(role)))
+                continue;
+            const segments = roof.children.flatMap((childId) => {
+                const segment = current(childId);
+                return segment?.type === 'roof-segment' ? [segment] : [];
+            });
+            if (role === 'fascia') {
+                // Each segment holds its fascia: the boards take it on every segment of the roof.
+                for (const segment of segments)
+                    written[segment.id] = paintRoleField(segment, role, ref);
+            }
+            else {
+                written[roof.id] = paintRoleField(roof, role, ref);
+                // The roof's finish shows on every segment: none keeps one of its own for the role.
+                for (const segment of segments)
+                    written[segment.id] = withoutOwnRole(segment, role);
+            }
+            painted.push({ id: roof.id, roles: [role] });
+            continue;
+        }
+        // A catalog item's surfaces are its model's (slot_<id> materials), which an operation cannot
+        // read: a host that has (assetViews) lets this name them; its role is written by name, as the
+        // editor's Paint writes the one clicked.
+        const declared = nodeSlotDeclarations(node);
+        if (!declared && node.type === 'item') {
+            const own = Object.keys(node.slots ?? {});
+            if (!input.role) {
+                const surfaces = context.assetViews?.[node.asset.id]?.surfaces ?? [];
+                const facts = [
+                    ...(surfaces.length ? [`its surfaces: ${surfaces.join(', ')}`] : []),
+                    ...(own.length ? [`painted so far: ${own.join(', ')}`] : []),
+                ];
+                refuse('unknown_role', `Item ${id}'s surfaces are its model's: name one as role${facts.length ? ` (${facts.join('; ')})` : ''}.`, { target: id, roles: surfaces.length ? [...surfaces] : own });
+            }
+            const slots = { ...(node.slots ?? {}) };
+            if (ref)
+                slots[input.role] = ref;
+            else
+                delete slots[input.role];
+            written[id] = { ...node, slots };
+            modelRoles.push(`${id} ${input.role}`);
+            painted.push({ id, roles: [input.role] });
+            continue;
+        }
+        if (!declared?.length)
+            refuse('not_paintable', `A ${node.type} has no surface paint gives: paint walls, slabs, ceilings, roofs, columns, fences, doors, windows, stairs, blocks, cabinets, shelves, items and the other built parts.`, { target: id, type: node.type });
+        const ids = declared.map((slot) => slot.slotId);
+        let roles;
+        // On a wall, exterior and interior are its faces' sides; elsewhere they are slots by name.
+        if (node.type === 'wall' && (input.role === 'exterior' || input.role === 'interior')) {
+            // A curtain wall has frame, glass and panels where a wall has faces.
+            if (!ids.includes('a'))
+                refuse('unknown_role', `A curtain wall has no ${input.role} face: its roles are ${ids.join(', ')}.`, { target: id, roles: ids });
+            roles = wallFacesTurned(scene(), node, input.role);
+            if (!roles.length)
+                refuse('side_unknown', `Wall ${id} has no ${input.role} face by its rooms or its stored sides: name its face, a or b.`, { target: id });
+        }
+        else if (node.type === 'wall' && WALL_TRIMS.includes(input.role)) {
+            // A trim named without a face is the trim on both faces, as a wall without a role is.
+            roles = ['a', 'b'].map((face) => getWallTrimSlotId(face, input.role));
+            if (!roles.every((role) => ids.includes(role)))
+                refuse('unknown_role', `A ${node.type}'s roles are ${ids.join(', ')}.`, {
+                    target: id,
+                    roles: ids,
+                });
+        }
+        else if (input.role) {
+            if (!ids.includes(input.role))
+                refuse('unknown_role', `A ${node.type}'s roles are ${ids.join(', ')}.`, {
+                    target: id,
+                    roles: ids,
+                });
+            roles = [input.role];
+        }
+        else
+            roles = defaultRoles(node.type, ids);
+        if (!roles.length)
+            refuse('unknown_role', `Name the ${node.type}'s surface: its roles are ${ids.join(', ')}.`, {
+                target: id,
+                roles: ids,
+            });
+        for (const role of roles) {
+            const target = current(id);
+            if (target.type === 'wall') {
+                const face = role === 'a' || role === 'b' ? role : null;
+                const scripted = face ? wallFaceScriptPaintRefusal(target, face) : undefined;
+                if (scripted)
+                    refuse('face_built_by_script', `${scripted.message} Nothing was painted.`, {
+                        target: id,
+                        face,
+                    });
+                Object.assign(written, face
+                    ? paintWallFace(scene(), target, face, ref)
+                    : planWallPaint(scene(), target, { kind: 'slot', slotId: role }, ref));
+                const parts = face && ref ? target.faceRegions?.filter((region) => region.face === face) : [];
+                if (parts?.length)
+                    keptParts.push(`${id} ${face}: ${parts.map((region) => region.id).join(', ')}`);
+                continue;
+            }
+            const next = { ...(target.slots ?? {}) };
+            if (ref)
+                next[role] = ref;
+            else
+                delete next[role];
+            written[id] = { ...target, slots: next };
+        }
+        painted.push({ id, roles });
+    }
+    const update = Object.entries(written).flatMap(([id, node]) => {
+        const data = changedData(nodes[id], node);
+        return Object.keys(data).length ? [{ id, data }] : [];
+    });
+    const createdMaterial = finish.created ? finish.sceneMaterial : undefined;
+    const note = [
+        finish.note,
+        throughRoof.length &&
+            `${throughRoof.join(', ')} ${throughRoof.length === 1 ? 'is a roof segment' : 'are roof segments'}: the finish went on the roof, which shows one finish per surface.`,
+        keptParts.length && `Painted parts keep their own finish (${keptParts.join('; ')}).`,
+        modelRoles.length &&
+            `${modelRoles.join(', ')}: an item's surfaces are its model's, so a role its model lacks does not show.`,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return {
+        result: {
+            ok: true,
+            painted,
+            finish: ref ?? 'default',
+            ...(finish.sceneMaterial
+                ? { materialId: finish.sceneMaterial.id, material: finish.sceneMaterial.material }
+                : {}),
+            ...(createdMaterial ? { createdMaterial } : {}),
+            ...(note ? { note } : {}),
+        },
+        changes: { update, ...(createdMaterial ? { materials: [createdMaterial] } : {}) },
+    };
+};

package/dist/agent-operations/photo-elevation.d.ts

@@ -0,0 +1,155 @@
+import { type Homography, type Vec3 } from '../building/photo-elevation.js';
+import type { SceneNodes } from './types.js';
+type Pt = [number, number];
+export type PhotoFaceInput = {
+    name?: string;
+    /** The walls of the face on one storey, end to end: their extent is the width. */
+    wallIds: string[];
+    /**
+     * Two points on each vertical edge of the face as seen, as fractions of the image. A face whose
+     * far edge leaves the photo gives only the corner it shares with another face of the call.
+     */
+    edges: {
+        left?: Pt[];
+        right?: Pt[];
+    };
+    /**
+     * The same feature on at least two storeys, two points along each, with its storey, and the
+     * feature's height above that floor when known (window heads 2.1 m): it sets the camera's height.
+     */
+    rows: {
+        levelId: string;
+        points: Pt[];
+        height?: number;
+    }[];
+    /** More horizontal lines on the face, two points each: they steady its vanishing point. */
+    lines?: Pt[][];
+    /**
+     * Points at known places on the face (window and door corners, eave ends): metres along it from
+     * its left end as seen, metres up from a floor (the face's, by default), and where the photo
+     * shows them. Each one steadies the pose.
+     */
+    points?: {
+        along: number;
+        height: number;
+        levelId?: string;
+        point: Pt;
+    }[];
+};
+export type PhotoElevationInput = {
+    faces: PhotoFaceInput[];
+    /**
+     * The camera's focal length on a 36 × 24 mm frame, when known: a frontal photo does not show
+     * it. A phone's main camera is about 26 mm.
+     */
+    focal35mm?: number;
+    /** More vertical lines anywhere on the building, two points each: they steady the camera's tilt. */
+    verticals?: Pt[][];
+};
+export type PhotoFacePlan = {
+    name: string;
+    widthMeters: number;
+    /**
+     * Metres along the face from its left end at the drawing's left and right sides: 0 and the
+     * width, unless the face runs out of the photo.
+     */
+    leftMeters: number;
+    rightMeters: number;
+    /** Metres above the lowest row's feature at the top and bottom of the drawing. */
+    topMeters: number;
+    bottomMeters: number;
+    pxPerMetre: number;
+    outWidth: number;
+    outHeight: number;
+    /** Drawing pixel to photo pixel. */
+    toSource: Homography;
+    /** Photo pixels per metre up each side of the drawing: few, and panes blur. */
+    sourcePxPerMetre: {
+        left: number;
+        right: number;
+    };
+    /** Root mean square of the picked points against the fit, in photo pixels. */
+    residualPx: number;
+    /** The picked feature on every storey the drawing shows, in drawing pixels. */
+    featureLines: {
+        levelId: string;
+        name: string;
+        y: number;
+    }[];
+    /** Where each row meets each edge in the photo, for a close-up to check. */
+    corners: {
+        edge: 'left' | 'right';
+        levelId: string;
+        point: Pt;
+        rowLine: [Pt, Pt];
+        edgeLine: [Pt, Pt];
+    }[];
+    /**
+     * Floor to floor between the rows' storeys, as the photo measures it and as the scene has it.
+     * Only with the camera: without it, the storeys are the drawing's vertical scale.
+     */
+    storeyHeight?: {
+        photo: number;
+        scene: number;
+    };
+    warnings: string[];
+};
+/** The camera several faces of the photo share. */
+export type PhotoCameraSummary = {
+    focalPx: number;
+    /** The focal length on a 36 × 24 mm frame: a phone's main camera is about 24–28 mm. */
+    focal35mm: number;
+    horizontalFovDeg: number;
+    /**
+     * Where the optical axis meets the photo, down from its top, in photo pixels: about half the
+     * photo's height for a phone photo as taken, near the horizon for a perspective-corrected one.
+     */
+    principalPointY: number;
+    /** The optical axis above the horizon (up is positive), and how far the photo is turned. */
+    pitchDeg: number;
+    rollDeg: number;
+    /** Camera from world, row-major: world x along the first face, y up, z out of it. */
+    rotation: number[];
+    /** The camera in the scene, for view_scene; null when the faces leave its side unknown. */
+    pose: PhotoPose | null;
+    assumptions: string;
+    warnings: string[];
+};
+/** Where the photo was taken from, in the scene's coordinates (y up), as view_scene takes it. */
+export type PhotoPose = {
+    projection: 'perspective';
+    position: Vec3;
+    target: Vec3;
+    /** The camera's up, which carries the photo's roll. */
+    up: Vec3;
+    /** Vertical field of view, degrees. */
+    fov: number;
+    /** The photo's width over its height. */
+    aspect: number;
+    /** How far below the photo's middle its optical axis meets it, as a share of its height. */
+    shift: number;
+    /** What set the camera's height: the rows' feature height, or the edges' foot taken for the ground. */
+    anchoredBy: 'row height' | 'edge base';
+    /** The focal length was taken (focal35mm, else a phone's), not read from the photo. */
+    focalAssumed: boolean;
+    /** The picked edges against the walls' ends projected through the pose, in photo pixels. */
+    edgeResidualPx: number;
+    /** How far the eye moves, in metres, when the picks move by their own error. */
+    spread?: number;
+};
+/**
+ * Plans the straightening of each face of a photo, pixels being the host's. Several faces, or one
+ * whose far edge leaves the photo, share the photo's one camera, found from the vanishing points
+ * of the picked lines: each face is then K·[along up origin], metric from its walls' width, and
+ * the storeys are measured. One face with both edges, or faces no camera fits, are each fitted
+ * from their own rows × edges, their heights from the storeys.
+ */
+export declare function planPhotoElevation(nodes: SceneNodes, input: PhotoElevationInput, image: {
+    width: number;
+    height: number;
+}): {
+    faces: PhotoFacePlan[];
+    camera: PhotoCameraSummary | null;
+};
+export {};
+//# sourceMappingURL=photo-elevation.d.ts.map

package/dist/agent-operations/photo-elevation.d.ts.map

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