Skip to main content

Add a vector layer

The base interface for vector layers, displaying their vector items as MapCore objects held in an overlay.

A vector layer displays its vector items as MapCore objects held in an overlay of the map device's overlay manager. The overlay is created when the layer's terrain is added to a viewport, so the layer becomes "initialized" only then (see IMcMapLayer::IsInitialized()); until then the state, draw-priority, brightness and collision-prevention setters only store the values and return IMcErrors::SUCCESS, and the matching getters return the stored values. It is inherited by IMcNativeVectorMapLayer (data converted to MapCore's format, in a directory or behind a URL), IMcRawVectorMapLayer (a GDAL/OGR data source read as is) and IMcNativeServerVectorMapLayer (MapCore's Map Layer Server); there is no web-service vector layer.

Used for:

  • State: SetOverlayState() and GetOverlayState() for the whole overlay, SetVectorItemObjectState() and GetVectorItemObjectState() for one vector item's object (the state selects the versions of the objects' properties to be used).
  • Draw priority: SetOverlayDrawPriority() and GetOverlayDrawPriority() (the overlay's priority relative to the objects' overlays); SetDrawPriorityConsistency() and GetDrawPriorityConsistency().
  • Brightness: SetBrightness() and GetBrightness(), in all viewports or in one of them.
  • Collision prevention: SetCollisionPrevention() and GetCollisionPrevention() (labels not hiding each other).
  • Tolerance for point: SetToleranceForPoint() and GetToleranceForPoint().
  • Layer parameters: IsLiteVectorLayer() and GetMinMaxSizeFactor().
  • The vector data: GetGeometryType(), GetLayerAttributes() and GetLayerDataSources(); the item IDs with VectorItemIDToOriginalID() and VectorItemIDFromOriginalID(); the fields with GetNumFields(), GetFieldData() and GetValidFieldsPerDataSource(); the items with GetVectorItemsCount(), GetVectorItemPoints(), GetScanExtendedData(), the GetFieldUniqueValuesAsXxx() and GetVectorItemFieldValueAsXxx() families and Query().
  • Extended geometry data: GetExtendedGeometryDataSize() and LoadExtendedGeometryDataToMemory().
  • Everything a map layer does, as IMcMapLayer (through the member-less IMcVectorBasedMapLayer): visibility, coordinate system and bounding box, ID and user data, tiles and levels of detail, saving and loading, type and casting.

Note: The data-query methods GetVectorItemPoints(), GetScanExtendedData(), the GetFieldUniqueValuesAsXxx() and GetVectorItemFieldValueAsXxx() families and Query() accept an optional IMcMapLayer::IAsyncOperationCallback. MapCore never takes ownership of the callback: the caller must keep it alive until the result is delivered and destroy it afterwards. The callback is never invoked when the method itself returns an error. Its effect depends on the layer type:

  • On a native-server layer (see IMcNativeServerVectorMapLayer) the callback is mandatory: the query is sent to the server, the method returns IMcErrors::SUCCESS once the request was issued, and the result and its status arrive later in the callback. Without a callback such a layer returns IMcErrors::SYNC_OPERATION_ON_NATIVE_SERVER_LAYER.
  • On any other layer the query is always performed synchronously. When a callback is passed, the result and its status are reported through the callback, the output parameters are emptied and the method itself returns IMcErrors::SUCCESS. Without a callback the result is returned through the output parameters and its status is the method's return value.

— from Map/IMcVectorMapLayer.h

That first sentence is the one to hold on to. A vector layer is not drawn like a raster layer — it becomes objects in an overlay, which is why so much of its behaviour is expressed in the vocabulary of the overlay manager, and why its initialisation is different from every other layer's.

Initialisation is different here​

A raster or elevation layer is initialised when its data has been read. A vector layer is initialised when its terrain has been added to a viewport, because that is when the overlay holding its objects is created.

Until then, the setters below — state, draw priority, brightness, collision prevention — do not fail. They store the value and return IMcErrors::SUCCESS, the matching getters return what was stored, and everything is applied when initialisation happens. So configuring a layer immediately after creating it is legal and is usually what you want. What you cannot do early is query it: the data methods need the loaded data and return IMcErrors::NOT_INITIALIZED.

Choose the interface​

InterfaceReads fromCreate() takes
IMcNativeVectorMapLayerData converted to MapCore's format, in a directory or behind a URLa directory or URL
IMcRawVectorMapLayerA GDAL/OGR data source, unconvertedIMcRawVectorMapLayer::SParams
IMcNativeServerVectorMapLayerMapCore's Map Layer Servera layer URL

