Skip to main content

Layers and terrain

A layer reads map data. A terrain assembles layers into something a viewport can show. Almost all the data-side work in a MapCore application is arranging these two.

The terrain​

Interface for a terrain: a set of map layers of different kinds, shown by viewports and queried by spatial queries.

A terrain is the unit of map content shown by a viewport (see IMcMapViewport::Create() and IMcMapViewport::AddTerrain()) or queried by a standalone spatial-queries interface (see IMcSpatialQueries::Create()). It holds a reference to its coordinate system and to each of its layers: a layer can belong to several terrains, and a terrain can be used by several viewports. A terrain is created by Create() from existing layers (or by Load() from a saved definition) and released with IMcBase::Release(). A map device must have been created (see IMcMapDevice::Create()) before any terrain or layer is created.

Used for:

  • Creation: Create() from an array of layers and an optional coordinate system (NULL takes it from the first layer that has one).
  • Terrain parameters: SetCoordinateSystem() and GetCoordinateSystem(); GetBoundingBox() (the union of the loaded layers' boxes); SetVisibility() and GetVisibility(), in all viewports or in one of them.
  • Terrain ID and user data: SetID() and GetID() (the ID looks the terrain up in IMcMapViewport::GetTerrainByID()); SetUserData() and GetUserData(); GetDisplayItemsAttachedTo3DModelWithoutDtm().
  • Layers: AddLayer() and RemoveLayer(); the per-terrain display parameters of a layer (scale range, draw priority, transparency, visibility) with SetLayerParams() and GetLayerParams() (see SLayerParams); GetLayers(), GetLayerByID() (by the ID set with IMcMapLayer::SetID()) and GetDtmLayer().
  • Saving and loading: Save() writes the terrain definition (its layers and their parameters, not the map data) to a file or a memory buffer, and Load() creates a terrain from it; the user data is saved only when bSaveUserData is true.

A terrain has at most one DTM layer, and all its layers must share its coordinate system and tiling scheme (see AddLayer() for the complete list of rules). Layers not yet initialized (see IMcMapLayer::IsInitialized()) are members of the terrain nevertheless: GetLayers() and GetDtmLayer() return them, SetLayerParams() accepts them, and GetBoundingBox() returns IMcErrors::NOT_INITIALIZED (with the box of the already initialized layers) until all of them are initialized.

See also: IMcMapLayer, IMcMapViewport::AddTerrain(), IMcSpatialQueries::Create()

— from Map/IMcMapTerrain.h

One structural point that shapes how you assemble a map: a terrain has at most one elevation layer. GetDtmLayer() returns it, singular. Raster, vector and object layers stack freely, but the ground's shape comes from one source.

That getter has one behaviour worth knowing before it confuses you: it returns the terrain's own elevation layer, and MapCore may have created one automatically — an automatically created layer is never returned. So NULL means "no elevation layer that you supplied", not "flat ground". A layer still loading is returned normally.

Per-layer display parameters​

SetLayerParams() and GetLayerParams() control how one layer appears within one terrain, so the same layer can be drawn differently in two terrains:

FieldEffectDefault
fMinScale, fMaxScaleScale range in which the layer is visible0 to FLT_MAX — always
nDrawPriorityDraw order among the terrain's layers0
byTransparency0 transparent, 255 opaque, between is semi-transparent255
bVisibilityWhether the layer is drawn at alltrue
bNearestPixelMagFilterNearest-pixel instead of bi-linear magnification, for raster layersfalse

Scale range is the main tool for building a map that stays legible as the user zooms: a detailed vector layer that is unreadable when zoomed out is given a fMaxScale and simply stops being drawn.

The layer family​

IMcMapLayer is the base interface for every layer. ELayerKind names the six kinds of data:

KindWhat it holds
ELK_DTMElevation
ELK_RASTERImagery and raster maps
ELK_VECTORVector features
ELK_STATIC_OBJECTSFixed 3D content — models converted from a 3D source, and buildings extruded from vector contours
ELK_CODE_MAPMaterial and traversability coding
ELK_HEAT_MAPAccumulated point values

Each kind then comes in up to four flavours, distinguished by where the data lives rather than what it contains. Taking elevation as the example, and reading straight from the interface descriptions:

InterfaceDescription
IMcDtmMapLayerThe base interface: gives a terrain its shape and underlies the spatial queries
IMcNativeDtmMapLayerData in MapCore format — converted
IMcRawDtmMapLayerRaw data — unconverted
IMcNativeServerDtmMapLayerData from MapCore's Map Layer Server
IMcWebServiceDtmMapLayerData from OGC web services — WMS, WMTS and WCS

The same pattern holds for raster (IMcRasterMapLayer and its Native, Raw, NativeServer, WebService variants), vector, material, traversability, 3D model and 3D extrusion layers. Once you know the pattern, the interface you need follows from two questions — what kind of data, and where does it come from — rather than from a list.

One asymmetry in that table is worth noting: WebService exists only for elevation and raster, because that is what the standards serve. Every other kind — vector, material, traversability, objects, 3D models, extrusions — has Raw, Native and NativeServer forms but no web-service form.

For the standard services, EWebMapServiceType covers EWMS_WMS, EWMS_WMTS, EWMS_WCS and EWMS_CSW, plus EWMS_MAPCORE for MapCore's own Map Layer Server. IMcMapDevice::GetWebServerLayers() asks a server what it offers, asynchronously, so you can present a real list rather than requiring the layer name up front.

WMTS servers do not agree on the axis order of the bounding box they report in their capabilities — X,Y for some, Y,X for others, and what counts as the default depends on the coordinate system. The enum that names the possibilities:

Order of WMTS coordinate axes.

— from Map/IMcMapLayer.h

Its values are ECAO_DEFAULT, the order the coordinate system implies; ECAO_INVERSE, the opposite of that; and ECAO_XY and ECAO_YX, which fix the order outright. The field that takes it is SWMTSParams::eCapabilitiesBoundingBoxAxesOrder, on the WMTS parameters, and its default is ECAO_DEFAULT. Set it to what the server actually does, so that MapCore reads the extent the way the server wrote it; a layer whose extent comes out transposed is the symptom of getting it wrong.

Converted or raw​

The distinction the interfaces draw is simply whether the data has been converted to MapCore's own format in advance. A Raw layer reads your source data where it sits; a Native layer reads data already converted.

Converting is a separate, offline step, so the choice is about when you pay a cost rather than whether: raw layers cost nothing to set up, converted layers cost a conversion pass and are what MapCore's own format exists for. Use raw data to get something on screen and for data that is still changing; convert what you intend to display repeatedly.

Lifetime​

Layers and terrains are created with a zero reference count, and the rules for owning them are in Threading and lifecycle. The short version: if you keep it, AddRef() it; if you are handing it straight to a terrain or a viewport, pass it as is and let that own it.

Loading is asynchronous. A layer exists before its data has arrived, IsInitialized() reports whether it has, and an IMcMapLayer::IReadCallback tells you when it does — including when it does not, with a string naming the file or request that failed. Removal is asynchronous too: RemoveLayerAsync() returns before the layer is gone. The full callback contract is in Threading and lifecycle.

How much of the layer is asynchronous depends on where it reads from, and the difference is easy to be caught by. Give a Native layer a directory and it is initialized by the time Create() returns: only tile data arrives later, so the layer's coordinate system and bounding box can be read immediately. Give the same layer a URL and initialization itself is deferred — IsInitialized() is false until OnInitialized() fires, and until then the layer has neither a coordinate system nor a bounding box to offer.

Anything derived from the layer's own metadata therefore has to wait: a terrain created with a NULL coordinate system has nothing to adopt yet, and GetBoundingBox() cannot frame a camera on a map whose extent is not known. This is not a web-specific rule, but it is unavoidable on the web, where a URL is the only kind of source there is.

Local cache​

Layers that read from a server can cache tiles on disk, which is what makes a network-backed map usable on a slow link and at all when disconnected. IMcMapDevice::GetMapLayersLocalCacheParams() reports the cache folder, its size limit and its current size, along with per-layer figures; SetMapLayersLocalCacheSize() changes the limit; and RemoveMapLayerFromLocalCache() clears one layer's cache, or every layer's if given NULL.

RemoveMapLayersLocalCache() is the stronger one and not merely "all of them": it removes the cache folder and stops creating or using a local cache at all. Reach for the per-layer call unless you mean to turn caching off.

Verified against MapCore 12.5.0

Written from Map/IMcMapTerrain.h, Map/IMcMapLayer.h, Map/IMcDtmMapLayer.h, Map/IMcMapDevice.h