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 from | Object IDs | |
|---|---|---|
| Extruded buildings | Contours in a vector data source, extruded to a height | 32, 64 or 128 bits, depending on the source |
| 3D models | A 3D model source | 128-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);
| Call | Does |
|---|---|
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 ID | Width |
|---|---|
| The vector items' own IDs (no ID column configured) | 32, or 64 on a multi-source layer |
| An integer metadata column | 32, or 64 for a 64-bit column |
| A binary-blob or UUID-string metadata column | 128 |
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.
| Call | Default | Effect when true |
|---|---|---|
SetDisplayingItemsAttachedToTerrain() | false | Object-scheme items attached to the terrain, and 'lite' vector layer objects, draw on top of the static objects |
SetDisplayingDtmVisualization() | false | DTM 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:
| Interface | Reads from |
|---|---|
IMcNativeVector3DExtrusionMapLayer | A converted directory, or a URL |
IMcRawVector3DExtrusionMapLayer | A GDAL/OGR data source directly |
IMcNativeServerVector3DExtrusionMapLayer | MapCore'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:
| Field | Meaning |
|---|---|
strHeightColumn | The metadata column holding each contour's height. This is what makes the layer more than footprints |
strObjectIDColumn | Optional. Empty means the vector item ID becomes the object ID — and sets the ID width |
strRoofTextureIndexColumn, strSideTextureIndexColumn | Optional columns holding an index into aSpecificTextures; empty means the default texture is used |
RoofDefaultTexture, SideDefaultTexture | The fallbacks, as SExtrusionTexture |
An SExtrusionTexture is a path, a scale (a zero component means 1), and two placement bit fields
built from ETexturePlacementFlags:
| Flag | Effect |
|---|---|
ETPF_NONE | Repeat 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_PIXELS | Repeat the edge pixels past the texture edge instead of the whole texture |
ETPF_RESTART_EACH_FACE | Restart the texture at each face. Meaningless for a roof |
ETPF_ALIGN_CENTER | Centre the texture on the face. Ignored under ETPF_FIT |
ETPF_REVERSE_ALIGNMENT | Align right instead of left, bottom instead of top. Ignored under ETPF_FIT |
ETPF_FIT | Fit 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.
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.
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:
| Parameter | Notes |
|---|---|
strRawDataDirectory | A local directory, an http(s) URL, or a local 3TZ archive (*.3tz) holding that same tree. Shorter than MAX_PATH |
eSourceVerticalDatumType | The source's vertical datum; see Add elevation data |
fTargetHighestResolution | Caps the source's resolution. Default MC_RAW_3D_MODEL_DEFAULT_TARGET_RESOLUTION (0.05) — 5 cm per pixel — used as passed, without rounding |
aRequestParams | Extra key=value pairs on each HTTP request |
bSmartRealityModel | Default 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
| Code | Cause |
|---|---|
IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYER | User colours, or height changes, on a layer that does not support them |
IMcErrors::NOT_INITIALIZED | No map device yet, or the layer's loading has not finished |
IMcErrors::INVALID_PARAMETERS | A NULL array with a non-zero count, an empty directory, or a URL with no / |
IMcErrors::ACTIVE_VECTOR_LAYER_NOT_FOUND | An extrusion layer's data source, or its requested sub-layer, could not be opened |
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEM | The data source carries no coordinate system and none was supplied |
IMcErrors::COORDINATE_SYSTEMS_MISMATCH | A raw 3DTiles layer was created without a target coordinate system |
IMcErrors::PRODUCTION_FILE_FORMAT_NOT_SUPPORTED | The raw model data is not 3DTiles |
IMcErrors::NOT_IMPLEMENTED | A 3DTiles version this build does not support, or a build without HTTP support |
IMcErrors::STORAGE_VERSION_MISMATCH | The layer was written by a newer MapCore |
IMcErrors::FILE_NOT_FOUND | A layer file is missing, or the raw data directory is empty or unreadable |
IMcErrors::CANT_READ_FILE | The path exceeds MAX_PATH, or a raw file could not be read or parsed |
IMcErrors::READ_FROM_STORAGE_FAILED | The layer's data could not be read |
IMcErrors::LOCALE_NOT_FOUND | The data source's locale is not supported by the system (Windows only) |
IMcErrors::FAILURE | The raw data could not be scanned, or the layer could not be built from it |