zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/web/src/core/walkability.js

@@ -0,0 +1,316 @@
+// @ts-check
+// Pedestrian Cool Walkability Index (PCWI) and A* thermally-optimal route
+// finder across the open-ground analysis grid.
+//
+// Combines thermal comfort (UTCI), solar shade, Green View Index (Konijnendijk
+// 3-30-300 rule), road traffic noise (WHO 53/65 dB thresholds) and terrain
+// slope into a 0-100 pedestrian quality index, and compares the shortest
+// obstacle-free route against the coolest / highest-comfort route.
+
+export const WALKABILITY_CLASSES = [
+  { min: 75, max: 101, label: 'Excellent (cool, shaded & quiet)', color: '#1d8f5f' },
+  { min: 55, max: 75, label: 'Good pedestrian comfort', color: '#6dbf67' },
+  { min: 35, max: 55, label: 'Moderate (exposed or noisy)', color: '#f0b429' },
+  { min: 0, max: 35, label: 'Poor (heat stress / high noise / steep)', color: '#d64545' }
+];
+
+export function walkabilityClass(score) {
+  if (!Number.isFinite(score)) return null;
+  const s = Math.max(0, Math.min(100, score));
+  return WALKABILITY_CLASSES.find((c) => s >= c.min && s < c.max) || WALKABILITY_CLASSES[WALKABILITY_CLASSES.length - 1];
+}
+
+export function thermalSubscore(utciC) {
+  if (!Number.isFinite(utciC)) return NaN;
+  if (utciC >= 9 && utciC <= 26) return 100;
+  if (utciC > 26) return Math.max(0, Math.min(100, 100 * (1 - (utciC - 26) / 16)));
+  return Math.max(0, Math.min(100, 100 * (1 - (9 - utciC) / 19)));
+}
+
+export function shadeSubscore(shadeVal) {
+  if (!Number.isFinite(shadeVal)) return NaN;
+  const frac = shadeVal > 1.01 ? shadeVal / 100 : shadeVal;
+  return Math.max(0, Math.min(100, frac * 100));
+}
+
+export function greenSubscore(gviPct) {
+  if (!Number.isFinite(gviPct)) return NaN;
+  return Math.max(0, Math.min(100, (gviPct / 30) * 100));
+}
+
+export function quietSubscore(noiseDba) {
+  if (!Number.isFinite(noiseDba)) return NaN;
+  if (noiseDba <= 50) return 100;
+  if (noiseDba >= 75) return 0;
+  return 100 * (1 - (noiseDba - 50) / 25);
+}
+
+export function slopeSubscore(slopeDeg) {
+  if (!Number.isFinite(slopeDeg)) return NaN;
+  if (slopeDeg <= 2) return 100;
+  if (slopeDeg >= 12) return 0;
+  return 100 * (1 - (slopeDeg - 2) / 10);
+}
+
+/**
+ * Compute a 0-100 Pedestrian Cool Walkability Index on open ground.
+ */
+export function pedestrianWalkabilityIndex({
+  ids = null,
+  utciGrid = null,
+  shadeGrid = null,
+  gviGrid = null,
+  noiseGrid = null,
+  slopeDegGrid = null,
+  cols,
+  rows,
+  weights = {}
+}) {
+  const n = cols * rows;
+  const out = new Float32Array(n).fill(NaN);
+  const wThermal = Math.max(0, weights.thermal ?? 0.35);
+  const wShade = Math.max(0, weights.shade ?? 0.25);
+  const wGreen = Math.max(0, weights.green ?? 0.15);
+  const wQuiet = Math.max(0, weights.quiet ?? 0.15);
+  const wSlope = Math.max(0, weights.slope ?? 0.10);
+
+  for (let i = 0; i < n; i++) {
+    if (ids && ids[i] !== 0) continue;
+    let sum = 0;
+    let wSum = 0;
+    if (utciGrid) {
+      const s = thermalSubscore(utciGrid[i]);
+      if (Number.isFinite(s)) { sum += wThermal * s; wSum += wThermal; }
+    }
+    if (shadeGrid) {
+      const s = shadeSubscore(shadeGrid[i]);
+      if (Number.isFinite(s)) { sum += wShade * s; wSum += wShade; }
+    }
+    if (gviGrid) {
+      const s = greenSubscore(gviGrid[i]);
+      if (Number.isFinite(s)) { sum += wGreen * s; wSum += wGreen; }
+    }
+    if (noiseGrid) {
+      const s = quietSubscore(noiseGrid[i]);
+      if (Number.isFinite(s)) { sum += wQuiet * s; wSum += wQuiet; }
+    }
+    if (slopeDegGrid) {
+      const s = slopeSubscore(slopeDegGrid[i]);
+      if (Number.isFinite(s)) { sum += wSlope * s; wSum += wSlope; }
+    }
+    if (wSum > 0) out[i] = Math.max(0, Math.min(100, sum / wSum));
+  }
+  return out;
+}
+
+function nearestWalkableCell(ids, walkScore, cols, rows, cell, minX, maxY, xy) {
+  const c0 = Math.max(0, Math.min(cols - 1, Math.round((xy[0] - minX) / cell)));
+  const r0 = Math.max(0, Math.min(rows - 1, Math.round((maxY - xy[1]) / cell)));
+  const isOk = (idx) => (!ids || ids[idx] === 0) && (!walkScore || Number.isFinite(walkScore[idx]));
+  if (isOk(r0 * cols + c0)) return r0 * cols + c0;
+  const maxRad = Math.max(cols, rows);
+  for (let rad = 1; rad <= maxRad; rad++) {
+    let best = -1;
+    let bestDist = Infinity;
+    const rMin = Math.max(0, r0 - rad), rMax = Math.min(rows - 1, r0 + rad);
+    const cMin = Math.max(0, c0 - rad), cMax = Math.min(cols - 1, c0 + rad);
+    for (let r = rMin; r <= rMax; r++) {
+      for (let c = cMin; c <= cMax; c++) {
+        if (Math.abs(r - r0) !== rad && Math.abs(c - c0) !== rad) continue;
+        const idx = r * cols + c;
+        if (!isOk(idx)) continue;
+        const d = (r - r0) * (r - r0) + (c - c0) * (c - c0);
+        if (d < bestDist) { bestDist = d; best = idx; }
+      }
+    }
+    if (best >= 0) return best;
+  }
+  return -1;
+}
+
+function aStarPath(cols, rows, startIdx, endIdx, passableFn, stepPenaltyFn) {
+  const n = cols * rows;
+  const gScore = new Float64Array(n).fill(Infinity);
+  const prev = new Int32Array(n).fill(-1);
+  const closed = new Uint8Array(n);
+  const endR = Math.floor(endIdx / cols), endC = endIdx % cols;
+
+  // Binary min-heap of (fScore, cellIndex)
+  const heapF = [];
+  const heapIdx = [];
+  const push = (f, idx) => {
+    let i = heapF.length;
+    heapF.push(f);
+    heapIdx.push(idx);
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (heapF[p] <= f) break;
+      heapF[i] = heapF[p]; heapIdx[i] = heapIdx[p];
+      i = p;
+    }
+    heapF[i] = f; heapIdx[i] = idx;
+  };
+  const pop = () => {
+    const topIdx = heapIdx[0];
+    const lastF = heapF.pop();
+    const lastIdx = heapIdx.pop();
+    if (heapF.length > 0 && lastF !== undefined && lastIdx !== undefined) {
+      let i = 0;
+      const half = heapF.length >> 1;
+      while (i < half) {
+        let l = (i << 1) + 1;
+        const r = l + 1;
+        if (r < heapF.length && heapF[r] < heapF[l]) l = r;
+        if (lastF <= heapF[l]) break;
+        heapF[i] = heapF[l]; heapIdx[i] = heapIdx[l];
+        i = l;
+      }
+      heapF[i] = lastF; heapIdx[i] = lastIdx;
+    }
+    return topIdx;
+  };
+
+  gScore[startIdx] = 0;
+  push(Math.hypot(Math.floor(startIdx / cols) - endR, (startIdx % cols) - endC), startIdx);
+
+  const dr = [-1, -1, -1, 0, 0, 1, 1, 1];
+  const dc = [-1, 0, 1, -1, 1, -1, 0, 1];
+  const dLen = [Math.SQRT2, 1, Math.SQRT2, 1, 1, Math.SQRT2, 1, Math.SQRT2];
+
+  while (heapF.length > 0) {
+    const curr = pop();
+    if (curr === endIdx) break;
+    if (closed[curr]) continue;
+    closed[curr] = 1;
+    const r = Math.floor(curr / cols), c = curr % cols;
+    const baseG = gScore[curr];
+    for (let k = 0; k < 8; k++) {
+      const nr = r + dr[k], nc = c + dc[k];
+      if (nr < 0 || nr >= rows || nc < 0 || nc >= cols) continue;
+      const next = nr * cols + nc;
+      if (closed[next] || !passableFn(next)) continue;
+      // Prevent corner-cutting through diagonal building cells
+      if (dr[k] !== 0 && dc[k] !== 0) {
+        if (!passableFn(r * cols + nc) || !passableFn(nr * cols + c)) continue;
+      }
+      const stepCost = dLen[k] * stepPenaltyFn(next);
+      const candG = baseG + stepCost;
+      if (candG < gScore[next]) {
+        gScore[next] = candG;
+        prev[next] = curr;
+        const h = Math.hypot(nr - endR, nc - endC);
+        push(candG + h, next);
+      }
+    }
+  }
+
+  if (!Number.isFinite(gScore[endIdx])) return null;
+  const cells = [];
+  let cur = endIdx;
+  while (cur >= 0) {
+    cells.push(cur);
+    if (cur === startIdx) break;
+    cur = prev[cur];
+  }
+  cells.reverse();
+  return cells;
+}
+
+function summarizeRouteCells(cells, { routeType, label, color, cols, cell, minX, maxY, walkScore, utciGrid, shadeGrid, gviGrid, noiseGrid }) {
+  const coords = cells.map((idx) => {
+    const r = Math.floor(idx / cols), c = idx % cols;
+    return [minX + c * cell, maxY - r * cell];
+  });
+  let lengthM = 0;
+  for (let i = 1; i < coords.length; i++) {
+    lengthM += Math.hypot(coords[i][0] - coords[i - 1][0], coords[i][1] - coords[i - 1][1]);
+  }
+  const meanOf = (arr) => {
+    if (!arr) return NaN;
+    let s = 0, cnt = 0;
+    for (const idx of cells) {
+      const v = arr[idx];
+      if (Number.isFinite(v)) { s += v; cnt++; }
+    }
+    return cnt > 0 ? s / cnt : NaN;
+  };
+  let shadePct = NaN;
+  if (shadeGrid) {
+    let s = 0, cnt = 0;
+    for (const idx of cells) {
+      const v = shadeGrid[idx];
+      if (Number.isFinite(v)) {
+        s += v > 1.01 ? v : v * 100;
+        cnt++;
+      }
+    }
+    if (cnt > 0) shadePct = s / cnt;
+  }
+  return {
+    route_type: routeType,
+    label,
+    color,
+    cells,
+    coords,
+    length_m: lengthM,
+    mean_utci_c: meanOf(utciGrid),
+    shade_pct: shadePct,
+    mean_gvi_pct: meanOf(gviGrid),
+    mean_noise_dba: meanOf(noiseGrid),
+    walk_score: meanOf(walkScore)
+  };
+}
+
+/**
+ * Find and compare the shortest obstacle-free pedestrian route vs. the
+ * thermally/environmentally optimal (coolest & shaded) route.
+ */
+export function findCoolRoute({
+  ids = null,
+  walkScore,
+  utciGrid = null,
+  shadeGrid = null,
+  gviGrid = null,
+  noiseGrid = null,
+  cols,
+  rows,
+  cell,
+  minX,
+  maxY,
+  startXY,
+  endXY,
+  coolBias = 2.8
+}) {
+  const startIdx = nearestWalkableCell(ids, walkScore, cols, rows, cell, minX, maxY, startXY);
+  const endIdx = nearestWalkableCell(ids, walkScore, cols, rows, cell, minX, maxY, endXY);
+  if (startIdx < 0 || endIdx < 0) return null;
+  const passable = (idx) => (!ids || ids[idx] === 0) && (!walkScore || Number.isFinite(walkScore[idx]));
+
+  const shortestCells = aStarPath(cols, rows, startIdx, endIdx, passable, () => 1.0);
+  if (!shortestCells) return null;
+
+  const bias = Math.max(0.2, coolBias);
+  const coolestCells = aStarPath(cols, rows, startIdx, endIdx, passable, (idx) => {
+    const sc = walkScore && Number.isFinite(walkScore[idx]) ? walkScore[idx] : 50;
+    const discomfort = Math.max(0, Math.min(1, (100 - sc) / 100));
+    return 1 + bias * Math.pow(discomfort, 1.5);
+  }) || shortestCells;
+
+  const meta = { cols, cell, minX, maxY, walkScore, utciGrid, shadeGrid, gviGrid, noiseGrid };
+  const shortest = summarizeRouteCells(shortestCells, {
+    routeType: 'shortest', label: 'Shortest path', color: '#e4572e', ...meta
+  });
+  const coolest = summarizeRouteCells(coolestCells, {
+    routeType: 'coolest', label: 'Coolest & shaded path', color: '#1d8f5f', ...meta
+  });
+
+  const detourPct = shortest.length_m > 0 ? ((coolest.length_m - shortest.length_m) / shortest.length_m) * 100 : 0;
+  const utciDeltaC = Number.isFinite(coolest.mean_utci_c) && Number.isFinite(shortest.mean_utci_c)
+    ? coolest.mean_utci_c - shortest.mean_utci_c : NaN;
+  const shadeGainPct = Number.isFinite(coolest.shade_pct) && Number.isFinite(shortest.shade_pct)
+    ? coolest.shade_pct - shortest.shade_pct : NaN;
+  const walkScoreGain = Number.isFinite(coolest.walk_score) && Number.isFinite(shortest.walk_score)
+    ? coolest.walk_score - shortest.walk_score : NaN;
+
+  return { shortest, coolest, detourPct, utciDeltaC, shadeGainPct, walkScoreGain };
+}

