Elevation API ATLAS Elevation 1 Rasterdatastorage

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

ADR-0044 · Author: Sybil Melton · Date: 2025-02-07 · Products: platform
Originally ADR-0053 ELEVATION_API_ATLAS_ELEVATION_1_RasterDataStorage (v3) · Source on Confluence ↗

Raster data storage

Context

Atlas ingest a rasterized geospatial data from external providers. This data then must be stored in a format that supports serving the subsets of it or querying through it by Atlas consumers. The storage system should must support cutting and serving the data into the tiles (defined in Output Data Abstraction ADR)

Decision

The Cloud Optimized GeoTiff (COG) was chosen as default storage format for geospatial data.

COGs leverage a powerful internal data structure that enhances their functionality. The data is organized in a way that enables efficient access through HTTP range requests, allowing users to retrieve specific portions of a file without the need to download the entire dataset. Notably, COGs exceeding dimensions of 1024 pixels by 1024 pixels are internally tiled to facilitate this process.

Data Organization

Internally, each COG contains a metadata header with a predefined structure. This header encapsulates the Image File Directory (IFD) for each internal data block, also known as an internal tile. The IFD is a crucial component of a COG, as it stores essential information such as TileOffsets and TileByteCounts for each internal tile. This setup enables the construction of an internal map of the data by fetching only the initial bytes, streamlining data retrieval.

An example cog internal structure:

Invalid Image Path

Key Components

HTTP Range Requests: The ability to access data via HTTP range requests is a key feature of COGs, facilitating the retrieval of specific portions of large datasets with minimal data transfer.
Internal Tiling: COGs are internally tiled into either 256x256 or 512x512 tiles, enhancing the efficiency of data access and retrieval. In image IDF each internal tile index has a byte offset mapped to it, therefore it allows to read it without parsing whole file.

Invalid Image Path

Metadata Header: The metadata header follows a specific structure and holds the IFD for each internal tile, providing essential details for data organization and retrieval.
IFD (Image File Directory): The IFD holds critical information, including TileOffsets and TileByteCounts, enabling the construction of an internal map of the data.
Internal Overviews: COGs offer an optional feature known as internal overviews, which are reduced-resolution versions of the raw data. By incorporating internal overviews, users can preview the data using fewer range requests.
Invalid Image Path

Summary

The reasons why it COG was chosen as a default storage file format for raaster data:

COG is official standard format for geospatial data [1]
An official Datasets already publish their data as COGs (eg. USGS)
COG allows to store metadata in file header (eg. bonding box, projection reference etc.)
COG file format is sorted internally, which allows to leverage HTTP range request to download only small chunk of the file.
Since it’s a tiff, it can consist of multiple images. This feature allows to store original image and the overviews within one file.

Consequences

COG is default raster file format
COGs must be stored on a server that supports HTTP Range request during download. Google Cloud Storage is the default choice.
The services can retrieve raw geospatial raster data by checking COG header and then requesting only for subset of tiles which intersects their area of interests.
The smallest unit of area that cog contains is represented by a 4 points bounding box (a pixel). It has a raw data value assign to it.

Alternatives Considered

Pre-rendering the tiles with GDAL (create XYZ file structure)

Pre-rendering elevation data introduces redundancy within the storage layer. If this alternative is selected, it necessitates the preservation of both the original data source and the pre-rendered XYZ file structure for every projection that is required to be supported.