Functions | Properties
Grid rendering
Image modules

Functions

bool Image._pushSchemetkRaster (GridColorScheme cScheme)
 Sets color scheme to use in process of generation of the image representation of the grid.
Grid Image.OpenAsGrid ()
 Opens the datasource of the image as grid.

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.
bool Image.AllowHillshade [get, set]
 Indicate whether hillshade algorithm will be used for generation of image representation of the grid.
GridColorScheme Image.CustomColorScheme [get, set]
 Gets or sets the color scheme to render image with.
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.
bool Image.GridRendering [get]
 Returns true if the image is rendered as grid.
PredefinedColorScheme Image.ImageColorScheme [get, set]
 Gets or sets the predefined color scheme for the image. Applicable for GDAL images only.
bool Image.IsGridProxy [get]
 Gets the value which indicates whether an image object represents a visualization proxy for another datasource.
int Image.SourceGridBandIndex [get, set]
 Gets or sets index of band within datasource whose values should be used to apply color scheme.
string Image.SourceGridName [get]
 Gets the name of the source grid in case the image represent a visualization proxy for a grid.

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.

dot_inline_dotgraph_18.png

Graph description

Working with grid data.

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

dot_inline_dotgraph_19.png

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:

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:

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:

It's implemented like this:

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

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

Parameters:
cSchemeThe color scheme.
Returns:
True on success and false otherwise.

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

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.

New API 4.9.1:
Added in version 4.9.1
bool Image.AllowHillshade [get, set]

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.

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

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.

bool Image.GridRendering [get]

Returns true if the image is rendered as grid.

New API 4.9.1:
Added in version 4.9.1

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.

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
int Image.SourceGridBandIndex [get, set]

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
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
 All Classes Files Functions Enumerations Properties Events