There is no web-service vector layer: WMS, WMTS and WCS serve pixels and coverages, not features.

Two variants cut across that table and both restrict what the rest of this page applies to:

  • A 'lite' layer is a native layer converted that way. It holds no per-item MapCore object, so per-item state cannot be overridden on it. IsLiteVectorLayer() reports it.
  • A rasterized layer is a raw layer whose data source name begins with MAPNIK: followed by the path of a styling sheet. It renders its data into raster tiles instead of into objects, and most of the interface is then either a no-op returning success with an empty result or returns IMcErrors::NOT_IMPLEMENTED. IsRasterizedVectorLayer() reports it. It is also the only kind of raw vector layer that supports a local cache — asking for one on any other raw vector layer returns IMcErrors::NOT_IMPLEMENTED.

Create the layer​

Converted data​

IMcNativeVectorMapLayer *pLayer = NULL;
IMcErrors::ECode eCode = IMcNativeVectorMapLayer::Create(&pLayer, "C:/maps/roads");

As elsewhere, strDirectory may be a URL and loading is then deferred.

Raw data​

IMcRawVectorMapLayer::Create() opens the data source synchronously, so a successful return means the layer is ready. IMcRawVectorMapLayer::SParams is the largest parameter struct in the layer family; the fields divide into four groups.

What to read:

FieldNotes
strDataSourceA raw file (.shp, .mdb, …), an XML file, or a PostGIS layer. Required
pSourceCoordinateSystemRequired unless the data source carries its own
pClipRectOptional clip, in the source's coordinate system, x and y only. NULL, all-zero or all-DBL_MAX means no clipping
strLocaleStrLocale for string handling; NULL or empty uses the current one

A multi-layer data source opens only its first sub-layer unless you append a suffix to strDataSource. To find out what is in one, call the static IMcRawVectorMapLayer::GetDataSourceSubLayersProperties() before creating the layer — it opens and closes the source itself and returns one SDataSourceSubLayerProperties per sub-layer with its index, name, geometry, item count, and the strMultiGeometriesSuffix to append. It works for every multi-layer format except XML, PG: (PostGIS) and SDE:.

How it is displayed:

FieldNotes
fMinScale, fMaxScaleScale range. Considered only when fMinScale < fMaxScale; not relevant for XML sources
strPointTextureFileTexture for a point layer; also the default texture under internal styling
dSimplificationToleranceLine and polygon simplification in map units. Default 0, no simplification

Performance — the four fields that decide whether a large layer is usable:

FieldDefaultEffect
uMaxNumVerticesPerTile100000Above this, objects that fit a child tile move down into it. Higher favours zoom-in, lower favours zoom-out; UINT_MAX disables
uMaxNumVisiblePointObjectsPerTile5000Point objects beyond this are hidden depending on scale; UINT_MAX disables
uMinPixelSizeForObjectVisibility8Lines and polygons smaller than this in pixels are hidden depending on scale; 0 disables
fOptimizationMinScale0Below this scale the two hiding optimisations are not applied at all. FLT_MAX disables them entirely

Styling — covered next.

GetCreateParams() reads the parameters back along with the target coordinate system and tiling scheme, as a shallow copy pointing at layer-owned memory.

From a Map Layer Server​

IMcNativeServerVectorMapLayer::Create() takes a layer URL containing a /. This layer holds no vector data of its own, which has a consequence you cannot design around: every data query must be made asynchronously. See Query the data.

Styling​

A converted layer carries its styling with it. A raw layer has to be told, through SParams::eAutoStylingType:

ValueWhat it does
EAST_INTERNALBuild MapCore schemes from the source's own styling. The default
EAST_NONENo automatic styling — MapCore's default schemes for the source's geometry
EAST_S52MapCore's predefined styling for S52/S57
EAST_CUSTOMYour own: a folder of styling XMLs and MapCore object schemes, named by strCustomStylingFolder

None of this applies when strDataSource is an XML file, which already is a styling description.

EAST_INTERNAL is the interesting one, because it can consume external style sheets as well as the source's own. SInternalStylingParams::strStylingFile accepts SLD (.sld), ArcGIS LYRX (.lyrx), and MapLibre (.json); leave it NULL and the data source's internal styling is used, which currently means KML and KMZ. Either way MapCore generates an XML file and a Schemes folder:

FieldNotes
strOutputFolderWhere to write them. NULL uses the data source's folder
strOutputXMLFileNameName of the generated XML. NULL derives it from the data source name
eVersionCompatibility of the generated schemes with older MapCore releases. Default IMcOverlayManager::ESVC_LATEST — no compatibility
fMaxScaleFactorCaps the overlay manager's scale factor for this layer. Default 1
pDefaultFontUsed where the styling defines no font. With an IMcLogFont it also supplies parameters the styling omits
fTextMaxScaleLargest scale at which text is drawn. Default FLT_MAX

That generation step is worth knowing about: styling a raw layer writes files next to your data unless you point strOutputFolder somewhere else. GetStylingParams() reads the parameters back — and returns NULL with success on a rasterized layer, which has none.

Adjust the appearance​

These act on the layer's overlay, and all of them may be called before initialisation.

Draw priority. By default a vector layer draws above all raster layers and below the objects' overlays, ordered among similar layers by its terrain's priority and its own. SetOverlayDrawPriority(true, nPriority) moves it into the object overlays' ordering at the priority you give. The two other priorities that interact with it are IMcMapViewport::SetTerrainDrawPriority() and IMcMapTerrain::SetLayerParams().

SetDrawPriorityConsistency() makes symbolic items of equal priority in layers of equal priority draw in a consistent order. It is off by default, and the header's own guidance is precise about the trade-off: it can degrade performance when many items share a draw priority, and it is recommended where there are many overlaps between same-priority items of significantly different colours.

Brightness. SetBrightness() takes −1 to 1: an offset added to every colour component, 0 unchanged, 1 white, −1 black. Per viewport or, with NULL, for all of them. Once the layer is initialised, GetBrightness() derives its answer from the colour override actually in effect, so it can differ from what you set if something changed the override meanwhile.

Collision prevention. SetCollisionPrevention() stops labels hiding one another. Off by default.

Size factors. GetMinMaxSizeFactor() reports the bounds set at conversion time (always 1 for a raw layer). They clamp the factor applied by IMcOverlayManager::SetItemSizeFactors() when it is called for vector items.

Object state​

Vector items are objects, so they have object state — the mechanism that selects which version of each property is used. Set it for the whole layer with SetOverlayState(), either as one sub-state or as an array of them, per viewport or for all viewports.

When state is an array, the version used for a property is the one from the first sub-state that defines it; when no sub-state defines it, the zero-state version is used. Passing NULL with a count of 0 resets to the zero state, and repeating a sub-state in the array is an error (IMcErrors::ID_ALREADY_EXISTS).

SetVectorItemObjectState() overrides that for one item by ID. The override is stored by the layer and reapplied whenever the item's object is recreated. Setting it for all viewports removes any per-viewport overrides of that item, and passing NULL for the array removes the override. It is not available on a 'lite' layer, which has no per-item object to carry it — IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYER.

Query the data​

Five of the calls below take an optional IMcMapLayer::IAsyncOperationCallback, and only these five: GetVectorItemPoints(), GetScanExtendedData(), Query(), and the GetFieldUniqueValuesAs…() and GetVectorItemFieldValueAs…() families. Everything else on this page is synchronous with no callback parameter at all.

For those five, the same call behaves differently depending on the layer:

  • On a native-server layer the asynchronous callback is mandatory. The query goes to the server, the method returns success once the request is issued, and the result arrives in the callback. Without a callback you get IMcErrors::SYNC_OPERATION_ON_NATIVE_SERVER_LAYER.
  • On any other layer the query is always synchronous. Without a callback the result comes back through the output parameters and the return value is its status. With one, the result is reported through the callback, the output parameters are left empty, and the method returns IMcErrors::SUCCESS regardless.

MapCore never takes ownership of the callback: keep it alive until the result is delivered, then destroy it. It is never invoked if the method itself returns an error.

What is in the layer​

GetVectorItemsCount() counts the items. GetGeometryType() reports the geometry, or UnSupportedGeometry — with success — for a multi-source layer whose sources disagree, and for a rasterized layer.

GetLayerDataSources() returns two parallel arrays, data-source names and IDs. GetLayerAttributes() returns layer-level attribute names and values, which currently exist only for .pc layers — do not confuse them with fields, which belong to items.

Fields​

Fields are the per-item metadata. They exist on raw layers, and on native layers only if they were converted with metadata; asking a native layer that was not gets IMcErrors::ACTIVE_VECTOR_LAYER_NOT_FOUND.

GetNumFields() counts them across every data source and GetFieldData() gives one field's name and EFieldType by index. On a multi-source layer, GetValidFieldsPerDataSource() narrows that to the fields valid for one source, which you identify by one of its item IDs, its name (case-insensitive) or its ID.

