Import_algorithm

ℹ️ Updated to qgis2fds 2.0.x

NIST FDS > Import FDS results converts supported calculated FDS output into georeferenced, temporal QGIS mesh layers. Use it after running FDS when you want to inspect wildfire spread, temperature, velocity, or another AGL slice quantity on the map. For case generation, see Export algorithm.

The importer reads an existing case. It does not run FDS, change the .fds input, alter any FDS result file, or save the QGIS project.

Processing stages

The importer performs five stages:

1. resolve the case folder and require <chid>.fds and <chid>.smv;
2. read ORIGIN_LAT, ORIGIN_LON, and NORTH_BEARING, then reconstruct the FDS mesh grids from the Smokeview manifest;
3. import every SLCF result declared with AGL_SLICE, at every available height and complete time frame;
4. import FIRE ARRIVAL TIME, FIRE RESIDENCE TIME, and LS SPREAD RATE BNDF results;
5. persist one georeferenced UGRID NetCDF file per dataset and add one temporal QGIS mesh layer per file.

Messages prefixed with [qgis2fds] identify the active stage and report the input directory, georeferencing, manifest contents, imported mesh sizes, dataset counts, and persistent output directory.

What is imported

The importer discovers data from the case's Smokeview manifest rather than guessing result filenames.

FDS output	Imported quantities	QGIS representation
SLCF with AGL_SLICE	Every quantity and every AGL height listed in the manifest	One temporal quadrilateral mesh layer per quantity and height
Structured BNDF	FIRE ARRIVAL TIME, FIRE RESIDENCE TIME, and LS SPREAD RATE	One temporal mesh layer per quantity, using horizontal boundary patches
GEOM boundary output (BNDE)	The same three wildfire quantities	One temporal triangular mesh layer per quantity on the actual GEOM terrain faces

Ordinary PBX, PBY, and PBZ slices are not imported. Cell-centred BNDC boundary output is not currently supported.

All SLCF AGL slice quantities of the FDS case are imported.

U-VELOCITY, V-VELOCITY, and W-VELOCITY remain separate scalar layers. U and V retain the components calculated along the local FDS X and Y axes. When both exist at the same AGL height, qgis2fds additionally combines them into one horizontal UV-VELOCITY vector layer and rotates that vector to UTM east and north. Other quantities remain scalar layers.

Files required from the FDS case

Set chid and fds_path to the same values used by the exporter. The case folder must contain:

• <chid>.fds, containing active ORIGIN_LAT, ORIGIN_LON, and NORTH_BEARING values in MISC;
• <chid>.smv, created by FDS and used as the authoritative manifest and mesh-grid description;
• every result file referenced by the manifest for the supported datasets being imported.

Depending on the terrain and output representation, the referenced files can include:

• .sf files for AGL slices;
• .bf files for structured boundary output;
• geometry-boundary files, normally .be, together with .gcf GEOM topology files.

These files should be in their original FDS case directory. FDS creates them when the simulation is started. Run FDS before using the importer.

Run the importer in QGIS

1. Open the QGIS project associated with the case.
2. Save the project if fds_path is relative, such as ./FDS.
3. Open the Processing Toolbox and expand NIST FDS.
4. Double-click Import FDS results.
5. Set the two parameters:

Exact QGIS label	Processing key	Example
FDS case identifier (CHID)	chid	golden_gate
FDS case folder	fds_path	./FDS

6. Click Run and review the messages beginning with [qgis2fds].

One run imports all supported datasets and all complete frames advertised by the manifest. There are no quantity, height, mesh, or time selectors.

After a successful run, every imported dataset appears as a separate mesh layer at the root of the Layers panel. qgis2fds activates the imported scalar or vector dataset group and enables temporal properties. Use the QGIS Temporal Controller to move through the calculated frames, and use Layer Properties > Symbology to choose a color ramp, value range, contours, or vector display.

Save the QGIS project manually if you want the new layer links and their styles to remain in the project.

How georeferencing is reconstructed

FDS result coordinates are metric offsets in the case's local X/Y system. They are not stored as UTM eastings and northings. qgis2fds reconstructs their map position as follows:

1. read ORIGIN_LAT, ORIGIN_LON, and NORTH_BEARING from the active MISC namelist in <chid>.fds;
2. select the local UTM CRS from the origin, using the same Norway and Svalbard exceptions as the exporter;
3. transform the WGS 84 origin to that UTM CRS;
4. calculate UTM true north at the origin;
5. rotate each FDS X/Y coordinate by the difference between the recorded NORTH_BEARING and UTM true north;
6. translate the rotated coordinate by the UTM origin easting and northing.

