Skip to main content

Add code and material layers

The base interface for code-map layers (raster-based layers when each pixel codes some information other than a color).

A code-map layer is loaded and displayed like a raster layer (it derives from IMcRasterMapLayer), but its pixel values are data: a material ID in IMcMaterialMapLayer, per-direction traversability flags in IMcTraversabilityMapLayer. Since the codes are not colors, the layer is drawn through a color table mapping each code to its visualization color, and a pixel's color code is decoded back into data by the sub-kind's methods (IMcMaterialMapLayer::GetMaterialIDFromColorCode(), IMcTraversabilityMapLayer::GetTraversabilityFromColorCode()).

Used for:

  • Color table: SetColorTable() and GetColorTable() (see SCodeMapData); an empty table makes the layer render its raw codes as colors, which allows retrieving them by rendering to a buffer.
  • Everything a raster layer does, as IMcRasterMapLayer: the color histogram and tile bitmaps, and through it everything a map layer does (see IMcMapLayer).

See also: IMcRasterMapLayer, IMcMaterialMapLayer, IMcTraversabilityMapLayer

— from Map/IMcCodeMapLayer.h

That parenthesis is the whole idea: the pixel values are data, not colour, and what the number means depends on which of the two kinds you have:

KindA pixel's value is
IMcMaterialMapLayerA material ID: what the ground at that point is made of
IMcTraversabilityMapLayerPer-direction traversability flags, coloured by how many directions are traversable

Because the values are not colours, the layer needs to be told how to draw them.

Code layers​

The colour table​

SetColorTable() maps each code to the colour used to display it, as an array of IMcCodeMapLayer::SCodeMapData — a code and a colour.

IMcCodeMapLayer::SCodeMapData aTable[] = {
{ 3, SMcBColor(120, 90, 60, 255) }, // soil
{ 6, SMcBColor(60, 130, 60, 255) }, // vegetation
};
pLayer->SetColorTable(aTable, 2);

Valid codes differ by kind: a material layer's code is a pixel value below 256, while a traversability layer's code is a count of traversable directions, from 0 up to whatever GetNumTraversabilityDirections() reports. Out-of-range codes make the whole call fail with IMcErrors::INVALID_PARAMETERS.

warning

On a material layer each code's colour is also applied to the two adjacent pixel values, to avoid accuracy problems in the shader. Two codes must therefore differ by at least 3. Codes that are one or two apart will bleed into each other.

The table applies to every viewport showing the layer.

Clearing the table is a feature, not just an undo. Pass NULL with a count of 0 — or an empty array — and the layer renders by interpreting each pixel's code as a colour. That is the trick for getting the raw codes back out: render to a buffer and read the pixel values.

GetColorTable() reads the table back, and distinguishes the two empty-ish states usefully: before you have ever called SetColorTable() it returns the layer's built-in default table; after you have cleared it, it returns an empty array.

Creating the layer​

Both kinds follow the same three-flavour pattern as raster layers, and the parameters are the raster ones minus the pixel-specific tuning:

KindConvertedFrom a serverRaw
MaterialIMcNativeMaterialMapLayerIMcNativeServerMaterialMapLayerIMcRawMaterialMapLayer
TraversabilityIMcNativeTraversabilityMapLayerIMcNativeServerTraversabilityMapLayerIMcRawTraversabilityMapLayer

The converted Create() takes a directory or URL plus bThereAreMissingFiles; the server one takes a layer URL containing a /; the raw one takes the same SRawParams as a raw raster layer. See Add a raster layer for those parameters in full and Tune the local cache for the cache argument.

One difference from raw raster worth knowing: a raw material layer always has a real coordinate system. There is no image-coordinate-system mode, because a code map without geography would be meaningless.

Materials​

The base interface for material layers - code-map layers whose pixels code material IDs.

A material layer is a code-map layer (see IMcCodeMapLayer) whose pixel codes are material IDs: the ID is the red channel of a pixel's color code, and a fully transparent color codes an unknown material. Besides the code-to-color mapping inherited from IMcCodeMapLayer, a material layer can carry a materials dictionary (see SetMaterialsData()): named materials keyed by their code (material ID), each optionally holding a data blob whose layout is described by a material definition composed of named sub-definitions. It is inherited by IMcNativeMaterialMapLayer, IMcRawMaterialMapLayer and IMcNativeServerMaterialMapLayer.

Used for:

  • Decoding pixels: GetMaterialIDFromColorCode().
  • The materials dictionary: SetMaterialsData() and GetMaterialsData() (see SMaterialSubDef, SMaterialDef and SMaterialData); lookups by name and index with GetMaterialsSubDefIndexByName(), GetMaterialsSubDefNameByIndex(), GetMaterialsDefIndexByName(), GetMaterialsDefNameByIndex(), GetMaterialSubDef() and GetMaterialDef(); a material by its ID with GetMaterialData(), and one field of its data blob with GetMaterialSubDefData().
  • Everything a code-map layer does, as IMcCodeMapLayer: the color table, and through it everything a raster layer and a map layer do (see IMcRasterMapLayer and IMcMapLayer).

