Elevation data

Elevation data and other single channel data can be used for various analysis and visualization purposes throughout the Maria system. This page shows an overview of the elevation data programming API's

The two main interfaces for elevation data are IElevationData (implemented by the NativeElevationData class) and IElevationDataManager (implemented by ElevationDataManager).

IElevationData

This interface contains methods for querying elevation data from a set of data layers.

Data layers

An elevation data set consists of one or more elevation data map entries stored on a Maria raster data service. The set of available map entries can be queried from the catalog service and any MapEntry with MapContentType = ElevationData can be used.

The elevation data layers are usually managed by the ElevationDataManager, but you can also specify them explicitly through a MapTemplate with the SetTemplate method

        /// <summary>
        /// Setup elevation data layers from the given template.
        /// This method will clear the current elevation data set.
        /// </summary>
        void SetTemplate(MapTemplate template);

        /// <summary>
        /// Get the currently active elevation data template.
        /// </summary>
        /// <returns></returns>
        MapTemplate GetTemplate();

The format of this elevation data template is described here: Elevation layers in templates

Elevation queries

The main purpose of the IElevationData interface is to calculate elevation values in a certain geographical point or area. The following methods are supported for this:

        /// <summary>
        /// Generalized API for elevation queries.
        /// </summary>
        /// <param name="lat">Latitude of the query point</param>
        /// <param name="lon">Longitude of the query point</param>
        /// <param name="queryParams">Parameters for the elevation query.</param>
        /// <returns>An ElevationResult containing the elevation and resolution of the source data</returns>
        ElevationResult CalcElevation(double lat, double lon, ElevationQueryParams queryParams);

        /// <summary>
        /// Calculate multiple elevations for a given point.
        /// </summary>
        /// <param name="lat">Latitude of the query point</param>
        /// <param name="lon">Longitude of the query point</param>
        /// <param name="queryParams">Parameters for the elevation query.</param>
        /// <returns>
        /// A list of ElevationResults containing the elevation and resolution of each layer in the source data. 
        /// To get further info on each of the layers, you can look up the matching ElevationDataSource entry in 
        /// IElevationDataManager.
        /// </returns>
        List<ElevationResult> CalcElevations(double lat, double lon, ElevationQueryParams queryParams);

        /// <summary>
        /// Synchronously calculate an elevation map covering the given raster projector.
        /// </summary>
        /// <param name="rp">Raster projector defining the area and projection of the elevation map.</param>
        /// <param name="queryParams">Parameters for the elevation query.</param>
        /// <returns>A bitmap of floating point elevation samples.</returns>
        BitmapFloatData CalcElevationMap(IRasterProjector rp, ElevationQueryParams queryParams);

        /// <summary>
        /// Calculate a normal map covering the given raster projector. The normal vectors are encoded as 
        /// XYZ -> RGB values. The alpha channel is not used.
        /// </summary>
        /// <param name="rp">Raster projector defining the area and projection of the elevation map.</param>
        /// <param name="interpolationMethod">Method of resampling/interpolation. Nearest is usually sufficient here.</param>
        /// <param name="timeoutMs">Timeout in ms. If 0, block indefinitely.</param>
        /// <returns></returns>
        Bitmap32Data CalcNormalMap(IRasterProjector rp, InterpolationMethod interpolationMethod = InterpolationMethod.Nearest, int timeoutMs = 0);

As we can see all these methods require an ElevationQueryParams object as input. This query object contains all the parameters for the elevation query, such as what data elevation data types to look for, what resolution we require, interpolation method etc. The elevation data query is actually a specialization of the more general raster data query:

    public class RasterQueryParams
    {
        /// <summary>
        /// Method of resampling/interpolation (Nearest or Bilinear).
        /// </summary>
        public InterpolationMethod interpolationMethod = InterpolationMethod.Bilinear;

        /// <summary>
        /// Only include data from data sets with any of the given tags
        /// </summary>
        public string Tags { get; set; }

        /// <summary>
        /// Minimum resolution (in m/pixel) of the data we want to base the calculation on.
        /// </summary>
        public double resolution = 0.0;

        /// <summary>
        /// Timeout in ms when waiting for data. If 0, wait indefinitely.
        /// </summary>
        public int timeoutMs = 0;
    };

    /// <summary>
    /// Parameter class for elevation data queries.
    /// </summary>
    public class ElevationQueryParams : RasterQueryParams
    {
        /// <summary>
        /// Query data type, only return samples of this data type. Ignored if set to Undefined.
        /// </summary>
        public ElevationDataType dataType = ElevationDataType.Undefined;
    };

