Create QUIC-Fire Input Files

QUIC-Fire requires the following gridded binary input files to run a fire simulation with custom fuels and topography data:

• treesrhof.dat: Fuel bulk density (kg/m^3).
• treesmoist.dat: Fuel moisture content (unitless).
• treesfueldepth.dat: Surface fuel bed depth (m).
• topo.dat: Elevation (m).

The FastFuels API provides a way to create these input files by aligning common data sources to a common grid and format, and then writing the data to the required binary format for QUIC-Fire. This tutorial walks users through the process of creating fuels and topography data for a small area in the Blue Mountain Recreation Area south of Missoula, Montana, and exporting the data to the required QUIC-Fire input files for a fire simulation.

Tutorial

1. Obtain a GeoJSON for your Region of Interest

   Spatial data is passed to the API via the GeoJSON format. You can use a tool like geojson.io to create a GeoJSON file for your region of interest. Or, many GIS software packages can export data to the GeoJSON format.

   The GeoJSON we will use for this tutorial is a simple polygon encapsulated in a FeatureCollection for an area in the Blue Mountain Recreation Area south of Missoula, Montana.

   GeoJSON

   {
     "type": "FeatureCollection",
     "features": [
       {
         "type": "Feature",
         "properties": {},
         "geometry": {
           "coordinates": [
             [
               [-114.09957018646286, 46.82933208815811],
               [-114.10141707482919, 46.828370407248826],
               [-114.10010954324228, 46.82690548814563],
               [-114.09560673134018, 46.8271123684554],
               [-114.09592544216444, 46.829058122675065],
               [-114.09957018646286, 46.82933208815811]
             ]
           ],
           "type": "Polygon"
         }
       }
     ]
   }

   Map
   

2. Create a Domain Resource

   Submit a POST request to the /v1/domains endpoint with the GeoJSON, in addition to name, description, and resolution fields in the request body.

   Note

   Replace the api-key header my-api-key with your API key. Future API calls in this tutorial will also require this header with a valid API key.

   curl

   Create Domain Resource API Call

       curl -X 'POST' \
       'https://api.fastfuels.silvxlabs.com/v1/domains' \
       -H 'accept: application/json' \
       -H 'api-key: my-api-key' \
       -H 'Content-Type: application/json' \
       -d '{
       "type": "FeatureCollection",
       "features": [
           {
           "type": "Feature",
           "properties": {},
           "geometry": {
               "coordinates": [
               [
                   [
                   -114.09957018646286,
                   46.82933208815811
                   ],
                   [
                   -114.10141707482919,
                   46.828370407248826
                   ],
                   [
                   -114.10010954324228,
                   46.82690548814563
                   ],
                   [
                   -114.09560673134018,
                   46.8271123684554
                   ],
                   [
                   -114.09592544216444,
                   46.829058122675065
                   ],
                   [
                   -114.09957018646286,
                   46.82933208815811
                   ]
               ]
               ],
               "type": "Polygon"
           }
           }
       ],
       "name": "Example",
       "description": "This is an example domain.",
       "horizontalResolution": 2,
       "verticalResolution": 1
       }'

   Python

   Create Domain Resource API Call

   import requests
   
   url = "https://api.fastfuels.silvxlabs.com/v1/domains"
   
   headers = {
       "accept": "application/json",
       "api-key": "my-api-key",
       "Content-Type": "application/json",
   }
   
   data = {
       "type": "FeatureCollection",
       "features": [
           {
               "type": "Feature",
               "properties": {},
               "geometry": {
                   "coordinates": [
                       [
                           [-114.09957018646286, 46.82933208815811],
                           [-114.10141707482919, 46.828370407248826],
                           [-114.10010954324228, 46.82690548814563],
                           [-114.09560673134018, 46.8271123684554],
                           [-114.09592544216444, 46.829058122675065],
                           [-114.09957018646286, 46.82933208815811],
                       ]
                   ],
                   "type": "Polygon",
               },
           }
       ],
       "name": "Example",
       "description": "This is an example domain.",
       "horizontalResolution": 2,
       "verticalResolution": 1,
   }
   
   response = requests.post(url, headers=headers, json=data)

   An example response is shown below:

   {
     "type": "FeatureCollection",
     "features": [
       {
         "type": "Feature",
         "geometry": {
           "type": "Polygon",
           "coordinates": [
             [
               [
                 721064,
                 5190012
               ],
               [
                 721514,
                 5190012
               ],
               [
                 721514,
                 5190284
               ],
               [
                 721064,
                 5190284
               ],
               [
                 721064,
                 5190012
               ]
             ]
           ]
         },
         "properties": {
           "name": "domain",
           "area": 122400,
           "perimeter": 1444
         }
       },
       {
         "type": "Feature",
         "geometry": {
           "type": "Polygon",
           "coordinates": [
             [
               [
                 721202.0930596117,
                 5190283.73496937
               ],
               [
                 721065.1931226599,
                 5190171.675898871
               ],
               [
                 721170.9221922038,
                 5190012.585851082
               ],
               [
                 721513.4767988613,
                 5190048.269428905
               ],
               [
                 721481.1717487838,
                 5190263.570731599
               ],
               [
                 721202.0930596117,
                 5190283.73496937
               ]
             ]
           ]
         },
         "properties": {
           "name": "input",
           "area": 92416.50443976666,
           "perimeter": 1209.8595907218044
         }
       }
     ],
     "name": "Example",
     "description": "This is an example domain.",
     "horizontalResolution": 2,
     "verticalResolution": 1,
     "crs": {
       "type": "name",
       "properties": {
         "name": "EPSG:32611"
       }
     },
     "tags": [],
     "id": "bd9be005f94b408482f3be0259d27bef",
     "createdOn": "2024-10-03T16:38:43.403831",
     "modifiedOn": "2024-10-03T16:38:43.403831"
   }

   Note

   The id field in the response is used to reference the domain in subsequent API calls.

