hoi4-agent-tools 4.3.0 → 4.4.0

package/dist/hoi4_agent_tools/map/reference-import.js

@@ -0,0 +1,333 @@
+/**
+ * Evidence for an imported reference (ADR 0067): what each registered sheet supplied, the class
+ * shares of the interpreted picture and how far the geography model's land agrees with it.
+ * Disagreement above the threshold is an error diagnostic, which blocks the write but leaves the
+ * preview and its evidence available.
+ */
+import sharp from 'sharp';
+import { canonicalJson } from '../core/canonical.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { rasterizeGeographyKind } from './relief/land.js';
+import { REFERENCE_TERRAIN } from './reference-world.js';
+/** Conservative defaults: block only on a gross mismatch, warn on any visible one. */
+export const DEFAULT_IMPORT_AGREEMENT = {
+    minLandIou: 0.85,
+    warnLandIou: 0.95,
+};
+const CELL = 128;
+const WORST_CELLS = 12;
+const FEATURE_LIMIT = 64;
+/** A point this many pixels from the drawing's coast still counts as on either side. */
+const COAST_TOLERANCE_PX = 3;
+const TERRAIN_NAMES = Object.fromEntries(Object.entries(REFERENCE_TERRAIN).map(([name, index]) => [index, name]));
+function surfaceAt(surface, x, y) {
+    const px = Math.floor(x * surface.width);
+    const py = Math.floor(y * surface.height);
+    if (px < 0 || py < 0 || px >= surface.width || py >= surface.height)
+        return undefined;
+    return surface.kind[py * surface.width + px];
+}
+/** True when some pixel within the coast tolerance of the point has the wanted surface. */
+function nearSurface(surface, x, y, wanted) {
+    const cx = Math.floor(x * surface.width);
+    const cy = Math.floor(y * surface.height);
+    for (let dy = -COAST_TOLERANCE_PX; dy <= COAST_TOLERANCE_PX; dy += 1)
+        for (let dx = -COAST_TOLERANCE_PX; dx <= COAST_TOLERANCE_PX; dx += 1) {
+            const px = cx + dx;
+            const py = cy + dy;
+            if (px < 0 || py < 0 || px >= surface.width || py >= surface.height)
+                continue;
+            if (wanted(surface.kind[py * surface.width + px]))
+                return true;
+        }
+    return false;
+}
+function measureAgreement(surface, geography, seed, thresholds) {
+    const { width, height } = surface;
+    const model = rasterizeGeographyKind(geography, { width, height, seed });
+    const columns = Math.ceil(width / CELL);
+    const rows = Math.ceil(height / CELL);
+    const drawingOnlyCells = new Float64Array(columns * rows);
+    const modelOnlyCells = new Float64Array(columns * rows);
+    let drawingLand = 0;
+    let modelLand = 0;
+    let both = 0;
+    for (let y = 0; y < height; y += 1)
+        for (let x = 0; x < width; x += 1) {
+            const pixel = y * width + x;
+            const drawn = surface.kind[pixel] === 1;
+            const modelled = model[pixel] === 1;
+            if (drawn)
+                drawingLand += 1;
+            if (modelled)
+                modelLand += 1;
+            if (drawn && modelled)
+                both += 1;
+            else if (drawn || modelled) {
+                const cell = Math.floor(y / CELL) * columns + Math.floor(x / CELL);
+                if (drawn)
+                    drawingOnlyCells[cell] = drawingOnlyCells[cell] + 1;
+                else
+                    modelOnlyCells[cell] = modelOnlyCells[cell] + 1;
+            }
+        }
+    const union = drawingLand + modelLand - both;
+    const worstCells = Array.from({ length: columns * rows }, (_, cell) => cell)
+        .map((cell) => ({
+        x: (cell % columns) * CELL,
+        y: Math.floor(cell / columns) * CELL,
+        drawingOnly: drawingOnlyCells[cell],
+        modelOnly: modelOnlyCells[cell],
+    }))
+        .filter((cell) => cell.drawingOnly + cell.modelOnly > 0)
+        .sort((left, right) => right.drawingOnly + right.modelOnly - (left.drawingOnly + left.modelOnly) ||
+        left.y - right.y ||
+        left.x - right.x)
+        .slice(0, WORST_CELLS);
+    const features = [];
+    const isLand = (kind) => kind === 1;
+    const isWater = (kind) => kind !== 1;
+    for (const site of geography.sites) {
+        if (site.onWater || site.lakeId !== undefined)
+            continue;
+        if (!nearSurface(surface, site.at.x, site.at.y, isLand))
+            features.push({ id: site.id, kind: 'site', issue: 'in the drawing’s water', ...site.at });
+    }
+    for (const volcano of geography.volcanoes)
+        if (!nearSurface(surface, volcano.at.x, volcano.at.y, isLand))
+            features.push({
+                id: volcano.id,
+                kind: 'volcano',
+                issue: 'in the drawing’s water',
+                ...volcano.at,
+            });
+    for (const river of geography.rivers) {
+        const { source, mouth } = river;
+        if (source.type === 'point' && surfaceAt(surface, source.x, source.y) !== 1)
+            features.push({
+                id: river.id,
+                kind: 'river',
+                issue: 'source in the drawing’s water',
+                x: source.x,
+                y: source.y,
+            });
+        if (mouth.type === 'point' && !nearSurface(surface, mouth.x, mouth.y, isWater))
+            features.push({
+                id: river.id,
+                kind: 'river',
+                issue: 'mouth on the drawing’s land',
+                x: mouth.x,
+                y: mouth.y,
+            });
+    }
+    features.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+    return {
+        landIou: union === 0 ? 1 : Number((both / union).toFixed(4)),
+        drawingLandPx: drawingLand,
+        modelLandPx: modelLand,
+        bothLandPx: both,
+        drawingOnlyLandPx: drawingLand - both,
+        modelOnlyLandPx: modelLand - both,
+        thresholds,
+        worstCells,
+        features: features.slice(0, FEATURE_LIMIT),
+        featureCount: features.length,
+    };
+}
+export function buildImportReport(input) {
+    const { surface, operationId } = input;
+    const terrainPx = {};
+    let sea = 0;
+    let lake = 0;
+    let land = 0;
+    for (let pixel = 0; pixel < surface.kind.length; pixel += 1) {
+        const kind = surface.kind[pixel];
+        if (kind === 0)
+            sea += 1;
+        else if (kind === 2)
+            lake += 1;
+        else {
+            land += 1;
+            const name = TERRAIN_NAMES[surface.terrain[pixel]] ?? 'other';
+            terrainPx[name] = (terrainPx[name] ?? 0) + 1;
+        }
+    }
+    const thresholds = {
+        minLandIou: input.thresholds?.minLandIou ?? DEFAULT_IMPORT_AGREEMENT.minLandIou,
+        warnLandIou: input.thresholds?.warnLandIou ?? DEFAULT_IMPORT_AGREEMENT.warnLandIou,
+    };
+    const report = {
+        operationId,
+        width: surface.width,
+        height: surface.height,
+        ...(input.registration === undefined
+            ? {}
+            : {
+                registration: {
+                    sheets: input.registration.coverage,
+                    uncoveredPx: input.registration.uncovered,
+                },
+            }),
+        classes: { seaPx: sea, lakePx: lake, landPx: land, terrainPx },
+        ...(input.geography === undefined
+            ? {}
+            : { agreement: measureAgreement(surface, input.geography, input.seed, thresholds) }),
+    };
+    const diagnostics = [];
+    for (const sheet of input.registration?.coverage ?? [])
+        if (sheet.pixels === 0)
+            diagnostics.push({
+                code: 'MAP_REFERENCE_SHEET_HIDDEN',
+                severity: 'warning',
+                category: 'map',
+                operationId,
+                message: `Sheet ${sheet.id} supplies no world pixel: higher-order sheets cover it or it lies outside the frame`,
+                details: { sheetId: sheet.id, hiddenPx: sheet.hidden },
+            });
+    const agreement = report.agreement;
+    if (agreement !== undefined) {
+        const severity = agreement.landIou < thresholds.minLandIou
+            ? 'error'
+            : agreement.landIou < thresholds.warnLandIou
+                ? 'warning'
+                : 'info';
+        diagnostics.push({
+            code: severity === 'error' ? 'MAP_IMPORT_SOURCES_DISAGREE' : 'MAP_IMPORT_SOURCES_AGREEMENT',
+            severity,
+            category: 'map',
+            operationId,
+            message: `The geography model's land and the reference's land overlap with intersection over union ${agreement.landIou} (block below ${thresholds.minLandIou}, warn below ${thresholds.warnLandIou}); ${agreement.drawingOnlyLandPx} pixels are land only in the reference and ${agreement.modelOnlyLandPx} only in the model. map-import-report.json lists the worst areas and map-import-alignment.png draws both coasts.`,
+            details: {
+                landIou: agreement.landIou,
+                drawingOnlyLandPx: agreement.drawingOnlyLandPx,
+                modelOnlyLandPx: agreement.modelOnlyLandPx,
+                worstCells: agreement.worstCells.slice(0, 3),
+            },
+        });
+        if (agreement.featureCount > 0)
+            diagnostics.push({
+                code: 'MAP_IMPORT_FEATURE_SURFACE',
+                severity: 'warning',
+                category: 'map',
+                operationId,
+                message: `${agreement.featureCount} model features lie on the wrong surface of the reference (a site or volcano in its water, a river source in water or mouth on land); see map-import-report.json`,
+                details: { features: agreement.features.slice(0, 8) },
+            });
+    }
+    return { report, diagnostics };
+}
+const CLASS_COLOURS = {
+    0: [150, 200, 90],
+    1: [40, 120, 50],
+    2: [220, 205, 120],
+    3: [140, 120, 110],
+    4: [235, 240, 245],
+    5: [150, 40, 30],
+    6: [150, 120, 70],
+    7: [80, 130, 110],
+    8: [30, 90, 40],
+};
+/**
+ * Offline review drawings of the import, at most `maxSide` pixels per side: the classes, and the
+ * registered picture with the reference coast in red and the model coast in yellow. They are
+ * drawings of the tool's interpretation, never game images.
+ */
+export async function renderImportImages(input) {
+    const { surface } = input;
+    const { width, height } = surface;
+    const scale = Math.min(1, input.maxSide / Math.max(width, height));
+    const outWidth = Math.max(1, Math.round(width * scale));
+    const outHeight = Math.max(1, Math.round(height * scale));
+    const classes = Buffer.alloc(outWidth * outHeight * 3);
+    const alignment = Buffer.alloc(outWidth * outHeight * 3);
+    const registered = input.registered === undefined
+        ? undefined
+        : await sharp(input.registered)
+            .resize(outWidth, outHeight, { fit: 'fill' })
+            .removeAlpha()
+            .raw()
+            .toBuffer();
+    const model = input.geography === undefined
+        ? undefined
+        : rasterizeGeographyKind(input.geography, { width, height, seed: input.seed });
+    const landAt = (kind, x, y) => kind[Math.min(height - 1, y) * width + Math.min(width - 1, x)] === 1;
+    for (let oy = 0; oy < outHeight; oy += 1)
+        for (let ox = 0; ox < outWidth; ox += 1) {
+            const x = Math.min(width - 1, Math.floor(ox / scale));
+            const y = Math.min(height - 1, Math.floor(oy / scale));
+            const pixel = y * width + x;
+            const target = (oy * outWidth + ox) * 3;
+            const kind = surface.kind[pixel];
+            const colour = kind === 0
+                ? [30, 70, 160]
+                : kind === 2
+                    ? [70, 170, 230]
+                    : CLASS_COLOURS[surface.terrain[pixel]];
+            classes.set(colour, target);
+            const base = registered?.subarray(target, target + 3) ?? Buffer.from(colour);
+            alignment[target] = Math.round(base[0] * 0.6);
+            alignment[target + 1] = Math.round(base[1] * 0.6);
+            alignment[target + 2] = Math.round(base[2] * 0.6);
+            const step = Math.max(1, Math.ceil(1 / scale));
+            const coast = (raster) => landAt(raster, x, y) !== landAt(raster, x + step, y) ||
+                landAt(raster, x, y) !== landAt(raster, x, y + step);
+            if (model !== undefined && coast(model))
+                alignment.set([255, 220, 0], target);
+            if (coast(surface.kind))
+                alignment.set([255, 40, 40], target);
+        }
+    const encode = (data) => sharp(data, { raw: { width: outWidth, height: outHeight, channels: 3 } })
+        .png({ compressionLevel: 9 })
+        .toBuffer();
+    return { classes: await encode(classes), alignment: await encode(alignment) };
+}
+const IMPORT_IMAGE_MAX_SIDE = 2_048;
+export async function buildImportArtifacts(prepared, ordinal) {
+    const suffix = ordinal === 0 ? '' : `-${ordinal + 1}`;
+    const images = await renderImportImages({
+        surface: prepared.surface,
+        registered: prepared.registered,
+        ...(prepared.geography === undefined ? {} : { geography: prepared.geography }),
+        seed: prepared.seed,
+        maxSide: IMPORT_IMAGE_MAX_SIDE,
+    });
+    const provenance = {
+        kind: 'map-import',
+        toolVersion: PACKAGE_VERSION,
+        schemaVersion: 'map-import.v1',
+        sourceHashes: prepared.sourceHashes,
+        renderProfile: { offline: true, maxSide: IMPORT_IMAGE_MAX_SIDE },
+        metadata: {
+            operationId: prepared.report.operationId,
+            binding: 'offline drawing of the interpreted reference and the geography model; not a game screenshot',
+        },
+    };
+    const writes = [
+        {
+            name: `map-import-report${suffix}.json`,
+            mimeType: 'application/json',
+            content: `${canonicalJson(prepared.report)}\n`,
+            provenance,
+        },
+        {
+            name: `map-import-classes${suffix}.png`,
+            mimeType: 'image/png',
+            content: images.classes,
+            provenance,
+        },
+        {
+            name: `map-import-alignment${suffix}.png`,
+            mimeType: 'image/png',
+            content: images.alignment,
+            provenance,
+        },
+    ];
+    if (prepared.registered !== undefined)
+        writes.push({
+            name: `map-import-registration${suffix}.png`,
+            mimeType: 'image/png',
+            content: prepared.registered,
+            provenance,
+        });
+    return writes;
+}

