@spec dted(String.t()) :: {:ok, Sidereon.Terrain.Dted.t()} | {:error, term()}

Open a DTED terrain directory.

The returned handle loads tiles lazily as lookups request them.

Open a DTED terrain directory or raise.

@spec height(Sidereon.Terrain.Dted.t(), number(), number(), lookup_options()) ::
  {:ok, float()} | {:error, lookup_error() | atom() | Sidereon.argument_error()}

Look up terrain height at {longitude_deg, latitude_deg}.

Returns {:ok, height_m} in meters above the DTED ORTHOMETRIC vertical datum, or {:error, reason}. Points outside cached DTED coverage return 0.0 from the core terrain model. Longitude is first by design.

A lookup that gives nonzero weight to a null posting returns {:error, {:unknown_terrain_elevation, fields}} unless a neighbouring tile knows the height at the same place, and a tile whose DSI names a horizontal datum other than WGS84 returns {:error, {:non_wgs84_terrain_tile, fields}}; see lookup_error/0. A query the lookup refuses, such as a non-finite coordinate, returns {:error, {:invalid_input, fields}} with the core reason in fields.message.

Look up one ORTHOMETRIC terrain height in meters or raise.

@spec height_batch(
  Sidereon.Terrain.Dted.t(),
  [{number(), number()}],
  lookup_options()
) ::
  [ok: float(), error: lookup_error() | atom()] | {:error, term()}

Look up a batch of terrain heights.

points is a list of {longitude_deg, latitude_deg} pairs. The returned list has one {:ok, height_m} or {:error, reason} entry per input, preserving order, with the reasons height/4 returns. Heights are meters above the DTED ORTHOMETRIC vertical datum.

Look up a batch of ORTHOMETRIC terrain heights in meters or raise.

@spec height_m(Sidereon.Terrain.Dted.t(), number(), number(), lookup_options()) ::
  {:ok, float()} | {:error, lookup_error() | atom() | Sidereon.argument_error()}

Alias for height/4, matching the Rust/Python/WASM height_m name.

@spec height_m_with_options(
  Sidereon.Terrain.Dted.t(),
  number(),
  number(),
  lookup_options()
) ::
  {:ok, float()} | {:error, lookup_error() | atom() | Sidereon.argument_error()}

Look up terrain height with explicit lookup options.

@spec load_tile(String.t()) ::
  {:ok, Sidereon.Terrain.DtedTile.t()} | {:error, tile_error() | term()}

Load one DTED tile from disk.

Returns {:ok, %DtedTile{}} or {:error, reason} with a tile_error/0. A tile is checked against the metadata the reader places postings by: UHL origins must be whole degrees inside their axis with that axis's hemisphere letters, a stated UHL data interval must span one degree over the posting count, and each data record must declare the longitude count of its position and latitude count zero. A tile on any horizontal datum loads; see tile_horizontal_datum/1.

Load one DTED tile or raise.

@spec tile_elevation(Sidereon.Terrain.DtedTile.t(), number(), number()) ::
  {:ok, integer()} | {:error, tile_error() | Sidereon.argument_error()}

Read the nearest posting elevation from a loaded DTED tile.

Returns an integer height in meters above the DTED ORTHOMETRIC vertical datum. Longitude is first. A posting holding the DTED null value is an unknown elevation, {:error, {:null_posting, %{longitude_index: i, latitude_index: j}}}; a point outside the tile is {:error, {:outside, fields}}.

Read one ORTHOMETRIC tile posting height in meters or raise.

@spec tile_horizontal_datum(Sidereon.Terrain.DtedTile.t()) :: horizontal_datum()

Return the horizontal datum a loaded DTED tile's DSI record states.

DtedTerrain lookups answer only from a tile whose datum is :wgs84 or :unstated, since queries are WGS84 positions.