hoi4-agent-tools 4.3.0 → 4.4.0

package/dist/hoi4_agent_tools/map/partition-geography.js

@@ -0,0 +1,113 @@
+import { ServiceError } from '../core/result.js';
+import { forEachPolylinePixel, rowStrips, scanAreaStrip, } from './geography/index.js';
+import { PARTITION_KIND } from './partition-fields.js';
+import { BARRIER_CREST, BARRIER_FORT_LINE, BARRIER_WALL, } from './relief/fields.js';
+/**
+ * Geography inputs of the partition (ADR 0058): the named regions and seas of the model become the
+ * `regionId` plane and the region table (with the density each asks for), and every range that
+ * declares itself a wall or an impassable barrier becomes a barrier line no province may straddle.
+ * Relief, rivers, fertility and terrain classes stay as the caller computed them.
+ */
+/** Pixels written by one range path per side: three pixels wide, so no 4-connected path crosses. */
+const WALL_HALF_WIDTH = 1;
+/**
+ * Return `fields` with `regionId`, `regions` and `barrier` taken from the resolved geography.
+ * Land regions are written on land pixels and named seas on sea pixels, so a lake is never part
+ * of a region by itself. Overlapping areas resolve in id order, later ids winning; ids are the
+ * 1-based position in the sorted list of regions that have an area, followed by the seas.
+ */
+export function partitionFieldsFromGeography(fields, geography, options = {}) {
+    const { width, height, kind } = fields;
+    const grid = { width, height };
+    const regionId = new Uint16Array(fields.regionId);
+    const barrier = new Uint8Array(fields.barrier);
+    const table = [];
+    const areas = [];
+    const seaAreas = [];
+    let next = 1;
+    for (const region of geography.regions) {
+        if (region.area === undefined)
+            continue;
+        const entry = { id: next, kind: 'land' };
+        if (region.name !== undefined)
+            entry.name = region.name;
+        if (region.provinceAreaPx !== undefined)
+            entry.provinceAreaPx = region.provinceAreaPx;
+        if (region.provincesPerState !== undefined)
+            entry.provincesPerState = region.provincesPerState;
+        table.push(entry);
+        areas.push({ id: next, area: region.area });
+        next += 1;
+    }
+    for (const sea of geography.seas) {
+        if (next > 65_535)
+            break;
+        const entry = { id: next, kind: 'sea' };
+        if (sea.name !== undefined)
+            entry.name = sea.name;
+        table.push(entry);
+        seaAreas.push({ id: next, area: sea.area });
+        next += 1;
+    }
+    for (const strip of rowStrips(grid, options.stripRows ?? 256)) {
+        for (const { id, area } of areas)
+            scanAreaStrip(area, grid, strip, (y, x0, x1) => {
+                const row = y * width;
+                for (let x = x0; x < x1; x++)
+                    if (kind[row + x] === PARTITION_KIND.land)
+                        regionId[row + x] = id;
+            });
+        for (const { id, area } of seaAreas)
+            scanAreaStrip(area, grid, strip, (y, x0, x1) => {
+                const row = y * width;
+                for (let x = x0; x < x1; x++)
+                    if (kind[row + x] === PARTITION_KIND.sea)
+                        regionId[row + x] = id;
+            });
+    }
+    const whole = { y0: 0, y1: height };
+    for (const range of geography.ranges) {
+        if (range.profile !== 'wall' && range.barrier !== 'impassable')
+            continue;
+        forEachPolylinePixel(range.path, grid, whole, (x, y) => {
+            for (let dy = -WALL_HALF_WIDTH; dy <= WALL_HALF_WIDTH; dy++)
+                for (let dx = -WALL_HALF_WIDTH; dx <= WALL_HALF_WIDTH; dx++) {
+                    if (Math.abs(dx) + Math.abs(dy) > WALL_HALF_WIDTH)
+                        continue;
+                    const yy = y + dy;
+                    if (yy < 0 || yy >= height)
+                        continue;
+                    barrier[yy * width + ((x + dx + width) % width)] = 255;
+                }
+        });
+    }
+    return { ...fields, regionId, barrier, regions: table };
+}
+/** Strength each model-drawn line of the terrain synthesis gives the partition's barrier plane. */
+const TERRAIN_LINE_STRENGTH = [
+    [BARRIER_WALL, 255],
+    [BARRIER_FORT_LINE, 180],
+    [BARRIER_CREST, 150],
+];
+/**
+ * Return `fields` with the lines the terrain synthesis drew from the model (ADR 0056) raised in
+ * its `barrier` plane: a wall outside its pass gaps at 255 (a hard line no province straddles), a
+ * fort line at 180 and a range crest at 150. Rivers and steep ground are left to the
+ * `riverDistance`, `slope` and `ridge` planes, which already carry them, so they do not count
+ * twice. A stronger value already in the plane is kept.
+ */
+export function partitionFieldsWithTerrainLines(fields, lines) {
+    const { width, height } = fields;
+    if (lines.width !== width || lines.height !== height)
+        throw new ServiceError('MAP_PARTITION_FIELDS_INVALID', 'The terrain barrier field does not match the partition dimensions', { width, height, barrier: { width: lines.width, height: lines.height } });
+    const barrier = new Uint8Array(fields.barrier);
+    for (let p = 0; p < barrier.length; p++) {
+        const sources = lines.sources[p];
+        if (sources === 0)
+            continue;
+        for (const [flag, strength] of TERRAIN_LINE_STRENGTH)
+            if ((sources & flag) !== 0 && strength > barrier[p])
+                barrier[p] = strength;
+    }
+    return { ...fields, barrier };
+}

