# Petrel Fuel Layer — v1.0 Global FM40 Crosswalk

**A free Petrel Layer — CC-BY-4.0, commercial use permitted.** Account required,
distributed via API.

What fuels a surface fire — not how it spreads. This Layer ships a single global
raster at **native ~270 m (9 arcsec)**: the Scott & Burgan 40 (FM40) surface
fuel-model **class** for every land cell, assigned deterministically from land
cover × climate. It feeds the surface-fuel grid of the Petrel Wildfire Hazard
(Cell2Fire), and is useful standalone for fire-behavior modelling, fuels
mapping, and wildland fire risk screening. It **replaces the earlier CC-BY-NC ML
fuel line** (`fuel_v0.1/v0.2_global_ml`) as the free, commercial-clean fuel
layer.

## Layer (1 × ~270 m global GeoTIFF)

| File | Description | Values | Dtype | NoData |
|---|---|---|---|---|
| `fuel_model_class_270m.tif` | Scott & Burgan FM40 surface fuel-model class | FM40 class code (categorical) | uint8 | 255 |

Global at 9 arcsec (~270 m, 0.0025°), EPSG:4326, 144000 × 54000 pixels spanning
60° S – 75° N, internally tiled with overviews, coast-clipped to the GSHHG-f
full-resolution shoreline. The raster is **categorical** — every cell holds an
FM40 class code directly; there is no scale factor to apply. `255` is NoData
(ocean, Antarctica, and unscored cells).

## FM40 class encoding (Scott & Burgan 2005)

FM40 codes are grouped into six fuel families. This Layer assigns the family and
a representative in-family code; the family is the reliable unit.

| Code range | Family | Covers |
|---|---|---|
| 91–99   | **NB** — non-burnable | urban, water, snow/ice, bare, agriculture |
| 101–109 | **GR** — grass | grasslands, savanna, steppe, tundra |
| 121–124 | **GS** — grass-shrub | mixed grass-shrub mosaics |
| 141–149 | **SH** — shrub | shrubland, Mediterranean maquis/chaparral |
| 161–165 | **TU** — timber-understory | open woodland, savanna woodland, boreal conifer |
| 181–189 | **TL** — timber-litter | closed-canopy forest litter (temperate, tropical) |
| 255     | — NoData | ocean, Antarctica, unscored |

## Reading the values (important)

- The raster is a **class code, not a magnitude.** Do not average, interpolate,
  or scale it. Reproject with **nearest-neighbour** only.
- The **family** (NB / GR / GS / SH / TU / TL) is the unit v1.0 validates and
  the unit you should key downstream logic on; the specific in-family code is a
  representative assignment, not a per-pixel measurement.
- FM40 describes **surface** fuel. Canopy attributes (cover, stand height,
  canopy base height, bulk density) are **not** part of v1.0 — see *Known
  limitations*.

## Quick start

**Via Petrel API** (recommended — returns 1-hour presigned URLs for every file
in the bundle; `$PETREL_API_KEY` is your `tlk.…` key, free tier works):
```bash
curl -s -H "X-API-Key: $PETREL_API_KEY" \
  https://api.petreldata.io/v1/layer/fuel/v1.0/bundle \
  | jq -r '.files[] | [.url, .name] | @tsv' \
  | while IFS=$'\t' read -r url name; do curl -s "$url" -o "$name"; done
```

**Point query** in Python (with rasterio — streams the COG, no full download):
```python
import os, requests, rasterio

FAM = {range(91,100): "NB non-burnable", range(101,110): "GR grass",
       range(121,125): "GS grass-shrub", range(141,150): "SH shrub",
       range(161,166): "TU timber-understory", range(181,190): "TL timber-litter"}
def family(c):
    return next((v for k, v in FAM.items() if c in k), "unknown")

r = requests.get(
    "https://api.petreldata.io/v1/layer/fuel/v1.0/bundle",
    headers={"X-API-Key": os.environ["PETREL_API_KEY"]},
).json()
url = {f["name"]: f["url"] for f in r["files"]}["fuel_model_class_270m.tif"]

lat, lon = 40.42, -3.70                         # Madrid (Mediterranean shrub)
with rasterio.open(url) as src:
    code = int(next(src.sample([(lon, lat)]))[0])
    if code == src.nodata:                       # 255
        print("no data (ocean / outside coverage)")
    else:
        print(f"FM40 class {code} — {family(code)}")
```