3. Create Road and Water Feature Resources

   This example uses Open Street Maps to collect road and water polygons (called features by the FastFuels API) in the domain. These features are used to remove fuel from the domain where roads and water are present.

   Submit a POST request to /v1/domains/{domainId}/features/road and /v1/domains/{domainId}/features/water endpoints with the domain ID and road and water feature data in the request body.

   curl

   Create Road and Water Features API Calls

   # Create a Road Features Resource
   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/features/road' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
     "sources": [
       "OSM"
     ]
   }'
   
   # Create a Water Features Resource
   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/features/water' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
     "sources": [
       "OSM"
     ]
   }'

   Python

   Create Road and Water Features API Calls

   import requests
   
   # Create a Road Features Resource
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/features/road"
   headers = {
       "accept": "application/json",
       "api-key": "your-api-key",
       "Content-Type": "application/json",
   }
   data = {"sources": ["OSM"]}
   
   response = requests.post(url, headers=headers, json=data)
   
   # Create a Water Features Resource
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/features/water"
   headers = {
       "accept": "application/json",
       "api-key": "your-api-key",
       "Content-Type": "application/json",
   }
   data = {"sources": ["OSM"]}
   
   response = requests.post(url, headers=headers, json=data)

   Both resources will return similar responses to one another. An example response for the road feature is shown below:

   {
     "sources": ["OSM"],
     "status": "pending",
     "createdOn": "2024-08-08T20:42:46.181878",
     "modifiedOn": "2024-08-08T20:42:46.181878",
     "checksum": "9e1c0b07c0f2459086481c7140bcec41"
   }

   Note the status field which has a value of pending until the feature is processed.

   Caution

   The status field must reach a value of completed before the feature can be used in subsequent API calls. Referencing resources with a status of pending or running will result in an error.

   Tip

   Use the GET endpoint to check the status of a resource.

4. Create a Tree Inventory Resource

   This example uses the TreeMap raster product in combination with the Forest Inventory and Analysis (FIA) database to create a tree inventory resource for the domain. In addition, we utilize the road and water features created in the previous step to remove trees from the domain where roads and water are present.

   Submit a POST request to the /v1/domains/{domainId}/inventories/tree endpoint with the domain ID and tree inventory data in the request body.

   curl

   Create Tree Inventory API Call

   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/inventories/tree' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
     "sources": [
       "TreeMap"
     ],
     "featureMasks": [
       "road",
       "water"
     ]
   }'

   Python

   Create Tree Inventory API Call

   import requests
   
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/inventories/tree"
   
   headers = {
       "accept": "application/json",
       "api-key": "my-api-key",
       "Content-Type": "application/json",
   }
   
   data = {"sources": ["TreeMap"], "featureMasks": ["road", "water"]}
   
   response = requests.post(url, headers=headers, json=data)

   An example response is shown below:

   {
     {
       "sources": [
         "TreeMap"
       ],
       "modifications": [],
       "TreeMap": {
         "version": "2016",
         "seed": 517578663
       },
       "featureMasks": [
         "road",
         "water"
       ],
       "status": "pending",
       "createdOn": "2024-08-08T21:29:57.596247",
       "modifiedOn": "2024-08-08T21:29:57.596247",
       "checksum": "3a6491875e4b4b34adeab3dc112224a0"
     }
   }