package/dist/hoi4_agent_tools/map/reference-preparation.js

@@ -1,19 +1,116 @@
-import { readReferenceImageSource } from '../core/bounded-source.js';
+import sharp from 'sharp';
+import { readReferenceImageSource, } from '../core/bounded-source.js';
+import { readWorkspaceJsonSource } from '../core/workspace-json.js';
+import { REFERENCE_SHEETS_SOURCE_MAX_BYTES, referenceSheetsDocumentSchema, } from '../schemas/reference-sheets.js';
 import { extractReferenceLabels } from './reference-labels.js';
+import { registerSheets, sheetAffine, sheetWorkingSize, warpSheets, } from './reference-sheets.js';
 import { extractReferenceWorld } from './reference-world.js';
 import { ServiceError } from '../core/result.js';
+const PREVIEW_MAX_SIDE = 3_072;
+async function loadSheetsDocument(resolver, workspaceId, reference, principal, signal) {
+    if (reference.sheets !== undefined)
+        return { document: reference.sheets };
+    if (reference.sheetsPath === undefined)
+        return undefined;
+    const read = await readWorkspaceJsonSource(resolver, workspaceId, reference.sheetsPath, REFERENCE_SHEETS_SOURCE_MAX_BYTES, {
+        pathInvalid: 'MAP_REFERENCE_SHEETS_PATH_INVALID',
+        tooLarge: 'MAP_REFERENCE_SHEETS_TOO_LARGE',
+        jsonInvalid: 'MAP_REFERENCE_SHEETS_JSON_INVALID',
+        label: 'Sheet document',
+    }, principal, signal);
+    const parsed = referenceSheetsDocumentSchema.safeParse(read.value);
+    if (!parsed.success)
+        throw new ServiceError('MAP_REFERENCE_SHEETS_INVALID', `Sheet document does not match reference-sheets version 1: ${parsed.error.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; ')}`, {
+            issues: parsed.error.issues.slice(0, 20).map((issue) => ({
+                path: issue.path.join('.'),
+                message: issue.message,
+            })),
+        });
+    return { document: parsed.data, evidence: read.evidence };
+}
 /** Analyze only bounded, authorized sources; the transaction retains the original source hashes. */
 export async function prepareReferenceWorld(resolver, workspaceId, operation, principal, signal) {
     const reference = operation.reference;
     if (reference === undefined)
         throw new ServiceError('MAP_REFERENCE_REQUIRED', 'Reference preparation requires imagePath');
+    const sheetsSource = await loadSheetsDocument(resolver, workspaceId, reference, principal, signal);
+    const sheeted = sheetsSource !== undefined;
+    const frame = reference.fit === 'frame' || sheeted;
+    const exact = reference.paletteMatch === 'exact';
+    if (sheeted &&
+        (reference.crop !== undefined ||
+            reference.politicalImagePath !== undefined ||
+            reference.terrainImagePath !== undefined ||
+            reference.heightImagePath !== undefined))
+        throw new ServiceError('MAP_REFERENCE_SHEETS_UNSUPPORTED', 'A registered sheet picture cannot be combined with crop or aligned political, terrain or height pictures yet');
+    if (frame && (operation.width === undefined || operation.height === undefined))
+        throw new ServiceError('MAP_REFERENCE_FRAME_SIZE_REQUIRED', 'A reference fitted to the frame needs explicit width and height');
+    // A frame-fitted picture keeps the frame's resolution instead of the default 3,072-pixel
+    // working copy; an exact palette is never resampled between colours.
+    const frameSize = { width: operation.width ?? 0, height: operation.height ?? 0 };
+    // Each sheet keeps at least one working pixel per world pixel; the maps alone decide the size.
+    const working = sheeted
+        ? {
+            size: () => sheetWorkingSize(sheetsSource.document.sheets.map((sheet) => sheetAffine(sheet)), frameSize),
+            kernel: exact ? 'nearest' : 'area',
+        }
+        : frame
+            ? {
+                size: (originalWidth, originalHeight) => {
+                    const cropWidth = reference.crop?.width ?? originalWidth;
+                    const cropHeight = reference.crop?.height ?? originalHeight;
+                    return {
+                        width: Math.ceil((originalWidth * operation.width) / cropWidth),
+                        height: Math.ceil((originalHeight * operation.height) / cropHeight),
+                    };
+                },
+                kernel: exact ? 'nearest' : 'area',
+            }
+            : undefined;
     const images = [];
     const load = async (relativePath) => {
-        const image = await readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal);
+        const image = await readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal, working);
         images.push(image);
         return image;
     };
     const main = await load(reference.imagePath);
