Elevation API ATLAS Elevation 5 Referenceconversionservice

Andi Lamprecht ·2026-05-11· 5 min read· Accepted

Elevation Reference Conversion Service

Context

This ADR defines a methodology used to smoothly convert between vertical datums. The decision if conversion should be provided either by inter-league accessible API, or as an local microservice within cluster is not in the scope of this ADR. It requires more discovery work (eg. performance testing )

Elevation data can come in multiple vertical and horizontal reference projections. There is no standard projection accepted by every external service as an input.

There are two categories of projections:

• Horizontal Projection
• Vertical Projection

Horizontal Projection

Horizontal projection defines a location of a point on a plane. It focus on the x (east-west) and y (north-south) coordinates. It helps in locating a point on the Earth’s surface in terms of latitude and longitude. The horizontal projections use ellipsoids or spheroids as reference surfaces.

Image below shows how a location of example point with same coordinates may differ depending on projection

Invalid Image Path

For the Continental US Area the most common used horizontal projections are

• WGS84 - A general-purpose ellipsoid with it’s center aligned to the center of the earth
• NAD83 - An ellipsoid with its center shifted to algin more precisely to the shape of Continental US

Invalid Image Path

Vertical Projection

Vertical projection defines an altitude of a point measured accordingly to a chosen system of reference
It is concerted with the z-axis, for given x and y coordinates, referenced either to ellipsoid or geoid.

For the Continental US Area the most common used horizontal projections are

• WGS84 - A distance from WGS84 ellipsoid
• NAVD88 - A distance from Geoid representing the gravity model of the earth. It returns orthometric height, which can be interpreted as value from the sea level, however the sea level is specific for each geoid model.

Invalid Image Path

Example measurement values for a point located in Norfolk

Invalid Image Path

So the system which designed for an elevation referenced in WGS84 expects the value -34.153, while system designed for the NAVD88 elevation expects 3.397m which is close to real altitude from the sea level.

Multiple systems in DroneUp

Elevation API

Serves JSON tiles in horizontal datum WGS84 and vertical datum NAVD88 (values provided by USGS).

Mapbox

Mapbox was designed to render terrain elevation data in MSL (NAVD88), it treats the no-data areas as 0 MSL.
It can be tricked to render data in different reference systems, however this behavior is not exposed officially and the full consequences are yet unknown.

Drones

Drones reports elevation data in either WGS84 reference or in a geoid that was pre-loaded to its GPS unit’s firmware. The geoid types depends of drone manufacturer.

DSS

DSS expects elevation data reported in reference to WGS84

Decision

Switching from one reference system to another is a non-trivial operation and error prone. To simplify this operation the elevation conversion service was designed to be the only source of truth for operations of this type. It exposes an API to freely switch between two most often used vertical reference systems WGS84 and NAVD88.

The service can be either deployed as standalone service, or be an internal part of the consumer k8s cluster, depending of the needs.

Conversion Service API

The service exposes an GRPC API with 2 methods:

• ConvertNAVD88ToWGS84 - Method used to translate a vertical data for a point given in NAVD88 to WGS84 reference
• ConvertWGS84ToNAVD88 - Method used to translate a vertical data for a point given in WGS84 to NAVD88 reference

The proto definition for the service:

syntax = "proto3";

service ProjectionService {
    rpc ConvertNAVD88ToWGS84(ConvertRequest) returns (ConvertResponse);
    rpc ConvertWGS84ToNAVD88(ConvertRequest) returns (ConvertResponse);
}

message ConvertRequest {
    double latitude = 1;
    double longitude = 2;
    double value = 3;
}

message ConvertResponse {
    double z = 3;
}

Conversion methodology

To convert the data from one reference system to another a C library PROJ was used. PROJ is a generic coordinate transformation software that transforms geospatial coordinates from one coordinate reference system (CRS) to another.

Proj requires to select a standard CRS (coordinate reference system) for both and input and output of the conversion.

Following Conversion methodologies were taken

NAVD88 to WGS84

The elevation JSON data comes in NAVD88 vertical component and WGS84 horizontal component. To convert it to WGS84 as vertical and WGS84 in horizontal following steps must be taken.

1. There is no official CRS for WGS84 horizontal + NAVD88 in vertical. The horizontal datum must be first converted into NAD83. In this conversion vertical component remains unchanged.

   • Input CRS: EPSG:4326 (WGS84 in horizotal)
   • Output CRS: EPSG:4269 (NAD83 in horizontal)

2. Translate NAD83(horizontal)+NAVD88(vertical) into WGS84(horizontal)+WGS84(vertical)

   • Input CRS: EPSG:5498 (NAD83 in horizotal, NAVD88 in vertical)
   • Output CRS: EPSG:4979 (WGS84 in horizotal, WGS84 in vertical)

WGS84 to NAVD88

This translation expects the input data incoming in WGS84 in both vertical and horizontal planes. There is a standard CRS for such combination so no intermediate translation is required.

1. Translate WGS84(horizontal)+WGS84(vertical) into NAD83(horizontal)+NAVD88(vertical)

   • Input CRS: EPSG:4979 (WGS84 in horizotal, WGS84 in vertical)
   • Output CRS: EPSG:5498 (NAD83 in horizotal, NAVD88 in vertical)

Consequences

• The service enables point-to-point NAVD88 <-> WGS84 conversion of vertical element value.

• Conversion has low latency (~1-2ms)

• Data grids required for NAVD88 <-> WGS84 conversion weights ~1.3GB, which increases the Docker size, however there are few potential resolutions if this becomes a problem:

  • Data grids not required for DroneUp operations can be removed
  • Data grids are accessible through CDN - pre-loading them on the docker may not be necessary

Alternatives considered

In-house conversion engine

Creating an in-house projection engine is possible, since PROJ keeps all GEOIDs definitions in public, but it would require a lot of effort and domain knowledge to introduce reliable system. PROJ is a settled solution which was already battle-tested -it’s being continuously developed since 1983.

Using official conversion tool

NOAA provides an official datum transformation tool, which can be downloaded and ran on EC2 instace, however since it was designed for general use-cases it’s latency may be not sufficient for our use cases. With PROJ we could design a lite version supporting only the needs our organization has.