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
| Interface | Reads from | Create() takes |
|---|---|---|
IMcNativeDtmMapLayer | Data converted to MapCore's format, in a directory or behind a URL | a directory or URL |
IMcRawDtmMapLayer | Your source files, unconverted | SRawParams |
IMcNativeServerDtmMapLayer | MapCore's Map Layer Server | a layer URL |
IMcWebServiceDtmMapLayer | A WMS, WMTS or WCS service | SWMSParams, 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:
| Value | Meaning |
|---|---|
EVDT_DEFAULT | Determine the datum from the source data where possible, otherwise use the default for that data type |
EVDT_GEOID | Orthometric heights — relative to the geoid, that is, above sea level |
EVDT_ELLIPSOID | Relative 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
| Code | Cause |
|---|---|
IMcErrors::NOT_INITIALIZED | No map device yet — or, from a getter, the layer's loading has not finished |
IMcErrors::INVALID_PARAMETERS | A required pointer is NULL; no raw components; a malformed pyramid |
IMcErrors::FILE_NOT_FOUND | A 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_MISMATCH | Raw components disagree about their coordinate system |
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEM | A component carries no coordinate system and none was supplied |
IMcErrors::CANT_READ_FILE | The source, or a service's capabilities, could not be processed |
IMcErrors::READ_FROM_STORAGE_FAILED | The layer's tile data could not be read |
IMcErrors::FAILURE | A tile exists but could not be loaded |
IMcErrors::NOT_IMPLEMENTED | This build has no HTTP support |
IMcErrors::LAYER_WEB_REQUEST_FAILURE | A required web request could not be issued |
IMcErrors::NATIVE_SERVER_LAYER_NOT_VALID | The Map Layer Server does not recognise the layer |
Local-cache codes are covered in Tune the local cache.