+    let warped;
+    let picture;
+    if (sheetsSource !== undefined) {
+        const sheets = registerSheets(sheetsSource.document, frameSize, {
+            width: main.originalWidth,
+            height: main.originalHeight,
+            sha256: main.source.sha256,
+        });
+        const raw = await sharp(main.bytes)
+            .flatten({ background: '#245b82' })
+            .removeAlpha()
+            .toColourspace('srgb')
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        signal?.throwIfAborted();
+        warped = warpSheets({ data: raw.data, width: raw.info.width, height: raw.info.height }, sheets, frameSize, {
+            fill: sheetsSource.document.fill,
+            sampling: exact ? 'nearest' : 'bilinear',
+            ...(signal === undefined ? {} : { signal }),
+        });
+        picture = { data: warped.rgb, width: warped.width, height: warped.height };
+    }
+    if (frame && !sheeted) {
+        const sourceAspect = (reference.crop?.width ?? main.originalWidth) /
+            (reference.crop?.height ?? main.originalHeight);
+        const frameAspect = operation.width / operation.height;
+        if (Math.abs(sourceAspect - frameAspect) > frameAspect * 0.01)
+            throw new ServiceError('MAP_REFERENCE_FRAME_ASPECT', `The reference (${reference.crop?.width ?? main.originalWidth} x ${reference.crop?.height ?? main.originalHeight}) does not have the frame's shape (${operation.width} x ${operation.height}); fitting it would distort the map. Crop or resize the picture, or use the default fit.`, {
+                sourceWidth: reference.crop?.width ?? main.originalWidth,
+                sourceHeight: reference.crop?.height ?? main.originalHeight,
+                width: operation.width,
+                height: operation.height,
+            });
+    }
     if (reference.crop !== undefined &&
         (reference.crop.x + reference.crop.width > main.originalWidth ||
             reference.crop.y + reference.crop.height > main.originalHeight))
