zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/web/src/core/acoustics.js

@@ -0,0 +1,341 @@
+// @ts-check
+// 3D urban acoustic and environmental noise propagation module
+// (ISO 9613-2 / CNOSSOS-EU inspired with Maekawa barrier diffraction).
+
+import { sampleRoadLines, streetCentrelines } from './road_sources.js';
+
+/**
+ * Compute Maekawa barrier diffraction attenuation in dB (0..20 dB, the ISO 9613-2 cap for single diffraction).
+ * @param {number} pathDiffMetres path difference delta in metres (<= 0 if unobstructed)
+ * @param {number} [freqHz] frequency in Hz (default 500 Hz)
+ * @returns {number} attenuation in dB (0..20)
+ */
+export function maekawaDiffraction(pathDiffMetres, freqHz = 500) {
+  if (!(pathDiffMetres > 0)) return 0;
+  const lambda = 343 / Math.max(20, freqHz);
+  const N = (2 / lambda) * pathDiffMetres;
+  if (N <= -0.05) return 0;
+  const val = 10 * Math.log10(Math.max(1, 3 + 20 * Math.max(0, N)));
+  return Math.min(20, Math.max(0, val));
+}
+
+export const NOISE_CLASSES = [
+  { min: 0, max: 55, label: 'Quiet', color: '#2b83ba' },
+  { min: 55, max: 65, label: 'Moderate', color: '#abdda4' },
+  { min: 65, max: 70, label: 'Loud', color: '#fdae61' },
+  { min: 70, max: Infinity, label: 'High noise', color: '#d7191c' }
+];
+
+/**
+ * Categorize a noise level value in dB(A).
+ * @param {number} dba
+ * @returns {{ min: number, max: number, label: string, color: string } | null}
+ */
+export function noiseClass(dba) {
+  if (!Number.isFinite(dba)) return null;
+  return NOISE_CLASSES.find((c) => dba < c.max) || NOISE_CLASSES[NOISE_CLASSES.length - 1];
+}
+
+/**
+ * Road noise sources: the given roads sampled every max(3 m, 1.5 cells), or
+ * street centrelines between buildings when there are none, or the south
+ * edge of a scene without buildings.
+ * @returns {Array<{ x: number, y: number, length: number }>}
+ */
+function noiseSources(roads, weights, cols, rows, cell, heights, porosity, minX, maxY) {
+  const step = Math.max(3, cell * 1.5);
+  const { sources, given } = sampleRoadLines(roads, weights, step);
+  if (sources.length || given) return sources;
+  const streets = streetCentrelines(heights, porosity, cols, rows, cell, minX, maxY, 25);
+  if (streets.length) return streets;
+  const edge = [];
+  const sy = maxY - (rows - 1) * cell;
+  const gridStep = Math.max(1, Math.round(step / cell));
+  for (let c = 0; c < cols; c += gridStep) edge.push({ x: minX + c * cell, y: sy, length: step });
+  return edge;
+}
+
+/**
+ * Items (sources or clusters) grouped into square clusters of `size` metres,
+ * each at the length-weighted centre of its members with their total length.
+ * @template {{ x: number, y: number, length: number }} T
+ * @param {T[]} items
+ * @param {number} size
+ * @returns {Array<{ x: number, y: number, length: number, members: T[] }>}
+ */
+function clusterSources(items, size) {
+  /** @type {Map<string, { x: number, y: number, length: number, members: T[] }>} */
+  const bins = new Map();
+  for (const s of items) {
+    if (!(s.length > 0)) continue;
+    const key = `${Math.floor(s.x / size)},${Math.floor(s.y / size)}`;
+    let b = bins.get(key);
+    if (!b) { b = { x: 0, y: 0, length: 0, members: [] }; bins.set(key, b); }
+    b.x += s.x * s.length;
+    b.y += s.y * s.length;
+    b.length += s.length;
+    b.members.push(s);
+  }
+  const out = [...bins.values()];
+  for (const b of out) { b.x /= b.length; b.y /= b.length; }
+  return out;
+}
+
+/**
+ * Precompute cells that have a solid building facade within 12 m.
+ * @param {Float32Array} heights
+ * @param {Float32Array|null} porosity
+ * @param {number} cols
+ * @param {number} rows
+ * @param {number} cell
+ * @returns {Uint8Array}
+ */
+function findNearSolidFacades(heights, porosity, cols, rows, cell) {
+  const result = new Uint8Array(cols * rows);
+  const rad = Math.ceil(12 / cell);
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const idx = r * cols + c;
+      if (heights[idx] > 0 && !(porosity && porosity[idx] > 0)) continue;
+      let hasNear = false;
+      for (let dr = -rad; dr <= rad && !hasNear; dr++) {
+        for (let dc = -rad; dc <= rad; dc++) {
+          const nr = r + dr, nc = c + dc;
+          if (nr >= 0 && nr < rows && nc >= 0 && nc < cols) {
+            const nidx = nr * cols + nc;
+            if (heights[nidx] > 0 && !(porosity && porosity[nidx] > 0)) {
+              if (Math.hypot(dc * cell, dr * cell) <= 12) {
+                hasNear = true;
+                break;
+              }
+            }
+          }
+        }
+      }
+      if (hasNear) result[idx] = 1;
+    }
+  }
+  return result;
+}
+
+/**
+ * Compute pedestrian-level environmental noise Lden (in dB(A)).
+ * @param {object} p
+ * @param {Float32Array} p.heights obstacle height above ground per cell (0 = open)
+ * @param {Float32Array|null} [p.porosity] optical porosity per cell (null = solid)
+ * @param {number} p.cols
+ * @param {number} p.rows
+ * @param {number} p.cell metres per cell
+ * @param {number} [p.minX]
+ * @param {number} [p.maxY]
+ * @param {Array<Array<[number, number]>>} [p.roads] road polylines
+ * @param {ArrayLike<number>|null} [p.roadWeights] relative traffic per road polyline (1 = the stated level; 2 doubles it)
+ * @param {number} [p.soundPowerDb] road sound power level per metre (dB(A))
+ * @param {number} [p.receiverHeight] receiver height above ground in metres
+ * @param {number} [p.sourceHeight] source height above ground in metres
+ * @param {number} [p.groundFactor] ground absorption factor 0..1 (0=hard, 1=porous)
+ * @param {number} [p.maxDist] maximum calculation distance in metres
+ * @param {((f: number) => void)|null} [p.onProgress] progress 0..1; the page stays responsive
+ * @returns {Promise<Float32Array>} noise grid in dB(A), NaN inside solid buildings
+ */
+export async function noisePropagation({
+  heights,
+  porosity = null,
+  cols,
+  rows,
+  cell,
+  minX = 0.5 * cell,
+  maxY = (rows - 0.5) * cell,
+  roads = [],
+  roadWeights = null,
+  soundPowerDb = 82,
+  receiverHeight = 1.5,
+  sourceHeight = 0.5,
+  groundFactor = 0.5,
+  maxDist = 400,
+  onProgress = null
+}) {
+  const sources = noiseSources(roads, roadWeights, cols, rows, cell, heights, porosity, minX, maxY);
+  // Two cluster levels: road samples within 64 m are traced one by one,
+  // 8 m clusters up to 160 m, 32 m clusters beyond, each heard as one source
+  // at its centre (a distant cluster spans a small angle).
+  const clusterSize = Math.max(8, 2 * Math.max(3, cell * 1.5));
+  const bigSize = 4 * clusterSize;
+  const clusters = clusterSources(sources, clusterSize);
+  const big = clusterSources(clusters, bigSize);
+  const near = 8 * clusterSize;
+  const mid = 5 * bigSize;
+  const nearFacades = findNearSolidFacades(heights, porosity, cols, rows, cell);
+  const dz = receiverHeight - sourceHeight;
+
+  const out = new Float32Array(cols * rows);
+
+  /** Energy (10^(L/10)) at a receiver from one source, rays marched every stepM metres. */
+  const energyFrom = (rx, ry, src, stepM, reflectionBonus) => {
+    const dx = rx - src.x;
+    const dy = ry - src.y;
+    const dist2d = Math.hypot(dx, dy);
+    if (dist2d > maxDist) return 0;
+    const dDirect = Math.hypot(dx, dy, dz);
+    const d = Math.max(2, dDirect);
+
+    // Ray march from source to receiver to find barriers and tree foliage
+    let maxPathDiff = 0;
+    let dTree = 0;
+    if (dist2d >= 1) {
+      const nSteps = Math.max(2, Math.ceil(dist2d / stepM));
+      const segStep = dist2d / nSteps;
+      for (let stepIdx = 1; stepIdx < nSteps; stepIdx++) {
+        const t = stepIdx / nSteps;
+        const gc = Math.floor((src.x + t * dx - minX) / cell + 0.5);
+        const gr = Math.floor((maxY - (src.y + t * dy)) / cell + 0.5);
+        if (gc < 0 || gc >= cols || gr < 0 || gr >= rows) continue;
+        const gidx = gr * cols + gc;
+        const h = heights[gidx];
+        if (porosity && porosity[gidx] > 0) {
+          dTree += segStep;
+        } else if (h > 0 && h > sourceHeight + t * dz) {
+          const d1 = t * dist2d;
+          const d2 = (1 - t) * dist2d;
+          const pathDiff = Math.hypot(d1, h - sourceHeight) + Math.hypot(d2, h - receiverHeight) - dDirect;
+          if (pathDiff > maxPathDiff) maxPathDiff = pathDiff;
+        }
+      }
+    }
+
+    const aBar = maekawaDiffraction(maxPathDiff);
+    const aTree = Math.min(4, 0.08 * dTree);
+    const aDiv = 20 * Math.log10(d) + 8;
+    // ISO 9613-2 Table 2 at 500 Hz (10 °C, 70 %): about 1.9 dB/km.
+    const aAir = 0.0019 * d;
+    const aGround = 1.5 * groundFactor * Math.log10(Math.max(1, d / 2));
+    const lwSeg = soundPowerDb + 10 * Math.log10(Math.max(0.1, src.length));
+    return Math.pow(10, (lwSeg - aDiv - aAir - aGround - aBar - aTree + reflectionBonus) / 10);
+  };
+
+  const fineStep = Math.max(1, cell);
+  const coarseStep = 2 * fineStep;
+  let lastYield = Date.now();
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const i = r * cols + c;
+      if (heights[i] > 0 && !(porosity && porosity[i] > 0)) {
+        out[i] = NaN;
+        continue;
+      }
+      const rx = minX + c * cell;
+      const ry = maxY - r * cell;
+      const bonus = nearFacades[i] === 1 ? 1.8 : 0;
+      let energySum = 0;
+      for (const K of big) {
+        const dK = Math.hypot(rx - K.x, ry - K.y);
+        if (dK > maxDist + bigSize) continue;
+        if (dK > mid) {
+          // Far: one source, rays sampled about 24 times (barriers of a few
+          // metres still register; far roads are faint and mostly screened).
+          energySum += energyFrom(rx, ry, K, Math.max(coarseStep, dK / 24), bonus);
+          continue;
+        }
+        for (const k of K.members) {
+          const dk = Math.hypot(rx - k.x, ry - k.y);
+          if (dk > maxDist + clusterSize) continue;
+          if (dk > near) {
+            energySum += energyFrom(rx, ry, k, Math.max(coarseStep, dk / 24), bonus);
+          } else {
+            for (const src of k.members) energySum += energyFrom(rx, ry, src, fineStep, bonus);
+          }
+        }
+      }
+      out[i] = energySum > 0 ? Math.max(35, Math.min(90, 10 * Math.log10(energySum))) : 35;
+    }
+    if (onProgress && Date.now() - lastYield > 50) {
+      onProgress((r + 1) / rows);
+      await new Promise((res) => setTimeout(res, 0));
+      lastYield = Date.now();
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Compute per-building facade noise statistics and quiet facade indicator.
+ * @param {Float32Array} noiseGrid noise grid in dB(A)
+ * @param {Int32Array|Array<number>} ids building feature keys per cell (0 = none)
+ * @param {number} cols
+ * @param {number} rows
+ * @returns {Map<number, { max: number, min: number, mean: number, quietFacade: number }>}
+ */
+export function buildingFacadeNoise(noiseGrid, ids, cols, rows) {
+  /** @type {Map<number, { max: number, min: number, mean: number, quietFacade: number }>} */
+  const result = new Map();
+  if (!ids || ids.length !== cols * rows) return result;
+
+  /** @type {Map<number, Array<number>>} */
+  const buildingCells = new Map();
+  for (let i = 0; i < ids.length; i++) {
+    const key = ids[i];
+    if (key > 0) {
+      let arr = buildingCells.get(key);
+      if (!arr) {
+        arr = [];
+        buildingCells.set(key, arr);
+      }
+      arr.push(i);
+    }
+  }
+
+  for (const [key, cells] of buildingCells.entries()) {
+    const adjacentOpenIndices = new Set();
+    for (const idx of cells) {
+      const c = idx % cols;
+      const r = Math.floor(idx / cols);
+
+      for (let dr = -2; dr <= 2; dr++) {
+        for (let dc = -2; dc <= 2; dc++) {
+          if (dr === 0 && dc === 0) continue;
+          const nc = c + dc;
+          const nr = r + dr;
+          if (nc >= 0 && nc < cols && nr >= 0 && nr < rows) {
+            const nidx = nr * cols + nc;
+            if (ids[nidx] !== key && Number.isFinite(noiseGrid[nidx])) {
+              adjacentOpenIndices.add(nidx);
+            }
+          }
+        }
+      }
+    }
+
+    if (adjacentOpenIndices.size === 0) {
+      result.set(key, { max: 35, min: 35, mean: 35, quietFacade: 1 });
+      continue;
+    }
+
+    let max = -Infinity;
+    let min = Infinity;
+    let sum = 0;
+    let count = 0;
+
+    for (const oIdx of adjacentOpenIndices) {
+      const val = noiseGrid[oIdx];
+      if (Number.isFinite(val)) {
+        if (val > max) max = val;
+        if (val < min) min = val;
+        sum += val;
+        count++;
+      }
+    }
+
+    if (count === 0) {
+      result.set(key, { max: 35, min: 35, mean: 35, quietFacade: 1 });
+      continue;
+    }
+
+    const mean = sum / count;
+    // quietFacade is 1 if at least one facade side has < 55 dB(A) or max - min >= 6 dB(A)
+    const quietFacade = (min < 55 || (max - min) >= 6) ? 1 : 0;
+    result.set(key, { max, min, mean, quietFacade });
+  }
+
+  return result;
+}

zero2geospatial3d/web/src/core/classify.js

@@ -0,0 +1,158 @@
+// @ts-check
+// Colour ramps and classification (equal interval, quantile, natural
+// breaks, categories) for recolouring features and analysis grids.
+
+export const RAMPS = {
+  viridis: ['#440154', '#482878', '#3e4989', '#31688e', '#26828e', '#1f9e89', '#35b779', '#6ece58', '#b5de2b', '#fde725'],
+  magma: ['#000004', '#1c1044', '#4f127b', '#812581', '#b5367a', '#e55964', '#fb8761', '#fec287', '#fcfdbf'],
+  inferno: ['#000004', '#1f0c48', '#550f6d', '#88226a', '#ba3655', '#e35933', '#f98e09', '#f9cb35', '#fcffa4'],
+  rdylbu: ['#a50026', '#d73027', '#f46d43', '#fdae61', '#fee090', '#ffffbf', '#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695'],
+  spectral: ['#9e0142', '#d53e4f', '#f46d43', '#fdae61', '#fee08b', '#ffffbf', '#e6f598', '#abdda4', '#66c2a5', '#3288bd', '#5e4fa2'],
+  rdbu: ['#67001f', '#b2182b', '#d6604d', '#f4a582', '#fddbc7', '#f7f7f7', '#d1e5f0', '#92c5de', '#4393c3', '#2166ac', '#053061'],
+  blues: ['#f7fbff', '#deebf7', '#c6dbef', '#9ecae1', '#6baed6', '#4292c6', '#2171b5', '#08519c', '#08306b'],
+  reds: ['#fff5f0', '#fee0d2', '#fcbba1', '#fc9272', '#fb6a4a', '#ef3b2c', '#cb181d', '#a50f15', '#67000d'],
+  greens: ['#f7fcf5', '#e5f5e0', '#c7e9c0', '#a1d99b', '#74c476', '#41ab5d', '#238b45', '#006d2c', '#00441b'],
+  terrain: ['#2b6b3f', '#5f9a4f', '#a8c47a', '#e9dfa3', '#d2b47c', '#a47b55', '#8a7a72', '#f2f2f2'],
+  greys: ['#000000', '#262626', '#4d4d4d', '#737373', '#969696', '#bdbdbd', '#d9d9d9', '#f0f0f0', '#ffffff']
+};
+export const QUALITATIVE = ['#4e79a7', '#f28e2b', '#e15759', '#76b7b2', '#59a14f', '#edc948', '#b07aa1', '#ff9da7', '#9c755f', '#bab0ac',
+  '#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'];
+export const RAMP_LABELS = {
+  viridis: 'Viridis', magma: 'Magma', inferno: 'Inferno', rdylbu: 'Red-Yellow-Blue', spectral: 'Spectral',
+  rdbu: 'Red-Blue', blues: 'Blues', reds: 'Reds', greens: 'Greens', terrain: 'Terrain', greys: 'Greys'
+};
+
+export function hexToRgb(hex) {
+  const h = String(hex || '#cccccc').replace('#', '');
+  const v = parseInt(h.length === 3 ? h.split('').map((c) => c + c).join('') : h.slice(0, 6), 16);
+  return [((v >> 16) & 255) / 255, ((v >> 8) & 255) / 255, (v & 255) / 255];
+}
+
+export function rgbToHex([r, g, b]) {
+  const c = (x) => Math.round(Math.max(0, Math.min(1, x)) * 255).toString(16).padStart(2, '0');
+  return `#${c(r)}${c(g)}${c(b)}`;
+}
+
+/** Ramp stops as RGB triples; name may end in '-r' for reversed. */
+export function rampStops(name) {
+  const reversed = String(name).endsWith('-r');
+  const key = reversed ? String(name).slice(0, -2) : String(name);
+  const stops = (RAMPS[key] || RAMPS.viridis).map(hexToRgb);
+  return reversed ? stops.reverse() : stops;
+}
+
+/** Colour at t in [0, 1] along a ramp (stops from rampStops). */
+export function rampColor(stops, t, out = [0, 0, 0]) {
+  const v = Math.max(0, Math.min(1, Number.isFinite(t) ? t : 0)) * (stops.length - 1);
+  const i = Math.min(stops.length - 2, Math.floor(v));
+  const f = v - i;
+  for (let k = 0; k < 3; k++) out[k] = stops[i][k] + (stops[i + 1][k] - stops[i][k]) * f;
+  return out;
+}
+
+function finiteSorted(values) {
+  const out = [];
+  for (const v of values) if (v !== null && v !== '' && Number.isFinite(Number(v))) out.push(Number(v));
+  return out.sort((a, b) => a - b);
+}
+
+export function equalBreaks(values, k) {
+  const s = finiteSorted(values);
+  if (!s.length) return [];
+  const lo = s[0];
+  const hi = s[s.length - 1];
+  return Array.from({ length: k + 1 }, (_, i) => lo + ((hi - lo) * i) / k);
+}
+
+export function quantileBreaks(values, k) {
+  const s = finiteSorted(values);
+  if (!s.length) return [];
+  const out = [s[0]];
+  for (let i = 1; i < k; i++) out.push(s[Math.min(s.length - 1, Math.floor((i * s.length) / k))]);
+  out.push(s[s.length - 1]);
+  return out;
+}
+
+/** Jenks natural breaks (Fisher-Jenks dynamic programme) on at most 3000 sampled values. */
+export function jenksBreaks(values, k) {
+  let s = finiteSorted(values);
+  if (!s.length) return [];
+  if (s.length > 3000) {
+    const step = s.length / 3000;
+    s = Array.from({ length: 3000 }, (_, i) => s[Math.floor(i * step)]);
+    s.push(finiteSorted(values).pop());
+  }
+  const n = s.length;
+  k = Math.max(1, Math.min(k, new Set(s).size));
+  const lower = Array.from({ length: n + 1 }, () => new Int32Array(k + 1));
+  const variance = Array.from({ length: n + 1 }, () => new Float64Array(k + 1).fill(Infinity));
+  for (let j = 1; j <= k; j++) { lower[1][j] = 1; variance[1][j] = 0; }
+  for (let l = 2; l <= n; l++) {
+    let sum = 0;
+    let sumSq = 0;
+    let w = 0;
+    let v = 0;
+    for (let m = 1; m <= l; m++) {
+      const i3 = l - m + 1;
+      const val = s[i3 - 1];
+      w++;
+      sum += val;
+      sumSq += val * val;
+      v = sumSq - (sum * sum) / w;
+      const i4 = i3 - 1;
+      if (i4 !== 0) {
+        for (let j = 2; j <= k; j++) {
+          if (variance[l][j] >= v + variance[i4][j - 1]) {
+            lower[l][j] = i3;
+            variance[l][j] = v + variance[i4][j - 1];
+          }
+        }
+      }
+    }
+    lower[l][1] = 1;
+    variance[l][1] = v;
+  }
+  const breaks = new Array(k + 1);
+  breaks[k] = s[n - 1];
+  breaks[0] = s[0];
+  let idx = n;
+  for (let j = k; j >= 2; j--) {
+    const id = lower[idx][j] - 2;
+    breaks[j - 1] = s[Math.max(0, id)];
+    idx = lower[idx][j] - 1;
+  }
+  return breaks;
+}
+
+export function breaksFor(method, values, k) {
+  if (method === 'quantile') return quantileBreaks(values, k);
+  if (method === 'jenks') return jenksBreaks(values, k);
+  return equalBreaks(values, k);
+}
+
+/** Class index of a value for breaks [b0..bk]: 0..k-1, or -1 if not finite. */
+export function classOf(value, breaks) {
+  const v = Number(value);
+  if (value === null || value === '' || !Number.isFinite(v) || breaks.length < 2) return -1;
+  for (let i = 1; i < breaks.length - 1; i++) if (v < breaks[i]) return i - 1;
+  return breaks.length - 2;
+}
+
+/** Distinct values by frequency, most common first (at most `limit`). */
+export function categories(values, limit = 20) {
+  const counts = new Map();
+  for (const v of values) {
+    const key = v === null || v === undefined || v === '' ? '(empty)' : String(v);
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit).map(([value, count]) => ({ value, count }));
+}
+
+/** Short number formatting for legends. */
+export function fmt(v, unit = '') {
+  if (!Number.isFinite(v)) return '–';
+  if (Number.isInteger(v)) return unit ? `${v.toLocaleString('en-US')} ${unit}` : v.toLocaleString('en-US');
+  const a = Math.abs(v);
+  const s = a >= 1000 ? Math.round(v).toLocaleString('en-US') : a >= 100 ? v.toFixed(0) : a >= 10 ? v.toFixed(1) : v.toFixed(2);
+  return unit ? `${s} ${unit}` : s;
+}