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:
| Kind | A pixel's value is |
|---|---|
IMcMaterialMapLayer | A material ID: what the ground at that point is made of |
IMcTraversabilityMapLayer | Per-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.
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:
| Kind | Converted | From a server | Raw |
|---|---|---|---|
| Material | IMcNativeMaterialMapLayer | IMcNativeServerMaterialMapLayer | IMcRawMaterialMapLayer |
| Traversability | IMcNativeTraversabilityMapLayer | IMcNativeServerTraversabilityMapLayer | IMcRawTraversabilityMapLayer |
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:
| Level | Struct | Is |
|---|---|---|
| Sub-definition | SMaterialSubDef | A named field of n bytes |
| Definition | SMaterialDef | A named, ordered list of sub-definitions — a record layout |
| Material | SMaterialData | A 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 pass | Effect on that group |
|---|---|
A non-NULL array | Replaces its entries |
A non-NULL array with count 0 | Clears it |
NULL with count 0 | Leaves it unchanged |
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:
| Call | Returns |
|---|---|
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
| Code | Cause |
|---|---|
IMcErrors::INVALID_PARAMETERS | A 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_FOUND | No material with that ID; or a sub-definition outside the material's definition or its blob |
IMcErrors::NOT_INITIALIZED | No map device yet, or the layer's loading has not finished |
IMcErrors::FILE_NOT_FOUND | A layer file is missing or unreadable, or no raw component could be opened |
IMcErrors::COORDINATE_SYSTEMS_MISMATCH | Raw components disagree about their coordinate system |
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEM | A component carries no coordinate system and none was supplied |
IMcErrors::READ_FROM_STORAGE_FAILED | The layer's tile data could not be read |
IMcErrors::CANT_READ_FILE | The raster source could not be processed |
IMcErrors::LAYER_WEB_REQUEST_FAILURE | A required web request could not be issued |
IMcErrors::NOT_IMPLEMENTED | This build has no HTTP support |