zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/web/src/analysis/climate.js

@@ -0,0 +1,278 @@
+// @ts-check
+// A year of outdoor climate around each building, from an EPW file.
+//
+// The open ground within `ringMetres` of a building is that building's
+// surroundings (each open cell goes to its nearest building). For it we take
+// the sky view factor, the sheltering wind ratio per wind sector, and the
+// sunlit share per sun position of the year (grouped into coarse sky bins).
+// Then every hour of the chosen daily window is evaluated with the EPW
+// weather: mean radiant temperature (SolarCal) and UTCI, pedestrian wind.
+import { skyHemisphere, solarPosition, sunVector } from '../core/solar.js';
+import { typicalDoy } from '../core/weather.js';
+import { windRatio, OPEN_PEDESTRIAN_FACTOR } from '../core/wind.js';
+import { meanRadiantTemperature, skyTemperature, utci } from '../core/comfort.js';
+import { splitKey, ExtrudedLayer } from '../scene/objects.js';
+
+const DEG = Math.PI / 180;
+
+/**
+ * Meteorological seasons as month groups (Dec-Feb, Mar-May, Jun-Aug,
+ * Sep-Nov). Field codes name the months; the season names follow the
+ * hemisphere: Dec-Feb is winter in the north and summer in the south.
+ */
+export const SEASONS = [['djf', 'Winter'], ['mam', 'Spring'], ['jja', 'Summer'], ['son', 'Autumn']];
+export function seasonNames(lat) {
+  return lat < 0 ? ['Summer', 'Autumn', 'Winter', 'Spring'] : SEASONS.map(([, name]) => name);
+}
+/** Month-group codes of summer and winter at a latitude. */
+export function summerCode(lat) { return lat < 0 ? 'djf' : 'jja'; }
+export function winterCode(lat) { return lat < 0 ? 'jja' : 'djf'; }
+export function seasonOf(month) {
+  return month === 12 || month <= 2 ? 0 : month <= 5 ? 1 : month <= 8 ? 2 : 3;
+}
+
+/** Open cells within `rings` steps of a building, labelled with its key (multi-source BFS). */
+export function surroundings(ids, heights, cols, rows, rings, isBuilding) {
+  const label = new Int32Array(cols * rows);
+  const dist = new Uint16Array(cols * rows);
+  let queue = [];
+  for (let i = 0; i < ids.length; i++) {
+    if (ids[i] && isBuilding(ids[i])) { label[i] = ids[i]; queue.push(i); }
+  }
+  for (let step = 1; step <= rings && queue.length; step++) {
+    const next = [];
+    for (const i of queue) {
+      const c = i % cols, r = (i - c) / cols;
+      const nb = [c > 0 ? i - 1 : -1, c < cols - 1 ? i + 1 : -1, r > 0 ? i - cols : -1, r < rows - 1 ? i + cols : -1];
+      for (const j of nb) {
+        if (j < 0 || label[j] || ids[j] || heights[j] > 0) continue;
+        label[j] = label[i];
+        dist[j] = step;
+        next.push(j);
+      }
+    }
+    queue = next;
+  }
+  // Building cells themselves are not "surroundings".
+  for (let i = 0; i < ids.length; i++) if (ids[i]) label[i] = 0;
+  return label;
+}
+
+/** A colour range that spreads the actual values (rounded to 5 %). */
+function rangeOf(values) {
+  let lo = Infinity, hi = -Infinity;
+  for (const v of values) { if (v < lo) lo = v; if (v > hi) hi = v; }
+  if (!Number.isFinite(lo)) return { min: 0, max: 100 };
+  return { min: Math.max(0, Math.floor(lo / 5) * 5), max: Math.min(100, Math.max(Math.floor(lo / 5) * 5 + 5, Math.ceil(hi / 5) * 5)) };
+}
+
+/** Mean of a per-cell array over each building's surroundings. */
+function meansByKey(label, values) {
+  const acc = new Map();
+  for (let i = 0; i < label.length; i++) {
+    const k = label[i];
+    if (!k || !Number.isFinite(values[i])) continue;
+    let a = acc.get(k);
+    if (!a) { a = [0, 0]; acc.set(k, a); }
+    a[0] += values[i];
+    a[1]++;
+  }
+  const out = new Map();
+  for (const [k, [s, n]] of acc) out.set(k, s / n);
+  return out;
+}
+
+/**
+ * @param {any} analyst  the Analyst (runners.js)
+ * @param {object} o
+ */
+export async function climateAroundBuildings(analyst, { area, cell, sectors = 8, hourFrom = 7, hourTo = 22, ringMetres = 15, onProgress }) {
+  const app = analyst.app;
+  const w = app.weather;
+  if (!w?.dryBulb) throw new Error('This analysis needs an EPW weather file (Layers > Scene > Load EPW, or pick one in QGIS).');
+  const s = app.site;
+  const prog = (a, b) => (f) => onProgress?.(a + (b - a) * f);
+  // 1. Geometry, surroundings.
+  const og = await analyst.obstacleGrid({ area, cell, onProgress: prog(0, 0.08) });
+  const { grid } = og;
+  const n = grid.cols * grid.rows;
+  const buildingLayers = new Set(app.layers.filter((l) => l instanceof ExtrudedLayer && !l.isWall).map((l) => l.index));
+  const label = surroundings(og.ids, og.heights, grid.cols, grid.rows, Math.max(1, Math.round(ringMetres / cell)),
+    (key) => buildingLayers.has(splitKey(key).layerIndex));
+  // 2. Sky view at pedestrian height.
+  const sky = await analyst.gridRun({ area, cell, directions: skyHemisphere(96), cosMode: 1, lift: 1.1, onProgress: prog(0.08, 0.2) });
+  const svfB = meansByKey(label, sky.values);
+  // 3. Wind per sector from the EPW, sheltering ratio per sector.
+  const sectorFreq = new Float64Array(sectors), sectorSpeed = new Float64Array(sectors);
+  const seasonFreq = SEASONS.map(() => new Float64Array(sectors));
+  const seasonSpeed = SEASONS.map(() => new Float64Array(sectors));
+  const seasonHours = new Float64Array(4), seasonCalm = new Float64Array(4);
+  let calmHours = 0, windowHours = 0;
+  const inWindow = (i) => w.hour[i] - 1 >= hourFrom && w.hour[i] - 1 < hourTo;
+  for (let i = 0; i < w.hours; i++) {
+    if (!inWindow(i)) continue;
+    windowHours++;
+    const sea = seasonOf(w.month[i]);
+    seasonHours[sea]++;
+    if (w.windSpeed[i] < 0.5) { calmHours++; seasonCalm[sea]++; continue; }
+    const k = Math.floor((((w.windDir[i] % 360) + 360) % 360) / (360 / sectors) + 0.5) % sectors;
+    sectorFreq[k]++;
+    sectorSpeed[k] += w.windSpeed[i];
+    seasonFreq[sea][k]++;
+    seasonSpeed[sea][k] += w.windSpeed[i];
+  }
+  const ratioB = new Map(); // key -> Float32Array(sectors)
+  const annualWind = new Float32Array(n);
+  for (let k = 0; k < sectors; k++) {
+    if (!sectorFreq[k]) continue;
+    sectorSpeed[k] /= sectorFreq[k];
+    const ratio = await windRatio({ heights: og.heights, porosity: og.porosity, cols: grid.cols, rows: grid.rows, cell,
+      windFromDeg: (k * 360) / sectors, onProgress: (f) => prog(0.2 + (0.25 * k) / sectors, 0.2 + (0.25 * (k + 1)) / sectors)(f) });
+    const share = sectorFreq[k] / Math.max(1, windowHours);
+    for (let i = 0; i < n; i++) if (Number.isFinite(ratio[i])) annualWind[i] += share * sectorSpeed[k] * ratio[i] * OPEN_PEDESTRIAN_FACTOR;
+    for (const [key, m] of meansByKey(label, ratio)) {
+      if (!ratioB.has(key)) ratioB.set(key, new Float32Array(sectors).fill(1));
+      ratioB.get(key)[k] = m;
+    }
+  }
+  for (let i = 0; i < n; i++) if (og.ids[i] || !Number.isFinite(sky.values[i])) annualWind[i] = NaN;
+  // 4. Sun: coarse sky bins of the window's sun positions; sunlit share per bin.
+  const binOfHour = new Int16Array(w.hours).fill(-1);
+  const bins = new Map();
+  const elevOfHour = new Float32Array(w.hours);
+  for (let i = 0; i < w.hours; i++) {
+    if (!inWindow(i)) continue;
+    const p = solarPosition(typicalDoy(w.month[i], w.day[i]), w.hour[i] - 0.5, s.lat, s.lon, s.utcOffset);
+    elevOfHour[i] = p.elevation / DEG;
+    if (p.elevation <= 1 * DEG) continue;
+    const key = Math.floor(p.elevation / (10 * DEG)) * 100 + Math.floor(p.azimuth / (15 * DEG));
+    let b = bins.get(key);
+    if (!b) { b = { id: bins.size, v: [0, 0, 0] }; bins.set(key, b); }
+    const v = sunVector(p.elevation, p.azimuth);
+    b.v[0] += v[0]; b.v[1] += v[1]; b.v[2] += v[2];
+    binOfHour[i] = b.id;
+  }
+  const binList = [...bins.values()];
+  const sunlitB = new Map(); // key -> Float32Array(bins)
+  for (let j = 0; j < binList.length; j++) {
+    const v = binList[j].v;
+    const len = Math.hypot(v[0], v[1], v[2]) || 1;
+    const run = await analyst.gridRun({ area, cell, directions: [{ dir: [v[0] / len, v[1] / len, v[2] / len], weight: 1 }], lift: 1.1,
+      onProgress: prog(0.45 + (0.4 * j) / binList.length, 0.45 + (0.4 * (j + 1)) / binList.length) });
+    for (const [key, m] of meansByKey(label, run.values)) {
+      if (!sunlitB.has(key)) sunlitB.set(key, new Float32Array(binList.length));
+      sunlitB.get(key)[j] = m;
+    }
+  }
+  // 5. Every hour of the window, for every building.
+  const keys = [...svfB.keys()];
+  const blank = () => ({ comfort: 0, heat: 0, cold: 0, windSum: 0, windy: 0, hours: 0 });
+  const stats = new Map(keys.map((k) => [k, { ...blank(), seasons: SEASONS.map(blank) }]));
+  for (let i = 0; i < w.hours; i++) {
+    if (!inWindow(i)) continue;
+    const ta = w.dryBulb[i], rh = w.rh[i], ws = w.windSpeed[i];
+    const k = ws < 0.5 ? -1 : Math.floor((((w.windDir[i] % 360) + 360) % 360) / (360 / sectors) + 0.5) % sectors;
+    const tSky = skyTemperature(ta, w.ir[i]);
+    const bin = binOfHour[i];
+    const sea = seasonOf(w.month[i]);
+    for (const key of keys) {
+      const svf = svfB.get(key);
+      const r = k < 0 ? 1 : (ratioB.get(key)?.[k] ?? 1);
+      const sunlit = bin >= 0 ? (sunlitB.get(key)?.[bin] ?? 0) : 0;
+      const tr = meanRadiantTemperature({ airTemp: ta, skyTemp: tSky, svf, sunlit, dni: w.dni[i], dhi: w.dhi[i], ghi: w.ghi[i], elevationDeg: elevOfHour[i] });
+      const v10 = Math.max(0.5, Math.min(17, ws * r));
+      const u = utci(ta, tr, v10, rh);
+      const ped = ws * r * OPEN_PEDESTRIAN_FACTOR;
+      const all = stats.get(key);
+      for (const st of [all, all.seasons[sea]]) {
+        st.hours++;
+        if (u >= 9 && u < 26) st.comfort++;
+        else if (u >= 32) st.heat++;
+        else if (u < 0) st.cold++;
+        st.windSum += ped;
+        if (ped > 5) st.windy++;
+      }
+    }
+    if (i % 400 === 0) { onProgress?.(0.85 + (0.15 * i) / w.hours); await new Promise((res) => setTimeout(res, 0)); }
+  }
+  // 6. Fields per building, a comfort halo grid, the wind map.
+  const perLayer = new Map();
+  const field = (layer, name) => {
+    let m = perLayer.get(layer);
+    if (!m) { m = new Map(); perLayer.set(layer, m); }
+    if (!m.has(name)) m.set(name, new Float32Array(layer.count).fill(NaN));
+    return m.get(name);
+  };
+  const comfortOfKey = new Map();
+  const seasonComfortOfKey = SEASONS.map(() => new Map());
+  const seasonal = new Map(); // key -> per-season summary for the report
+  for (const [key, st] of stats) {
+    const { layerIndex, id } = splitKey(key);
+    const layer = app.layers.find((l) => l.index === layerIndex);
+    if (!layer || !st.hours) continue;
+    const f = id - 1;
+    const pct = (100 * st.comfort) / st.hours;
+    comfortOfKey.set(key, pct);
+    field(layer, 'comfort_pct')[f] = pct;
+    field(layer, 'heat_stress_h')[f] = st.heat;
+    field(layer, 'cold_stress_h')[f] = st.cold;
+    field(layer, 'ped_wind_ms')[f] = st.windSum / st.hours;
+    field(layer, 'windy_pct')[f] = (100 * st.windy) / st.hours;
+    field(layer, 'svf_ground')[f] = svfB.get(key);
+    const rows = st.seasons.map((x) => (x.hours ? { comfort: (100 * x.comfort) / x.hours, heat: x.heat, cold: x.cold,
+      wind: x.windSum / x.hours, windy: (100 * x.windy) / x.hours, hours: x.hours } : null));
+    seasonal.set(key, rows);
+    SEASONS.forEach(([code], s) => {
+      if (!rows[s]) return;
+      seasonComfortOfKey[s].set(key, rows[s].comfort);
+      field(layer, `comfort_pct_${code}`)[f] = rows[s].comfort;
+    });
+    const summer = rows[SEASONS.findIndex(([code]) => code === summerCode(s.lat))];
+    const winter = rows[SEASONS.findIndex(([code]) => code === winterCode(s.lat))];
+    if (summer) field(layer, `heat_stress_h_${summerCode(s.lat)}`)[f] = summer.heat;
+    if (winter) {
+      field(layer, `cold_stress_h_${winterCode(s.lat)}`)[f] = winter.cold;
+      field(layer, `ped_wind_ms_${winterCode(s.lat)}`)[f] = winter.wind;
+      field(layer, `windy_pct_${winterCode(s.lat)}`)[f] = winter.windy;
+    }
+  }
+  const fields = [];
+  for (const [layer, m] of perLayer) for (const [name, values] of m) fields.push({ layer, name, values });
+  const haloOf = (map) => {
+    const out = new Float32Array(n).fill(NaN);
+    for (let i = 0; i < n; i++) if (label[i] && map.has(label[i])) out[i] = map.get(label[i]);
+    return out;
+  };
+  const halo = haloOf(comfortOfKey);
+  const haloSeasons = { year: halo };
+  SEASONS.forEach(([code], s) => { haloSeasons[code] = haloOf(seasonComfortOfKey[s]); });
+  const allComfort = [...comfortOfKey.values(), ...seasonComfortOfKey.flatMap((m) => [...m.values()])];
+  // Per-building wind roses for the report.
+  const freq = Array.from(sectorFreq, (x) => x / Math.max(1, windowHours));
+  const names = seasonNames(s.lat);
+  const bySeason = SEASONS.map(([code], k) => ({ code, name: names[k],
+    freq: Array.from(seasonFreq[k], (x) => x / Math.max(1, seasonHours[k])),
+    speed: Array.from(seasonSpeed[k], (x, j) => (seasonFreq[k][j] ? x / seasonFreq[k][j] : 0)),
+    calm: seasonCalm[k] / Math.max(1, seasonHours[k]) }));
+  app.climateRoses = { sectors, freq, speed: Array.from(sectorSpeed), calm: calmHours / Math.max(1, windowHours), ratios: ratioB,
+    window: [hourFrom, hourTo], source: w.location.city || app.weatherSource, bySeason };
+  app.climateSeasonal = seasonal;
+  const windowLabel = `${String(hourFrom).padStart(2, '0')}:00–${String(hourTo).padStart(2, '0')}:00`;
+  let sum = 0, cnt = 0;
+  for (const v of comfortOfKey.values()) { sum += v; cnt++; }
+  let windMax = 1;
+  for (const v of annualWind) if (v > windMax) windMax = v; // no spread: the grid can hold millions of cells
+  return [{
+    kind: 'climate', title: 'Comfortable hours around buildings (year)', subtitle: `${windowLabel}, ${w.location.city || 'EPW'}; UTCI 9–26 °C`,
+    unit: '%', grid, values: halo, ids: og.ids, display: { ...rangeOf(allComfort), ramp: 'rdylbu' }, fields,
+    seasonal: haloSeasons, season: 'year',
+    stats: [['Buildings', String(cnt)], ['Mean comfortable share', `${cnt ? (sum / cnt).toFixed(0) : 0} %`],
+      ['Hours evaluated per building', String(windowHours)], ['Sun positions', String(binList.length)]],
+    notes: 'Each building\'s surroundings: open ground within ' + ringMetres + ' m. Hourly UTCI from the EPW weather with the local sky view, sun and sheltered wind (screening model). Fields: comfort_pct, heat_stress_h, cold_stress_h, ped_wind_ms, windy_pct, svf_ground; per month group (djf = Dec–Feb …) comfort_pct_djf/mam/jja/son; summer heat_stress_h and winter cold_stress_h, ped_wind_ms and windy_pct of the hemisphere\'s summer and winter months.'
+  }, {
+    kind: 'windyear', title: 'Annual pedestrian wind', subtitle: `${windowLabel}, frequency-weighted over ${sectors} directions`,
+    unit: 'm/s', grid, values: annualWind, ids: og.ids, display: { min: 0, max: Math.ceil(windMax), ramp: 'spectral-r' },
+    fields: [], stats: [['Calm hours', `${((100 * calmHours) / Math.max(1, windowHours)).toFixed(0)} %`]],
+    notes: 'Mean of the sheltered pedestrian wind over the year (screening, not CFD).'
+  }];
+}

