osmWorkflow/scripts/lib/area-config.js

"use strict";

const fs = require("fs");
const path = require("path");
const { BUDGETS } = require("./stage-manifest");

function readAreaConfig(file, options = {}) {
  if (!fs.existsSync(file)) {
    throw new Error(`Config file not found: ${file}`);
  }
  return normalizeAreaConfig(JSON.parse(fs.readFileSync(file, "utf8")), options);
}

function normalizeAreaConfig(raw, options = {}) {
  const repoRoot = options.repoRoot || path.resolve(__dirname, "..", "..");
  const id = requireText(raw.id, "id");
  const input = path.resolve(requireText(raw.input, "input"));
  if (!fs.existsSync(input)) {
    throw new Error(`Input OSM XML not found: ${input}`);
  }

  const outputRoot = path.resolve(raw.outputRoot || path.join(repoRoot, "outputs"));
  const outputOverrides = raw.outputs || {};
  const areaDir = path.resolve(outputOverrides.areaDir || path.join(outputRoot, id));
  const fileStem = outputOverrides.fileStem || id;
  const compress = normalizeCompressConfig(raw.compress);
  const budget = normalizeBudgetConfig(raw.budget);
  const compressedFileStem = outputOverrides.compressedFileStem ||
    `${fileStem}-compressed-webp${compress.textureSize}${compress.meshopt ? "-meshopt" : ""}`;
  const pipelineDir = path.resolve(outputOverrides.pipelineDir || path.join(areaDir, "_pipeline"));
  const geojsonDir = path.resolve(outputOverrides.geojsonDir || path.join(areaDir, "osm2streets_web_out"));
  const outputs = {
    areaDir,
    geojsonDir,
    gpkg: path.resolve(outputOverrides.gpkg || path.join(areaDir, `${fileStem}.gpkg`)),
    qgisProject: path.resolve(outputOverrides.qgisProject || path.join(areaDir, `${fileStem}.qgz`)),
    qgisPreview: path.resolve(outputOverrides.qgisPreview || path.join(areaDir, `${fileStem}-preview.png`)),
    blend: path.resolve(outputOverrides.blend || path.join(areaDir, `${fileStem}.blend`)),
    render: path.resolve(outputOverrides.render || path.join(areaDir, `${fileStem}.png`)),
    glb: path.resolve(outputOverrides.glb || path.join(areaDir, `${fileStem}.glb`)),
    trafficSignalsDynamicGlb: path.resolve(
      outputOverrides.trafficSignalsDynamicGlb || path.join(areaDir, `${fileStem}-traffic-signals-dynamic.glb`),
    ),
    trafficSignalsCountdown0Glb: path.resolve(outputOverrides.trafficSignalsCountdown0Glb || path.join(areaDir, `${fileStem}-traffic-signals-countdown-0.glb`)),
    trafficSignalsCountdown1Glb: path.resolve(outputOverrides.trafficSignalsCountdown1Glb || path.join(areaDir, `${fileStem}-traffic-signals-countdown-1.glb`)),
    metadata: path.resolve(outputOverrides.metadata || path.join(areaDir, `${fileStem}.json`)),
    cesiumPreview: path.resolve(
      outputOverrides.cesiumPreview || path.join(areaDir, `${fileStem}-cesium-preview.html`),
    ),
    compressedGlb: path.resolve(
      outputOverrides.compressedGlb || path.join(areaDir, `${compressedFileStem}.glb`),
    ),
    compressedMetadata: path.resolve(
      outputOverrides.compressedMetadata || path.join(areaDir, `${compressedFileStem}.json`),
    ),
    compressedCesiumPreview: path.resolve(
      outputOverrides.compressedCesiumPreview || path.join(areaDir, `${compressedFileStem}-cesium-preview.html`),
    ),
    vehicleRoute: path.resolve(outputOverrides.vehicleRoute || path.join(areaDir, `${fileStem}-vehicle-route.json`)),
    vehicleModel: path.resolve(outputOverrides.vehicleModel || path.join(areaDir, `${fileStem}-vehicle-car.gltf`)),
    // Signals are an auxiliary intermediates artifact shared by Blender and
    // the browser preview. They deliberately are not one of the QGIS layers.
    trafficSignals: path.resolve(outputOverrides.trafficSignals || path.join(geojsonDir, "traffic_signals.json")),
    pipelineDir,
    stageManifestDir: path.resolve(outputOverrides.stageManifestDir || path.join(pipelineDir, "stages")),
  };

  return {
    id,
    input,
    outputRoot,
    qgisApp: raw.qgisApp || (process.platform === "darwin" ? "/Applications/QGIS.app" : "/usr"),
    blenderApp: raw.blenderApp || (process.platform === "darwin" ? "/Applications/Blender.app" : "/usr/bin/blender"),
    stages: {
      intermediates: raw.stages?.intermediates ?? raw.stages?.qgis ?? true,
      blender: raw.stages?.blender ?? true,
      cesium: raw.stages?.cesium ?? true,
      reimport: false,
      preview: false,
      compress: false,
    },
    qgis: {
      arrowScale: raw.qgis?.arrowScale ?? raw.arrowScale ?? 0.8,
      arrowMergeTriangles: raw.qgis?.arrowMergeTriangles ?? raw.arrowMergeTriangles ?? true,
      arrowOutlineSimplifyMeters: raw.qgis?.arrowOutlineSimplifyMeters ?? raw.arrowOutlineSimplifyMeters ?? 0.05,
      intersectionCornerSourceMaxDimensionMeters: raw.qgis?.intersectionCornerSourceMaxDimensionMeters ?? raw.intersectionCornerSourceMaxDimensionMeters ?? 2.6,
      clipPad: raw.qgis?.clipPad ?? raw.clipPad ?? 0.002,
      canvasPad: raw.qgis?.canvasPad ?? raw.canvasPad ?? 0.001,
      previewPad: raw.qgis?.previewPad ?? raw.previewPad ?? 0.0007,
      canvasExtent: raw.qgis?.canvasExtent ?? raw.canvasExtent ?? null,
      previewExtent: raw.qgis?.previewExtent ?? raw.previewExtent ?? null,
      layerPrefix: raw.qgis?.layerPrefix ?? raw.layerPrefix ?? "osm2streets",
    },
    turnLaneArrows: {
      enabled: booleanOption(raw.turnLaneArrows?.enabled, false, "turnLaneArrows.enabled"),
    },
    osm2streets: raw.osm2streets || {
      debug_each_step: false,
      dual_carriageway_experiment: false,
      sidepath_zipping_experiment: false,
      inferred_sidewalks: true,
      osm2lanes: true,
    },
    blender: {
      treeStyle: raw.blender?.treeStyle || "natural",
      officeOverrides: raw.blender?.officeOverrides || raw.blender?.office_overrides || "",
    },
    compress,
    budget,
    outputs,
  };
}