See also: IMcCodeMapLayer::SetColorTable()

— from Map/IMcCodeMapLayer.h

Colouring a material layer only needs the code table above. The materials dictionary is for the other half of the job: knowing what code 6 actually is, and carrying arbitrary per-material data alongside it — friction, radar reflectivity, whatever your application models.

The dictionary has three levels, and they only make sense together:

LevelStructIs
Sub-definitionSMaterialSubDefA named field of n bytes
DefinitionSMaterialDefA named, ordered list of sub-definitions — a record layout
MaterialSMaterialDataA code, a colour, a name, and an optional blob laid out by one definition

So a definition describes a struct, and every material using that definition carries a blob in exactly that shape. Several materials can share one definition, which is the normal case.

SetMaterialsData() installs all three groups in one call, and each group is handled independently:

You passEffect on that group
A non-NULL arrayReplaces its entries
A non-NULL array with count 0Clears it
NULL with count 0Leaves it unchanged
danger

The entries are stored as shallow copies. The names, SMaterialDef::aSubDefIndices and SMaterialData::aMaterialData all keep pointing at your memory, which must stay valid for as long as the layer uses the dictionary. This is the single most likely way to crash with this interface.

uMaterialDataNumBytes must equal the sum of the field sizes in the material's definition.

Reading the dictionary back​

GetMaterialsData() returns all three groups — each output optional, at least one required — with the same shallow pointers you supplied. For individual lookups:

CallReturns
GetMaterialData()One material by its ID; IMcErrors::ID_NOT_FOUND if there is none
GetMaterialsSubDefIndexByName() / GetMaterialsDefIndexByName()An index by name, or UINT_MAX — with success — if the name is unknown
GetMaterialsSubDefNameByIndex() / GetMaterialsDefNameByIndex()The name at an index
GetMaterialSubDef() / GetMaterialDef()The entry at an index

The by-name lookups returning UINT_MAX and success is the detail to code against: a missing name is not an error, so check the index rather than the return code.

Getting from a pixel to a material​

GetMaterialSubDefData() extracts one named field out of a material's blob, working out the offset from the sub-definition's position in that material's definition. It returns success and leaves the output untouched when the material simply has no blob, and IMcErrors::ID_NOT_FOUND when the sub-definition is not part of the material's definition, or its byte range runs past the end of the blob.

GetMaterialIDFromColorCode() closes the loop from a rendered pixel back to the dictionary: the material ID is the red channel of the colour code, and a fully transparent colour means an unknown material, reported as UINT_MAX.

Put together, the typical flow is: render or query a point, take the colour code, call GetMaterialIDFromColorCode(), call GetMaterialData() with that ID, then pull the fields you care about with GetMaterialSubDefData().

Traversability​

A traversability layer stores, per pixel, whether each of several compass directions can be crossed. GetNumTraversabilityDirections() reports how many directions the layer holds; the directions are evenly spaced, at i × 360 / n degrees starting from 0.

GetTraversabilityFromColorCode() decodes a colour code into an array of STraversabilityDirection — an angle in degrees and a flag each. As with materials the data lives in the red channel, this time as bit flags, and a fully transparent colour means unknown traversability, reported as an empty array with IMcErrors::SUCCESS.

The colour table for a traversability layer is keyed by the count of traversable directions rather than by a code, which makes the obvious visualisation — impassable through fully open — a table of n + 1 entries from 0 to n.

Error codes​

CodeCause
IMcErrors::INVALID_PARAMETERSA code out of range for its layer kind; a NULL array with a non-zero count; a NULL definition or sub-definition name; a required output pointer is NULL; an index is out of range; every array passed to SetMaterialsData() / GetMaterialsData() is NULL
IMcErrors::ID_NOT_FOUNDNo material with that ID; or a sub-definition outside the material's definition or its blob
IMcErrors::NOT_INITIALIZEDNo map device yet, or the layer's loading has not finished
IMcErrors::FILE_NOT_FOUNDA layer file is missing or unreadable, or no raw component could be opened
IMcErrors::COORDINATE_SYSTEMS_MISMATCHRaw components disagree about their coordinate system
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEMA component carries no coordinate system and none was supplied
IMcErrors::READ_FROM_STORAGE_FAILEDThe layer's tile data could not be read
IMcErrors::CANT_READ_FILEThe raster source could not be processed
IMcErrors::LAYER_WEB_REQUEST_FAILUREA required web request could not be issued
IMcErrors::NOT_IMPLEMENTEDThis build has no HTTP support

Verified against MapCore 12.5.0

Written from Map/IMcCodeMapLayer.h, Map/IMcRasterMapLayer.h, Map/IMcMapLayer.h