package/dist/hoi4_agent_tools/map/partition-graph.js

@@ -0,0 +1,165 @@
+import { ServiceError } from '../core/result.js';
+/** Build the weighted graph in one pass over the province raster. */
+export function buildProvinceGraph(input) {
+    const { width, height, pixel, barrier } = input;
+    const count = input.kind.length;
+    if (pixel.length !== width * height)
+        throw new ServiceError('MAP_PARTITION_GRAPH_INVALID', 'The province raster does not match the map dimensions');
+    if (barrier !== undefined && barrier.length !== pixel.length)
+        throw new ServiceError('MAP_PARTITION_GRAPH_INVALID', 'The barrier plane does not match the map dimensions');
+    const index = new Map();
+    let capacity = 1 << 14;
+    let lengthList = new Uint32Array(capacity);
+    let sumList = new Float64Array(capacity);
+    let fromList = new Int32Array(capacity);
+    let toList = new Int32Array(capacity);
+    let edges = 0;
+    const add = (a, b, strength) => {
+        const low = a < b ? a : b;
+        const high = a < b ? b : a;
+        const key = low * 65_536 + high;
+        let slot = index.get(key);
+        if (slot === undefined) {
+            slot = edges++;
+            if (slot === capacity) {
+                capacity *= 2;
+                const l = new Uint32Array(capacity);
+                l.set(lengthList);
+                lengthList = l;
+                const s = new Float64Array(capacity);
+                s.set(sumList);
+                sumList = s;
+                const f = new Int32Array(capacity);
+                f.set(fromList);
+                fromList = f;
+                const t = new Int32Array(capacity);
+                t.set(toList);
+                toList = t;
+            }
+            fromList[slot] = low;
+            toList[slot] = high;
+            index.set(key, slot);
+        }
+        lengthList[slot]++;
+        sumList[slot] += strength;
+    };
+    if (count > 65_535)
+        throw new ServiceError('MAP_PARTITION_GRAPH_INVALID', 'The graph supports 65,535 provinces');
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            const p = row + x;
+            const id = pixel[p];
+            const east = x + 1 < width ? p + 1 : row;
+            const other = pixel[east];
+            if (other !== id)
+                add(id, other, barrier === undefined ? 0 : Math.max(barrier[p], barrier[east]));
+            if (y + 1 < height) {
+                const south = p + width;
+                const below = pixel[south];
+                if (below !== id)
+                    add(id, below, barrier === undefined ? 0 : Math.max(barrier[p], barrier[south]));
+            }
+        }
+    }
+    const degree = new Int32Array(count + 1);
+    for (let e = 0; e < edges; e++) {
+        degree[fromList[e] + 1]++;
+        degree[toList[e] + 1]++;
+    }
+    for (let i = 0; i < count; i++)
+        degree[i + 1] += degree[i];
+    const offsets = degree;
+    const cursor = Int32Array.from(offsets.subarray(0, count));
+    const to = new Int32Array(offsets[count]);
+    const length = new Uint32Array(offsets[count]);
+    const mean = new Float32Array(offsets[count]);
+    // Edges sorted by (low, high) keep every row ascending without a second sort.
+    const order = Array.from({ length: edges }, (_, i) => i).sort((a, b) => fromList[a] - fromList[b] || toList[a] - toList[b]);
+    for (const e of order) {
+        const a = fromList[e];
+        const b = toList[e];
+        const strength = sumList[e] / lengthList[e] / 255;
+        to[cursor[a]] = b;
+        length[cursor[a]] = lengthList[e];
+        mean[cursor[a]++] = strength;
+    }
+    for (const e of order) {
+        const a = fromList[e];
+        const b = toList[e];
+        const strength = sumList[e] / lengthList[e] / 255;
+        to[cursor[b]] = a;
+        length[cursor[b]] = lengthList[e];
+        mean[cursor[b]++] = strength;
+    }
+    // Rows now hold the high-numbered neighbours of each province, then the low-numbered ones.
+    sortRows(offsets, to, length, mean);
+    const kind = Uint8Array.from({ length: count }, (_, i) => input.kind[i]);
+    const size = Uint32Array.from({ length: count }, (_, i) => input.size[i]);
+    const centerX = new Float32Array(count);
+    const centerY = new Float32Array(count);
+    for (let i = 0; i < count; i++) {
+        const n = Math.max(1, size[i]);
+        centerX[i] = input.sumX[i] / n;
+        centerY[i] = input.sumY[i] / n;
+    }
+    return {
+        count,
+        kind,
+        offsets,
+        to,
+        length,
+        barrier: mean,
+        centerX,
+        centerY,
+        width,
+        height,
+        size,
+    };
+}
+function sortRows(offsets, to, length, barrier) {
+    for (let row = 0; row + 1 < offsets.length; row++) {
+        const start = offsets[row];
+        const end = offsets[row + 1];
+        // Insertion sort: rows hold a handful of neighbours.
+        for (let i = start + 1; i < end; i++) {
+            const t = to[i];
+            const l = length[i];
+            const b = barrier[i];
+            let j = i - 1;
+            while (j >= start && to[j] > t) {
+                to[j + 1] = to[j];
+                length[j + 1] = length[j];
+                barrier[j + 1] = barrier[j];
+                j--;
+            }
+            to[j + 1] = t;
+            length[j + 1] = l;
+            barrier[j + 1] = b;
+        }
+    }
+}
+/**
+ * Directed edge costs for growing territory over the graph: centroid distance (across the seam
+ * when shorter) times `1 + barrier * strength`, aligned with `graph.to`. Territory assignment
+ * runs its Dijkstra on these and may add its own terms.
+ */
+export function provinceEdgeCosts(graph, options = {}) {
+    const beta = options.barrier ?? 6;
+    const water = options.water ?? 3;
+    const cost = new Float32Array(graph.to.length);
+    for (let a = 0; a < graph.count; a++)
+        for (let e = graph.offsets[a]; e < graph.offsets[a + 1]; e++) {
+            const b = graph.to[e];
+            let dx = graph.centerX[a] - graph.centerX[b];
+            if (dx > graph.width / 2)
+                dx -= graph.width;
+            else if (dx < -graph.width / 2)
+                dx += graph.width;
+            const dy = graph.centerY[a] - graph.centerY[b];
+            const distance = Math.sqrt(dx * dx + dy * dy);
+            cost[e] =
+                distance * (1 + beta * graph.barrier[e]) * (graph.kind[a] === graph.kind[b] ? 1 : water);
+        }
+    return cost;
+}

