# Elevation data import and export

This document defines the first implementation scope for elevation data in the
MapTools Converter. It deliberately follows the formats that the MapTools
Android app can query directly for elevation profiles and hillshading.

## Supported source formats

| Format | File extensions | Import | Notes |
| --- | --- | --- | --- |
| SRTM HGT | `.hgt` | Yes | One-degree tiles; bounds are derived from the tile name. |
| DEM GeoTIFF | `.tif`, `.tiff`, `.geotiff` | Yes | Preferred exchange format; embedded georeferencing is required. |
| ESRI ASCII Grid | `.asc` | Yes | Geographic grids are supported directly. |
| DTED | `.dt0`, `.dt1`, `.dt2` | Yes | Level and bounds are read from the DTED header. |

ZIP containers are not accepted in the initial converter version; contained
terrain files need to be unpacked before import. GeoPackage is not advertised
as a terrain format because the current MapTools app deliberately rejects
GeoPackage DEMs for elevation queries and hillshading.

## Supported target formats

| Format | Output layout | Intended use |
| --- | --- | --- |
| DEM GeoTIFF | One raster for the selected union bounds | Recommended default and general interchange. |
| ESRI ASCII Grid | One raster for the selected union bounds | Transparent, text-based interchange. |
| SRTM HGT | One or more one-degree tiles | Direct use by software expecting SRTM tiles. |
| DTED | One or more one-degree cells | Compatibility with DTED consumers. |

GeoTIFF output is a single-band Float32 DEM with embedded WGS84
georeferencing and an explicit NoData value. These properties match the
GeoTIFF elevation reader in MapTools. HGT uses big-endian signed Int16 samples;
DTED uses the standard 3428-byte UHL/DSI/ACC prefix and sign-magnitude samples.

Rectangle and circle selections are combined as a geometric union. Raster
cells outside that union are written as NoData, so overlapping selection areas
are neither counted nor exported twice.

## Workflow rules

- Map, POI and elevation inputs are independent source groups and can be used
  separately or together.
- A terrain-only input enables only terrain outputs.
- A map-only or POI-only workflow keeps its existing output choices.
- Mixed inputs expose the output choices for every available source group.
- Terrain data remain separate files. They are not embedded in a Mapsforge
  `.map`, because the Mapsforge binary map specification contains vector map
  data rather than a general elevation raster.
- MapTools can import the resulting terrain files directly. A later optional
  manifest may group map, POI and terrain files without changing their native
  formats.

## Interactive preview

Elevation-only workflows render a bounded Web-Mercator preview directly from
the loaded DEM values. Hypsometric colors and a north-west hillshade make the
terrain recognizable without downloading a base map. NoData cells stay
transparent, and a compact legend shows the actual minimum and maximum in the
selected metric or imperial unit system.

When map and elevation sources are combined, the same terrain raster is drawn
beneath map geometry, labels and POIs. The preview contains at most 720 × 720
samples regardless of source resolution. It is a visual aid only: selection
coordinates and export sampling continue to use the original georeferencing
and full-resolution source rasters.

## Resource behaviour

Conversion is row- or tile-oriented. Source rasters are sampled through
reusable random-access sessions. All target formats are written incrementally;
GeoTIFF uses uncompressed strips capped at 8 MiB. The classic TIFF UInt32
offset limit is checked before writing and oversized selections are rejected
with a clear request to choose a smaller area.