@@ -31,7 +128,24 @@ export async function prepareReferenceWorld(resolver, workspaceId, operation, pr
             width: Math.max(1, Math.round((reference.crop.width * main.workingWidth) / main.originalWidth)),
             height: Math.max(1, Math.round((reference.crop.height * main.workingHeight) / main.originalHeight)),
         };
-    const text = await extractReferenceLabels(main.bytes);
+    // The registered picture, reduced, is what previews show and what text recognition reads.
+    const previewBytes = picture === undefined
+        ? undefined
+        : await sharp(picture.data, {
+            raw: { width: picture.width, height: picture.height, channels: 3 },
+        })
+            .resize({
+            width: PREVIEW_MAX_SIDE,
+            height: PREVIEW_MAX_SIDE,
+            fit: 'inside',
+            withoutEnlargement: true,
+        })
+            .png()
+            .toBuffer();
+    // Text recognition masks labels out of heuristic classification; an exact palette has none.
+    const text = exact
+        ? { labels: [], warnings: [] }
+        : await extractReferenceLabels(previewBytes ?? main.bytes);
     signal?.throwIfAborted();
     const textMasks = text.labels
         .slice(0, Math.max(0, 256 - (reference.ignoreMasks?.length ?? 0)))
@@ -45,7 +159,10 @@ export async function prepareReferenceWorld(resolver, workspaceId, operation, pr
             { x: left, y: bottom },
         ];
     });