The single point elevation data queries return an ElevationResult which looks like this:

    public class ElevationResult
    {
        public enum StatusCode
        {
            Undefined = 0,
            /// <summary>
            /// The query finished successfully
            /// </summary>
            OK,
            /// <summary>
            /// No data could be found at the given position.
            /// </summary>
            Missing,
            /// <summary>
            /// The query took longer than the given timeout values
            /// </summary>
            Timeout,
            /// <summary>
            /// Some unspecified error caused the query to fail.
            /// </summary>
            Error
        };

        /// <summary>
        /// The result status of the query. 
        /// </summary>
        public StatusCode Status { get; set; }

        /// <summary>
        /// The actual elevation value, if status == OK
        /// </summary>
        public double Value { get; set; }

        /// <summary>
        /// Estimated data resolution (in m/pixel) of the dataset from which the result was taken.
        /// </summary>
        public double Resolution { get; set; }

        /// <summary>
        /// Identifier for the elevation data layer that was used to produce this sample.
        /// This value can be used to look up further info about the data source by resolving
        /// it in ElevationDataManager.DataSources
        /// </summary>
        public int LayerId { get; set; }

        /// <summary>
        /// Type of elevation data (TerrainModel, Bathymetry, etc).
        /// </summary>
        public ElevationDataType DataType { get; set; }
    }

As we can see the result contains information on the sample we found in the given input position. In order to get more information on the underlying data layer, you need an ElevationDataManager handling the layers.

Note on async methods

The IElevationData interface currently contains a set of methods with Async in their names which return Task objects. We don't really recommend using these, and they may be obsoleted in a future version. Instead, wrap any time consuming elevation methods in your own async caller method to have better control over these operations.

IElevationDataManager

The ElevationDataManager uses the catalog service to find all available elevation data sets and provides an interface for sorting and filtering these layers according to certain critieria, and building an ElevationData template which is used by the IElevationData interface as described above.

ElevationDataClient

The ElevationDataClient class is a utility class for setting up an ElevationDataManager with corresponding tile cache and service clients, and can be found in the TPG.GeoFramework.MapLayer assembly.

It can either be set up completely standalone where it creates its own tile cache and service clients (requires a MapCatalogService config in the app.config), or with an existing catalog service client. In these cases you need to dispose the ElevationDataClient after use, in order to clean up the internal tile cache and service client structures.

Alternatively you can also set up the ElevationClient with an existing NativeTileCacheManager. This tile cache must be set up with the correct MapDataProviders for reading elevation data tiles. In this case, no disposal is necessary as long as you dispose the NativeTileCacheManager somewhere else.

Example:

var elevationDataClient = new ElevationDataClient();
var elevationDataManager = elevationDataClient.ElevationDataManager;
if(elevationDataManager != null)
{
    var elevationDataQuery = new ElevationDataSortByResolution();

    // Sort elevation layers on resolution and generate a template 
    elevationDataManager.UpdateDataSources();
    elevationDataManager.GenerateLayers(elevationDataQuery);
    var elevationData = elevationDataManager.ElevationData;
    var elevResult = elevationData.CalcElevationEx(60.0, 10.0, InterpolationMethod.Bilinear, 0.0);
    if (elevResult.Status == ElevationResult.StatusCode.OK)
    {
        ElevationDataSource elevSource = null;
        elevationDataManager.DataSources.TryGetValue(elevResult.LayerId, out elevSource);
        var mapSignature = elevSource != null ? elevSource.MapEntry.MapSignature : "(Unknown)";
        Console.WriteLine(@"Elevation = {0}, resolution = {1}, map signature = {2}", elevResult.Value, elevResult.Resolution, mapSignature);
    }
    else
        Console.WriteLine(@"Elevation calculation failed, status = {0}", elevResult.Status);

    // Clean up
    elevationDataClient.Dispose();
}