Skip to main content

Add static objects

The base interface for static-objects layers - 3D models and buildings extruded from vector contours.

A static-objects layer renders 3D models or buildings extruded from vector contours as a part of its terrain:

  • IMcVector3DExtrusionMapLayer holds buildings extruded from vector contours, each carrying an ID whose length in bits is a property of the layer (see IMcVector3DExtrusionMapLayer::GetObjectIDBitCount()).
  • IMc3DModelMapLayer holds models converted from a 3D source: a whole-terrain model (buildings, trees, etc., without IDs), separate building and/or tree models (each carrying a 128-bit ID, a UUID), or a whole-terrain model together with such separate models.

The layer keeps a user-defined color per object ID, applied as a modulation color: each of the object's pixels is multiplied by it, channel by channel, after normalizing the color from the [0, 255] range to [0, 1]. The default, white opaque, therefore multiplies by 1 and leaves the object's own appearance, while a fully transparent color zeroes the alpha and hides the object. The colors belong to the layer, so they apply in every viewport the layer is displayed in.

Used for:

  • Object colors: SetObjectsColors(), SetObjectsColor(), RemoveAllObjectsColors(), GetObjectsColors() and GetObjectColor() (see SObjectColor).
  • Layer parameters: SetDisplayingItemsAttachedToTerrain() and SetDisplayingDtmVisualization(), deciding what is drawn on top of the static objects, for all viewports or for one of them.
  • Object indexing: GetIndexedObjectIDs() and RemoveIndexedObjectIDs() for the objects indexed by spatial queries (see IMcSpatialQueries::SQueryParams::bStoreFoundStaticObjectsIDIndexing).
  • Everything a map layer does, as IMcMapLayer: visibility, coordinate system and bounding box, ID and user data, tiles and levels of detail, saving and loading, type and casting.

See also: IMcMapLayer, IMcSpatialQueries

— from Map/IMcStaticObjectsMapLayer.h

Two very different kinds of data end up here, and knowing which you have decides everything else:

Built fromObject IDs
Extruded buildingsContours in a vector data source, extruded to a height32, 64 or 128 bits, depending on the source
3D modelsA 3D model source128-bit UUIDs, or none at all

Both are static: part of the terrain, not overlay objects. You do not move them, and you do not address them through the overlay manager. What you can do to any of them is colour them and query them.

Colour objects​

Colour is the one facility every static-objects layer shares, and — as the description above says — it modulates the object's own appearance rather than replacing it: white opaque, the default, leaves the object as it is, and a fully transparent colour hides it.

IMcStaticObjectsMapLayer::SObjectColor Colors[] = {
IMcStaticObjectsMapLayer::SObjectColor(uBuildingID, SMcBColor(255, 80, 80, 255)),
};
pLayer->SetObjectsColors(Colors, 1);
CallDoes
SetObjectsColors()Sets a colour per object, from an array of ID/colour pairs
SetObjectsColor()Sets one colour on many objects
GetObjectColor()Reads one object's colour
GetObjectsColors()Reads every object that has a non-default colour
RemoveAllObjectsColors()Restores every object to white opaque

Three behaviours are worth internalising. Setting an object to white opaque is the same as removing its colour: it drops out of GetObjectsColors(), so an empty array from that call means nothing in the layer is user-coloured. Asking for the colour of an ID that is not in the layer at all is not an error — you get white opaque and IMcErrors::SUCCESS. And the colours belong to the layer, not to a viewport, so a highlight applied here appears in every viewport showing the layer. If you need per-viewport highlighting, static objects are not the mechanism.

RemoveAllObjectsColors() is deliberately more forgiving than the setters: on a layer that does not support user colours the setters return IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYER while the removal is simply a no-op, so cleanup code needs no capability check.

Address objects​

SMcVariantID carries object IDs at any of the three widths. An object with no ID is reported as the empty ID — SMcVariantID::SetEmpty() sets it, SMcVariantID::IsEmpty() detects it — and note that all 128 bits are set for empty, not just the bits the layer actually uses.

For an extrusion layer, GetObjectIDBitCount() tells you the width, which follows the source:

Source of the IDWidth
The vector items' own IDs (no ID column configured)32, or 64 on a multi-source layer
An integer metadata column32, or 64 for a 64-bit column
A binary-blob or UUID-string metadata column128

Read the width rather than assuming it: the possible values are 32, 64 and 128, and GetObjectIDBitCount() is the only thing that will tell you which one this layer's data produced.

Finding objects through queries​

Static objects are found by spatial query rather than by enumeration. When a query runs with IMcSpatialQueries::SQueryParams::bStoreFoundStaticObjectsIDIndexing set, the IDs it finds are accumulated in the layer, and:

  • GetIndexedObjectIDs() returns everything accumulated so far — empty if no query has indexed an object of this layer yet;
  • RemoveIndexedObjectIDs() takes IDs out again, silently ignoring any that are not there.

The accumulation is the point and also the trap: nothing clears it for you, so a long-running application that indexes on every query grows that set until it removes entries itself.

Layer-level display options​