5. Create a Tree Grid

   In this example we use our tree inventory data to create a 3D grid of voxelized canopy fuel. We select bulk density, and moisture content as attributes to include in the 3D grid. The bulk density information is calculated from individual trees in the tree inventory using allometric equations. We set live fuel moisture content to be a uniform 100% across all occupied cells in the grid.

   Submit a POST request to the /v1/domains/{domainId}/grids/tree endpoint with the domain ID and tree grid data in the request body.

   curl

   Create Tree Grid API Call

   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/tree' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
     "attributes": [
       "bulkDensity",
       "fuelMoisture"
     ],
     "fuelMoisture": {
       "source": "uniform",
       "value": 125
     }
   }'

   Python

   Create Tree Grid API Call

   import requests
   
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/tree"
   
   headers = {
       "accept": "application/json",
       "api-key": "my-api-key",
       "Content-Type": "application/json",
   }
   
   data = {
       "attributes": ["bulkDensity", "fuelMoisture"],
       "fuelMoisture": {"source": "uniform", "value": 100},
   }
   
   response = requests.post(url, headers=headers, json=data)

   An example response is shown below:

    {
      "attributes": ["bulkDensity", "fuelMoisture"],
      "bulkDensity": {
        "source": "TreeInventory"
      },
      "fuelMoisture": {
        "source": "uniform",
        "value": 100
      },
      "status": "pending",
      "createdOn": "2024-08-08T21:39:37.299594",
      "modifiedOn": "2024-08-08T21:39:37.299594",
      "checksum": "3ea9349392d6403b853e209bfbc18f25",
      "treeInventoryChecksum": "3a6491875e4b4b34adeab3dc112224a0"
    }

6. Create a Surface Grid

   We use national coverage data of the 40 Fire Behavior Fuel Models from the LANDFIRE program to create a surface grid of relevant attributes needed for the QUIC-Fire module. In this example we include fuel load, fuel bed depth, and fuel moisture content in the surface grid. In addition, we specify the proportion of 10-hour fuels and the curing of live herbaceous and live woody components that should be included in the fuel bed. We also provide measurements of fuel moisture content for each of the size classes in the fuel bed.

   Submit a POST request to the /v1/domains/{domainId}/grids/surface endpoint with the domain ID and surface grid data in the request body.

   curl

   Create Surface Grid API Call

   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/surface' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
     "attributes": [
       "fuelLoad",
       "fuelDepth",
       "fuelMoisture"
     ],
     "fuelLoad": {
       "source": "LANDFIRE",
       "product": "FBFM40",
       "version": "2022",
       "interpolationMethod": "linear",
       "fractionOneHour": 1,
       "fractionTenHour": 0.1,
       "fractionHundredHour": 0,
       "fractionLiveHerbaceous": 0,
       "fractionLiveWoody": 0,
       "curingLiveHerbaceous": "0.5",
       "curingLiveWoody": "0.05"
     },
     "fuelMoisture": {
       "source": "uniformBySizeClass",
       "oneHour": 0.15,
       "tenHour": 0.2,
       "hundredHour": 0.25,
       "liveHerbaceous": 0.75,
       "liveWoody": 0.9
     }
   }'

   Python

   Create Surface Grid API Call

   import requests
   
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/surface"
   
   headers = {
       "accept": "application/json",
       "api-key": "my-api-key",
       "Content-Type": "application/json",
   }
   
   data = {
       "attributes": ["fuelLoad", "fuelDepth", "fuelMoisture"],
       "fuelLoad": {
           "source": "LANDFIRE",
           "product": "FBFM40",
           "version": "2022",
           "interpolationMethod": "linear",
           "fractionOneHour": 1,
           "fractionTenHour": 0.1,
           "fractionHundredHour": 0,
           "fractionLiveHerbaceous": 0,
           "fractionLiveWoody": 0,
           "curingLiveHerbaceous": 0.5,
           "curingLiveWoody": 0.05,
       },
       "fuelMoisture": {
           "source": "uniformBySizeClass",
           "oneHour": 0.15,
           "tenHour": 0.2,
           "hundredHour": 0.25,
           "liveHerbaceous": 0.75,
           "liveWoody": 0.9,
       },
   }
   
   response = requests.post(url, headers=headers, json=data)

   An example response is shown below:

    {
      "attributes": [
        "fuelLoad",
        "fuelDepth",
        "fuelMoisture"
      ],
      "fuelLoad": {
        "source": "LANDFIRE",
        "product": "FBFM40",
        "version": "2022",
        "interpolationMethod": "linear",
        "fractionOneHour": 1,
        "fractionTenHour": 0.1,
        "fractionHundredHour": 0,
        "fractionLiveHerbaceous": 0,
        "fractionLiveWoody": 0,
        "curingLiveHerbaceous": 0.5,
        "curingLiveWoody": 0.05
      },
      "fuelDepth": {
        "source": "LANDFIRE",
        "product": "FBFM40",
        "version": "2022",
        "interpolationMethod": "nearest"
      },
      "fuelMoisture": {
        "source": "uniformBySizeClass",
        "oneHour": 0.15,
        "tenHour": 0.2,
        "hundredHour": 0.25,
        "liveHerbaceous": 0.75,
        "liveWoody": 0.9
      },
      "modifications": [],
      "status": "pending",
      "createdOn": "2024-08-08T22:15:07.053512",
      "modifiedOn": "2024-08-08T22:15:07.053512",
      "checksum": "1b4ffc5faec84496bb6c41796c4706c7"
    }

