hoi4-agent-tools 4.3.0 → 4.5.0

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

@@ -0,0 +1,231 @@
+/**
+ * Registration of a picture made of drawn sheets onto the world frame (ADR 0067, step 2).
+ *
+ * Every sheet becomes one affine map from normalised picture coordinates to normalised world
+ * coordinates. Each world pixel is mapped back by the inverse of the highest-order sheet whose box
+ * (and clip) holds it and sampled from the working picture, so the result is one frame-aligned
+ * picture from which every map layer is derived. Only `+ - * /` are used, so results are the same
+ * on every platform.
+ */
+import { ServiceError } from '../core/result.js';
+const NONE = 255;
+const UNCOVERED_COLOUR = [0x24, 0x5b, 0x82];
+export function sheetAffine(sheet) {
+    if (sheet.affine !== undefined)
+        return sheet.affine;
+    const [anchorX, anchorY] = sheet.anchor;
+    const [targetX, targetY] = sheet.target;
+    const [scaleX, scaleY] = sheet.scale;
+    return [scaleX, 0, targetX - scaleX * anchorX, 0, scaleY, targetY - scaleY * anchorY];
+}
+export function invertAffine(affine) {
+    const [a, b, c, d, e, f] = affine;
+    const determinant = a * e - b * d;
+    if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-12)
+        return undefined;
+    const ia = e / determinant;
+    const ib = -b / determinant;
+    const id = -d / determinant;
+    const ie = a / determinant;
+    return [ia, ib, -(ia * c + ib * f), id, ie, -(id * c + ie * f)];
+}
+export function applyAffine(affine, x, y) {
+    return [affine[0] * x + affine[1] * y + affine[2], affine[3] * x + affine[4] * y + affine[5]];
+}
+/**
+ * Check a document against the picture and the frame and build each sheet's maps. Throws for a
+ * picture the registrations were not made for, a degenerate map or a sheet entirely outside the
+ * frame.
+ */
+export function registerSheets(document, frame, picture) {
+    if (document.source !== undefined &&
+        (document.source.width !== picture.width || document.source.height !== picture.height))
+        throw new ServiceError('MAP_REFERENCE_SHEETS_SOURCE_MISMATCH', `The sheet registrations were made for a ${document.source.width} x ${document.source.height} picture, but the reference is ${picture.width} x ${picture.height}`, {
+            expectedWidth: document.source.width,
+            expectedHeight: document.source.height,
+            width: picture.width,
+            height: picture.height,
+        });
+    if (document.source?.sha256 !== undefined && document.source.sha256 !== picture.sha256)
+        throw new ServiceError('MAP_REFERENCE_SHEETS_SOURCE_MISMATCH', 'The sheet registrations were made for a picture with another SHA-256', { expectedSha256: document.source.sha256, sha256: picture.sha256 });
+    return document.sheets.map((sheet, index) => {
+        const forward = sheetAffine(sheet);
+        const inverse = invertAffine(forward);
+        if (inverse === undefined)
+            throw new ServiceError('MAP_REFERENCE_SHEET_DEGENERATE', `Sheet ${sheet.id} maps its box onto a line or a point`, { sheetId: sheet.id });
+        const [left, top, right, bottom] = sheet.box;
+        const corners = [
+            applyAffine(forward, left, top),
+            applyAffine(forward, right, top),
+            applyAffine(forward, left, bottom),
+            applyAffine(forward, right, bottom),
+        ];
+        const minX = Math.min(...corners.map(([x]) => x));
+        const maxX = Math.max(...corners.map(([x]) => x));
+        const minY = Math.min(...corners.map(([, y]) => y));
+        const maxY = Math.max(...corners.map(([, y]) => y));
+        if (maxX <= 0 || minX >= 1 || maxY <= 0 || minY >= 1)
+            throw new ServiceError('MAP_REFERENCE_SHEET_OUTSIDE', `Sheet ${sheet.id} lies entirely outside the world frame`, { sheetId: sheet.id, bounds: { left: minX, top: minY, right: maxX, bottom: maxY } });
+        const clip = sheet.clip === undefined
+            ? undefined
+            : Float64Array.from(sheet.clip.flatMap(([x, y]) => [x, y]));
+        return {
+            id: sheet.id,
+            order: sheet.order,
+            index,
+            forward,
+            inverse,
+            box: sheet.box,
+            ...(clip === undefined ? {} : { clip }),
+            pixels: {
+                minX: Math.max(0, Math.floor(minX * frame.width)),
+                minY: Math.max(0, Math.floor(minY * frame.height)),
+                maxX: Math.min(frame.width - 1, Math.ceil(maxX * frame.width) - 1),
+                maxY: Math.min(frame.height - 1, Math.ceil(maxY * frame.height) - 1),
+            },
+        };
+    });
+}
+/**
+ * Working picture size at which every sheet still has at least one working pixel per world
+ * pixel: the longest world distance one picture unit travels along each picture axis.
+ */
+export function sheetWorkingSize(forwards, frame) {
+    let width = 1;
+    let height = 1;
+    for (const forward of forwards) {
+        const [a, b, , d, e] = forward;
+        width = Math.max(width, Math.sqrt((a * frame.width) ** 2 + (d * frame.height) ** 2));
+        height = Math.max(height, Math.sqrt((b * frame.width) ** 2 + (e * frame.height) ** 2));
+    }
+    return { width: Math.ceil(width), height: Math.ceil(height) };
+}
+function insideSheet(sheet, x, y) {
+    const [left, top, right, bottom] = sheet.box;
+    if (x < left || x >= right || y < top || y >= bottom)
+        return false;
+    const clip = sheet.clip;
+    if (clip === undefined)
+        return true;
+    let inside = false;
+    for (let index = 0, previous = clip.length - 2; index < clip.length; previous = index, index += 2) {
+        const ax = clip[index];
+        const ay = clip[index + 1];
+        const bx = clip[previous];
+        const by = clip[previous + 1];
+        if (ay > y !== by > y && x < ((bx - ax) * (y - ay)) / (by - ay) + ax)
+            inside = !inside;
+    }
+    return inside;
+}
+/**
+ * Warp the working picture (raw RGB) into the frame. `nearest` sampling keeps the colours of an
+ * indexed picture; `bilinear` blends neighbours for drawings. Throws when two sheets of equal
+ * order both cover a world pixel, and when `fill` is `error` and a world pixel has no sheet.
+ */
+export function warpSheets(picture, sheets, frame, options) {
+    const { width, height } = frame;
+    if (sheets.length > NONE)
+        throw new ServiceError('MAP_REFERENCE_SHEETS_LIMIT', 'Too many sheets');
+    const rgb = Buffer.alloc(width * height * 3);
+    const owner = new Uint8Array(width * height).fill(NONE);
+    const ordered = [...sheets].sort((left, right) => right.order - left.order || left.index - right.index);
+    const taken = new Float64Array(sheets.length);
+    const hidden = new Float64Array(sheets.length);
+    let ties = 0;
+    let tieSample;
+    const pictureWidth = picture.width;
+    const pictureHeight = picture.height;
+    const data = picture.data;
+    for (let y = 0; y < height; y += 1) {
+        if ((y & 63) === 0)
+            options.signal?.throwIfAborted();
+        const worldY = (y + 0.5) / height;
+        for (const sheet of ordered) {
+            const { minX, maxX, minY, maxY } = sheet.pixels;
+            if (y < minY || y > maxY)
+                continue;
+            const [ia, ib, ic, id, ie, iff] = sheet.inverse;
+            for (let x = minX; x <= maxX; x += 1) {
+                const worldX = (x + 0.5) / width;
+                const pictureX = ia * worldX + ib * worldY + ic;
+                const pictureY = id * worldX + ie * worldY + iff;
+                if (!insideSheet(sheet, pictureX, pictureY))
+                    continue;
+                const pixel = y * width + x;
+                const current = owner[pixel];
+                if (current !== NONE) {
+                    hidden[sheet.index] = hidden[sheet.index] + 1;
+                    if (sheets[current].order === sheet.order) {
+                        ties += 1;
+                        tieSample ??= { x, y, sheets: [sheets[current].id, sheet.id] };
+                    }
+                    continue;
+                }
+                owner[pixel] = sheet.index;
+                taken[sheet.index] = taken[sheet.index] + 1;
+                const sourceX = pictureX * pictureWidth - 0.5;
+                const sourceY = pictureY * pictureHeight - 0.5;
+                const target = pixel * 3;
+                if (options.sampling === 'nearest') {
+                    const column = Math.min(pictureWidth - 1, Math.max(0, Math.round(sourceX)));
+                    const row = Math.min(pictureHeight - 1, Math.max(0, Math.round(sourceY)));
+                    const source = (row * pictureWidth + column) * 3;
+                    rgb[target] = data[source];
+                    rgb[target + 1] = data[source + 1];
+                    rgb[target + 2] = data[source + 2];
+                }
+                else {
+                    const left = Math.min(pictureWidth - 1, Math.max(0, Math.floor(sourceX)));
+                    const top = Math.min(pictureHeight - 1, Math.max(0, Math.floor(sourceY)));
+                    const right = Math.min(pictureWidth - 1, left + 1);
+                    const bottom = Math.min(pictureHeight - 1, top + 1);
+                    const fx = Math.min(1, Math.max(0, sourceX - left));
+                    const fy = Math.min(1, Math.max(0, sourceY - top));
+                    const p00 = (top * pictureWidth + left) * 3;
+                    const p10 = (top * pictureWidth + right) * 3;
+                    const p01 = (bottom * pictureWidth + left) * 3;
+                    const p11 = (bottom * pictureWidth + right) * 3;
+                    for (let channel = 0; channel < 3; channel += 1) {
+                        const upper = data[p00 + channel] + (data[p10 + channel] - data[p00 + channel]) * fx;
+                        const lower = data[p01 + channel] + (data[p11 + channel] - data[p01 + channel]) * fx;
+                        rgb[target + channel] = Math.round(upper + (lower - upper) * fy);
+                    }
+                }
+            }
+        }
+    }
+    if (ties > 0)
+        throw new ServiceError('MAP_REFERENCE_SHEETS_OVERLAP_ORDER', `${ties} world pixels are covered by two sheets of the same order (first at ${tieSample.x}, ${tieSample.y}: ${tieSample.sheets.join(' and ')}); give one of them a higher order or clip it`, { pixels: ties, sample: tieSample });
+    let uncovered = 0;
+    let uncoveredSample;
+    for (let pixel = 0; pixel < owner.length; pixel += 1)
+        if (owner[pixel] === NONE) {
+            uncovered += 1;
+            uncoveredSample ??= { x: pixel % width, y: Math.floor(pixel / width) };
+            // The open-sea colour every heuristic mode reads as water, so no ink appears at sheet edges.
+            rgb.set(UNCOVERED_COLOUR, pixel * 3);
+        }
+    if (uncovered > 0 && options.fill === 'error')
+        throw new ServiceError('MAP_REFERENCE_SHEETS_UNCOVERED', `${uncovered} world pixels lie outside every sheet (first at ${uncoveredSample.x}, ${uncoveredSample.y}); add a sheet or set fill to "sea"`, { pixels: uncovered, sample: uncoveredSample });
+    const coverage = sheets.map((sheet) => {
+        const [left, top, right, bottom] = sheet.box;
+        const corners = [
+            applyAffine(sheet.forward, left, top),
+            applyAffine(sheet.forward, right, bottom),
+        ];
+        return {
+            id: sheet.id,
+            order: sheet.order,
+            pixels: taken[sheet.index],
+            hidden: hidden[sheet.index],
+            bounds: {
+                left: Math.min(corners[0][0], corners[1][0]),
+                top: Math.min(corners[0][1], corners[1][1]),
+                right: Math.max(corners[0][0], corners[1][0]),
+                bottom: Math.max(corners[0][1], corners[1][1]),
+            },
+        };
+    });
+    return { width, height, rgb, owner, coverage, uncovered };
+}

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

