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 (
NULLtakes 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:
| Field | Effect | Default |
|---|---|---|
fMinScale, fMaxScale | Scale range in which the layer is visible | 0 to FLT_MAX — always |
nDrawPriority | Draw order among the terrain's layers | 0 |
byTransparency | 0 transparent, 255 opaque, between is semi-transparent | 255 |
bVisibility | Whether the layer is drawn at all | true |
bNearestPixelMagFilter | Nearest-pixel instead of bi-linear magnification, for raster layers | false |
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:
| Kind | What it holds |
|---|---|
ELK_DTM | Elevation |
ELK_RASTER | Imagery and raster maps |
ELK_VECTOR | Vector features |
ELK_STATIC_OBJECTS | Fixed 3D content — models converted from a 3D source, and buildings extruded from vector contours |
ELK_CODE_MAP | Material and traversability coding |
ELK_HEAT_MAP | Accumulated 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:
| Interface | Description |
|---|---|
IMcDtmMapLayer | The base interface: gives a terrain its shape and underlies the spatial queries |
IMcNativeDtmMapLayer | Data in MapCore format — converted |
IMcRawDtmMapLayer | Raw data — unconverted |
IMcNativeServerDtmMapLayer | Data from MapCore's Map Layer Server |
IMcWebServiceDtmMapLayer | Data 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.