7. Create a Topography Grid

   In this tutorial we use data from LANDFIRE to create a grid of elevation values for the gridded domain.

   Submit a POST request to the /v1/domains/{domainId}/grids/topography endpoint with the domain ID and topography grid data in the request body.

   curl

   Create Topography Grid API Call

   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/topography' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
     "attributes": [
       "elevation"
     ]
   }'

   Python

   Create Topography Grid API Call

   import requests
   
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/topography"
   
   headers = {
       "accept": "application/json",
       "api-key": "my-api-key",
       "Content-Type": "application/json",
   }
   
   data = {"attributes": ["elevation"]}
   
   response = requests.post(url, headers=headers, json=data)

   An example response is shown below:

   {
     "attributes": [
       "elevation"
     ],
     "elevation": {
       "source": "LANDFIRE",
       "version": "2020",
       "interpolationMethod": "cubic"
     },
     "status": "pending",
     "createdOn": "2024-08-08T22:27:01.579359",
     "modifiedOn": "2024-08-08T22:27:01.579359",
     "checksum": "56f089985f484e4284b2022adf09b01f"
   }

8. Create a QUIC-Fire Grid Export

   To export grids to the set of QUIC-Fire input files we need to create an Export off of the Grids resource.

   To do this, submit a POST request to the /v1/domains/{domainId}/grids/exports/QUICFire endpoint.

   curl

   Create QUIC-Fire Grid Export API Call

   curl -X 'POST' \
     'https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/exports/QUICFire' \
     -H 'accept: application/json' \
     -H 'api-key: my-api-key' \
     -d ''

   Python

   Create QUIC-Fire Grid Export API Call

   import requests
   
   url = "https://api.fastfuels.silvxlabs.com/v1/domains/bd9be005f94b408482f3be0259d27bef/grids/exports/QUICFire"
   
   headers = {"accept": "application/json", "api-key": "my-api-key"}
   
   response = requests.post(url, headers=headers)

   An example response is shown below:

   {
   "domainId": "bd9be005f94b408482f3be0259d27bef",
   "resource": "grids",
   "format": "QUICFire",
   "status": "pending",
   "createdOn": "2024-08-08T22:39:51.732582",
   "modifiedOn": "2024-08-08T22:39:51.732582",
   "expiresOn": "2024-08-15T22:39:51.732582"
   }

9. Download QUIC-Fire Input Files

   Once the Export resource reaches a status of completed, you can download the QUIC-Fire input files by submitting a GET request to the /v1/domains/{domainId}/grids/exports/QUICFire endpoint. The response body contains a signedURL field which will download the compressed input files when accessed.

   {
   "domainId": "bd9be005f94b408482f3be0259d27bef",
   "resource": "grids",
   "format": "QUICFire",
   "status": "completed",
   "createdOn": "2024-08-08T22:39:51.732582Z",
   "modifiedOn": "2024-08-08T22:40:14.776532Z",
   "expiresOn": "2024-08-15T22:39:51.732582Z",
   "signedUrl": "..."
   }

   Note

   The signedUrl field in the response is a temporary download link that will expire after a set period of time. Check the expiresOn field in the response to determine when the URL will expire.