> For the complete documentation index, see [llms.txt](https://docs.whiffle.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.whiffle.cloud/getting-started/adding-custom-data/geodata.md).

# Geodata

Run a simulation on terrain, surface and canopy height data from a site survey instead of the default global datasets.

Custom geodata replaces the default global elevation and vegetation data with data of the site itself, for example:

* A terrain map at 1 m resolution, in place of a global dataset at 30 m.
* A canopy height map of the season the simulation covers, rather than a single fixed one.

An uploaded file can be reused in any number of simulations.

Three types of data can be uploaded:

* ⛰️ **Terrain (DTM)** is the bare ground elevation.
* 🏢 **Surface (DSM)** is the ground including buildings etc.
* 🌳 **Canopy height (CHM)** is the height of the vegetation.

#### Uploading a file

1. Navigate to the **Geodata** tab and click **“New Geodata”**.
2. Drop the file onto **Upload GeoTiff**, or browse for it.
3. Enter a **Name** and choose the **Type**.
4. Tick **Data meets specification**.
5. Under **Finalise geodata**, click **Mark as Final**. A finalized entry can be attached to a simulation and can no longer be edited.

The form is saved while it is filled in, so it can be left and finalized later.

The **Type** decides how the values are read:

| Type             | Select                    | Values are              |
| ---------------- | ------------------------- | ----------------------- |
| ⛰️ Terrain       | **Digital Terrain Model** | metres above sea level  |
| 🏢 Surface       | **Digital Surface Model** | metres above sea level  |
| 🌳 Canopy height | **Canopy Height Model**   | metres above the ground |

#### Attaching geodata to a simulation

During simulation setup, open the **Geodata** section of the **Site** step and select the entries to be used.

{% hint style="info" %}
A simulation takes **at most one file of each type**: one terrain, one surface and one canopy height file. Selecting a different file of the same type replaces the previous one, and a type that is not uploaded runs on the default dataset.
{% endhint %}

#### How custom geodata is used

An uploaded file does not replace the default datasets outright. Where the file has a value, that value is used. Everywhere else the default global dataset applies.

Two consequences follow:

* ✅ A file covering only part of the simulated area is fine. The remainder runs on the default data, with no gap and no error.
* ⚠️ A file covering none of the simulated area changes nothing, and the simulation runs entirely on the default data without warning.

#### Where custom geodata applies

Only the LES domains around the site take custom geodata. The meso domain surrounding them always runs on the default datasets.

| Domain   | Grid                          | Data used                                                      |
| -------- | ----------------------------- | -------------------------------------------------------------- |
| **LES**  | 100 m and 40 m                | Custom geodata where it has values, default datasets elsewhere |
| **Meso** | coarser, surrounding the site | Default datasets only                                          |

#### Preparing a file

A file has to meet four requirements.

| Requirement                        | Needs to be                                                                                                                                   |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 📁 **Format**                      | A GeoTIFF, with the extension `.tif` or `.tiff`, of at most 1.5 GB.                                                                           |
| 🌍 **Coordinate reference system** | Present. Any projection is accepted and is converted to the projection of the simulation, but a file without one cannot be placed on the map. |
| 📏 **Values**                      | In metres: above sea level for terrain and surface, above the ground for canopy height.                                                       |
| 🕳️ **No-data value**              | Recorded in the `GDAL_NODATA` header tag, number 42113. Those pixels are treated as missing, and the default dataset fills them in.           |

{% hint style="warning" %}
The no-data value must be one that cannot occur as a real height. `NaN` is the safest choice where the file stores decimal values, and a value outside the physical range, such as -9999, works everywhere. Do not use 0, which is a valid measurement.
{% endhint %}