Reading values is typed rather than variant: GetVectorItemFieldValueAsInt(), …AsDouble(), …AsString() and …AsWString() for one item's field, and GetFieldUniqueValuesAsInt(), …AsDouble(), …AsString() and …AsWString() for every distinct value of a field — which is what you want for building a filter UI. When these are delivered through the callback instead, EVectorFieldReturnedType tells the callback which type it is holding.

Filtering​

Query() takes an SQL WHERE clause over field values and returns the matching item IDs:

CMcDataArray<UINT64> auItemsID;
pLayer->Query("\"Road Class\" = 'motorway' OR Lanes > 3", &auItemsID);

Quote a field name containing spaces with ", and quote string values with '. Every data source of the layer is queried and the results unified.

Geometry​

GetVectorItemPoints() returns an item's points in world coordinates, as one array per part — more than one only for a multi-line or multi-polygon. The layer must be initialised.

GetScanExtendedData() belongs with IMcSpatialQueries::ScanInGeometry(). A scan reports one target per vector item, but an item can be a unification of several original ones: a multi-geometry, a polygon with holes, or the line unification a 'lite' layer performs. This call splits that target back into the original items, returning one SVectorItemFound each with the range of the unified point array it covers.

IDs are composite on a multi-source layer. VectorItemIDToOriginalID() splits a MapCore item ID into the source's own ID plus the data source's name and ID, and VectorItemIDFromOriginalID() reverses it. On a single-source layer the two IDs are equal and the data-source ID is zero.

Speeding up geometry access on native layers​

GetVectorItemPoints() and GetScanExtendedData() read a native layer's geometry from file on every call. LoadExtendedGeometryDataToMemory() loads that file once and keeps it, and GetExtendedGeometryDataSize() tells you what that will cost in bytes — check it first if memory is tight. Both are no-ops returning success on any other layer type, and on a native layer converted without geometry data. The size call is what opens the geometry file, so it is also the cheapest way to find out whether the layer has any.

3D extrusion​

IMcVector3DExtrusionMapLayer builds volumes from vector contours — buildings from footprints. It derives from both IMcVectorBasedMapLayer and IMcStaticObjectsMapLayer, and it behaves far more like the latter: its output is static objects, addressed by object ID, not vector items addressed by item ID. It is documented with the other static-object layers in Add static objects.

IMcVectorBasedMapLayer itself has no members. It exists so that IMcMapLayer::CastToVectorBasedMapLayer() can identify "a layer built from vector data", covering both the vector layers and the extrusion layers.

3D models​

IMc3DModelMapLayer holds meshes converted from a 3D source rather than anything extruded from vector geometry, so despite the visual similarity it shares no API with vector layers. See Add static objects.

Error codes​

CodeCause
IMcErrors::NOT_INITIALIZEDThe layer's terrain is not in a viewport yet, or its data has not loaded
IMcErrors::NO_OVERLAYInitialised, but the layer has no overlay
IMcErrors::NO_OVERLAY_MANAGERThe overlay is not in an overlay manager
IMcErrors::NOT_THE_SAME_OVERLAY_MANAGERThe viewport belongs to a different overlay manager
IMcErrors::THE_PROPERTY_CANT_BE_SET_PER_VIEWPORTA per-viewport state change would alter a property version an object defines for all viewports
IMcErrors::SYNC_OPERATION_ON_NATIVE_SERVER_LAYERA data query on a native-server layer without a callback
IMcErrors::ACTIVE_VECTOR_LAYER_NOT_FOUNDThe data source could not be opened, or a native layer was converted without metadata
IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYERPer-item state on a 'lite' layer
IMcErrors::NOT_IMPLEMENTEDA rasterized layer, an unsupported local cache, or a build without HTTP support
IMcErrors::ID_NOT_FOUNDThe item or data source was not found, or no geometry data is held for it
IMcErrors::ID_ALREADY_EXISTSA sub-state array repeats a sub-state
IMcErrors::LOCALE_NOT_FOUNDstrLocaleStr is not a locale the system supports (Windows only)
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEMThe data source carries no coordinate system and none was supplied
IMcErrors::COORDINATES_NOT_CONVERTEDThe source's area could not be converted to the target coordinate system
IMcErrors::CANNOT_ALLOC_BUFFERThe extended-geometry buffer could not be allocated

Verified against MapCore 12.5.0

Written from Map/IMcVectorMapLayer.h, Map/IMcMapLayer.h, Map/IMcStaticObjectsMapLayer.h