zero2geospatial3d/web/src/analysis/compliance.js

@@ -0,0 +1,345 @@
+// @ts-check
+// Planning check: pass / fail of each building against sun, daylight, wind
+// and heat criteria, with the analyses it needs run on demand.
+//
+// These are screening proxies of the named guidance, not formal assessments:
+// BRE 209 (Site layout planning for daylight and sunlight, 3rd ed. 2022) asks
+// for VSC on window centres with an overcast sky; here the facade sky view
+// factor stands in for it.
+import { sunPath } from '../core/solar.js';
+import { typicalDoy } from '../core/weather.js';
+import { surroundings, summerCode } from './climate.js';
+import { featureKey, splitKey, ExtrudedLayer } from '../scene/objects.js';
+
+export const CRITERIA = [
+  { id: 'amenity_sun', label: 'Sun on surrounding open ground (21 Mar)', short: 'Amenity sun',
+    unit: '%', test: 'min', threshold: 50,
+    help: 'Share of the open ground within 15 m that gets at least 2 h of sun on 21 March. BRE 209: at least half of an amenity area.' },
+  { id: 'facade_vsc', label: 'Daylight on the walls (VSC)', short: 'Daylight',
+    unit: '%', test: 'min', threshold: 27,
+    help: 'Mean vertical sky component of the walls under the CIE overcast sky. BRE 209: 27 % or more at a window keeps enough daylight (39.6 % is an open wall).' },
+  { id: 'neighbour_daylight', label: 'Daylight kept after scenario B (VSC B / A)', short: 'B / A daylight',
+    unit: '×', test: 'min', threshold: 0.8,
+    help: 'Wall VSC with scenario B divided by that with A. BRE 209: less than 0.8 times the former value is a noticeable loss. Needs "Run A vs B" with daylight (VSC).' },
+  { id: 'wind', label: 'Windy hours around it', short: 'Wind',
+    unit: '%', test: 'max', threshold: 5,
+    help: 'Share of the hours with pedestrian wind above 5 m/s (needs the climate year and an EPW).' },
+  { id: 'heat', label: 'Summer heat-stress hours around it', short: 'Summer heat',
+    unit: 'h', test: 'max', threshold: 300,
+    help: 'Summer hours with UTCI of 32 °C or more on the surrounding ground (needs the climate year and an EPW). The limit is a project choice.' },
+  { id: 'facade_noise', label: 'Max facade noise level (Lden)', short: 'Facade noise',
+    unit: 'dB(A)', test: 'max', threshold: 65,
+    help: 'Highest road traffic noise level at the building perimeter. 65 dB Lden is a common noise action-plan level; the WHO 2018 guideline for road traffic is 53 dB.' },
+  { id: 'green_view', label: 'Green View Index around it (GVI)', short: 'Green view',
+    unit: '%', test: 'min', threshold: 15,
+    help: 'Mean pedestrian-level Green View Index on the surrounding open ground.' },
+  { id: 'air_no2', label: 'Street air quality around it (NO2)', short: 'Air NO2',
+    unit: 'µg/m³', test: 'max', threshold: 40,
+    help: 'Mean street-canyon NO2 concentration on the surrounding open ground. 40 µg/m³ is the EU annual limit; the WHO 2021 guideline is 10 µg/m³.' },
+  { id: 'canyon_vent', label: 'Canyon ventilation efficiency (VEI)', short: 'Ventilation',
+    unit: '', test: 'min', threshold: 0.35,
+    help: 'Mean street-canyon Ventilation Efficiency Index on the surrounding open ground (>= 0.35 avoids stagnant canyon pockets).' },
+  { id: 'solar_roof', label: 'Rooftop solar irradiation', short: 'Solar roof',
+    unit: 'kWh/m²', test: 'min', threshold: 800,
+    help: 'Mean annual solar irradiation on the building roof (>= 800 kWh/m² is suitable for rooftop PV).' }
+];
+
+export const PRESET_PROFILES = [
+  { key: 'defaults', name: 'Defaults (BRE 209 & Urban Environment)',
+    criteria: ['amenity_sun', 'facade_vsc', 'neighbour_daylight', 'wind', 'heat', 'facade_noise', 'green_view'] },
+  { key: 'bre209', name: 'BRE 209 Daylight & Sunlight',
+    criteria: ['amenity_sun', 'facade_vsc', 'neighbour_daylight'] },
+  { key: 'who_health', name: 'WHO Urban Health (Noise, Air, Heat & Green)',
+    criteria: ['heat', 'facade_noise', 'air_no2', 'canyon_vent', 'green_view'],
+    thresholds: { facade_noise: 55, air_no2: 25, green_view: 20 } },
+  { key: 'solar_district', name: 'Solar & Energy-Ready District',
+    criteria: ['amenity_sun', 'facade_vsc', 'solar_roof'],
+    thresholds: { solar_roof: 900 } },
+  { key: 'complete_audit', name: 'Complete 10-Point Urban Audit',
+    criteria: CRITERIA.map((c) => c.id) }
+];
+
+export function presetProfile(key) {
+  const base = defaultProfile();
+  const found = PRESET_PROFILES.find((p) => p.key === key);
+  if (!found) return base;
+  return {
+    name: found.name,
+    criteria: [...found.criteria],
+    thresholds: { ...base.thresholds, ...(found.thresholds || {}) }
+  };
+}
+
+export const PROFILE_FORMAT = '02geo3d-planning-profile';
+// Criteria renamed since a profile may have been saved: the old id switches
+// the new criterion on, but its threshold is not carried over (other units).
+const RENAMED = { facade_daylight: 'facade_vsc' };
+
+/** The built-in profile: every criterion at its default threshold. */
+export function defaultProfile() {
+  return { name: 'Defaults (BRE 209 proxies)', criteria: CRITERIA.map((c) => c.id), thresholds: Object.fromEntries(CRITERIA.map((c) => [c.id, c.threshold])) };
+}
+
+/** A profile as a JSON file: name, the criteria in use and their thresholds. */
+export function profileJson(p) {
+  return JSON.stringify({
+    format: PROFILE_FORMAT, version: 1, name: p.name || 'Planning profile',
+    criteria: CRITERIA.map((c) => ({ id: c.id, label: c.label, unit: c.unit, test: c.test === 'min' ? 'at least' : 'at most',
+      enabled: p.criteria.includes(c.id), threshold: p.thresholds[c.id] ?? c.threshold }))
+  }, null, 2);
+}
+
+/**
+ * Read a profile file. Unknown criteria are ignored, missing ones keep their
+ * default and stay off; a threshold must be a finite number.
+ * @returns {{ name: string, criteria: string[], thresholds: Record<string, number>, ignored: string[] }}
+ */
+export function parseProfile(text) {
+  let data;
+  try { data = typeof text === 'string' ? JSON.parse(text) : text; } catch { throw new Error('This file is not JSON.'); }
+  if (!data || data.format !== PROFILE_FORMAT || !Array.isArray(data.criteria)) throw new Error('This is not a planning-check profile.');
+  const known = new Map(CRITERIA.map((c) => [c.id, c]));
+  const out = defaultProfile();
+  out.name = String(data.name || 'Planning profile').slice(0, 80);
+  out.criteria = [];
+  const ignored = [];
+  for (const item of data.criteria) {
+    const renamed = RENAMED[item?.id];
+    if (renamed) {
+      if (item.enabled !== false && !out.criteria.includes(renamed)) out.criteria.push(renamed);
+      continue;
+    }
+    const c = known.get(item?.id);
+    if (!c) { ignored.push(String(item?.id)); continue; }
+    const v = Number(item.threshold);
+    if (item.threshold !== undefined && item.threshold !== null && Number.isFinite(v)) out.thresholds[c.id] = v;
+    if (item.enabled !== false) out.criteria.push(c.id);
+  }
+  return { ...out, ignored };
+}
+
+/** Pass (true), fail (false) or not available (null) for one value. */
+export function judge(criterion, value) {
+  if (!Number.isFinite(value)) return null;
+  return criterion.test === 'min' ? value >= criterion.threshold : value <= criterion.threshold;
+}
+
+/** Buildings to check: the selection, scenario B layers, all in the area, or a given list ('targets'). */
+export function scopeBuildings(app, scope, targets = null) {
+  if (scope === 'targets') return [...(targets || [])];
+  const out = [];
+  const layers = app.layers.filter((l) => l instanceof ExtrudedLayer && !l.isWall);
+  if (scope === 'selected') {
+    for (const l of layers) for (const f of app.selectedIndices(l)) out.push({ layer: l, f });
+  } else if (scope === 'scenarioB') {
+    for (const l of layers.filter((x) => x.entry.scenario === 'B')) for (let f = 0; f < l.count; f++) out.push({ layer: l, f });
+  } else {
+    const a = app.area();
+    for (const l of layers) {
+      if (!l.visible) continue;
+      for (let f = 0; f < l.count; f++) {
+        const x = l.centroid[f * 2], y = l.centroid[f * 2 + 1];
+        if (x >= a.minX && x <= a.maxX && y >= a.minY && y <= a.maxY) out.push({ layer: l, f });
+      }
+    }
+  }
+  return out;
+}
+
+function areaAround(app, targets, margin = 150) {
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  for (const { layer, f } of targets) {
+    const x = layer.centroid[f * 2], y = layer.centroid[f * 2 + 1];
+    minX = Math.min(minX, x); maxX = Math.max(maxX, x); minY = Math.min(minY, y); maxY = Math.max(maxY, y);
+  }
+  const sc = app.sceneArea();
+  return { minX: Math.max(sc.minX, minX - margin), maxX: Math.min(sc.maxX, maxX + margin),
+    minY: Math.max(sc.minY, minY - margin), maxY: Math.min(sc.maxY, maxY + margin) };
+}
+
+/**
+ * Run the check.
+ * @param {any} app
+ * @param {{ scope: string, criteria: string[], thresholds: Record<string, number>, onProgress?: (f: number) => void }} o
+ */
+export async function planningCheck(app, { scope, criteria, thresholds, profile = '', targets: given = null, fresh = false, onProgress }) {
+  const targets = scopeBuildings(app, scope, given);
+  if (!targets.length) throw new Error(scope === 'selected' ? 'Select buildings first (click, Shift+click, or select them in QGIS).' : 'No buildings to check.');
+  const active = CRITERIA.filter((c) => criteria.includes(c.id)).map((c) => ({ ...c, threshold: thresholds[c.id] ?? c.threshold }));
+  const area = scope === 'area' ? app.area() : areaAround(app, targets);
+  const cell = Math.max(1, Math.min(2, app.analyst.defaultCell(area, 1024)));
+  const a = app.analyst;
+  const values = new Map(active.map((c) => [c.id, new Map()])); // id -> key -> value
+  const keyOf = ({ layer, f }) => featureKey(layer.index, f + 1);
+  const want = new Set(targets.map(keyOf));
+  const step = (k) => (f) => onProgress?.((k + f) / 4);
+  // 1. Amenity sun: 2 h on 21 March over each building's surroundings.
+  if (values.has('amenity_sun')) {
+    const s = app.site;
+    const dirs = sunPath(typicalDoy(3, 21), s.lat, s.lon, s.utcOffset, { stepMinutes: 10 });
+    const run = await a.gridRun({ area, cell, directions: dirs, withIds: true, lift: 0.3, onProgress: step(0) });
+    const label = surroundings(run.ids, new Float32Array(run.ids.length), run.grid.cols, run.grid.rows, Math.round(15 / cell), (k) => want.has(k));
+    const acc = new Map();
+    for (let i = 0; i < label.length; i++) {
+      const k = label[i];
+      if (!k || !Number.isFinite(run.values[i])) continue;
+      const v = acc.get(k) || [0, 0];
+      v[1]++;
+      if (run.values[i] >= 2) v[0]++;
+      acc.set(k, v);
+    }
+    for (const [k, [ok, n]] of acc) values.get('amenity_sun').set(k, (100 * ok) / n);
+  }
+  // 2. Daylight on the walls: vertical sky component.
+  if (values.has('facade_vsc')) {
+    const res = await a.daylightVsc({ area, directions: 192, onProgress: step(1) });
+    for (const fld of res[0].fields) {
+      fld.layer.setResultField(fld.name, fld.values);
+      if (fld.name !== 'vsc_facade') continue;
+      fld.values.forEach((v, i) => { if (Number.isFinite(v)) values.get('facade_vsc').set(featureKey(fld.layer.index, i + 1), v); });
+    }
+  }
+  // 3. Neighbour daylight after scenario B (from a previous "Run A vs B" with daylight).
+  if (values.has('neighbour_daylight')) {
+    for (const t of targets) {
+      const A = t.layer.extraFields.get('vsc_facade_A')?.[t.f];
+      const B = t.layer.extraFields.get('vsc_facade_B')?.[t.f];
+      if (Number.isFinite(A) && Number.isFinite(B) && A > 0) values.get('neighbour_daylight').set(keyOf(t), B / A);
+    }
+  }
+  // 4-5. Wind and summer heat from the climate year (run it if an EPW exists).
+  const needClimate = values.has('wind') || values.has('heat');
+  if (needClimate && app.weather?.dryBulb) {
+    // fresh: heights have changed since the stored climate fields were made.
+    const missing = fresh || targets.some((t) => !Number.isFinite(t.layer.extraFields.get('windy_pct')?.[t.f]));
+    if (missing) {
+      const res = await a.climateYear({ area, cell: Math.max(2, cell), sectors: 8, hourFrom: 7, hourTo: 22, ringMetres: 15, onProgress: step(2) });
+      for (const fld of res[0].fields) fld.layer.setResultField(fld.name, fld.values);
+    }
+    for (const t of targets) {
+      const k = keyOf(t);
+      if (values.has('wind')) values.get('wind').set(k, t.layer.extraFields.get('windy_pct')?.[t.f]);
+      if (values.has('heat')) values.get('heat').set(k, t.layer.extraFields.get(`heat_stress_h_${summerCode(app.site.lat)}`)?.[t.f]);
+    }
+  }
+  // 6. Facade noise level (Lden).
+  if (values.has('facade_noise')) {
+    const missing = fresh || targets.some((t) => !Number.isFinite(t.layer.extraFields.get('noise_dba_max')?.[t.f]));
+    if (missing) {
+      const res = await a.noise({ area, cell: Math.max(2, cell) });
+      for (const fld of res[0].fields) fld.layer.setResultField(fld.name, fld.values);
+    }
+    for (const t of targets) {
+      values.get('facade_noise').set(keyOf(t), t.layer.extraFields.get('noise_dba_max')?.[t.f]);
+    }
+  }
+  // 7. Green View Index (GVI).
+  if (values.has('green_view')) {
+    const missing = fresh || targets.some((t) => !Number.isFinite(t.layer.extraFields.get('gvi_pct')?.[t.f]));
+    if (missing) {
+      const res = await a.greenView({ area, cell: Math.max(2, cell) });
+      for (const fld of res[0].fields) fld.layer.setResultField(fld.name, fld.values);
+    }
+    for (const t of targets) {
+      values.get('green_view').set(keyOf(t), t.layer.extraFields.get('gvi_pct')?.[t.f]);
+    }
+  }
+  // 8-9. Street air quality (NO2) and canyon ventilation efficiency (VEI).
+  if (values.has('air_no2') || values.has('canyon_vent')) {
+    const missing = fresh || targets.some((t) => (
+      (values.has('air_no2') && !Number.isFinite(t.layer.extraFields.get('air_no2_ugm3')?.[t.f])) ||
+      (values.has('canyon_vent') && !Number.isFinite(t.layer.extraFields.get('vent_index')?.[t.f]))
+    ));
+    if (missing) {
+      const res = await a.ventilation({ area, cell: Math.max(2, cell) });
+      for (const item of res) {
+        for (const fld of item.fields || []) fld.layer.setResultField(fld.name, fld.values);
+      }
+    }
+    for (const t of targets) {
+      const k = keyOf(t);
+      if (values.has('air_no2')) values.get('air_no2').set(k, t.layer.extraFields.get('air_no2_ugm3')?.[t.f]);
+      if (values.has('canyon_vent')) values.get('canyon_vent').set(k, t.layer.extraFields.get('vent_index')?.[t.f]);
+    }
+  }
+  // 10. Rooftop solar irradiation (kWh/m²).
+  if (values.has('solar_roof')) {
+    const missing = fresh || targets.some((t) => !Number.isFinite(t.layer.extraFields.get('roof_kwh_m2')?.[t.f]));
+    if (missing) {
+      const res = await a.solarRadiation({ area, cell: Math.max(2, cell) });
+      for (const fld of res[0].fields) fld.layer.setResultField(fld.name, fld.values);
+    }
+    for (const t of targets) {
+      values.get('solar_roof').set(keyOf(t), t.layer.extraFields.get('roof_kwh_m2')?.[t.f]);
+    }
+  }
+  onProgress?.(1);
+  // Verdicts.
+  const rows = targets.map((t) => {
+    const k = keyOf(t);
+    const props = t.layer.features[t.f].properties;
+    const checks = active.map((c) => {
+      const v = values.get(c.id).get(k);
+      return { id: c.id, value: Number.isFinite(v) ? v : NaN, pass: judge(c, v) };
+    });
+    const failed = checks.filter((c) => c.pass === false).length;
+    const passed = checks.filter((c) => c.pass === true).length;
+    return { key: k, layer: t.layer, f: t.f, name: String(props.name || props.NAME || `#${t.f + 1}`), height: t.layer.heights[t.f], checks, failed, passed };
+  });
+  rows.sort((p, q) => q.failed - p.failed || p.name.localeCompare(q.name));
+  // Fields: per criterion 1 / 0, and the number failed.
+  const fields = [];
+  const byLayer = new Map();
+  for (const r of rows) {
+    let m = byLayer.get(r.layer);
+    if (!m) {
+      m = { failed: new Float32Array(r.layer.count).fill(NaN), per: new Map(active.map((c) => [c.id, new Float32Array(r.layer.count).fill(NaN)])) };
+      byLayer.set(r.layer, m);
+    }
+    m.failed[r.f] = r.failed;
+    for (const ch of r.checks) if (ch.pass !== null) m.per.get(ch.id)[r.f] = ch.pass ? 1 : 0;
+  }
+  for (const [layer, m] of byLayer) {
+    fields.push({ layer, name: 'check_failed', values: m.failed });
+    for (const [id, v] of m.per) fields.push({ layer, name: `check_${id}`, values: v });
+  }
+  const passAll = rows.filter((r) => r.failed === 0 && r.passed > 0).length;
+  const stats = [['Buildings checked', String(rows.length)], ['Pass every available check', `${passAll} (${Math.round((100 * passAll) / rows.length)} %)`]];
+  for (const c of active) {
+    const judged = rows.map((r) => r.checks.find((x) => x.id === c.id)).filter((x) => x.pass !== null);
+    stats.push([c.short, judged.length ? `${judged.filter((x) => x.pass).length} / ${judged.length} pass` : 'n/a']);
+  }
+  const result = {
+    kind: 'compliance', title: 'Planning check', subtitle: `${rows.length} buildings · ${active.length} criteria`, unit: '',
+    fields, stats, rows, criteria: active, scope, profile,
+    legend: [{ color: '#2e9e5b', label: 'Passes every check' }, { color: '#f0b429', label: 'Fails one' }, { color: '#d64545', label: 'Fails two or more' },
+      { color: '#c9c9c9', label: 'Not checked' }],
+    notes: 'Screening proxies of the named guidance (BRE 209 for sun and daylight); confirm borderline cases with a formal assessment.'
+  };
+  // In QGIS: the same three colours on check_failed, in 2D and in the 3D view.
+  const hex = (rgb) => `#${rgb.map((x) => Math.round(x * 255).toString(16).padStart(2, '0')).join('')}`;
+  result.qgisStyle = {
+    field: 'check_failed',
+    categories: [{ value: 0, color: hex(VERDICT[0]), label: 'Passes every check' }, { value: 1, color: hex(VERDICT[1]), label: 'Fails one' },
+      ...[2, 3, 4, 5].map((k) => ({ value: k, color: hex(VERDICT[2]), label: `Fails ${k} checks` }))],
+    other: { color: '#c9c9c9', label: 'Not checked' }
+  };
+  // Show it as building colours while the result is on screen.
+  result.onShow = () => paintVerdicts(app, rows);
+  result.onHide = () => { for (const l of app.layers) if (l instanceof ExtrudedLayer) app.recolor(l); };
+  return [result];
+}
+
+const VERDICT = { 0: [0.18, 0.62, 0.36], 1: [0.94, 0.71, 0.16], 2: [0.84, 0.27, 0.27] };
+function paintVerdicts(app, rows) {
+  const touched = new Set();
+  for (const l of app.layers) {
+    if (!(l instanceof ExtrudedLayer) || l.isWall) continue;
+    for (let f = 0; f < l.count; f++) l.colors.set([0.79, 0.79, 0.79], f * 3);
+    touched.add(l);
+  }
+  for (const r of rows) r.layer.colors.set(VERDICT[Math.min(2, r.failed)], r.f * 3);
+  for (const l of touched) l.applyColors();
+}
+
+export { splitKey };