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

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 data provider.
        /// </summary>
        /// <param name="name">Name for the new layer.</param>
        /// <param name="provider">Data provider. Should be of type ElevationColorMapProvider.</param>
        /// <param name ="paletteId">ID of the palette to be used. This palette name must be available in the given data provider.</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 name, IMapDataProvider provider, string paletteId, bool smoothInterpolation = true);

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

The smoothInterpolation parameter controls wether or not the output should be smoothed, i.e if the colors should be interpolated between neighboring points. This should be combined with the InterpolationMethod property of the ElevationColorMapProvider used to produce the actual data (see below).

Data Provider

In order to fill this layer with input data, you need an IMapDataProvider, more specifically an ElevationColorMapProvider. Note that the "Elevation" part of this type name is more for historical reasons. The input data need not be elevation, but it should be single channel.

This data provider needs to be set up with two things:

• A color palette with an ID matching the color palette in the color map layer.
• An IElevationData with at least one map data signature as input.

Color Palette

The color palette is an object of type TPG.GeoFramework.MapLayer.ColorInterpolationTable and is assigned to the data provider through the ColorTables property. The ElevationColorMapProvider will by default be set up with 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.

Elevation Data

The actual data values are served through the IElevationData interface to the ElevationColorMapProvider. Again, the name indicates that this must be elevation data, but it can in fact be any single channel raster data. The IElevationData can be set up with data either directly by setting a template, or by using an ElevationDataManager in which you can enable/disable specific data layers.

Example

The following code example sets up a color map layer with a single data layer (provided as a MapEntry), using the standard "elevation" palette and nearest point interpolation.

void CreateColorMapLayer(MapEntry mapEntry, INativeTileCacheManager tileCacheManager)
{
   // Create dedicated IElevationData and ElevationColorMapProvider for this layer.
   var elevationInterfacer = new ElevationDataInterfacer(tileCacheManager);
   var elevationData = new ElevationDataFactory().New(elevationInterfacer);
   var elevationMapProvider = new ElevationColorMapProvider(new TileCacheSpec(), elevationData);
   elevationMapProvider.InterpolationMethod = InterpolationMethod.Nearest;

   // Create new color map layer
   var rasterLayer = _mapLayerViewModel.AddColorMapLayer("ColorMapLayer:" + mapEntry.MapSignature, elevationMapProvider, "elevation", false);
   rasterLayer.Visible = true;
            
   // Update elevation data 
   var template = CreateElevationTemplate(mapEntry);
   elevationData.SetTemplate(template);
}

For completeness, here is a utility method to convert a MapEntry into an elevation data template:

MapTemplate CreateElevationTemplate(MapEntry mapEntry)
{
    var elevTemplate = new MapTemplate();

    var elevationDataSource = new ServiceDatasourceInfo()
    {
        MapSignature = mapEntry.MapSignature,
        WantedMapContentType = mapEntry.MapType,
    };

    var elevTemplateLayer = new MapTemplateLayer()
    {
        DatasourceInfo = elevationDataSource,
        LayerType = TemplateLayerType.ElevationLayer,
        Name = mapEntry.MapSignature
    };

    elevTemplate.TemplateLayers.Add(elevTemplateLayer);

    return elevTemplate;
}

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