# Relative Elevation Model (REM) — QGIS Plugin

A QGIS Processing plugin that generates a **Relative Elevation Model (REM)**:
a raster showing how high every terrain cell sits *above the nearest river
channel*. By removing the regional valley slope, a REM reveals subtle
floodplain features — levees, palaeochannels, oxbows, point bars and low
terraces — that are invisible in a normal DEM.

Created as part of the **EAMENA** project
(University of Leicester / Durham University / University of Oxford).

---

## What is a REM?

A normal DEM stores **absolute** elevation, so a river flowing downhill makes
the whole valley appear tilted, burying the small height differences that
matter on a floodplain. A REM re-references every cell to the elevation of
the **nearest point on the river**, flattening that regional slope:

```
REM = DEM − river_surface
```

where `river_surface` is a smooth raster of the river's elevation,
interpolated across the whole DEM from samples taken along the channel.

Typical REM values:

| Height above river | Feature |
|---|---|
| 0 m | the channel itself |
| 0.5 – 2 m | levees, natural banks, point bars |
| 2 – 6 m | palaeochannels, low terraces |
| 6 – 10 m+ | higher terraces, valley sides |

---

## ⚠️ Important requirement: coordinate systems

**The DEM and the river line MUST:**

1. be in the **same** coordinate reference system (CRS), and
2. use a **projected** CRS with **metres** as the unit
   (e.g. UTM, a national grid, or Web Mercator EPSG:3857).

Geographic CRSs (latitude/longitude in degrees, e.g. EPSG:4326) will **not**
work: distances and the sample interval are measured in map units, so degrees
produce meaningless results. If your data is in degrees, reproject both the
DEM and the river line to a suitable projected CRS first.

---

## The two tools

The plugin installs two algorithms under
**Processing Toolbox → REM Tools**, and adds two buttons into the Plugins toolbar:

### 1. Create River Line from DEM  (semi-automatic)

Extracts a river/channel network straight from the DEM:

```
fill sinks → flow accumulation → threshold → thin → vectorise
```

The result is deliberately *raw*. **Inspect and clean it by hand**
(delete spurious branches, join gaps) before using it for the REM.

> For very flat regions — such as the **Sudd** in South Sudan — automatic
> extraction struggles, because flow has no clear direction. In those cases
> draw the river line by hand instead; it gives far better results.

### 2. Generate Relative Elevation Model (REM)

Takes the DEM and a (clean) river line and produces the REM.

---

## Procedure

```
        ┌─────────────┐        ┌──────────────┐
        │  DEM (proj.)│        │  River line  │
        └──────┬──────┘        └──────┬───────┘
               │   (same projected CRS, metres)
               │                      │
               │            ┌─────────▼──────────┐
               │            │ Points along line  │
               │            │ every N metres     │
               │            └─────────┬──────────┘
               │                      │
               │            ┌─────────▼──────────┐
               └───────────►│ Sample DEM value   │
                            │ at each point      │
                            └─────────┬──────────┘
                                      │  points with elevation
                            ┌─────────▼──────────┐
                            │ IDW interpolation  │
                            │ (coarse, then warp │
                            │  to DEM grid)      │
                            └─────────┬──────────┘
                                      │  river_surface raster
        ┌─────────────┐     ┌─────────▼──────────┐
        │  DEM (proj.)│────►│  REM = DEM − river │
        └─────────────┘     │  surface, clamped  │
                            │  at 0              │
                            └─────────┬──────────┘
                                      │
                            ┌─────────▼──────────┐
                            │  REM raster        │
                            │  (0–10 m ramp)     │
                            └────────────────────┘
```

### The formula

For every cell:

```
REM(x, y) = max( 0, DEM(x, y) − river_surface(x, y) )
```

The `max(0, …)` clamps the channel and any interpolation noise to zero, so
no cell is reported as below the river.

---

## Output styling

The REM is loaded automatically with a bundled colour ramp covering
**0 to 10 metres** above the river:

- 0 m → deep blue (channel)
- ~5 m → green / yellow
- 10 m → dark red

Cells **higher than 10 m** above the river are rendered **transparent**, so
the floodplain stands out cleanly over a basemap. 0–10 m is a fixed,
comparable range: a value of 3 m means the same thing on every map you make,
unlike a percentile stretch that changes between datasets.

To re-apply or tweak the ramp manually:
**Layer Properties → Symbology → Style → Load Style → `styles/rem_style.qml`**.

---

## Parameters (Generate REM)

| Parameter | Required | Notes |
|---|---|---|
| Input DEM | yes | Projected, metre-based raster |
| River line | yes | Polyline in the **same** projected CRS as the DEM |
| Sample interval (m) | yes | Spacing of elevation samples along the river. Start at ~5× the DEM pixel size |
| IDW resolution factor | advanced | Runs IDW at N× the DEM pixel size for speed (default 10) |
| IDW neighbours / power | advanced | Interpolation tuning |
| Clip above percentile | advanced | Removes bridge/culvert spikes (98 is a good start; 0 = off) |
| Output REM raster | yes | The result |
| Output river sample points | optional | QC layer of sampled elevations |

---

## Requirements

- **QGIS ≥ 3.16**
- **SAGA** — used by the river extractor (fill sinks, flow accumulation)
- **GRASS** — used by the river extractor (`r.thin`, `r.to.vect`)

Both ship with the QGIS standalone installer on all platforms. They are only
needed for *Create River Line*; *Generate REM* works without them.

---

## Installation

**From ZIP:** Plugins → Manage and Install Plugins → Install from ZIP →
select the plugin ZIP.

**Manual:** copy the `rem_plugin/` folder into your QGIS plugins directory:

| Platform | Path |
|---|---|
| Windows | `%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\` |
| macOS | `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/` |
| Linux | `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/` |

---

## Tips & troubleshooting

**Auto-extraction gives too many / too few rivers**
Adjust the flow accumulation threshold. Higher = fewer, larger rivers.

**Flat terrain (e.g. the Sudd)**
Draw the river line by hand; automatic extraction is unreliable where flow
has no clear gradient.

**REM has bright spikes at bridges**
Enable percentile clipping (98–99).

**Everything comes out 0 / blank**
Check that the DEM and river line share the same projected CRS in metres.

**Very slow on large DEMs**
Increase the sample interval, or raise the IDW resolution factor.

---

## Licence

GPL-3.0 license

---

## Credits

Created by Ishiba RO ©️ 2026