package/dist/hoi4_agent_tools/map/partition-groups.js

@@ -0,0 +1,164 @@
+/** A binary max-heap keyed by score, then by the lower ids. */
+class CandidateHeap {
+    #items = [];
+    get size() {
+        return this.#items.length;
+    }
+    static #before(x, y) {
+        if (x.score !== y.score)
+            return x.score > y.score;
+        if (x.a !== y.a)
+            return x.a < y.a;
+        return x.b < y.b;
+    }
+    push(item) {
+        const items = this.#items;
+        let i = items.length;
+        items.push(item);
+        while (i > 0) {
+            const parent = (i - 1) >> 1;
+            if (!CandidateHeap.#before(items[i], items[parent]))
+                break;
+            [items[i], items[parent]] = [items[parent], items[i]];
+            i = parent;
+        }
+    }
+    pop() {
+        const items = this.#items;
+        if (items.length === 0)
+            return undefined;
+        const top = items[0];
+        const last = items.pop();
+        if (items.length > 0) {
+            items[0] = last;
+            let i = 0;
+            for (;;) {
+                const l = i * 2 + 1;
+                const r = l + 1;
+                let best = i;
+                if (l < items.length && CandidateHeap.#before(items[l], items[best]))
+                    best = l;
+                if (r < items.length && CandidateHeap.#before(items[r], items[best]))
+                    best = r;
+                if (best === i)
+                    break;
+                [items[i], items[best]] = [items[best], items[i]];
+                i = best;
+            }
+        }
+        return top;
+    }
+}
+/**
+ * Cluster `members` (province ids) over the graph. Returns the cluster of every member, numbered
+ * from 0 by the smallest member id of each cluster.
+ */
+export function clusterProvinces(members, graph, options, hooks = {}) {
+    const lambda = options.lambda ?? 12;
+    const hard = options.hardBarrier ?? 0.6;
+    const unlike = options.unlikeGround ?? 0.55;
+    const sorted = [...members].sort((a, b) => a - b);
+    const local = new Map(sorted.map((id, index) => [id, index]));
+    const n = sorted.length;
+    const sizeOf = new Int32Array(n).fill(1);
+    const perimeter = new Float64Array(n);
+    const version = new Int32Array(n);
+    const alive = new Uint8Array(n).fill(1);
+    const affinity = Array.from({ length: n }, () => new Map());
+    const shared = Array.from({ length: n }, () => new Map());
+    for (let i = 0; i < n; i++) {
+        const id = sorted[i];
+        for (let e = graph.offsets[id]; e < graph.offsets[id + 1]; e++) {
+            perimeter[i] += graph.length[e];
+            const other = local.get(graph.to[e]);
+            if (other === undefined || other === i)
+                continue;
+            if (hooks.group !== undefined && hooks.group(id) !== hooks.group(graph.to[e]))
+                continue;
+            const strength = graph.barrier[e];
+            const damp = 1 / ((1 + lambda * strength) * (1 + lambda * strength));
+            let weight = graph.length[e] * damp;
+            if (strength > hard)
+                weight *= 0.05;
+            if (hooks.label !== undefined && hooks.label(id) !== hooks.label(graph.to[e]))
+                weight *= unlike;
+            affinity[i].set(other, weight);
+            shared[i].set(other, graph.length[e]);
+        }
+    }
+    const heap = new CandidateHeap();
+    const scoreOf = (a, b) => {
+        const total = sizeOf[a] + sizeOf[b];
+        if (total > options.max)
+            return 0;
+        let factor = total <= options.target ? 1 : (options.max - total) / (options.max - options.target + 1);
+        const small = Math.min(sizeOf[a], sizeOf[b]) < options.min;
+        if (small)
+            factor = Math.max(factor, 0.05) * 2;
+        if (factor <= 0)
+            return 0;
+        const base = affinity[a].get(b);
+        return (base / Math.sqrt(Math.max(1, perimeter[a]) * Math.max(1, perimeter[b]))) * factor;
+    };
+    const offer = (a, b) => {
+        const low = Math.min(a, b);
+        const high = Math.max(a, b);
+        const score = scoreOf(low, high);
+        if (score > 0)
+            heap.push({ score, a: low, b: high, versionA: version[low], versionB: version[high] });
+    };
+    for (let i = 0; i < n; i++)
+        for (const other of affinity[i].keys())
+            if (other > i)
+                offer(i, other);
+    const parent = Int32Array.from({ length: n }, (_, i) => i);
+    for (let top = heap.pop(); top !== undefined; top = heap.pop()) {
+        const { a, b } = top;
+        if (!alive[a] || !alive[b] || version[a] !== top.versionA || version[b] !== top.versionB)
+            continue;
+        // Merge b into a. Only pairs that involve a change, so only a's version moves on.
+        const between = shared[a].get(b) ?? 0;
+        perimeter[a] = perimeter[a] + perimeter[b] - 2 * between;
+        sizeOf[a] += sizeOf[b];
+        alive[b] = 0;
+        parent[b] = a;
+        affinity[a].delete(b);
+        shared[a].delete(b);
+        for (const [c, weight] of affinity[b]) {
+            if (c === a)
+                continue;
+            const combined = (affinity[a].get(c) ?? 0) + weight;
+            const length = (shared[a].get(c) ?? 0) + (shared[b].get(c) ?? 0);
+            affinity[a].set(c, combined);
+            shared[a].set(c, length);
+            affinity[c].delete(b);
+            shared[c].delete(b);
+            affinity[c].set(a, combined);
+            shared[c].set(a, length);
+        }
+        affinity[b].clear();
+        shared[b].clear();
+        version[a]++;
+        for (const c of affinity[a].keys())
+            offer(a, c);
+    }
+    // Number clusters by their smallest member (members are sorted, so the first one seen).
+    const root = (i) => {
+        let r = i;
+        while (parent[r] !== r)
+            r = parent[r];
+        return r;
+    };
+    const dense = new Map();
+    const result = new Map();
+    for (let i = 0; i < n; i++) {
+        const r = root(i);
+        let id = dense.get(r);
+        if (id === undefined) {
+            id = dense.size;
+            dense.set(r, id);
+        }
+        result.set(sorted[i], id);
+    }
+    return result;
+}