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:
| Kind | Holds | Typical source |
|---|---|---|
ELK_RASTER | Imagery and scanned maps | Georeferenced images |
ELK_DTM | Elevation | Height grids |
ELK_VECTOR | Points, lines, polygons, with attributes | GIS vector files, spatial databases |
ELK_STATIC_OBJECTS | 3D models and extruded buildings | Model files, vector footprints with heights |
ELK_CODE_MAP | Material and traversability codes | Coded raster grids |
ELK_HEAT_MAP | Scalar values rendered as a colour ramp | Value 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_NONE | MapCore's default schemes, chosen from the data's geometry |
EAST_INTERNAL | The source's own styling — supported for KML and KMZ, or wherever SInternalStylingParams::strStylingFile names an external *.sld, ArcGIS *.lyrx, or MapLibre *.json |
EAST_S52 | MapCore's built-in styling for S-52/S-57 nautical charts |
EAST_CUSTOM | Your 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