zero2geospatial3d/web/src/core/weather.js

@@ -0,0 +1,225 @@
+// @ts-check
+// Weather: EnergyPlus EPW parsing, monthly summaries, wind rose, annual
+// sun-direction bins for radiation, and a clear-sky year when no EPW exists.
+import { solarPosition, sunVector } from './solar.js';
+
+const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const MONTH_START = MONTH_DAYS.reduce((acc, d, i) => { acc.push(i ? acc[i - 1] + MONTH_DAYS[i - 1] : 0); return acc; }, []);
+export const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** Day of year in a 365-day typical year. */
+export function typicalDoy(month, day) {
+  return MONTH_START[month - 1] + day;
+}
+
+/**
+ * Parse EPW text.
+ * @param {string} text
+ * @returns {{ location: object, hours: number,
+ *   month: Uint8Array, day: Uint8Array, hour: Uint8Array,
+ *   dryBulb: Float32Array, dewPoint: Float32Array, rh: Float32Array, pressure: Float32Array,
+ *   ir: Float32Array, ghi: Float32Array, dni: Float32Array, dhi: Float32Array,
+ *   windDir: Float32Array, windSpeed: Float32Array, skyCover: Float32Array }}
+ */
+export function parseEpw(text) {
+  const lines = text.split(/\r?\n/);
+  const loc = lines[0].split(',').map((s) => s.trim());
+  if (loc[0]?.toUpperCase() !== 'LOCATION' || loc.length < 10) throw new Error('Not an EPW file (no LOCATION line).');
+  const location = {
+    city: loc[1], region: loc[2], country: loc[3], source: loc[4], wmo: loc[5],
+    lat: Number(loc[6]), lon: Number(loc[7]), utcOffset: Number(loc[8]), elevation: Number(loc[9])
+  };
+  const rows = [];
+  for (let i = 8; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line || !/^\s*-?\d/.test(line)) continue;
+    rows.push(line.split(','));
+  }
+  if (rows.length < 8760) throw new Error(`EPW has ${rows.length} hourly records; 8760 are required.`);
+  const n = 8760;
+  const f32 = () => new Float32Array(n);
+  const data = {
+    location, hours: n,
+    month: new Uint8Array(n), day: new Uint8Array(n), hour: new Uint8Array(n),
+    dryBulb: f32(), dewPoint: f32(), rh: f32(), pressure: f32(), ir: f32(),
+    ghi: f32(), dni: f32(), dhi: f32(), windDir: f32(), windSpeed: f32(), skyCover: f32()
+  };
+  // Leap-year files carry Feb 29: drop it so the year has 8760 hours.
+  let k = 0;
+  for (const r of rows) {
+    if (k >= n) break;
+    const m = Number(r[1]);
+    const d = Number(r[2]);
+    if (m === 2 && d === 29) continue;
+    data.month[k] = m;
+    data.day[k] = d;
+    data.hour[k] = Number(r[3]);
+    data.dryBulb[k] = num(r[6], 99.9, 20);
+    data.dewPoint[k] = num(r[7], 99.9, 10);
+    data.rh[k] = num(r[8], 999, 50);
+    data.pressure[k] = num(r[9], 999999, 101325);
+    data.ir[k] = num(r[12], 9999, NaN);
+    data.ghi[k] = Math.max(0, num(r[13], 9999, 0));
+    data.dni[k] = Math.max(0, num(r[14], 9999, 0));
+    data.dhi[k] = Math.max(0, num(r[15], 9999, 0));
+    data.windDir[k] = num(r[20], 999, 0);
+    data.windSpeed[k] = Math.max(0, num(r[21], 999, 0));
+    data.skyCover[k] = num(r[22], 99, 5);
+    k++;
+  }
+  if (k < n) throw new Error('EPW ended before 8760 hours.');
+  return data;
+}
+
+function num(text, missing, fallback) {
+  const v = Number(text);
+  return Number.isFinite(v) && v < missing ? v : fallback;
+}
+
+/** Index of the EPW record for a month, day and clock hour (1..24 = hour ending). */
+export function hourIndex(month, day, hourEnding) {
+  return (typicalDoy(month, day) - 1) * 24 + (hourEnding - 1);
+}
+
+/** Monthly means and sums for charts. */
+export function monthlySummary(w) {
+  const out = MONTH_NAMES.map((name) => ({ name, tMean: 0, tMin: Infinity, tMax: -Infinity, rh: 0, ghiKwh: 0, wind: 0, n: 0 }));
+  for (let i = 0; i < w.hours; i++) {
+    const m = out[w.month[i] - 1];
+    const t = w.dryBulb[i];
+    m.tMean += t; m.rh += w.rh[i]; m.wind += w.windSpeed[i]; m.ghiKwh += w.ghi[i] / 1000; m.n++;
+    if (t < m.tMin) m.tMin = t;
+    if (t > m.tMax) m.tMax = t;
+  }
+  for (const m of out) {
+    if (!m.n) continue;
+    m.tMean /= m.n; m.rh /= m.n; m.wind /= m.n;
+  }
+  return out;
+}
+
+/**
+ * Wind rose: frequency (fraction of hours) per direction sector and speed
+ * class. Calm hours (< 0.5 m/s) are counted separately.
+ */
+export function windRose(w, { sectors = 16, classes = [0.5, 2, 4, 6, 8, 11], months = null, hours = null } = {}) {
+  const table = Array.from({ length: sectors }, () => new Array(classes.length).fill(0));
+  let calm = 0;
+  let total = 0;
+  let speedSum = 0;
+  for (let i = 0; i < w.hours; i++) {
+    if (months && !months.includes(w.month[i])) continue;
+    if (hours && !hours.includes(w.hour[i])) continue;
+    const v = w.windSpeed[i];
+    total++;
+    speedSum += v;
+    if (v < classes[0]) { calm++; continue; }
+    const s = Math.floor((((w.windDir[i] % 360) + 360) % 360) / (360 / sectors) + 0.5) % sectors;
+    let c = classes.length - 1;
+    for (let j = 1; j < classes.length; j++) if (v < classes[j]) { c = j - 1; break; }
+    table[s][c]++;
+  }
+  const freq = table.map((row) => row.map((x) => (total ? x / total : 0)));
+  const sectorFreq = freq.map((row) => row.reduce((a, b) => a + b, 0));
+  let prevailing = 0;
+  sectorFreq.forEach((f, i) => { if (f > sectorFreq[prevailing]) prevailing = i; });
+  // Mean speed of the prevailing sector (non-calm hours).
+  let pSum = 0;
+  let pN = 0;
+  for (let i = 0; i < w.hours; i++) {
+    if (months && !months.includes(w.month[i])) continue;
+    if (hours && !hours.includes(w.hour[i])) continue;
+    const v = w.windSpeed[i];
+    if (v < classes[0]) continue;
+    const s = Math.floor((((w.windDir[i] % 360) + 360) % 360) / (360 / sectors) + 0.5) % sectors;
+    if (s === prevailing) { pSum += v; pN++; }
+  }
+  return {
+    sectors, classes, freq, sectorFreq, calm: total ? calm / total : 0,
+    meanSpeed: total ? speedSum / total : 0,
+    prevailingDirection: prevailing * (360 / sectors),
+    prevailingSpeed: pN ? pSum / pN : 0
+  };
+}
+
+// ASHRAE clear-sky model constants per month (A in W/m2, B, C; ASHRAE
+// Handbook of Fundamentals, 1985): DNI = A exp(-B / sin(altitude)), DHI = C DNI.
+const ASHRAE_CLEAR = [
+  [1230, 0.142, 0.058], [1215, 0.144, 0.060], [1186, 0.156, 0.071], [1136, 0.180, 0.097],
+  [1104, 0.196, 0.121], [1088, 0.205, 0.134], [1085, 0.207, 0.136], [1107, 0.201, 0.122],
+  [1151, 0.177, 0.092], [1192, 0.160, 0.073], [1221, 0.149, 0.063], [1233, 0.142, 0.057]
+];
+
+/** Hourly clear-sky DNI/DHI/GHI (Wh/m2 per hour) for a site: an upper bound with no clouds. */
+export function clearSkyYear(lat, lon, utcOffset) {
+  const n = 8760;
+  const w = { location: { lat, lon, utcOffset, city: 'Clear sky', clearSky: true }, hours: n,
+    month: new Uint8Array(n), day: new Uint8Array(n), hour: new Uint8Array(n),
+    ghi: new Float32Array(n), dni: new Float32Array(n), dhi: new Float32Array(n) };
+  let k = 0;
+  for (let m = 1; m <= 12; m++) {
+    for (let d = 1; d <= MONTH_DAYS[m - 1]; d++) {
+      for (let h = 1; h <= 24; h++) {
+        w.month[k] = m; w.day[k] = d; w.hour[k] = h;
+        const p = solarPosition(typicalDoy(m, d), h - 0.5, lat, lon, utcOffset);
+        if (p.elevation > 0.0175) {
+          const [A, B, C] = ASHRAE_CLEAR[m - 1];
+          const s = Math.sin(p.elevation);
+          const dni = A * Math.exp(-B / s);
+          w.dni[k] = dni;
+          w.dhi[k] = C * dni;
+          w.ghi[k] = dni * s + C * dni;
+        }
+        k++;
+      }
+    }
+  }
+  return w;
+}
+
+/**
+ * Bin the year's direct-beam hours into sky patches. Each patch becomes one
+ * direction (the DNI-weighted mean sun vector of its hours) with the patch's
+ * DNI sum in Wh/m2 as weight. Also returns DHI and GHI sums for the diffuse
+ * and ground-reflected terms.
+ * @param {any} w weather (EPW or clear sky)
+ * @param {{ lat: number, lon: number, utcOffset: number, months?: number[]|null, altStepDeg?: number, azStepDeg?: number }} site
+ */
+export function annualSunBins(w, { lat, lon, utcOffset, months = null, altStepDeg = 5, azStepDeg = 7.5 }) {
+  const bins = new Map();
+  let dhiSum = 0;
+  let ghiSum = 0;
+  let dniSum = 0;
+  for (let i = 0; i < w.hours; i++) {
+    if (months && !months.includes(w.month[i])) continue;
+    dhiSum += w.dhi[i];
+    ghiSum += w.ghi[i];
+    const dni = w.dni[i];
+    if (dni <= 0) continue;
+    const p = solarPosition(typicalDoy(w.month[i], w.day[i]), w.hour[i] - 0.5, lat, lon, utcOffset);
+    if (p.elevation <= 0.0087) continue; // below 0.5 degrees
+    dniSum += dni;
+    const altBin = Math.floor(p.elevation / (altStepDeg * Math.PI / 180));
+    const azBin = Math.floor(p.azimuth / (azStepDeg * Math.PI / 180));
+    const key = altBin * 1000 + azBin;
+    const v = sunVector(p.elevation, p.azimuth);
+    let b = bins.get(key);
+    if (!b) { b = { x: 0, y: 0, z: 0, weight: 0 }; bins.set(key, b); }
+    b.x += v[0] * dni; b.y += v[1] * dni; b.z += v[2] * dni; b.weight += dni;
+  }
+  const directions = [];
+  for (const b of bins.values()) {
+    const len = Math.hypot(b.x, b.y, b.z) || 1;
+    directions.push({ dir: [b.x / len, b.y / len, b.z / len], weight: b.weight });
+  }
+  return { directions, dhiSum, ghiSum, dniSum };
+}
+
+/** Hourly conditions for comfort analysis. */
+export function conditionsAt(w, month, day, hourEnding) {
+  const i = hourIndex(month, day, hourEnding);
+  return {
+    airTemp: w.dryBulb?.[i], rh: w.rh?.[i], windSpeed: w.windSpeed?.[i], windDir: w.windDir?.[i],
+    ghi: w.ghi[i], dni: w.dni[i], dhi: w.dhi[i], ir: w.ir?.[i]
+  };
+}