-    const surface = await extractReferenceWorld(main.bytes, {
+    const uncovered = warped === undefined
+        ? undefined
+        : Uint8Array.from(warped.owner, (owner) => (owner === 255 ? 1 : 0));
+    const surface = await extractReferenceWorld(picture ?? main.bytes, {
         width: operation.width ?? 5_632,
         height: operation.height ?? 2_048,
         seed: operation.seed ?? 1,
@@ -57,6 +174,9 @@ export async function prepareReferenceWorld(resolver, workspaceId, operation, pr
             ? {}
             : { riverAnnotations: reference.riverAnnotations }),
         ...(reference.palette === undefined ? {} : { palette: reference.palette }),
+        ...(frame ? { fit: 'stretch' } : {}),
+        ...(exact ? { paletteMatch: 'exact' } : {}),
+        ...(uncovered === undefined ? {} : { uncovered }),
         ...(reference.coastDetail === undefined ? {} : { coastDetail: reference.coastDetail }),
         ...(political === undefined ? {} : { politicalImageBytes: political.bytes }),
         ...(terrain === undefined ? {} : { terrainImageBytes: terrain.bytes }),
@@ -104,7 +224,8 @@ export async function prepareReferenceWorld(resolver, workspaceId, operation, pr
         Math.min(surface.width, surface.height) * 0.025);
     // An explicit review is authoritative, including an empty list. OCR still helps mask ink,
     // but must not reintroduce discarded or uncertain names outside the supplied label set.
-    const automaticText = reference.labels === undefined ? text.labels : [];
+    // Names are never read from a registered drawing: its labels are the owner's to review.
+    const automaticText = reference.labels === undefined && !sheeted ? text.labels : [];
     const labels = automaticText
         .filter(({ text: label }) => !/\b(?:map|world|sea|ocean|bay|strait|channel|flow|belt|signature|north|south|east|west|compass)\b/iu.test(label))
         .slice(0, 200)
@@ -243,5 +364,17 @@ export async function prepareReferenceWorld(resolver, workspaceId, operation, pr
             diagnostics: [...new Set(warnings)],
         },
         images,
+        documents: sheetsSource?.evidence === undefined ? [] : [sheetsSource.evidence],
+        ...(previewBytes === undefined ? {} : { previewBytes }),
+        ...(warped === undefined
+            ? {}
+            : {
+                registration: {
+                    coverage: warped.coverage,
+                    uncovered: warped.uncovered,
+                    width: warped.width,
+                    height: warped.height,
+                },
+            }),
     };
 }