Color Map Layers

General

Color map layers, or paletted data layers are single channel data layers, for example elevation data, which can be colored according to a user definable palette. Values in the map data are matched with colors in the palette, and the neighboring values may be interpolated over the span of colors in the palette.

Colors may be mapped directly to data values, or there may be a calculation involved. For example we have the possibility to assign colors based on slope or aspect of elevation data sets.

• 

  Elevation values

• 

  Elevation without smoothing

• 

  Slope values

Low Level API

The MariaGDK API allows you to define map layers that are generated dynamically based on some data input combined with a color palette and some conversion function. Typically this can be to assign colors to certain elevation values, or by converting an elevation data set to a slope map and coloring the slope values according to the slope values.

Color Map Data Provider

The low level map data provider which takes raster data as input and produces an output color map is usually a ColorMapDataProvider which has various methods for converting input single channel raster values to output colors by mapping values to a color table.

Most applications will register a default ColorMapDataProvider to handle ElevationData

_elevationColorMapProvider = new ColorMapDataProvider(new TileCacheSpec(), _elevationData, colorTableManager);
_tileCacheManager.AddMapDataProvider(MapContentType.ElevationColorMap, _elevationColorMapProvider);

Any ColorMapLayer defined with MapContentType = ElevationColorMap will use this provider.

You can also define custom color map layers which use other data providers. These providers will be generated based on the input data, as described below.

Color Map Layer

The main API for creating elevation color map layers is through the IMapLayerViewModel interface with the following methods

namespace TPG.GeoFramework.MapLayer.Contracts
{
    public interface IMapLayerViewModel : IExportableLayer
    {
       ...
        /// <summary>
        /// Create a named color map layer with the given input data.
        /// </summary>
        /// <param name="layerSignature">Name for the new layer.</param>
        /// <param name ="paletteId">ID of the palette to be used. This palette name must be available in the requested data provider.</param>
        /// <param name="rasterData">Raster dataset to use as input for the color map layer</param>
        /// <param name="smoothInterpolation">Enable smooth interpolation of the map colors.</param>
        /// <returns>A new raster layer with the given properties.</returns>
        IMapServiceRasterLayerData AddColorMapLayer(string layerSignature, string paletteId, IGenericRasterDataset rasterData, bool smoothInterpolation);

        /// <summary>
        /// Add elevation color map layer. This method will create an elevation color map based on
        /// the global data provider for ElevationColorMaps. This usually means all enabled elevation data
        /// layers in the main ElevationDataManager.
        /// </summary>
        /// <param name="layerSignature">Name for the new data layer.</param>
        /// <param name ="paletteId">ID of the palette to be used. This palette name must be available in the global ElevationColorMap data provider.</param>
        /// <param name="smoothInterpolation">Enable smooth interpolation of the map colors.</param>
        /// <returns></returns>
        IMapServiceRasterLayerData AddElevationColorMapLayer(string layerSignature, string paletteId, bool smoothInterpolation);

        /// <summary>
        ///  Return raster layer for elevation color map (if any).
        /// </summary>
        /// <returns></returns>
        IRasterLayerData GetColorMapLayer(string name);

        /// <summary>
        /// Remove the given color map layer from the layer list.
        /// </summary>
        /// <param name="layer"></param>
        void RemoveColorMapLayer(IMapServiceRasterLayerData layer);

    }
}

The default implementation of this interface is typically TPG.GeoFramework.MapLayer.NativeMapLayerViewModel.

As we can see, there are two methods for creating Color map layers, one of which takes an IGenericRasterDataSet as input (See Generic raster data). The simple version, with no dataset specified will assume that you want elevation data as input, and will use the default color map data provider registered for the ElevationColorMap MapContentType as described above.

The other version registers a new ColorMapDataProvider with the given IGenericRasterDataSet as input and can be used to produce color maps based on any single channel input data.

Color Palettes

The "paletteId" parameter in the API above refers to a color table which must be registered in the IColorInterpolationTableManager which can be accessed through the the IMapLayerViewModel.ColorTableManager property. The default ColorInterpolationTableManager implementation will set up the following standard palettes:

• elevation - Elevation color values from 0 to 7000m
• bathymetry - Elevation color values from -500 to 0m
• slope - Slope values from 24 to 50 degrees.
• aspect - 0 - 360 degrees.

