Skip to main content

Add elevation data

The base interface for DTM (elevation) layers, which give a terrain its shape and underlie the spatial queries.

A DTM (elevation) layer gives the terrain its shape: it forms the ground of a 3D map, can be visualized on both 2D and 3D maps (see IMcMapViewport::SetDtmVisualization() and IMcMapViewport::SetHeightLines()), and is what the spatial queries (heights, lines of sight, intersections, etc.; see IMcSpatialQueries) stand on. A terrain has at most one DTM layer (see IMcMapTerrain::GetDtmLayer()). The interface is inherited by IMcNativeDtmMapLayer (data converted to MapCore's format, in a directory or behind a URL), IMcRawDtmMapLayer (unconverted source files), IMcNativeServerDtmMapLayer (MapCore's Map Layer Server) and IMcWebServiceDtmMapLayer (OGC WMS, WMTS and WCS servers).

Used for:

  • Tile geometry: GetTileGeometryByKey() (a tile's triangulated geometry, see STileGeometry); for a layer already in a terrain, the cache-based IMcSpatialQueries::GetDtmLayerTileGeometryByKey() is preferable.
  • Everything a map layer does, as IMcMapLayer: visibility, coordinate system and bounding box, ID and user data, tiles and levels of detail, saving and loading, type and casting.

See also: IMcMapLayer, IMcSpatialQueries::GetTerrainHeight()

— from Map/IMcDtmMapLayer.h

Elevation — DTM, in MapCore's vocabulary — is what gives the ground its shape. It is also what almost every calculation stands on: line of sight, height queries, terrain-following paths and the whole 3D view need to know where the ground is.

One structural rule shapes everything below: a terrain has at most one elevation layer. Raster and vector layers stack freely; the ground's shape comes from a single source. IMcMapTerrain::GetDtmLayer() returns it, singular.

Choose the interface​

InterfaceReads fromCreate() takes
IMcNativeDtmMapLayerData converted to MapCore's format, in a directory or behind a URLa directory or URL
IMcRawDtmMapLayerYour source files, unconvertedSRawParams
IMcNativeServerDtmMapLayerMapCore's Map Layer Servera layer URL
IMcWebServiceDtmMapLayerA WMS, WMTS or WCS serviceSWMSParams, SWMTSParams or SWCSParams

The pattern, the ownership rules and the web-service parameters are the same as for raster layers — Add a raster layer documents them in full, and this page covers only what differs.

Create the layer​

Converted data​

IMcNativeDtmMapLayer *pLayer = NULL;
IMcErrors::ECode eCode = IMcNativeDtmMapLayer::Create(&pLayer, "C:/maps/dtm");

Simpler than its raster counterpart: the only tuning parameter is uNumLevelsToIgnore, which drops that many of the finest levels of detail and is mainly a diagnostic — it lets you see what the layer looks like without its best data. GetCreateParams() reads it back. As with raster, strDirectory may be a URL, and then loading is deferred.

Raw data​

IMcRawDtmMapLayer::Create() takes the same SRawParams as a raw raster layer, with one difference that will bite if you do not know it: at least one component is required. There is no dynamic elevation layer, so the empty component list that a dynamic raster layer starts from is an error here.

fHighestResolution is read as map units per DTM point rather than per pixel. GetComponents() and GetResolutions() report the component list and the resolutions pyramid, exactly as for raster.

From a server​

IMcNativeServerDtmMapLayer::Create() takes a layer URL containing a / and defers loading — it returns once the server requests are issued, and reports IMcErrors::NATIVE_SERVER_LAYER_NOT_VALID through the callback if the server does not recognise the layer. IMcWebServiceDtmMapLayer::Create() is overloaded for WMS, WMTS and WCS; as with raster layers, do not assume its capabilities fetch is deferred — it can fail synchronously — and use IsInitialized() rather than inferring. See Add a raster layer.

One WCS parameter is DTM-specific: SWCSParams::bDontUseServerInterpolation. Leave it false to let the server interpolate, set it true to have MapCore interpolate instead — worth trying when a server's own interpolation visibly terraces the ground.

Vertical datums​

MapCore does not attach a vertical datum to a DTM layer. Heights are whatever the source data holds, interpreted through the layer's coordinate system, and the SDK's vocabulary for the distinction is EMcVerticalDatumType:

ValueMeaning
EVDT_DEFAULTDetermine the datum from the source data where possible, otherwise use the default for that data type
EVDT_GEOIDOrthometric heights — relative to the geoid, that is, above sea level
EVDT_ELLIPSOIDRelative to the source coordinate system's ellipsoid

You declare that type where MapCore has to reconcile two sources — static-object layers and map production both take one — and it does not appear on the DTM layer itself, because a DTM layer is the reference rather than something being reconciled against it. When you need to convert between the two conventions, IMcGeographicCalculations provides ConvertHeightFromEllipsoidToGeoid() and ConvertHeightFromGeoidToEllipsoid().

The practical consequence: if your elevation data and your object heights use different vertical datums, nothing detects it for you. Objects will sit consistently above or below the ground by the geoid–ellipsoid separation at that location. Establish which convention each source uses before you conclude that a layer is misaligned.

Query heights​

Reading heights out of a terrain is IMcSpatialQueries work, not layer work: point heights, ground intersections, profiles and line of sight are all asked of the queries interface, against the terrain rather than against one layer. The layer interface below is for the cases where you want the raw tiles.

Work with tiles directly​

GetTileGeometryByKey() returns one tile's mesh as an STileGeometry: point coordinates and normals, triangle indices, and the tile's minimum and maximum height. Two things about it are easy to get wrong.

Coordinates are tile-local, relative to the tile's minimum corner, not world coordinates.

Skirt data lives at the end. A tile's mesh carries a skirt — the vertical apron that hides the seam against neighbouring tiles — and its points and indices are appended after the real ones. uNumSkirtPoints and uNumSkirtIndices say how many, so a consumer that wants only the surface takes the arrays minus those counts, and fMinHeight already excludes the skirt's added points.

bBuildIfPossible decides what happens when the tile you asked for does not exist but a coarser one does: build the geometry from the relevant part of the coarser tile, or fail with IMcErrors::FILE_NOT_FOUND.

As with the raster equivalent, this call bypasses the terrain cache and reloads the tile every time. If the layer is in a terrain, IMcSpatialQueries::GetDtmLayerTileGeometryByKey() is the cache-aware version and the one to prefer.

Error codes​

CodeCause
IMcErrors::NOT_INITIALIZEDNo map device yet — or, from a getter, the layer's loading has not finished
IMcErrors::INVALID_PARAMETERSA required pointer is NULL; no raw components; a malformed pyramid
IMcErrors::FILE_NOT_FOUNDA layer file is missing, no component could be opened, uNumLevelsToIgnore is too large, or a tile does not exist and bBuildIfPossible is false
IMcErrors::COORDINATE_SYSTEMS_MISMATCHRaw components disagree about their coordinate system
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEMA component carries no coordinate system and none was supplied
IMcErrors::CANT_READ_FILEThe source, or a service's capabilities, could not be processed
IMcErrors::READ_FROM_STORAGE_FAILEDThe layer's tile data could not be read
IMcErrors::FAILUREA tile exists but could not be loaded
IMcErrors::NOT_IMPLEMENTEDThis build has no HTTP support
IMcErrors::LAYER_WEB_REQUEST_FAILUREA required web request could not be issued
IMcErrors::NATIVE_SERVER_LAYER_NOT_VALIDThe Map Layer Server does not recognise the layer

Local-cache codes are covered in Tune the local cache.

Verified against MapCore 12.5.0

Written from Map/IMcDtmMapLayer.h, Map/IMcMapLayer.h, Map/IMcMapTerrain.h, Calculations/IMcSpatialQueries.h, Calculations/IMcGeographicCalculations.h, McCommonTypes.h