For FDS coordinate (x, y), UTM origin (E0, N0), and calculated rotation β, the horizontal transformation is:

E = E0 + x cos(β) - y sin(β)
N = N0 + x sin(β) + y cos(β)

The resulting local UTM CRS is embedded in every output NetCDF file. Horizontal velocity vectors receive the same rotation so their components point along UTM east and north.

How files become mesh layers

The import pipeline is:

• .fds: geographic origin and north bearing
• .smv: meshes, quantities, filenames
• .sf files: AGL values and frame times
• .bf files: boundary values and frame times
• .gcf + .be files: GEOM topology, values, times

become one temporal UGRID file and QGIS layer per dataset.

AGL entries from all FDS meshes are assembled into one quadrilateral frame for each AGL height. Each quantity at that height is written as a separate layer. Values are attached to mesh vertices.

For wildfire boundary output, qgis2fds prefers a complete GEOM result set when FDS advertises both GEOM and structured files. GEOM topology is read from the .gcf files, values are attached to triangular faces, and duplicate structured output is not imported. Otherwise, horizontal structured boundary patches become quadrilateral faces with values on vertices; vertical patches are omitted because they collapse to lines in a 2D map.

All files contributing to one dataset must describe the same FDS meshes, topology, and time frames. qgis2fds stops if quantities or component files disagree rather than silently combining incompatible results.

Temporal data

Every complete time frame is imported. If FDS is still writing a final Fortran record when the importer reads it, qgis2fds ignores that incomplete trailing frame and reports a warning. Earlier complete frames remain usable.

The NetCDF writer uses 1970-01-01 UTC as a technical reference time because FDS times are elapsed simulation seconds rather than calendar dates. FDS seconds are converted to the hours expected by the mesh provider; the relative time and spacing between frames are preserved.

For the most reproducible result, run the importer after FDS finishes. To refresh data from a longer or completed simulation, run the importer again; the new run receives a new output directory and does not replace the earlier import.

Generated files and layer names

The first import writes below:

<fds_path>/<chid>_qgis_results/

If that directory already exists, qgis2fds creates <chid>_qgis_results_2, then _3, and so on. It does not cache or reuse an older imported dataset.

Each QGIS mesh layer is backed by one standalone UGRID NetCDF file. Typical outputs are:

golden_gate_qgis_results/
├── golden_gate_SLCF_AGL_5_level_set_value.nc
├── golden_gate_SLCF_AGL_5_temperature.nc
├── golden_gate_SLCF_AGL_5_uv_velocity.nc
├── golden_gate_SLCF_AGL_5_u_velocity.nc
├── golden_gate_SLCF_AGL_5_v_velocity.nc
├── golden_gate_SLCF_AGL_5_w_velocity.nc
├── golden_gate_BNDF_fire_arrival_time.nc
├── golden_gate_BNDF_fire_residence_time.nc
└── golden_gate_BNDF_ls_spread_rate.nc

Only files for quantities actually produced by FDS are created. Layer names follow the same information, for example:

golden_gate SLCF AGL=5 — TEMPERATURE
golden_gate SLCF AGL=5 — UV-VELOCITY
golden_gate SLCF AGL=5 — U-VELOCITY
golden_gate SLCF AGL=5 — V-VELOCITY
golden_gate BNDF — FIRE ARRIVAL TIME

The MDAL UGRID provider also creates a static Bed Elevation dataset group for the mesh frame. This is normal. qgis2fds activates the imported result group automatically; you can switch dataset groups in the mesh layer's Symbology properties.

Diagnostics and failure behavior

Processing feedback reports five stages: reading parameters, reading case georeferencing, importing AGL slices, importing wildfire boundary results, and finalizing the layers. It also reports the selected CRS, rotation, manifest counts, mesh dimensions, number of dataset layers, output folder, and incomplete-frame warnings.

Layers are added to the QGIS project only after every selected result has been read and persisted successfully. A late error therefore does not leave a partially populated Layers panel. Files already written to the run's unique output directory can remain on disk after such an error and may be removed manually when they are no longer needed.

For error messages and remedies, see Recover from errors. For command-line use, see Scripting.

Current limitations

• Only SLCF entries with AGL are imported; ordinary planar slices are ignored.
• Wildfire BNDF import is limited to FIRE ARRIVAL TIME, FIRE RESIDENCE TIME, and LS SPREAD RATE.
• Cell-centred BNDC output is not supported; use vertex-centred BNDF output.
• There are no dataset or time filters, so large cases can require substantial memory, processing time, and disk space.
• One NetCDF file is written per dataset. This keeps every QGIS layer independent, but duplicates the mesh frame between quantities.