@@ -75,12 +75,22 @@ export const referenceWorldOptionsSchema = z
         .optional(),
     coastDetail: z.number().min(0).max(1).optional(),
     fit: z.enum(['contain', 'stretch']).optional(),
+    paletteMatch: z.enum(['nearest', 'exact']).optional(),
+    uncovered: bytesSchema.optional(),
     politicalImageBytes: bytesSchema.optional(),
     terrainImageBytes: bytesSchema.optional(),
     heightImageBytes: bytesSchema.optional(),
 })
     .strict();
 async function decode(bytes) {
+    if (!(bytes instanceof Uint8Array)) {
+        if (bytes.width < 1 ||
+            bytes.height < 1 ||
+            bytes.width * bytes.height > REFERENCE_IMAGE_PIXEL_LIMIT ||
+            bytes.data.length !== bytes.width * bytes.height * 3)
+            throw new ServiceError('MAP_REFERENCE_IMAGE_BLOCKED', 'Reference image exceeds the bounded decode limit');
+        return bytes;
+    }
     if (bytes.byteLength === 0 || bytes.byteLength > REFERENCE_IMAGE_BYTE_LIMIT)
         throw new ServiceError('MAP_REFERENCE_IMAGE_BLOCKED', 'Reference image bytes exceed the bounded decode limit');
     try {
@@ -173,6 +183,54 @@ function classify(color, mode, palette) {
         return semanticCode('hills');
     return 3;
 }
+const UNKNOWN_COLOR_LIMIT = 16;
+const UNKNOWN_COLOR_SAMPLES = 5;
+/** Classify by exact palette colour; report every other colour with counts and positions. */
+function exactCodes(data, width, height, palette, toSource, uncovered) {
+    const known = new Map();
+    for (const entry of palette) {
+        const key = (entry.color.r << 16) | (entry.color.g << 8) | entry.color.b;
+        const code = semanticCode(entry.kind);
+        if (known.has(key) && known.get(key) !== code)
+            throw new ServiceError('MAP_REFERENCE_PALETTE_CONFLICT', 'One palette colour is given two different kinds', { color: [entry.color.r, entry.color.g, entry.color.b] });
+        known.set(key, code);
+    }
+    const codes = new Uint8Array(width * height);
+    const unknown = new Map();
+    let unknownPixels = 0;
+    for (let pixel = 0; pixel < codes.length; pixel += 1) {
+        // Pixels outside every registered sheet are open sea whatever colour stands there.
+        if (uncovered?.[pixel])
+            continue;
+        const key = (data[pixel * 3] << 16) | (data[pixel * 3 + 1] << 8) | data[pixel * 3 + 2];
+        const code = known.get(key);
+        if (code !== undefined) {
+            codes[pixel] = code;
+            continue;
+        }
+        unknownPixels += 1;
+        let entry = unknown.get(key);
+        if (entry === undefined) {
+            entry = { count: 0, samples: [] };
+            unknown.set(key, entry);
+        }
+        entry.count += 1;
+        if (entry.samples.length < UNKNOWN_COLOR_SAMPLES)
+            entry.samples.push(toSource(pixel % width, Math.floor(pixel / width)));
+    }
+    if (unknownPixels > 0) {
+        const colors = [...unknown.entries()]
+            .sort(([leftKey, left], [rightKey, right]) => right.count - left.count || leftKey - rightKey)
+            .slice(0, UNKNOWN_COLOR_LIMIT)
+            .map(([key, { count, samples }]) => ({
+            color: [key >> 16, (key >> 8) & 255, key & 255],
+            count,
+            samples,
+        }));
+        throw new ServiceError('MAP_REFERENCE_PALETTE_UNKNOWN_COLOR', `${unknownPixels} reference pixels in ${unknown.size} colours match no palette entry; add the colours to the palette or repaint them. Samples are source pixel coordinates.`, { unknownPixels, unknownColors: unknown.size, colors });
+    }
+    return codes;
+}
 function fillUnknown(codes, width, height) {
     if (!codes.includes(255))
         return;
@@ -329,6 +387,9 @@ export async function extractReferenceWorld(imageBytes, input) {
     const height = options.height ?? 2048;
     if (width * height > REFERENCE_WORLD_PIXEL_LIMIT)
         throw new ServiceError('MAP_REFERENCE_PIXELS_BLOCKED', 'Reference output exceeds the pixel budget');
+    const exact = options.paletteMatch === 'exact';
+    if (exact && (options.palette?.length ?? 0) === 0)
+        throw new ServiceError('MAP_REFERENCE_PALETTE_REQUIRED', 'Exact palette matching needs a palette that lists every colour of the picture');
     const scale = options.fit === 'stretch' ? 1 : Math.min(width / crop.width, height / crop.height);
     const bounds = options.fit === 'stretch'
         ? { x: 0, y: 0, width, height }
@@ -345,14 +406,27 @@ export async function extractReferenceWorld(imageBytes, input) {
         .resize(bounds.width, bounds.height, { kernel: sharp.kernel.nearest })
         .raw()
         .toBuffer();
-    const mode = options.mode === undefined || options.mode === 'auto' ? modeFor(resized) : options.mode;
+    const mode = exact
+        ? 'political'
+        : options.mode === undefined || options.mode === 'auto'
+            ? modeFor(resized)
+            : options.mode;
     const diagnostics = [
-        `Reference interpretation uses ${mode} visual heuristics; illustrated labels and ambiguous biomes may need semantic overrides.`,
+        exact
+            ? 'Reference interpretation matches every pixel to the exact palette; no visual heuristics are applied.'
+            : `Reference interpretation uses ${mode} visual heuristics; illustrated labels and ambiguous biomes may need semantic overrides.`,
     ];
     const codes = new Uint8Array(width * height);
-    const localCodes = mode === 'sketch' || mode === 'grayscale'
-        ? grayscaleCodes(resized, bounds.width, bounds.height, mode)
-        : undefined;
+    // Unknown-colour samples name the source pixel, so the picture can be repainted there.
+    const toSource = (x, y) => ({
+        x: Math.min(source.width - 1, crop.x + Math.floor(((x + 0.5) * crop.width) / bounds.width)),
+        y: Math.min(source.height - 1, crop.y + Math.floor(((y + 0.5) * crop.height) / bounds.height)),
+    });
+    const localCodes = exact
+        ? exactCodes(resized, bounds.width, bounds.height, options.palette ?? [], toSource, options.uncovered?.length === bounds.width * bounds.height ? options.uncovered : undefined)
+        : mode === 'sketch' || mode === 'grayscale'
+            ? grayscaleCodes(resized, bounds.width, bounds.height, mode)
+            : undefined;
     for (let y = 0; y < bounds.height; y += 1)
         for (let x = 0; x < bounds.width; x += 1) {
             const local = y * bounds.width + x;
@@ -360,9 +434,9 @@ export async function extractReferenceWorld(imageBytes, input) {
             codes[target] =
                 localCodes?.[local] ?? classify(pixelColor(resized, local), mode, options.palette ?? []);
         }
-    if (mode === 'illustrated' || mode === 'satellite')
+    if (!exact && (mode === 'illustrated' || mode === 'satellite'))
         cleanWaterTexture(codes, resized, width, bounds, options.coastDetail ?? 1, diagnostics);
-    if (mode !== 'sketch' && mode !== 'grayscale')
+    if (!exact && mode !== 'sketch' && mode !== 'grayscale')
         maskOceanText(codes, resized, width, bounds, diagnostics);
     const transform = (point) => ({
         x: bounds.x + ((point.x * source.width - crop.x) / crop.width) * bounds.width,
@@ -376,8 +450,22 @@ export async function extractReferenceWorld(imageBytes, input) {
         throw new ServiceError('MAP_REFERENCE_MASK_WORK_BLOCKED', 'Reference polygon controls exceed the bounded scanline work budget');
     for (const mask of options.ignoreMasks ?? [])
         polygon(codes, width, height, mask.map(transform), 255);
+    const uncovered = options.uncovered;
+    if (uncovered !== undefined && uncovered.length !== codes.length)
+        throw new ServiceError('MAP_REFERENCE_OPTIONS_INVALID', 'The uncovered mask must have the frame size');
+    // Open sea outside every sheet is decided, not inferred: no mask fill, cleanup or smoothing moves it.
+    if (uncovered !== undefined)
+        for (let pixel = 0; pixel < codes.length; pixel += 1)
+            if (uncovered[pixel])
+                codes[pixel] = 0;
     fillUnknown(codes, width, height);
-    const protectedFeatures = (options.annotations?.length ?? 0) > 0 ? new Uint8Array(codes.length) : undefined;
+    const protectedFeatures = (options.annotations?.length ?? 0) > 0 || uncovered !== undefined
+        ? new Uint8Array(codes.length)
+        : undefined;
+    if (protectedFeatures !== undefined && uncovered !== undefined)
+        for (let pixel = 0; pixel < codes.length; pixel += 1)
+            if (uncovered[pixel])
+                protectedFeatures[pixel] = 1;
     for (const annotation of options.annotations ?? []) {
         polygon(codes, width, height, annotation.polygon.map(transform), semanticCode(annotation.kind));
         if (protectedFeatures)
@@ -394,7 +482,7 @@ export async function extractReferenceWorld(imageBytes, input) {
         throw new ServiceError('MAP_REFERENCE_RIVER_COMPLEXITY', 'Annotated rivers exceed the bounded point budget');
     const rivers = (options.riverAnnotations ?? []).flatMap((points) => clipRiver(points.map(transform).map((point) => ({ x: point.x - bounds.x, y: point.y - bounds.y })), bounds.width, bounds.height).map((path) => path.map((point) => ({ x: point.x + bounds.x, y: point.y + bounds.y }))));
     traceCoastalRivers(kind, width, height, rivers, diagnostics);
-    normalizeWater(kind, width, height, rivers, diagnostics);
+    normalizeWater(kind, width, height, rivers, diagnostics, !exact);
     cleanSmallComponents(kind, width, height, protectedFeatures, diagnostics);
     repairCorners(kind, width, height, diagnostics);
     // Corner repairs can detach an inlet from the ocean. Recheck sea fragments as well as
@@ -404,7 +492,7 @@ export async function extractReferenceWorld(imageBytes, input) {
             break;
         repairCorners(kind, width, height, diagnostics);
     }
-    if (mode === 'illustrated')
+    if (!exact && mode === 'illustrated')
         smoothIllustratedTerrain(terrain, kind, width, height, protectedFeatures, diagnostics);
     const elevation = new Float32Array(codes.length);
     const moisture = new Float32Array(codes.length);
@@ -428,7 +516,8 @@ export async function extractReferenceWorld(imageBytes, input) {
         inferredCountries: [],
         diagnostics,
     };
-    inferCountries(result, resized, mode);
+    if (!exact)
+        inferCountries(result, resized, mode);
     await applyLayers(result, input, crop);
     normalizeElevation(result, options.seed, options.heightImageBytes !== undefined);
     return result;
@@ -915,7 +1004,7 @@ function connectedPath(pixels, width, height) {
         throw new ServiceError('MAP_REFERENCE_RIVER_COMPLEXITY', 'Visible river path exceeds the bounded trace length; use a smaller reference output');
     return path;
 }
-function normalizeWater(kind, width, height, rivers, diagnostics) {
+function normalizeWater(kind, width, height, rivers, diagnostics, thinWaterToRivers = true) {
     const visited = new Uint8Array(kind.length);
     const queue = new Int32Array(kind.length);
     let lakeCount = 0;
@@ -953,7 +1042,9 @@ function normalizeWater(kind, width, height, rivers, diagnostics) {
         const spanX = maxX - minX + 1;
         const spanY = maxY - minY + 1;
         const thin = tail / Math.max(spanX, spanY) <= Math.max(2, Math.min(width, height) / 350);
-        if (thin && Math.max(spanX, spanY) >= Math.max(5, Math.min(width, height) / 100)) {
+        if (thinWaterToRivers &&
+            thin &&
+            Math.max(spanX, spanY) >= Math.max(5, Math.min(width, height) / 100)) {
             const points = connectedPath(queue.subarray(0, tail), width, height);
             for (let index = 0; index < tail; index += 1)
                 kind[queue[index]] = 1;