# RavingDesk Terrain Analyzer (DEM slope, aspect, hillshade, contours)

> Slope, aspect, hillshade, curvature, sinks and contour lines from your elevation model. Reads a digital elevation model you supply — ESRI ASCII grid, XYZ grid, GeoTIFF (WGS84 or UTM) or a Terrarium/Mapbox/grey PNG heightmap — and computes slope and aspect with Horn’s method, a hillshade for any sun position, Zevenbergen–Thorne curvature, closed depressions with Priority-Flood, contour lines as GeoJSON, and optionally cut/fill volumes against a reference elevation and a viewshed from an observer with earth curvature and refraction. Returns statistics, a PNG map and the contours. It is the terrain engine of RavingDesk’s Data & charts “Terrain” step.

Part of usefulweb.app (https://usefulweb.app/). Part of [RavingDesk](https://ravingdesk.usefulweb.app/) (ownerApp: ravingdesk). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://ravingdeskterrainanalyzer.usefulweb.app/ (interactive tool at https://ravingdeskterrainanalyzer.usefulweb.app/tool)
- JSON API: POST https://ravingdeskterrainanalyzer.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://ravingdeskterrainanalyzer.usefulweb.app/api/v1/tool)
- OpenAPI: https://ravingdeskterrainanalyzer.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://ravingdeskterrainanalyzer.usefulweb.app/mcp - tool `ravingdesk_terrain_analyzer`

## Inputs
- file (file): Elevation model (DEM) - ESRI ASCII grid (.asc), XYZ grid text, GeoTIFF (Int16, UInt16 or Float32, one band, uncompressed or Deflate, WGS84 or UTM) or a PNG heightmap. Up to 25 MB and 1,048,576 cells.
- text (textarea): Or paste an ESRI ASCII grid or XYZ points
- crs (select): Coordinate system of an ASCII or XYZ grid - GeoTIFFs carry their own coordinate system; PNG heightmaps are always local.
- utmZone (text): UTM zone - Only for “WGS84 UTM zone”: zone number and N or S.
- pngEncoding (select): PNG heightmap encoding
- cellSize (number): Cell size of a PNG heightmap - PNG heightmaps and TIFFs without georeferencing have no cell size of their own.
- greyMin (number): Elevation of black (grey PNG)
- greyMax (number): Elevation of white (grey PNG)
- layer (select): Map layer for the PNG
- azimuth (number): Sun azimuth (hillshade) - Clockwise from north; 315° (north-west) is the cartographic convention.
- altitude (number): Sun altitude (hillshade)
- zFactor (number): Z factor - Multiplies elevations, e.g. 0.3048 when elevations are in feet and cells in metres.
- contourInterval (number): Contour interval - Empty: a round interval giving about 10–20 levels.
- referenceElevation (number): Reference elevation for cut and fill (optional) - Volumes above (cut) and below (fill) a level plane at this elevation.
- observer (text): Observer for a viewshed (optional) - A cell (“row 30, col 20”), grid coordinates “x, y” on local grids, or a coordinate in any notation on georeferenced grids.
- observerHeight (number): Observer eye height above ground
- earthCurvature (boolean): Earth curvature and refraction (k = 0.13) in the viewshed

## Method
- DEM reading: ESRI ASCII grids (xll/yll corner or centre, cellsize or dx/dy, NODATA_value); XYZ points on a regular grid (cell centres; missing positions become no data); GeoTIFF subset (one band of Int16, UInt16 or Float32, uncompressed or Deflate, strips or tiles, predictors 1–3, ModelTiepoint + ModelPixelScale or a north-up ModelTransformation, WGS84 EPSG:4326 or WGS84 UTM EPSG:326xx/327xx; other coordinate systems, LZW, BigTIFF and rotated grids are refused with a reason); PNG heightmaps (Terrarium, Mapbox Terrain-RGB or grey; transparent pixels are no data). Only files you supply are read — nothing is downloaded.
- Slope and aspect follow Horn (1981): dz/dx = ((c + 2f + i) − (a + 2d + g)) / (8·Δx) and dz/dy = ((a + 2b + c) − (g + 2h + i)) / (8·Δy) over the 3 × 3 window; slope = atan(√(dz/dx² + dz/dy²)); aspect is the compass direction the slope faces (0° = north, 90° = east), flat cells have none. Edge and no-data neighbours take the centre value.
- Hillshade = 255 · (cos Z · cos S + sin Z · sin S · cos(azimuth − aspect)) with Z = 90° − sun altitude; curvature = −2·(D + E) after Zevenbergen & Thorne (1987) in 1/m (positive = convex; Esri reports 100× this value).
- Closed depressions are filled with Priority-Flood (Barnes, Lehman & Mulla 2014): starting from the grid edge in rising order, every cell lower than its spill level is raised to it; the fill depth and volume are reported. Contours are traced with marching squares on the cell centres (saddles resolved by the mean of the four corners).
- Cut/fill: Σ (z − reference) · cell area above the plane (cut) and below it (fill). Viewshed: rays from the observer to every edge cell (Franklin & Ray’s R2 scheme) with interpolation between the two straddling cells; a cell is visible when its elevation angle is not below the steepest angle before it; the earth-curvature drop is d²/(2R)·(1 − k) with R = 6,371,008.8 m and k = 0.13.
- Cell sizes on geographic grids come from the WGS84 radii of curvature at each row (meridional M and prime vertical N·cos φ) and cell areas from the exact ellipsoidal quadrangle; UTM and local grids use map metres (the UTM scale factor of 0.9996–1.0004 is ignored).