See the code doc for more info on how to set up a custom palette, but it is fairly self explanatory. You simply fill in a table mapping input data values to output colors.

Color Map Layers in Templates

In order to handle custom data color map templates, you need to set up a template layer handler for this. This will set up data providers based on the template data and assign them to color map layers that reference these data. Note that this handler is not necessary if you are only using color maps based on the default elevation data.

This handler needs a ColorTableManager for handling the palettes used in the color map layers.

   // Automatically create color map layers from template data.
   _mapController.TemplateLayerHandlers.Insert(0, new ColorMapLayerTemplateHandler(_tileCacheManager, _mapCatalogServiceClient, colorTableManager));

MARIA API

The MARIA API for creating elevation color map layers is through the IMariaMapLayer and IColorMapHandler interfaces with the following methods.

namespace TPG.Maria.MapContracts
{
    public interface IMariaMapLayer : IMariaLayer
    {
       ...
        /// <summary>
        /// Get handler for a paletted data layer.
        /// </summary>
        /// <returns>New ColorMapHandler instance.</returns>
        IColorMapHandler CreateColorMapHandler();

        /// <summary>
        /// Create a color map layer from the given raster data set.
        /// </summary>
        /// <param name="data"></param>
        /// <returns></returns>
        IColorMapHandler CreateColorMapHandler(IGenericRasterDataset data);
    }
}

namespace TPG.Maria.MapContracts
{
    public interface IColorMapHandler : IDisposable
    {
      /// <summary>
        /// Get or set the name of the color palette to use as layer colors.
        /// </summary>
        string ActiveColorPalette { get; set; }

        /// <summary>
        /// Get or set the interpolation method to use for elevation data calculations.
        /// </summary>
        ResamplingMethod Resampling { get; set; }

        /// <summary>
        /// The underlying raster data set for this color map layer
        /// </summary>
        IGenericRasterDataset Data { get; }
        
        /// <summary>
        /// Name identifier for the raster map layer
        /// </summary>
        string LayerName { get; set; }

        /// <summary>
        /// Include all MapEntries tagged with any of these tags in the dataset. If empty,
        /// ignore tags.
        /// </summary>
        List<string> Tags { get; set; }

        /// <summary>
        /// Include all these map signatures in the dataset. If empty, include all 
        /// signatures.
        /// </summary>
        List<string> MapSignatures { get; set; }

        /// <summary>
        /// Include only MapEntries of this type in the dataset. 
        /// </summary>
        MapContentType ContentType { get; set; }

        /// <summary>
        /// Update data sources and generate color map layer.
        /// </summary>
        void UpdateData();

        /// <summary>
        /// Force clear all map layer data for this color map layer.
        /// </summary>
        void ClearData();
    }
}

There are two methods for creating ColorMapHandlers, one of which can take a custom IGenericRasterDataset as input. The other will generate the necessary objects internally.

Color palettes are created in the same way as in the "Low Level API" and are accessed through the IMariaMapLayer.ColorTableManager property.

Example

The following example shows how to set up a color map layer for clutter data through the Maria API. Note that the Maria Map layer must be initialized before calling CreateColorMapHandler(). This can for example be run on the MariaMapLayer.LayerInitialized event.

// Add color table
var clutterTable = new ColorInterpolationTable("clutter_palette", "value");
var colorRange = new ColorValueRange();
colorRange.Add(0.0f, Color.FromArgb(0, 0, 0, 0));
colorRange.Add(1.0f, Color.FromArgb(180, 255, 218, 185));
colorRange.Add(14.0f, Color.FromArgb(180, 255, 255, 255));
...
clutterTable.ColorRanges.Add(colorRange);
_mapLayer.ColorTableManager.AddColorTable("clutter_palette", clutterTable);

var colorMapHandler = _mapLayer.CreateColorMapHandler();
colorMapHandler.Tags.Add("clutter");
colorMapHandler.ContentType = MapContentType.GenericData;
colorMapHandler.LayerName = "Clutter Color Map";
colorMapHandler.ActiveColorPalette = "clutter_palette";
colorMapHandler.Resampling = ResamplingMethod.Nearest;
colorMapHandler.UpdateData();