function normalizeBudgetConfig(raw) {
  if (raw !== undefined && raw !== null && (typeof raw !== "object" || Array.isArray(raw))) {
    throw new Error("budget must be an object");
  }
  const value = raw || {};
  const budget = {
    glbBytes: megabytesOption(value.glbSizeMb, BUDGETS.glbBytes, "budget.glbSizeMb"),
    glbNodes: integerOption(value.nodes, BUDGETS.glbNodes, "budget.nodes"),
    glbImages: integerOption(value.images, BUDGETS.glbImages, "budget.images"),
    glbTriangles: integerOption(value.triangles, BUDGETS.glbTriangles, "budget.triangles"),
    glbImageBytes: megabytesOption(value.embeddedImageBytesMb, BUDGETS.glbImageBytes, "budget.embeddedImageBytesMb"),
    reason: value.reason ?? "",
  };
  if (typeof budget.reason !== "string") {
    throw new Error("budget.reason must be a string");
  }
  const loosened = Object.keys(BUDGETS).some((key) => budget[key] > BUDGETS[key]);
  if (loosened && budget.reason.trim() === "") {
    throw new Error("budget.reason is required when a budget exceeds the default");
  }
  return budget;
}

function requireText(value, key) {
  if (typeof value !== "string" || value.trim() === "") {
    throw new Error(`Missing config key: ${key}`);
  }
  return value;
}

function normalizeCompressConfig(raw) {
  const value = raw || {};
  return {
    textureSize: numberOption(value.textureSize, 768, "compress.textureSize", 64, 4096),
    quality: numberOption(value.quality, 82, "compress.quality", 1, 100),
    effort: numberOption(value.effort, 80, "compress.effort", 0, 100),
    meshopt: booleanOption(value.meshopt, false, "compress.meshopt"),
  };
}

function numberOption(value, fallback, label, min, max) {
  const number = value === undefined ? fallback : Number(value);
  if (!Number.isFinite(number) || number < min || number > max) {
    throw new Error(`${label} must be a finite number in [${min}, ${max}]`);
  }
  return number;
}

function integerOption(value, fallback, label) {
  const number = value === undefined ? fallback : Number(value);
  if (!Number.isInteger(number) || number < 1) {
    throw new Error(`${label} must be a positive integer`);
  }
  return number;
}

function megabytesOption(value, fallbackBytes, label) {
  const megabytes = value === undefined ? fallbackBytes / 1024 / 1024 : Number(value);
  if (!Number.isFinite(megabytes) || megabytes <= 0) {
    throw new Error(`${label} must be a positive finite number`);
  }
  return Math.round(megabytes * 1024 * 1024);
}

function booleanOption(value, fallback, label) {
  if (value === undefined) return fallback;
  if (typeof value === "boolean") return value;
  if (value === "true") return true;
  if (value === "false") return false;
  throw new Error(`${label} must be boolean`);
}

module.exports = {
  normalizeAreaConfig,
  readAreaConfig,
};