Fire scene and synthetic trees ============================== Purpose ------- The fire scene turns a P144 fire run and a synthetic individual-tree inventory into a portable 3D package: a tree table, stand squares, fire events, a per-tree ignition schedule, a manifest, and a standalone viewer. The scene is a run artifact. It does not change the compiled dataset, the ecosystem package, or the event log. The tree layer is synthetic. The polygons and the fire event log are the authoritative pieces. Every scene manifest says so. Real VRI polygons can replace the built-in square footprints through the Nemora adapter. Tree inventory -------------- ``ws4.tree.inventory.v1`` is a table with one row per tree: .. list-table:: :header-rows: 1 :widths: 24 16 60 * - Column - Type - Meaning * - ``tree_id`` - string - Stable id within the scene. * - ``fragment_id`` - integer - The WS4 fragment the tree belongs to. * - ``x``, ``y``, ``z`` - number - Scene coordinates in metres. ``z`` is the ground elevation. * - ``species`` - string - Species label. * - ``dbh_cm`` - number - Diameter at breast height. * - ``height_m`` - number - Total height. * - ``crown_ratio`` - number - Live crown length divided by height, in [0, 1]. * - ``crown_radius_m`` - number - Crown radius. * - ``live`` - boolean - Live or dead at scene start. * - ``decay_class`` - integer - Dead-wood decay class, 0 for live. * - ``crown_fuel_t`` - number - Crown fuel mass in tonnes. * - ``surface_fuel_t_ha`` - number - Local surface fuel load. * - ``snag_t`` - number - Standing dead mass in tonnes. * - ``provenance`` - string - Generator provenance label. The built-in generator places trees uniformly inside each fragment's synthetic square, draws a lognormal DBH, derives height and crown size from DBH, and assigns a crown fuel mass. A fragment is a square whose side is ``sqrt(area_ha * 10000)`` metres; the fragments are laid out in a near-square grid unless explicit origins are supplied. The generator is seeded per fragment, so the same area map and seed reproduce the same tree table. ``TreeInventory`` also carries optional ``fragment_polygons``. When present, each fragment has a real exterior ring and ``bounds_violations`` checks the polygon, not a square. Nemora adapter -------------- ``ws4.scene.nemora`` adapts a Nemora tree table without importing Nemora at runtime: - ``load_vri_polygons`` reads a GeoJSON FeatureCollection and keeps each Polygon or the largest part of a MultiPolygon; - ``load_nemora_tree_table`` reads CSV or Parquet and normalizes aliases such as ``dbh`` to ``dbh_cm`` and ``height`` to ``height_m``; - ``trees_from_nemora`` places every tree in its VRI polygon, either from an explicit ``fragment_id`` or by point-in-polygon, and raises if the assignment is missing or ambiguous; - ``load_nemora_scene`` is the file-level entry point. The inventory source records the adapter version, Nemora version, seed, polygon source, and CRS. Missing fuel columns get documented defaults: crown fuel is ``0.2 × biomass`` when biomass exists, otherwise ``0.0015 × DBH²``; surface fuel defaults to 10 t/ha; snag load defaults to zero. These are placeholders, not a calibrated fuel model. The adapter is thin on purpose. Nemora's API is external and may change; WS4 reads the exported table and keeps the contract at the file boundary. Scene package ------------- ``ws4.fire.scene.v1`` writes: .. code-block:: text fire_scene/ manifest.json # schema, seed, replay digest, counts, synthetic flag trees.parquet # the tree inventory stands.parquet # fragment polygons, area, origin, burn time fires.csv # the fire events used by the viewer animation.parquet # per-tree ignition, burn duration, intensity, state event_log.json # the full P144 event log summary.json # counts, tree summary, timeline end payload.json # compact bounds/stands/trees/fires/timeline payload viewer.html # standalone viewer with the scene data embedded The manifest records the fire run's replay digest, the scenario, the tree generator, the seed, the particle budget, the burn duration, and the scene time unit. The animation can use the fragment event time or a P156 growth field sampled at each tree position. With the growth field, each tree gets its own cell arrival time and the front moves continuously through the stand. The event log remains the authority for the fragment-level outcome. The scene clock defaults to years for the annual P144 event path. A growth-driven scene can set ``time_unit="minutes"``; the demo uses minutes since ignition, a two-minute tree burn, and a timeline of about 122 minutes. Viewer ------ ``viewer.html`` is a standalone page. It embeds the scene JSON, so it opens from a local file without a server. It uses Three.js from a CDN, so the first slice needs internet access for the module. Web workspace ------------- The WS4 web service discovers a completed scene in a run directory when it contains ``fire_scene/manifest.json`` (or ``fire-scene``, ``fire``, or ``scene``) with schema version ``ws4.fire.scene.v1``. The read-only endpoints are: - ``GET /api/fire/scenes``: discovered scenes and manifest summaries; - ``GET /api/fire/runs/{run}``: one scene manifest and summary; - ``GET /api/fire/runs/{run}/payload``: the compact viewer payload from ``payload.json``; - ``GET /api/fire/runs/{run}/viewer``: the viewer with the vendored Three.js paths; - ``GET /api/fire/observed/dogrib.svg``: the read-only Dogrib observed-versus-simulated validation view. The **Fire** workspace shows the scene over the main canvas, with a shared timeline, play/pause, speed, camera controls, tree and fragment inspection, and side-by-side Scene A and Scene B comparison. The viewer accepts ``?embedded=1`` and a small ``postMessage`` API so the workspace timeline can drive both scenes. An **Observed comparison** button opens the Dogrib validation SVG in a new tab. The standalone viewer keeps its CDN module import; the served web viewer uses the local vendored Three.js module. The viewer provides: - an orbit camera over the landscape; - instanced trees with species colours and live, burning, scorched, torched, and consumed states; - a Play/Pause timeline with speed control and a scrubber; - procedural flame particles with a noise/temperature shader and additive blending; - smoke particles with curl-like wander and buoyancy; - short-lived embers near the active front; - a screen-space heat-haze pass and an optional bloom pass (``?bloom=0`` disables bloom); - a fire light and a gradual burnt-scar tint on the stands; - outcome-aware crowns: scorched trees keep their crown, torched trees shrink and darken, and consumed trees collapse to a charred remnant; - a Focus fire button that frames the active front; - tree/fragment counts, a burning/burnt readout, active particle count, and fps. The viewer is a visual prototype, not a calibrated fire-behaviour or tree-mortality model. The flames and smoke are procedural; flame intensity and smoke scale with the local P156 directional ROS when a growth field is supplied. Scorched/torched/consumed are visual classes derived from local flame length against crown base and tree height; they are not a validated mortality prediction. The burn duration is a scene parameter. Example ------- .. code-block:: bash python examples/fire_3d_demo.py The script builds a synthetic landscape, runs the P156 FBP growth field, samples the field at 22,500 tree positions, and writes ``tmp/fire-3d-demo/viewer.html``. Open that file in a browser with WebGL2. Programmatically: .. code-block:: python from ws4.scene import load_nemora_scene, sample_tree_ignition trees = load_nemora_scene( "nemora_trees.csv", "vri_polygons.geojson", seed=7, source="public-vri", crs="EPSG:3005", nemora_version="0.3.0", ) animation = sample_tree_ignition(trees, growth, cell_size_m=5.0, burn_duration=2.0) Real VRI cluster ---------------- .. code-block:: bash python examples/fire_3d_vri_demo.py The VRI demo uses a 12-polygon cluster from the public TSA 24 block geometry in ``examples/fire_scene_vri``. The polygons are translated to a local origin and populated with 12,588 Nemora-placed synthetic stems at 120 stems/ha. The growth grid is masked to the polygons, so the fire front follows the real stand shapes instead of a square grid. The current result is 95.42 ha burned, 27.07 m/min head ROS, 8.40 m flame length, and a 0–240 minute ignition window. The manifest records the VRI source, the Nemora adapter version, the seed, and the synthetic-tree flag. Validation ---------- - The same areas and seed reproduce the same tree table and scene. - Every generated tree lies inside its fragment square or VRI polygon. - A tree outside its VRI polygon raises an adapter error. - The Nemora adapter records the adapter version, Nemora version, seed, polygon source, and CRS. - A growth-driven scene samples the cell arrival time at each tree and reports per-tree ignition times. - The tree summary reports stems per hectare, basal area, and mean size. - Every animated ignition maps to a fire event; the manifest carries the event-log replay digest. - The scene package writes every listed file and the viewer opens without a JavaScript error. - The visual check is manual: play the timeline and confirm the fire front, flames, smoke, burnt scar, and post-fire tree state. Current limits -------------- - The tree layer is synthetic and is not a VRI inventory measurement. - The built-in generator uses square fragment footprints. The Nemora adapter accepts real VRI polygons, but the tree allometry and fuel defaults are placeholders, not a calibration. - Flames, smoke, embers, heat haze, and bloom are implemented as a procedural real-time slice. They are not a CFD solver or a photoreal VFX shot. Distance-based tree LOD and an offline high-fidelity smoke tier are not implemented. - The P155.3 visual checklist is `notes/reports/p155-visual-checklist.md`; the headless frame-rate capture used SwiftShader and is a floor, not a hardware measurement. - The viewer uses a CDN for Three.js. The WS4 web Fire workspace and a vendored module are P155.4. - The burn duration, intensities, and particle counts are scene parameters, not a fire physics calibration. Cross-references ---------------- - :doc:`ecosystem-fire` - :doc:`ecosystem-scenarios` - :doc:`ecosystem-package` - :doc:`../concepts/the-simulation`