Two options resolve conflicts between static objects and everything drawn around them. Both can be set per viewport, or with NULL for all viewports — and setting them for all viewports also makes them the default applied to any viewport the layer is added to later.

CallDefaultEffect when true
SetDisplayingItemsAttachedToTerrain()falseObject-scheme items attached to the terrain, and 'lite' vector layer objects, draw on top of the static objects
SetDisplayingDtmVisualization()falseDTM visualisation takes the static objects into account and draws on top of them

Leave both off and static objects win; turn one on when annotations are disappearing into buildings.

Extruded buildings​

The interface for static-objects layer built by extruding contours from a vector data source.

Each object of the layer is a body extruded from one contour of the vector source, so besides the user-defined color of IMcStaticObjectsMapLayer the layer also keeps a user-defined extrusion height per object ID. Whether the heights can be changed at all depends on the data the layer was built with (see IsExtrusionHeightChangeSupported()). It is inherited by IMcNativeVector3DExtrusionMapLayer, IMcRawVector3DExtrusionMapLayer and IMcNativeServerVector3DExtrusionMapLayer.

Used for:

  • Object ID: GetObjectIDBitCount() (32, 64 or 128 bits, according to the source of the objects' IDs).
  • Object extrusion heights: IsExtrusionHeightChangeSupported(); SetObjectExtrusionHeight(), SetObjectsExtrusionHeights() and RemoveAllObjectsExtrusionHeights(); GetObjectExtrusionHeight() and GetObjectsExtrusionHeights() (see SObjectExtrusionHeight).
  • Identification as a vector-based layer, as IMcVectorBasedMapLayer (see IMcMapLayer::CastToVectorBasedMapLayer()).
  • Everything a static-objects layer does, as IMcStaticObjectsMapLayer: object colors, display options and object indexing, and through it everything a map layer does (see IMcMapLayer).

Note: Like the colors, the user-defined heights belong to the layer, so they apply in every viewport the layer is displayed in. Their setters lock the layer's data while the matching getters read it without locking by design, so the getters must be called from the same thread as the setters.

— from Map/IMcStaticObjectsMapLayer.h

Each object is one contour from a vector source, extruded to a height taken from that source's metadata. Three flavours, as elsewhere:

InterfaceReads from
IMcNativeVector3DExtrusionMapLayerA converted directory, or a URL
IMcRawVector3DExtrusionMapLayerA GDAL/OGR data source directly
IMcNativeServerVector3DExtrusionMapLayerMapCore's Map Layer Server

Creating a raw extrusion layer​

IMcRawVector3DExtrusionMapLayer::SParams says where the data is; SGraphicalParams, which it extends, says how to extrude and texture it. The metadata columns are the interesting part, because they are how the source's own attributes drive the geometry:

FieldMeaning
strHeightColumnThe metadata column holding each contour's height. This is what makes the layer more than footprints
strObjectIDColumnOptional. Empty means the vector item ID becomes the object ID — and sets the ID width
strRoofTextureIndexColumn, strSideTextureIndexColumnOptional columns holding an index into aSpecificTextures; empty means the default texture is used
RoofDefaultTexture, SideDefaultTextureThe fallbacks, as SExtrusionTexture

An SExtrusionTexture is a path, a scale (a zero component means 1), and two placement bit fields built from ETexturePlacementFlags:

FlagEffect
ETPF_NONERepeat the whole texture, starting at the top-left of the side faces or the north-west corner of the roof's bounding rectangle
ETPF_REPEAT_EDGE_PIXELSRepeat the edge pixels past the texture edge instead of the whole texture
ETPF_RESTART_EACH_FACERestart the texture at each face. Meaningless for a roof
ETPF_ALIGN_CENTERCentre the texture on the face. Ignored under ETPF_FIT
ETPF_REVERSE_ALIGNMENTAlign right instead of left, bottom instead of top. Ignored under ETPF_FIT
ETPF_FITFit the texture to the face, cancelling the alignment flags

As with raw vector layers, a multi-layer data source needs its sub-layer suffix or you get the first sub-layer. The data source is opened synchronously, so a successful return means the layer is ready. One failure path is unusual and worth reading twice: if the data source cannot be opened, the layer is never built — OnReadError() is called with the details before Create() returns, and OnInitialized() is never called at all. Callback code that expects OnInitialized() to fire on every path will wait forever.

Indexing a raw extrusion layer​

BuildIndexingData() pre-indexes the data source, and there is then a second Create() overload that consumes the result. A layer created from indexed data takes its coordinate systems, clipping rectangle and tiling scheme from the indexing data, not from its creation parameters — which is exactly why those fields live on SParams and not on SGraphicalParams. strDataSource is validated against the one recorded in the index.

warning

BuildIndexingData() deletes the entire contents of the indexing directory before it starts, and so does DeleteIndexingData(). Point them at a directory that holds nothing else.

bUseExisting, on by default, makes BuildIndexingData() do nothing when the directory already holds an index built with the same parameters.

Changing extrusion heights​

A layer keeps a user-defined extrusion height per object, exactly as it keeps a colour, with FLT_MAX meaning "the original height".

Not every layer supports it. Only one carrying its contours' extrusion information — the objects' wall-texture parameters — can change heights; IsExtrusionHeightChangeSupported() reports whether this one can, and the setters return IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYER if it cannot. The check needs the layer to be loaded, so it returns IMcErrors::NOT_INITIALIZED if you ask too early.

Increases are capped. Every extrusion Create() takes fExtrusionHeightMaxAddition, defaulting to 0. A requested height more than that above the original is silently clamped to original + fExtrusionHeightMaxAddition. With the default, that means heights can be lowered but not raised — if raising them is the point, pass a real value at creation, because it cannot be changed afterwards.

SetObjectExtrusionHeight() and SetObjectsExtrusionHeights() set heights, GetObjectExtrusionHeight() and GetObjectsExtrusionHeights() read them back, and RemoveAllObjectsExtrusionHeights() restores the originals — again a no-op rather than an error on a layer that does not support changes.

warning

The height setters lock the layer's data; the getters read it without locking, by design. Call them from the same thread as the setters.

3D models​

The interface for 3D model layer, holding a level-of-detail tree of textured meshes from a 3D model source.

A 3D model layer holds a level-of-detail tree of textured meshes converted from a 3D model source (see IMcRaw3DModelMapLayer): a whole-terrain model (buildings, trees, etc., without IDs), separate building and/or tree models (each carrying a 128-bit ID, a UUID), or a whole-terrain model together with such separate models. It adds to IMcStaticObjectsMapLayer the parameter controlling which levels of detail are displayed.

Used for:

  • Layer parameters: SetResolutionFactor() biasing the level of detail displayed at a given scale, for all viewports or for one of them.
  • Everything a static-objects layer does, as IMcStaticObjectsMapLayer: object colors, display options and object indexing, and through it everything a map layer does (see IMcMapLayer).

See also: IMcStaticObjectsMapLayer

— from Map/IMcStaticObjectsMapLayer.h

Only the separate building and tree models — those carrying a UUID — can be addressed and coloured individually; a whole-terrain model has no IDs.

A 3D model layer reads its source data as it is: IMcRaw3DModelMapLayer is the only interface of this kind, and it reads 3DTiles raw data from a directory, from a 3TZ archive (*.3tz) holding that same tree, or over HTTP.

Display parameters​

SetResolutionFactor() biases which level of detail is chosen for a given local scale: 1 is the level intended for that scale, above 1 is coarser, below 1 is finer, and the minimum accepted is 0.1. It is the first thing to reach for when a model layer is too heavy — or looks blurrier than the data allows. It is per viewport or, with NULL, for all viewports and every viewport added later.

Raw 3DTiles​

IMcRaw3DModelMapLayer::Create() supports 3DTiles data only. It requires a target coordinate system — NULL is rejected with IMcErrors::COORDINATE_SYSTEMS_MISMATCH, not with an argument error — and accepts:

ParameterNotes
strRawDataDirectoryA local directory, an http(s) URL, or a local 3TZ archive (*.3tz) holding that same tree. Shorter than MAX_PATH
eSourceVerticalDatumTypeThe source's vertical datum; see Add elevation data
fTargetHighestResolutionCaps the source's resolution. Default MC_RAW_3D_MODEL_DEFAULT_TARGET_RESOLUTION (0.05) — 5 cm per pixel — used as passed, without rounding
aRequestParamsExtra key=value pairs on each HTTP request
bSmartRealityModelDefault false. When true, the model gets no footprint: none is traced from its root contents, and a footprint the tileset supplies is ignored

GetCreateParams() reports those back, each output individually optional.

Error codes​

CodeCause
IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYERUser colours, or height changes, on a layer that does not support them
IMcErrors::NOT_INITIALIZEDNo map device yet, or the layer's loading has not finished
IMcErrors::INVALID_PARAMETERSA NULL array with a non-zero count, an empty directory, or a URL with no /
IMcErrors::ACTIVE_VECTOR_LAYER_NOT_FOUNDAn extrusion layer's data source, or its requested sub-layer, could not be opened
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEMThe data source carries no coordinate system and none was supplied
IMcErrors::COORDINATE_SYSTEMS_MISMATCHA raw 3DTiles layer was created without a target coordinate system
IMcErrors::PRODUCTION_FILE_FORMAT_NOT_SUPPORTEDThe raw model data is not 3DTiles
IMcErrors::NOT_IMPLEMENTEDA 3DTiles version this build does not support, or a build without HTTP support
IMcErrors::STORAGE_VERSION_MISMATCHThe layer was written by a newer MapCore
IMcErrors::FILE_NOT_FOUNDA layer file is missing, or the raw data directory is empty or unreadable
IMcErrors::CANT_READ_FILEThe path exceeds MAX_PATH, or a raw file could not be read or parsed
IMcErrors::READ_FROM_STORAGE_FAILEDThe layer's data could not be read
IMcErrors::LOCALE_NOT_FOUNDThe data source's locale is not supported by the system (Windows only)
IMcErrors::FAILUREThe raw data could not be scanned, or the layer could not be built from it

Verified against MapCore 12.5.0

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