See [`API_USAGE.md`](API_USAGE.md) for more snippets.

## Documentation

| Document | Purpose |
|---|---|
| [`methodology.md`](methodology.md) | How the crosswalk assigns FM40 from land cover × climate |
| [`model_card.md`](model_card.md) | Intended use, inputs, limitations |
| [`data_sources.md`](data_sources.md) | All input datasets with citations + licenses |
| [`validation_report.md`](validation_report.md) | Validation status (biome plausibility + US LANDFIRE family agreement) + known limitations |
| [`RELEASE_NOTES.md`](RELEASE_NOTES.md) | Client-facing version history |
| [`API_USAGE.md`](API_USAGE.md) | curl / Python / R code snippets |
| [`bulk_download_instructions.md`](bulk_download_instructions.md) | Download flow + attribution |
| [`LICENSE.md`](LICENSE.md) | CC-BY-4.0 summary + required attribution |
| [`CITATION.cff`](CITATION.cff) | How to cite this dataset |

## License

**Creative Commons Attribution 4.0 International** (CC-BY-4.0).

You may share and adapt this Layer for **any purpose, including commercially**,
with attribution. This Layer is CC-BY-4.0 because it derives **only** from
CC-BY-4.0 sources — ESA WorldCover 2021 and Beck et al. (2018) Köppen-Geiger —
with no Meta canopy (CC-BY-NC), no LANDFIRE, and no share-alike (ODbL) inputs.

Attribution must credit Petrel **and** the two upstream sources: *"© ESA
WorldCover 2021"* and *"Beck et al. (2018) Köppen-Geiger"*. See
[`LICENSE.md`](LICENSE.md) for the full statement.

## Citation

```
Petrel Data (2026). Petrel Fuel Layer v1.0 — Global FM40 Crosswalk.
https://petreldata.io/layers/fuel/v1.0
```

See [`CITATION.cff`](CITATION.cff) for Citation File Format metadata.

## Known limitations (read before using)

- **v1.0 ships the fuel-model class only.** The four canopy attributes the
  earlier ML line carried (canopy cover, stand height, canopy base height, bulk
  density) are, in this crosswalk, per-family class-typical *constants* — they
  are **not** shipped as data in v1.0. Real per-pixel canopy from the CC-BY ETH
  global canopy-height layer is the flagged v1.1 item. See
  [`methodology.md`](methodology.md).
- **It is a deterministic crosswalk, not a trained model.** FM40 is assigned
  from exactly two inputs (WorldCover × Köppen). There is no accuracy score in
  the statistical sense; validation is biome plausibility plus US LANDFIRE
  family agreement. See [`validation_report.md`](validation_report.md).
- **Soft spots.** Savanna tree cover in humid-C climates can over-read as
  closed timber, and alpine/tundra transitions are coarse (Köppen is ~1 km).
  Both are v1.1 refinement targets (add elevation + real canopy height).
- **~270 m cells and a ~1 km climate driver** — suitable for landscape- to
  regional-scale fuels mapping, not parcel-level fuel typing.
- **Antarctica is excluded by standard**; ocean is NoData (GSHHG-f coast clip).

## Provenance

- **Built by:** the Petrel ML pipeline (config `configs/fuel_layer.yaml`,
  promoted via the canonical Petrel postprocess chain); the FM40 crosswalk
  itself lives in `petrel-global-fuel/pgflib/models/fuel_crosswalk.py`
- **STAC item:** [`fuel_v1.0_global_crosswalk_stac_item.json`](fuel_v1.0_global_crosswalk_stac_item.json)