FireViewer Spatial contains the deterministic tooling and contracts used to build, validate, package and consume measured geographic maps and observed temporal spatial layers.
This repository is not an emergency-response system, an official geographic authority or a certified fire-propagation predictor. A valid package proves only the checks recorded by its own manifests and receipts.
The spatial subsystem is deliberately separate from evidence acquisition, visual detection, multimodal assessment and Part.4 fire-state reconstruction.
flowchart TD
sources["Measured geographic sources and immutable revisions"] --> maps["Part.1: deterministic tiled map production"]
maps --> packages["OpenUSD and web-view packages"]
packages --> checks["Structural, geometric, provenance and visual gates"]
checks --> consumer["Backend and 2D or 3D consumers"]
observations["Reviewed temporal geographic inputs"] --> timeline["Separate perimeter timeline package"]
timeline --> consumer
Incident observations and reconstructed fire states can later reference a measured map, but they do not rewrite the map itself.
- measured terrain grids and elevation handling;
- orthophoto-derived ground textures under explicit source/provenance rules;
- deterministic levels of detail;
- explicit GPS asset placement and placement inventories;
- portable OpenUSD scene composition and package manifests;
- resumable tile-sharded Map Builder execution with deterministic checkpoint ownership;
- dependent final assembly after shard completion;
- tiled browser packages with progressive terrain/placement loading and shared prototypes;
- asset-free production that preserves an explicitly empty prototype namespace across resume;
- observed affected/active temporal layers without silently inventing missing observations;
- consumer schemas that pin package, revision, build, contract and hash;
- structural, geographic, provenance, dependency, size and human-review gates;
- provider-specific deployment adapters kept outside the deterministic core contracts.
The Map Builder receives an immutable request, a caller-provided scratch directory and an output directory. Cloud launch, object storage, credentials and publication are execution adapters rather than part of the geographic contract.
The terminal completion receipt is written last. A partial output without its required completion state must not be presented as a valid production map.
A successful unit test, container run or cloud replay does not qualify every map size, source condition, browser or publication route.
Real retained measured-map packages are hosted in:
fireviewer/simple-measured-scenes-v1
Current retained production includes Die / Justin in Drôme, France.
Existing published map directories, filenames and package paths can be consumed directly by the FireViewer viewer and other clients.
Do not rename, move, flatten or reorganise existing published map packages as part of repository/documentation cleanup.
A structural migration requires an explicit versioned migration contract and coordinated updates to every consumer.
The repository currently retains reference/map-builder-reference-v1.
This directory is a semantic validation baseline for the AWS Map Builder migration, containing request identity, hashes, metrics and validation receipts. It is not a production map and must not be listed as one.
It is intentionally left at its current path. Moving it merely to make the tree look cleaner would create unnecessary compatibility risk and is outside the documentation update.
FireViewer keeps these concepts separate:
- measured map — geographic context produced from measured source products;
- observation — dated evidence about a wildfire or its environment;
- Part.4 3.3 reconstruction — deterministic probabilistic fire-state reconstruction from reviewed spatial observations;
- simulation — generated scenario or reproduction material;
- viewer derivative — runtime representation optimised for exploration.
A viewer GLB never replaces authoritative map/source contracts. A simulation never becomes measured geography or real-event evidence.
Daily fire-state reconstruction belongs to the backend's Part.4 3.3, not this map builder. It uses a private dated spatial seed and an uncalibrated fusion profile. Map and timeline tooling must not be described as autonomous perimeter inference, and a valid map package does not qualify a reconstructed fire state. See the reconstruction boundary.
- Geographic map, temporal wildfire state, simulation and visualisation remain separate.
- Observed affected and active areas remain distinct.
- Unknown state between observations is represented as unknown or explicitly reconstructed, not silently treated as observation.
- Consumers reference immutable artifacts rather than rebuilding them implicitly.
- Derived viewer files do not replace authoritative JSON/GeoJSON/OpenUSD provenance.
- Deliverables keep source, licence, contract, revision and SHA-256 provenance where applicable.
- Temporary source rasters are not silently redistributed in final packages.
- Synthetic tests, cloud execution and human visual acceptance are separate gates.
blender/README.md— measured-map and temporal-layer production modules.contracts/spatial/v1— immutable consumer references.contracts/terrain/v1— active terrain/spatial contracts.contracts/spatial/provenance— generated-package provenance.omniverse/contracts/v2— Omniverse composition boundary; not measured-map publication.reference/map-builder-reference-v1— validation/migration baseline, not a production map.
A safe contract smoke that does not start map production is:
python -m pytest -q test_scene_consumer_contract.pySubsystem tests require the dependencies named by their corresponding requirements files. Cloud acquisition, Blender import, OpenUSD/Kit validation, rendering and final visual review remain separate acceptance gates.
Generated production packages and source rasters are not committed to the source repository. Infrastructure state, credentials, private requests and operator-specific values remain untracked.
The canonical FireViewer documentation defines the cross-project architecture, resource status, evidence rules and current maturity.
Code is licensed under AGPL-3.0-or-later. Original documentation is available under CC BY 4.0. Geographic sources and 3D assets retain their own licences and attribution requirements.
See SECURITY.md for responsible disclosure.
Research, mapping, provenance, rights or infrastructure: unicornwhodev@gmail.com.