Functions
bool	Image._pushSchemetkRaster (GridColorScheme cScheme)
	Sets color scheme to use in process of generation of the image representation of the grid. More...

Grid	Image.OpenAsGrid ()
	Opens the datasource of the image as grid. More...

Properties
tkGridRendering	Image.AllowGridRendering `[get, set]`
	Gets or sets the value which indicates whether the image will be rendered as grid, i.e. with a color scheme applied to a band set by Image.SourceGridBandIndex. More...

bool	Image.AllowHillshade `[get, set]`
	Indicate whether hillshade algorithm will be used for generation of image representation of the grid. More...

GridColorScheme	Image.CustomColorScheme `[get, set]`
	Gets or sets the color scheme to render image with. More...

GridColorScheme	Image.GridProxyColorScheme `[get]`
	Gets grid color scheme this proxy image was generated with. The method should be called for proxy images only: Image.IsGridProxy = true. More...

bool	Image.GridRendering `[get]`
	Returns true if the image is rendered as grid. More...

PredefinedColorScheme	Image.ImageColorScheme `[get, set]`
	Gets or sets the predefined color scheme for the image. Applicable for GDAL images only. More...

bool	Image.IsGridProxy `[get]`
	Gets the value which indicates whether an image object represents a visualization proxy for another datasource. More...

int	Image.SourceGridBandIndex `[get, set]`
	Gets or sets index of band within datasource whose values should be used to apply color scheme. More...

string	Image.SourceGridName `[get]`
	Gets the name of the source grid in case the image represent a visualization proxy for a grid. More...

Detailed Description

Here is a list of properties and methods that affects rendering of grids. The properties and methods described here belong to Image class.

Graph description

Working with grid data.

Image class can be used for rendering grid data. Grid datasources can be rendered in 2 ways:

direct rendering using GDAL drivers (see grid rendering section below);
rendering using proxy image.

In both cases the name of the original datasource is stored in Image.SourceGridName property. Source grid can be opened using Image.OpenAsGrid. No interpolation is usually used during rendering of grid datasources since it's often desirable to see borders of individual pixels (see Image.UpsamplingMode, Image.DownsamplingMode). More details on grids see of Grid class.
1. Grid rendering.

Any GDAL-based image can be displayed using so called grid rendering, i.e. not by using it's own colors but by mapping the values of one of its bands to new set of colors. Grid rendering is used depending on datasource type:

for grid datasources it's the only one available since no colors are stored in datasource itself;
for regular RGB images the usage can be turned on/off with Image.AllowGridRendering property; grid rendering in this case actually is nothing more than the usage of synthetic colors to display on of the original color bands.

Image.IsRgb property can be used to determine whether the current datasource is grid or RGB image. The rendering method can be returned by Image.GridRendering property. Grid rendering always applies to a single band specified by Image.SourceGridBandIndex.

Color scheme for grid rendering can be set using:

Image.CustomColorScheme property (or an older alternative Image._pushSchemetkRaster method);
Image.ImageColorScheme property (will be used when no custom color scheme was set);

Forcing grid rendering for RGB image:

string filename = "image.tif";
var img = new Image();
if (img.Open(filename, ImageType.USE_FILE_EXTENSION, true, null))
{
    if (img.IsRgb)
    {
        img.AllowGridRendering = tkGridRendering.grForceForAllFormats;
        img.ImageColorScheme = PredefinedColorScheme.SummerMountains;
        img.SourceGridBandIndex = 2;    // let's choose second band 
        Debug.Print("Image is rendered as grid: " + img.GridRendering);
    }
}

Setting custom unique values color scheme for directly rendered grid:

string filename = "grid.asc";        
var img = new Image();
if (img.Open(filename, ImageType.USE_FILE_EXTENSION, true, null))
{
    if (!img.IsRgb)
    {
        var grid = img.OpenAsGrid();
        if (grid != null)
        {
            var scheme = grid.GenerateColorScheme(tkGridSchemeGeneration.gsgUniqueValues, PredefinedColorScheme.FallLeaves);
            img.CustomColorScheme = scheme;
            grid.Close();
            Debug.Print("Image is rendered as grid: " + img.GridRendering);
        }
    }
}

Setting default color scheme for directly rendered grid:

string filename = "grid.asc";
var img = new Image();
if (img.Open(filename, ImageType.USE_FILE_EXTENSION, true, null))
{
    if (!img.IsRgb)
    {
        img.ImageColorScheme = PredefinedColorScheme.Glaciers;
        img.CustomColorScheme = null;   // make sure that there is no custom color scheme to override out setting
    }
}

2. Proxy images for grids.

Proxy image is regular RGB image file created for rendering a grid. It can have BMP or GTiff format and name of the grid + "_proxy" postfix (see details on their creation in Grid class). The rendering of proxy image has no differences compared to any other RGB image. Additional responsibilities of Image class in this case include:

identification of proxy image on opening;
providing diagnostic properties for user, so that original grid can be accessed.

It's implemented like this:

Image.Open method will analyze filename for "_proxy" suffix and then will try to find .mwleg color scheme file for it;
if such file exists, the name of the source grid will be read from it and set to Image.SourceGridName property;
Image.IsGridProxy property will be set to true.

The source grid can be accessed using Image.OpenAsGrid method.

Here is an examples which demonstrate changing of format for proxy image already added to the map from BMP to GTiff (it's not very practical example, but good demonstration of API):

int layerHandle = 0;     // a layer with image
var img = axMap1.get_Image(layerHandle);
if (img.IsGridProxy && img.SourceType != tkImageSourceType.istGDALBased)
{
    var grid = img.OpenAsGrid();
    if (grid != null)
    {
        var scheme = img.GridProxyColorScheme;  // we shall use the same color scheme
        axMap1.RemoveLayer(layerHandle);        // removing original proxy
 
        var gs = new GlobalSettings();
        gs.GridProxyFormat = tkGridProxyFormat.gpfTiffProxy;    // new one must be GTiff
 
        var newImage = grid.CreateImageProxy(scheme);
        if (newImage != null)
        {
            axMap1.AddLayer(newImage, true);
        }
    }
}

Function Documentation

◆ _pushSchemetkRaster()

bool Image._pushSchemetkRaster ( GridColorScheme cScheme )

Sets color scheme to use in process of generation of the image representation of the grid.

Parameters

cScheme The color scheme.

Returns: True on success and false otherwise.

◆ OpenAsGrid()

Grid Image.OpenAsGrid ( )

Opens the datasource of the image as grid.

Returns: Grid object or null if the operation failed.

If the image represents a visualization proxy for grid, than the grid datasource will be opened, otherwise the datasource of image itself.

New API 4.9.1:: Added in version 4.9.1

Properties

◆ AllowGridRendering

tkGridRendering Image.AllowGridRendering

getset

Gets or sets the value which indicates whether the image will be rendered as grid, i.e. with a color scheme applied to a band set by Image.SourceGridBandIndex.

New API 4.9.1:: Added in version 4.9.1

◆ AllowHillshade

bool Image.AllowHillshade

getset

Indicate whether hillshade algorithm will be used for generation of image representation of the grid.

The behaviour has changed in v4.9. Now when active it only switches ColoringType from Hillshade to Gradient. In v.4.8. it used to have the same behaviour as Image.AllowExternalColorScheme.

◆ CustomColorScheme

GridColorScheme Image.CustomColorScheme

getset

Gets or sets the color scheme to render image with.

This property should be used for grid datasources in the first place (when there is no build-in colors). But may also be used for a single band of regular RGB/ARGB images for synthetic colors and hillshading. When no custom color scheme is set, grid rendering is chosen the color scheme from Image.ImageColorScheme will be used.

New API 4.9.1:: Added in version 4.9.1

◆ GridProxyColorScheme

GridColorScheme Image.GridProxyColorScheme

get

Gets grid color scheme this proxy image was generated with. The method should be called for proxy images only: Image.IsGridProxy = true.

Color scheme will be read from .mwleg XML file on the disk.

◆ GridRendering

bool Image.GridRendering

get

Returns true if the image is rendered as grid.

New API 4.9.1:: Added in version 4.9.1

◆ ImageColorScheme

PredefinedColorScheme Image.ImageColorScheme

getset

Gets or sets the predefined color scheme for the image. Applicable for GDAL images only.

The color scheme is used for generation of image representation of the grid.

◆ IsGridProxy

bool Image.IsGridProxy

get

Gets the value which indicates whether an image object represents a visualization proxy for another datasource.

Will return true if the image was opened with Grid.OpenAsImage only. When opened directly the link to the source grid will be lost.

New API 4.9.1:: Added in version 4.9.1

◆ SourceGridBandIndex

int Image.SourceGridBandIndex

getset

Gets or sets index of band within datasource whose values should be used to apply color scheme.

Other bands will ignored during display process. This is useful for multiband grids (e.g. NetCDF), but may also be used with RGB images, to set synthetic colors for a single band.

New API 4.9.1:: Added in version 4.9.1

◆ SourceGridName

string Image.SourceGridName

get

Gets the name of the source grid in case the image represent a visualization proxy for a grid.

New API 4.9.0:: Added in version 4.9.0

Functions

Properties

Detailed Description

Function Documentation

◆ _pushSchemetkRaster()

◆ OpenAsGrid()

Properties

◆ AllowGridRendering

◆ AllowHillshade

◆ CustomColorScheme

◆ GridProxyColorScheme

◆ GridRendering

◆ ImageColorScheme

◆ IsGridProxy

◆ SourceGridBandIndex

◆ SourceGridName