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. 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.

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();

    }
}

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 color palette with given name.
        /// </summary>
        /// <param name="name">Name of color palette to retrieve.</param>
        /// <returns>Color palette or null if not found.</returns>
        ColorInterpolationTable GetColorPalette(string name);

        /// <summary>
        /// Add a new color palette or update an existing color palette.
        /// </summary>
        /// <param name="name">Name of color palette.</param>
        /// <param name="colorInterpolationTable">Color palette instance to add or update.</param>
        void AddOrUpdateColorPalette(string name, ColorInterpolationTable colorInterpolationTable);

        /// <summary>
        /// Remove a color palette with given name.
        /// </summary>
        /// <param name="name">Name of color palette to remove.</param>
        void RemoveColorPalette(string name);

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

        /// <summary>
        /// Set the elevation map entry to use for the paletted map layer.
        /// </summary>
        /// <param name="mapEntry"></param>
        void SetElevationMapEntry(MapEntry mapEntry);
    }
}

The following example shows how to create or update a color map layer through the MARIA API. Color palettes are created in the same way as in the "Low Level API" and added or updated using "AddOrUpdateColorPalette" and removed using "RemoveColorPalette".

var elevationMapEntry = ...;
var colorMapHandler = _mapLayer.CreateColorMapHandler();

// The active color palette name is set to one of the elevation providers color palette names 
colorMapHandler.ActiveColorPalette = "PaletteName";
colorMapHandler.SetElevationMapEntry(elevationMapEntry);

The following example shows how to remove a color map layer through the MARIA API.

var colorMapHandler = _mapLayer.CreateColorMapHandler();
...
colorMapHandler.Dispose();