zero2geospatial3d/web/src/core/wind.js

@@ -0,0 +1,131 @@
+// @ts-check
+// Pedestrian-level wind screening on a building-height grid. NOT CFD: a fast
+// geometric estimate meant to find sheltered and exposed places, to be
+// confirmed with a flow simulation or wind-tunnel test where it matters.
+//
+// For each open cell the ratio to the open-terrain pedestrian wind is
+//   ratio = (1 - wake deficit) x channelling x corner factor
+// wake deficit   strongest upwind wake: A exp(-x / (k h)) for an obstacle of
+//                height h at distance x (recovery over about 10-15 h, the
+//                usual near-wake length behind a building)
+// channelling    open fetch along the wind with buildings close on both
+//                sides (a street aligned with the wind) speeds the flow up
+// corner factor  cells beside a building much taller than its surroundings
+//                (downwash and corner streams)
+// The open-terrain pedestrian wind is the 10 m reference speed scaled by a
+// log profile over open terrain: ln(1.5/z0) / ln(10/z0) with z0 = 0.03 m.
+
+export const OPEN_PEDESTRIAN_FACTOR = Math.log(1.5 / 0.03) / Math.log(10 / 0.03);
+
+/**
+ * @param {object} p
+ * @param {Float32Array} p.heights obstacle height above ground per cell (0 = open)
+ * @param {Float32Array|null} [p.porosity] optical porosity per cell 0..1 (trees ~0.5), null = solid
+ * @param {number} p.cols
+ * @param {number} p.rows
+ * @param {number} p.cell metres
+ * @param {number} p.windFromDeg meteorological direction the wind comes from
+ * @param {number} [p.wakeAmplitude]
+ * @param {number} [p.wakeLength] recovery length in obstacle heights
+ * @param {(f: number) => void} [p.onProgress]
+ * @returns {Promise<Float32Array>} ratio per cell, NaN inside buildings
+ */
+export async function windRatio({ heights, porosity = null, cols, rows, cell, windFromDeg, wakeAmplitude = 0.75, wakeLength = 3.5, onProgress }) {
+  const out = new Float32Array(cols * rows);
+  // Unit vector pointing upwind (towards where the wind comes from), in
+  // grid steps: +x east = +col, +y north = -row.
+  const from = windFromDeg * Math.PI / 180;
+  const ux = Math.sin(from);
+  const uy = Math.cos(from);
+  const dc = ux;
+  const dr = -uy;
+  // Perpendicular (for channelling).
+  const pc = -dr;
+  const pr = dc;
+  let hMax = 0, hSum = 0, hN = 0;
+  for (const h of heights) { if (h > hMax) hMax = h; if (h > 0) { hSum += h; hN++; } }
+  const hMean = hN ? hSum / hN : 0;
+  let hasTall = false;
+  for (const h of heights) if (h > 2 * hMean && h > 20) { hasTall = true; break; }
+  const maxSteps = Math.ceil(Math.min(600, Math.max(60, wakeLength * 5 * hMax)) / cell);
+  const sideSteps = Math.ceil(40 / cell);
+  // Round, then check the bounds: c = cols - 0.3 would round into the next row.
+  const at = (c, r) => {
+    const ic = Math.round(c), ir = Math.round(r);
+    return ic < 0 || ir < 0 || ic >= cols || ir >= rows ? 0 : heights[ir * cols + ic];
+  };
+  const poro = (c, r) => {
+    const ic = Math.round(c), ir = Math.round(r);
+    return porosity && ic >= 0 && ir >= 0 && ic < cols && ir < rows ? porosity[ir * cols + ic] || 0 : 0;
+  };
+  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; }
+      // 1. Wake deficit from upwind obstacles.
+      let deficit = 0;
+      let fetch = maxSteps * cell;
+      for (let s = 1; s <= maxSteps; s++) {
+        const cc = c + dc * s;
+        const rr = r + dr * s;
+        if (cc < 0 || rr < 0 || cc > cols - 1 || rr > rows - 1) break;
+        const h = at(cc, rr);
+        if (h <= 0) continue;
+        const x = s * cell;
+        if (x < fetch) fetch = x;
+        const d = wakeAmplitude * (1 - poro(cc, rr)) * Math.exp(-x / (wakeLength * h));
+        if (d > deficit) deficit = d;
+        if (x > wakeLength * 5 * hMax) break;
+      }
+      // 2. Channelling: buildings close on both sides, open along the wind.
+      let left = 0, right = 0, hl = 0, hr = 0;
+      for (let s = 1; s <= sideSteps && !left; s++) { const h = at(c + pc * s, r + pr * s); if (h > 0) { left = s * cell; hl = h; } }
+      for (let s = 1; s <= sideSteps && !right; s++) { const h = at(c - pc * s, r - pr * s); if (h > 0) { right = s * cell; hr = h; } }
+      let channel = 1;
+      if (left && right) {
+        const width = left + right;
+        const hSide = Math.min(hl, hr);
+        const along = Math.min(1, fetch / (3 * width));
+        channel = 1 + 0.25 * along * Math.min(1, hSide / width);
+      }
+      // 3. Corner/downwash: a much taller building close by.
+      let corner = 1;
+      if (hasTall) {
+        const rad = Math.ceil(30 / cell);
+        let best = 0;
+        for (let dy = -rad; dy <= rad; dy += 2) {
+          for (let dx = -rad; dx <= rad; dx += 2) {
+            const h = at(c + dx, r + dy);
+            if (h > 2 * hMean && h > 20) {
+              const dist = Math.hypot(dx, dy) * cell;
+              if (dist < 0.6 * h) best = Math.max(best, (1 - dist / (0.6 * h)) * Math.min(1, h / (4 * hMean)));
+            }
+          }
+        }
+        corner = 1 + 0.35 * best;
+      }
+      out[i] = Math.max(0.05, Math.min(1.6, (1 - deficit) * channel * corner));
+    }
+    if (onProgress && r % 32 === 0) {
+      onProgress(r / rows);
+      await new Promise((res) => setTimeout(res, 0));
+    }
+  }
+  return out;
+}
+
+/**
+ * Indicative pedestrian comfort class for a wind speed (m/s) at pedestrian
+ * height, with the thresholds of the LDDC (Lawson) criteria: sitting < 4,
+ * standing < 6, strolling < 8, business walking < 10. Lawson applies them to
+ * the speed exceeded 5 percent of the time, so feed it the 95th-percentile
+ * reference speed, not the mean.
+ */
+export function lawsonClass(speed) {
+  if (!Number.isFinite(speed)) return null;
+  if (speed < 4) return { key: 'sitting', label: 'Sitting', color: '#2c7bb6' };
+  if (speed < 6) return { key: 'standing', label: 'Standing', color: '#abd9e9' };
+  if (speed < 8) return { key: 'strolling', label: 'Strolling', color: '#ffffbf' };
+  if (speed < 10) return { key: 'walking', label: 'Business walking', color: '#fdae61' };
+  return { key: 'uncomfortable', label: 'Uncomfortable', color: '#d7191c' };
+}