Skip to main content

Data formats

MapCore supplies no data. Everything you display is yours, and the first decision about it is not which file format it is in — it is whether MapCore reads it where it sits, or reads a converted copy.

That choice, and the interfaces behind it, are in Layers and terrain. This page is about the data itself: what each kind of layer expects to be pointed at.

The kinds of layer data​

IMcMapLayer::ELayerKind enumerates six kinds, and between them they cover every layer you are likely to build a map from:

KindHoldsTypical source
ELK_RASTERImagery and scanned mapsGeoreferenced images
ELK_DTMElevationHeight grids
ELK_VECTORPoints, lines, polygons, with attributesGIS vector files, spatial databases
ELK_STATIC_OBJECTS3D models and extruded buildingsModel files, vector footprints with heights
ELK_CODE_MAPMaterial and traversability codesCoded raster grids
ELK_HEAT_MAPScalar values rendered as a colour rampValue grids

The enum is not a property you can read back: no method returns a layer's kind. What identifies a layer at runtime is IMcMapLayer::GetLayerType(), or one of the CastToDtmMapLayer()-style methods. ELayerKind is an input — to IMcSpatialQueries::SetTerrainQueriesNumCacheTiles() and to the production functions that take a source type.

A kind is not a format. What varies within a kind is where the bytes come from, and that is the next three sections.

MapCore's own format​

A converted, or native, layer is one that has been through MapCore's conversion into its own tiled format. That is the format the engine is built around: pre-tiled, with a resolution pyramid already computed, so drawing is a read rather than a computation.

You never author it by hand — the conversion tools produce it — but it is worth recognising on disk, because "point at the layer directory" means the directory that looks like this:

a layer definition file — Raster.bin for a native raster layer — alongside the tile index, tile data and one directory per resolution level. The internal layout is MapCore's own and is not a documented interchange format; what matters for using it is the rule below.

Point a Native layer's Create() at the directory that contains those files, not at a file inside it. Each successive resolution level is coarser than the one before, which is what lets the engine pick a level per view instead of scaling the finest data.

Converted layers are also the only kind that can be served: the NativeServer layer interfaces read exactly this format over HTTP from MapCore's Map Layer Server. A URL in place of a directory changes when the layer becomes usable, not what it contains — see Layers and terrain.

Reading data where it sits​

A raw layer reads your source data directly, with no conversion pass. What it accepts is described per layer kind rather than by one global list.

Raster. Georeferenced imagery, read through GDAL — which is visible in the API: a raw raster layer can build the levels of detail your files lack and writes them as GDAL's *.ovr overview files (SRawParams::bAddLevelsOfDetailIfAbsent). The formats available in a given release are therefore the ones the bundled GDAL was built with, so treat GDAL's own format list as the reference and confirm against your release rather than against this page.

A raw layer is a set of components rather than a single file: SRawParams::aComponents lists them, each ECT_FILE or ECT_DIRECTORY, relative to strDirectory. That is how a raw layer spans a folder of tiles that were never one image, and how auPyramidResolutions marks which components begin each resolution level when the sources form a pyramid of their own.

Vector. IMcRawVectorMapLayer::SParams::strDataSource takes a vector file — *.shp, *.mdb and others — a database connection such as PostGIS, or an XML file in MapCore's own vector schema. A multi-layer data source opens only its first sub-layer unless you name the one you want with a suffix.

Vector is also the one kind where styling travels with the data, and how it is styled is a property of the source rather than of the map. IMcRawVectorMapLayer::EAutoStylingType chooses:

EAST_NONEMapCore's default schemes, chosen from the data's geometry
EAST_INTERNALThe source's own styling — supported for KML and KMZ, or wherever SInternalStylingParams::strStylingFile names an external *.sld, ArcGIS *.lyrx, or MapLibre *.json
EAST_S52MapCore's built-in styling for S-52/S-57 nautical charts
EAST_CUSTOMYour own styling XMLs and object schemes, from a folder you supply

One special case worth knowing exists rather than discovering: a strDataSource prefixed with MAPNIK: followed by a stylesheet path produces a rasterized vector layer — vector data drawn as imagery, with a much smaller API on the resulting layer. IsRasterizedVectorLayer() reports it.

Static objects and 3D models. Two different things behind one layer kind. Model files give you 3D geometry directly. Vector footprints give you extruded geometry: polygons plus a height, turned into buildings at load time, which is why IMcVector3DExtrusionMapLayer reads a vector data source much as a vector layer does — a vector file or a database connection, though without the XML option a vector layer additionally accepts.

A raw extrusion source may optionally be indexed in advance with BuildIndexingData(), and IMcRawVector3DExtrusionMapLayer then has a second Create() overload that consumes the index. It is not a prerequisite: that layer also has a Create() that scans the source directly, and a raw 3DTiles layer always scans its source directly. What indexing buys is that the layer takes its coordinate systems, clipping rectangle and tiling scheme from the index rather than from its creation parameters. The index is tied to the data source it was built from — change the source and creation fails with IMcErrors::LAYER_INDEX_SOURCE_MISMATCH.

Elevation. Height grids, listed as components exactly as a raw raster layer's sources are, with one difference: at least one component is required. There is no dynamic elevation layer to add components to afterwards.

Web services​

The third source of data is a server, and here the format is a protocol rather than a file. IMcMapLayer::EWebMapServiceType covers the OGC services — EWMS_WMS, EWMS_WMTS, EWMS_WCS and EWMS_CSW for catalogue search — plus EWMS_MAPCORE for MapCore's own Map Layer Server.

IMcMapDevice::GetWebServerLayers() asks a server what it offers and delivers the answer asynchronously, so you can present the real list instead of requiring a layer name up front. Standard-service layers can be cached on disk, which is what makes them usable on a slow link and at all when disconnected.

Two things that are not the file format​

The coordinate system usually is not in the file — or is not trusted from it. Raw layers take a source coordinate system explicitly, because the same bytes mean different ground positions under a different datum. A converted layer carries the coordinate system it was converted into, which is why a terrain created with NULL can adopt its layer's. See Coordinate systems.

Elevation has a second datum, and it is the one people forget. EMcVerticalDatumType says what your heights are measured from: EVDT_GEOID for orthometric heights (relative to sea level), EVDT_ELLIPSOID for heights above the coordinate system's ellipsoid, and EVDT_DEFAULT to let MapCore determine it from the source where it can. Getting this wrong does not fail — it offsets your heights against the ground by the geoid–ellipsoid separation at that location, silently.

Choosing​

Convert what you will display repeatedly; read raw what is still changing or is being looked at once. Conversion costs a pass over the data and produces a copy; raw costs work on every frame that touches it, and for imagery without its own overviews it costs the most at the coarse zoom levels where you are asking for the most ground at once.

The exception worth stating: only converted layers can be served over HTTP, so a layer that several clients will read is a converted layer whether or not performance was your reason.

See also​

  • Layers and terrain — the layer interfaces, the four flavours of each, and how layers are grouped into a terrain
  • Coordinate systems — world, screen and image frames, and their units
  • Quickstart — a converted raster layer on screen, in four languages

Verified against MapCore 12.5.0

Written from Map/IMcMapLayer.h, Map/IMcRasterMapLayer.h, Map/IMcVectorMapLayer.h, Map/IMcDtmMapLayer.h, Map/IMcStaticObjectsMapLayer.h, Map/IMcCodeMapLayer.h, McCommonTypes.h, Map/IMcMapDevice.h, Production/IMcMapProduction.h, IMcErrors.h