Grid Class Reference

The grid object is used to represent a grid which can be added to the map. More...

Collaboration diagram for Grid:

Public Member Functions
bool	AssignNewProjection (string Projection)
	Assign new projection to the grid. More...
void	CellToProj (int Column, int Row, out double x, out double y)
	Uses a cell's column and row position to find the center of the cell in projected map coordinates. More...
bool	Clear (object ClearValue)
	Clears all data in the grid, setting the value of all cells in the grid to the specified clear value. More...
bool	Close ()
	Closes the grid. More...
Image	CreateImageProxy (GridColorScheme ColorScheme)
	Creates a proxy image file to display grid data. More...
bool	CreateNew (string Filename, GridHeader Header, GridDataType DataType, object InitialValue, bool InRam, GridFileType fileType, ICallback cBack)
	Creates a new grid. More...
GridColorScheme	GenerateColorScheme (tkGridSchemeGeneration Method, PredefinedColorScheme Colors)
	Generates colour scheme for the grid. More...
GdalRasterBand	get_Band (int bandIndex)
	Gets datasource band with specified index. More...
string	get_ErrorMsg (int ErrorCode)
	Retrieves the error message associated with the specified error code. More...
object	get_Value (int Column, int Row)
	Returns the value stored in the grid at the specified cell. More...
bool	GetFloatWindow (int StartRow, int EndRow, int StartCol, int EndCol, ref float Vals)
	Returns an array with grid values which lie within specified bounds. More...
bool	GetFloatWindow2 (int StartRow, int EndRow, int StartCol, int EndCol, ref double Vals)
	Returns an array with grid values which lie within specified bounds. Double overload of Grid.GetFloatWindow method. More...
bool	GetRow (int Row, ref float Vals)
	The faster way to read the array values that are of a specific size. More...
bool	GetRow2 (int Row, ref double Vals)
	Provides the faster way to read the array values that are of a specific size. Double overload of Grid.GetRow. More...
bool	Open (string Filename, GridDataType DataType, bool InRam, GridFileType fileType, ICallback cBack)
	Opens a grid. More...
Image	OpenAsImage (GridColorScheme Scheme, tkGridProxyMode proxyMode=tkGridProxyMode.gpmAuto, ICallback cBack=null)
	Opens grid as image. More...
bool	OpenBand (int bandIndex)
	Makes the specified band of the grid active. More...
void	ProjToCell (double x, double y, out int Column, out int Row)
	Converts a point in projected map coordinates to a cell (column, row) in the grid. More...
bool	PutFloatWindow (int StartRow, int EndRow, int StartCol, int EndCol, ref float Vals)
	Sets an array of values for a given region of the grid. More...
bool	PutFloatWindow2 (int StartRow, int EndRow, int StartCol, int EndCol, ref double Vals)
	Sets an array of values for a given region of the grid. Double overload of Grid.PutFloatWindow. More...
bool	PutRow (int Row, ref float Vals)
	Provides The faster way to write the array values that are of a specific size. More...
bool	PutRow2 (int Row, ref double Vals)
	Provides The faster way to write the array values that are of a specific size. Double overload of Grid.PutRow. More...
bool	RemoveImageProxy ()
	Removes proxy image file created for grid display. More...
bool	Resource (string newSrcPath)
	Changes the grid source without closing it. More...
GridColorScheme	RetrieveColorScheme (tkGridSchemeRetrieval Method)
	Retrieves colour scheme from the grid. More...
GridColorScheme	RetrieveOrGenerateColorScheme (tkGridSchemeRetrieval retrievalMethod, tkGridSchemeGeneration generateMethod, PredefinedColorScheme Colors)
	Tries to retrieve any existing color scheme associated with grid or generates a new one if none is found. More...
bool	Save (string Filename, GridFileType GridFileType, ICallback cBack)
	Saves the grid. More...
void	set_Value (int Column, int Row, object pVal)
	Sets the value of the specified cell of the grid. More...
bool	SetInvalidValuesToNodata (double MinThresholdValue, double MaxThresholdValue)
	Sets invalid values to no data values. More...

Properties
GdalRasterBand	ActiveBand [get]
	Gets the active band of the datasource. More...
int	ActiveBandIndex [get]
	The index of the active band within grid. More...
tkCanDisplayGridWoProxy	CanDisplayWithoutProxy [get]
	Gets the value indicating whether grid source can be displayed by Image class without creation of proxy file. More...
string	CdlgFilter [get]
	Returns the common dialog filter containing all supported file extensions in string format. More...
GridDataType	DataType [get]
	Returns the data type of the values stored in the grid. More...
Extents	Extents [get]
	Gets extents of the grid. More...
string	Filename [get]
	The filename associated with the object. More...
ICallback	GlobalCallback [get, set]
	The global callback is the interface used by MapWinGIS to pass progress and error events to interested applications. More...
bool	HasValidImageProxy [get]
	Gets the value indicating whether grid has a valid image proxy for visualization. More...
GridHeader	Header [get]
	Returns the header of the grid. More...
bool	InRam [get]
	Returns whether the grid is loaded in to RAM memory or not. More...
string	Key [get, set]
	The key may be used by the programmer to store any string data associated with the object. More...
int	LastErrorCode [get]
	Retrieves the last error generated in the object. More...
object	Maximum [get]
	Returns the maximum value stored in the grid. More...
object	Minimum [get]
	Returns the minimum value stored in the grid. More...
int	NumBands [get]
	Gets the number of within the grid. More...
tkGridProxyMode	PreferedDisplayMode [get, set]
	Gets or sets the value indicating how the grid should be displayed. More...
GridColorScheme	RasterColorTableColoringScheme [get]
	Gets grid colour scheme object used for rendering of the image representation of the grid, in case the datasource has a color table (GTiff with indexed colors, for example). More...
tkGridSourceType	SourceType [get]
	Gets the type of grid source, which defines a) whether any grid source is opened and b) if so, what the inner representation of grid by MapWinGIS. More...

Detailed Description

The grid object is used to represent a grid which can be added to the map.

Grid datasource holds values describing distribution of certain characteristic over territory (e.g. elevation, population, precipitation, etc.), but usually doesn't define how these values should be rendered. In most cases grid datasource have a single band, but there may be mutiband ones as well (NetCDF format for example).
To render a grid, a color scheme must be chosen which will define how grid values will be mapped to colors. Some datasources may hold such color scheme (for examples GTiff with indexed colors). In many other cases the choice of color scheme is arbitrary. Here is an example of the same grid rendered with 2 different color schemes (SummerMountains and DesertFires).

MapWinGIS doesn't render Grid class directly, but uses Image class to do it. The distinction between these two is:

• Grid class provides access to underlying values of a stored characteristic (e.g. population, precipitation, etc.);
• Image class holds colors for each of those values mapped with specific color scheme.

By default MapWinGIS renders grid with hillshading effect which can be switched on/off and adjusted in GridColorScheme class.
Metadata about grid can be accessed through GridHeader object (Grid.Header property). It includes size, coordinate system and projection, etc.

Attention

Grid.Header property must not be called multiple times in a loop as it can trigger reading the data from disk on each occasion.

A. TYPES OF GRID RENDERING.

MapWinGIS can render grid datasource in 2 different ways:

1. Direct rendering by Image class.
   

• grid datasource is opened by GDAL drivers;
• before each rendering values of grids are mapped into colors + additional hillshading effect may be applied;
• the rendering process is much more computationally intensive than rendering of regular RGB images, therefore an approach provide poor performance for large datasets.

Grid rendering may also by applied to a single band of regular RGB image, displaying it with synthetic colors. See more information on direct grid rendering in description of Image class.

Note

Internally grids can be handled by either GDAL drivers or MapWinGIS own drivers. There is no way to affect which one will be chosen, however it's possible to check which one is used by Grid.SourceType property. The significance of it is that grid formats not supported by GDAL can't rendered directly by Image class.

1. Creation of so called proxy image to render a grid.
   

• all values of the grid are mapped to colors and the output is saved as a new image file with BMP or GTiff format;
• the selection of image format depends upon GlobalSettings.GridProxyFormat property;
• conversion is made by Utils.GridToImage2 method; the operation may take significant amount of time;
• Grid.OpenAsImage, Grid.CreateImageProxy, FileManager.Open can create proxy images by running Utils.GridToImage2 method internally;
• a proxy image is written with the same name as for the source grid + "_proxy.bmp" or "_proxy.tif" postfix, for example a proxy for "grid.asc" will be named "grid_proxy.tif";
• a color scheme always is written to the disk along with image (xml file with .mwleg extension, for example "grid_proxy.bmp.mwleg");

For multiband datasources proxy image will be created for the band marked as active by Grid.ActiveBandIndex. Use Grid.OpenBand to change the index.
There is no visual differences between 2 methods of grid rendering, however performance may differ substantially.
B. COLOR SCHEME FOR GRID.
Color scheme for grids can be retrieved in the following ways:

• from .mwleg XML file previously saved to the disk;
• from datasource itself, for example color table in indexed GTiff datasource (Grid.RasterColorTableColoringScheme);
• can be automatically generated using PredefinedColorScheme and values of grid (Grid.GenerateColorScheme);
• manual generation (in case some very specific coloring is required).

The first 2 approaches are covered by Grid.RetrieveColorScheme. Grid.RetrieveOrGenerateColorScheme method will look for any existing color scheme first, and if nothing is available will resort to generation. This is recommended approach in the most scenarios.
To generate color scheme manually the following code can be used:

var grid = some_code_to_open_grid;
var scheme = new GridColorScheme();
scheme.UsePredefined((double)grid.Minimum, (double)grid.Maximum, PredefinedColorScheme.SummerMountains);
scheme.ApplyColoringType(ColoringType.Hillshade);

See PredefinedColorScheme enumerations for available colors. Hillshading effect can be turned on/off with GridColorScheme.ApplyColoringType or by changing coloring of individual breaks (GridColorBreak.ColoringType).

C. HOW TO ADD GRID TO THE MAP.
Depending on requirements it can be done in fully automatic way with a single line or code (which is the best thing to do in most cases), or with manual coding if default behaviour isn't suitable. The approaches can be classified as:

• passing Grid object AxMap.AddLayer method;
• manual creation of Image for a Grid and passing it to AxMap.AddLayer;
• using FileManager class (in fact it uses the first approach internally, therefore all description is applicable for it as well).

Attention

The samples below assume that the following variables are defined:

string filename = @"d:\grid.asc";
Utils ut = new Utils();

1. Using FileManager class.

The most generic one:

axMap1.AddLayerFromFilename(filename, tkFileOpenStrategy.fosAutoDetect, true);

With creation of proxy image:

int handle = axMap1.AddLayerFromFilename(filename, tkFileOpenStrategy.fosProxyForGrid, true);

Opening as direct grid. Along with usual reasons (invalid filename, corrupted file), the approach may fail in case:

• size of grid exceeds GlobalSettings.MaxNoProxyGridSizeMb property (this may be addressed by changing global settings like demonstrated);
• grid format isn't supported by GDAL (nothing can be done about that).

var gs = new GlobalSettings();
gs.MaxNoProxyGridSizeMb = 100.0;    // size in MB; 20.0 is default value
handle = axMap1.AddLayerFromFilename(filename, tkFileOpenStrategy.fosDirectGrid, true);

With a check that something was actually opened:

int handle = axMap1.AddLayerFromFilename(filename, tkFileOpenStrategy.fosAutoDetect, true);
if (handle != -1 && axMap1.FileManager.LastOpenIsSuccess) 
{
    MessageBox.Show("Grid was added to the map. Open strategy: " + axMap1.FileManager.LastOpenStrategy.ToString());
}
else
{
    MessageBox.Show("Failed to open grid: " + ut.ErrorMsgFromObject(axMap1.FileManager));
}

Using custom instance of FileManager:

var fm = new FileManager();
if (fm.get_CanOpenAs(filename, tkFileOpenStrategy.fosDirectGrid))
{
   var img = fm.OpenRaster(filename, tkFileOpenStrategy.fosDirectGrid, null);
   if (img == null)
   {
       MessageBox.Show("Failed to open grid: " + ut.ErrorMsgFromObject(fm) + "; Open strategy: " + fm.LastOpenStrategy);
   }
   else
   {
       int handle = axMap1.AddLayer(img, true);
   }
}

2. Passing Grid to AxMap.AddLayer method.

The following logic will be executed:

• color scheme will retrieved with Grid.RetrieveOrGenerateColorScheme;
• Grid.OpenAsImage will be called to choose rendering mode.

The selection of rendering mode depends on:

• Grid.PreferedDisplayMode property;
• if previous set to auto, GlobalSettings.GridProxyMode property.

See details in description of tkGridProxyMode enumeration.

The selection of proxy format depends on GlobalSettings.GridProxyFormat property.

A color scheme used for rendering will be written to disk with:

• datasource name + .mwleg extension (for direct rendering);
• proxy name + .mwleg extension (for proxy rendering);

For direct rendering saving of color scheme to disk can be disabled with GlobalSettings.SaveGridColorSchemeToFile property.

The selection of color scheme depends on:

• GlobalSettings.RandomColorSchemeForGrids (if true will be selected randomly from PredefinedColorScheme enumeration);
• GlobalSettings.DefaultColorSchemeForGrids (when random one is turned off);

var grid = new Grid();
if (grid.Open(filename, GridDataType.UnknownDataType, true, GridFileType.UseExtension, null))
{
   grid.PreferedDisplayMode = tkGridProxyMode.gpmAuto;   // or other mode if needed
   int handle = axMap1.AddLayer(grid, true);
   var img = axMap1.get_Image(handle);
   if (img != null)
   {
       MessageBox.Show("Grid was opened. Rendering: " + (img.IsGridProxy ? "using proxy" : "direct"));
   }
   else
   {
       MessageBox.Show("To add grid to map: " + axMap1.get_ErrorMsg(axMap1.LastErrorCode));
   }
   grid.Close();   // we no longer need it as Image class is used for rendering
}
else
{
   MessageBox.Show("Failed to open grid: " + ut.ErrorMsgFromObject(grid));
}

3. Manual opening/creation of Image for Grid.

With automatic selection of rendering mode:

var grid = new Grid();
if (grid.Open(filename, GridDataType.UnknownDataType, true, GridFileType.UseExtension, null))
{
    var scheme = grid.RetrieveOrGenerateColorScheme(tkGridSchemeRetrieval.gsrAuto, tkGridSchemeGeneration.gsgGradient, PredefinedColorScheme.SummerMountains);
    var img = grid.OpenAsImage(scheme, tkGridProxyMode.gpmAuto, null);
    if (img != null)
    {
        int handle = axMap1.AddLayer(img, true);
    }
    else
    {
        MessageBox.Show("Failed to create image representation for the grid: " + ut.ErrorMsgFromObject(grid));
    }
    grid.Close();   // we no longer need it as Image class is used for rendering
}
else
{
    MessageBox.Show("Failed to open grid: " + ut.ErrorMsgFromObject(grid));
}

Opening for direct rendering without using Grid class:

var image = new Image();
if (image.Open(filename, ImageType.USE_FILE_EXTENSION, false, null))
{
    if (image.IsRgb)
    {
        MessageBox.Show("It's not a grid.");
    }
    else
    {
        image.ImageColorScheme = PredefinedColorScheme.SummerMountains;     // or any other
        int handle = axMap1.AddLayer(image, true);
        if (handle == -1)
        {
            MessageBox.Show("Failed to open image: " + axMap1.get_ErrorMsg(axMap1.LastErrorCode));
        }
        else
        {
            MessageBox.Show("Data source is rendered as: " + (image.GridRendering ? "grid" : "image"));
        }
    }
}
else
{
    MessageBox.Show("Failed to open image: " + ut.ErrorMsgFromObject(image));
}

Manual creation of image proxy and color scheme:

var grid = new Grid();
if (grid.Open(filename, GridDataType.UnknownDataType, true, GridFileType.UseExtension, null))
{
    var scheme = new GridColorScheme();
    scheme.UsePredefined((double)grid.Minimum, (double)grid.Maximum, PredefinedColorScheme.SummerMountains);
    scheme.ApplyColoringType(ColoringType.Hillshade);
 
    // grid.CreateImageProxy(scheme) can be used as well
    var img = ut.GridToImage2(grid, scheme, tkGridProxyFormat.gpfTiffProxy, false, null);
    if (img == null)
    {
        MessageBox.Show("Failed to create proxy image for grid:" + ut.ErrorMsgFromObject(ut));
    }
    else
    {
        int handle = axMap1.AddLayer(img, true);
    }
 
    grid.Close();   // we no longer need it as Image class is used for rendering
}
else
{
    MessageBox.Show("Failed to open grid: " + ut.ErrorMsgFromObject(grid));
}

To work with image proxies directly the following API members can be used: Grid.CreateImageProxy, Grid.HasValidImageProxy, Grid.RemoveImageProxy, Image.IsGridProxy.
D. Reading and editing the values.

Grids can be opened in either in-memory or disk based mode. Grid values can be retrieved and edited using:

• Grid.get_Value / Grid.set_Value methods;
• Grid.GetRow2 / Grid.PutRow2, Grid.GetFloatWindow2 / Grid.PutFloatWindow2 methods (for .NET clients perhaps only after tweaking marshalling in interop assemblies).

For in-memory mode to save the changes to disk Grid.Save methods must be called. In disk-based mode the changes are saved automatically.

The size of grid can be obtained from its header (GridHeader.NumberRows, GridHeader.NumberCols).
For multiband datasource to read or edit values in the band other than first one use Grid.OpenBand.

bool inRam = true;
var grid = new Grid();
if (grid.Open(filename, GridDataType.UnknownDataType, inRam, GridFileType.UseExtension, null))
{
    var header = grid.Header;   // better to cache it in variable to avoid multiple reading from disk
    double noData = (double)header.NodataValue;
    for (int i =0; i < header.NumberCols; i++)
    {
        for (int j = 0; j < header.NumberCols; j++)
        {
            double val = grid.get_Value(i, j)
            if (val != noData && val > 1000)
            {
                grid.set_Value(i, j, noData);
            }
        }
    }
 
    // when inRam is set to false no saving is needed
    if (!grid.Save(grid.Filename, GridFileType.UseExtension, null ))
    {
        MessageBox.Show("Failed to save changes: " + ut.ErrorMsgFromObject(grid));
    }
    grid.Close();
}
else
{
    MessageBox.Show("Failed to open grid: " + ut.ErrorMsgFromObject(grid));
}

E. Coordinate system and projection.

Information about geographic coordinate system and projection of grid can be retrieved using GridHeader.GeoProjection property. It is used by AxMap control when AxMap.GrabProjectionFromData is true. However grid can also be rendered fine if no coordinate system is specified, although projection aware functionality of MapWinGIS (tiles, scalebar) will be unavailable or won't function properly.

The location and scaling of grid in world coordinates is defined by GridHeader.XllCenter, GridHeader.YllCenter, GridHeader.dX, GridHeader.dY. While Grid.CellToProj, Grid.ProjToCell can be used to convert from cell coordinates to world coordinates.

Information about coordinates system and projection will be copied to output image when a proxy for the grid is created by Utils.GridToImage2 and all other API members which are using this method.

var grid = new Grid();
if (grid.Open(filename, GridDataType.UnknownDataType, inRam, GridFileType.UseExtension, null))
{
    var gp = grid.Header.GeoProjection;
    MessageBox.Show(gp.IsEmpty() ? "No coordinates system for grid is specified." :  "Coordinate system for grid: " + grid.Header.GeoProjection.ExportToWKT());
    if (gp.IsEmpty)
    {
        double x, y;
        grid.CellToProj(0, 0, out x, out y);
        MessageBox.Show(string.Format("World coordinates of the first cell: x={0}; y={1}", x, y));
    }
    grid.Close();
}

F. Support of GDAL overviews (version 4.9.2):

When opening grids MapWinGIS will recoginze existing GDAL overviews and will automatically create new overviews if needed (GlobalSettings.MinOverviewWidth). By default (GlobalSettings.GridProxyMode = gpmAuto) overviews option will always be chosen over proxy image creation, as it takes significantly less time. For original grids external overviews will be created (.ovr file), for proxy images - built-in overviews.
The use of proxy images for grid can still occur under following conditions:

• proxy image already exists while there is no overviews;
• grid datasource isn't supported by GDAL, so can't be opened directly;
• proxy image option was chosen explicitly with GlobalSettings.GridProxyMode = gpmUseProxy or AxMap.AddLayerFromFilename (filename, fosProxyForGrid, true).

Member Function Documentation

AssignNewProjection()

bool Grid.AssignNewProjection

(

string

Projection

)

Assign new projection to the grid.

Parameters

Projection

Projection string in proj4 format.

Returns

True on success or false otherwise.

CellToProj()

void Grid.CellToProj	(	int	Column,
		int	Row,
		out double	x,
		out double	y
	)

Uses a cell's column and row position to find the center of the cell in projected map coordinates.

Parameters

Column	The column of the cell to find the center in projected map coordinates.
Row	The row of the cell to find the center in projected map coordinates.
x	Returns the x projected map coordinate of the center of the specified cell.
y	Returns the y projected map coordinate of the center of the specified cell.

Clear()

bool Grid.Clear

(

object

ClearValue

)

Clears all data in the grid, setting the value of all cells in the grid to the specified clear value.

Parameters

ClearValue

The value to set all of the grid's cells to.

Returns

A boolean value representing the success or failure of clearing the grid.

Close()

bool Grid.Close

(

)

Closes the grid.

Returns

A boolean value representing the success or failure of closing the grid.

CreateImageProxy()

Image Grid.CreateImageProxy

(

GridColorScheme

ColorScheme

)

Creates a proxy image file to display grid data.

Parameters

ColorScheme

Colour scheme which specified how the data will be visualized.

Returns

Created image proxy or null if the operation failed.

The format of proxy can be changed in GlobalSettings.GridProxyFormat.

New API 4.9.1:

Added in version 4.9.1

CreateNew()

bool Grid.CreateNew	(	string	Filename,
		GridHeader	Header,
		GridDataType	DataType,
		object	InitialValue,
		bool	InRam,
		GridFileType	fileType,
		ICallback	cBack
	)

Creates a new grid.

Parameters

Filename	The filename for the new grid.
Header	The header defining the attributes of the new grid.
DataType	The data type of the new grid.
InitialValue	The initial value for each cell of the new grid.
InRam	Optional. A boolean value representing the grid being stored in memory(RAM) when True, and the grid being stored on disk when False.
fileType	Optional. The grid file type.
cBack	Optional. The ICallback object that will receive the progress and error events during the creation of the new grid.

Returns

A boolean value representing the success or failure of the creation of the new grid.

GenerateColorScheme()

GridColorScheme Grid.GenerateColorScheme	(	tkGridSchemeGeneration	Method,
		PredefinedColorScheme	Colors
	)

Generates colour scheme for the grid.

Parameters

Method	Method of generation to be used.
Colors	Predefined colour scheme to be mapped to the values of grid.

Returns

Generated colour scheme or null if the operation failed.

New API 4.9.1:

Added in version 4.9.1

get_Band()

GdalRasterBand Grid.get_Band

(

int

bandIndex

)

Gets datasource band with specified index.

Parameters

bandIndex

Index of the band.

Returns

The band or null if index is not valid.

New API 4.9.4:

Added in version 4.9.4

get_ErrorMsg()

string Grid.get_ErrorMsg

(

int

ErrorCode

)

Retrieves the error message associated with the specified error code.

Parameters

ErrorCode

The numeric code of error returned by Grid.LastErrorCode.

Returns

The description of the error.

get_Value()

object Grid.get_Value	(	int	Column,
		int	Row
	)

Returns the value stored in the grid at the specified cell.

Parameters

Column	The column representing the cell for which the value is required.
Row	The row representing the cell for which the value is required.

Returns

The value stored in the grid in the specified cell.

GetFloatWindow()

bool Grid.GetFloatWindow	(	int	StartRow,
		int	EndRow,
		int	StartCol,
		int	EndCol,
		ref float	Vals
	)

Returns an array with grid values which lie within specified bounds.

For inner use or C++ use only. Only a single value will be returned to .NET.

Parameters

StartRow	The start row of the window.
EndRow	The end row of the window.
StartCol	The start colour of the window.
EndCol	The end colour of the window.
Vals	A supposed array (only a single value in .NET).

Returns

True on success and false otherwise.

GetFloatWindow2()

bool Grid.GetFloatWindow2	(	int	StartRow,
		int	EndRow,
		int	StartCol,
		int	EndCol,
		ref double	Vals
	)

Returns an array with grid values which lie within specified bounds. Double overload of Grid.GetFloatWindow method.

For inner use or C++ use only. Only a single value will be returned to .NET.

Parameters

StartRow	The start row of the window.
EndRow	The end row of the window.
StartCol	The start colour of the window.
EndCol	The end colour of the window.
Vals	A supposed array (only a single value in .NET).

Returns

True on success and false otherwise.

New API 4.9.1:

Added in version 4.9.1

GetRow()

bool Grid.GetRow	(	int	Row,
		ref float	Vals
	)

The faster way to read the array values that are of a specific size.

The row is the integer row to read from the grid object. The vals variable is actually the first element of the array of floats that you want to be populated with the values from the grid. Since arrays are stored sequentially in memory, passing the first element allows the prediction of where the other values must go. It is very important that you always dimension the array as being of type float, and always make sure that you dimension it from 0 to numCols - 1.

Parameters

Row	The Integer value of the row to retrieve values for.
Vals	Reference to the first element of the array of floats that will hold the row of values.

Returns

True on success and false otherwise.

GetRow2()

bool Grid.GetRow2	(	int	Row,
		ref double	Vals
	)

Provides the faster way to read the array values that are of a specific size. Double overload of Grid.GetRow.

The row is the integer row to read from the grid object. The vals variable is actually the first element of the array of floats that you want to be populated with the values from the grid. Since arrays are stored sequentially in memory, passing the first element allows the prediction of where the other values must go. It is very important that you always dimension the array as being of type double, and always make sure that you dimension it from 0 to numCols - 1.

Parameters

Row	The Integer value of the row to retrieve values for.
Vals	Reference to the first element of the array of doubles that will hold the row of values.

Returns

True on success and false otherwise.

New API 4.9.1:

Added in version 4.9.1

Open()

bool Grid.Open	(	string	Filename,
		GridDataType	DataType,
		bool	InRam,
		GridFileType	fileType,
		ICallback	cBack
	)

Opens a grid.

Parameters

Filename	The filename of the grid to be opened.
DataType	Optional. The data type of the grid to be opened.
InRam	Optional. A boolean value representing whether the grid will be stored in RAM or on disk.
fileType	Optional. The file type of the grid. The default file type is "Use Extension".
cBack	Optional. The ICallback object that will receive the progress and error events during the creation of the new grid.

Returns

A boolean value that represents the success or failure of opening the grid.

OpenAsImage()

Image Grid.OpenAsImage	(	GridColorScheme	Scheme,
		tkGridProxyMode	proxyMode = tkGridProxyMode.gpmAuto,
		ICallback	cBack = null
	)

Opens grid as image.

Parameters

Scheme	Colour scheme which specifies how grid will be visualized.
proxyMode	Proxy mode to be used.
cBack	Callback interface.

Returns

Resulting image object or null if the operation failed.

Depending on the proxy mode, grid datasource can be opened directly, or a proxy file can be created.

New API 4.9.1:

Added in version 4.9.1

OpenBand()

bool Grid.OpenBand

(

int

bandIndex

)

Makes the specified band of the grid active.

Parameters

bandIndex

Index of the band to be set active.

Returns

True on success and false otherwise.

New API 4.9.0:

Added in version 4.9.0

ProjToCell()

void Grid.ProjToCell	(	double	x,
		double	y,
		out int	Column,
		out int	Row
	)

Converts a point in projected map coordinates to a cell (column, row) in the grid.

If the point lies outside the bounds of the grid, a column and row are returned which are outside the boundaries of the grid. For example, if the point lies to the left or lies below the grid boundaries, a negative column or row will be returned. Similarly, if the point lies above or to the right of the grid boundaries, a column or row which is greater than the number of columns or rows will be returned.

Parameters

x	The x projected map coordinate for which the corresponding cell in the grid is required.
y	The y projected map coordinate for which the corresponding cell in the grid is required.
Column	The column the specified point lies within. This value may not be within the valid bounds of the grid.
Row	The row the specified point lies within. This value may not be within the valid bounds of the grid.

PutFloatWindow()

bool Grid.PutFloatWindow	(	int	StartRow,
		int	EndRow,
		int	StartCol,
		int	EndCol,
		ref float	Vals
	)

Sets an array of values for a given region of the grid.

Parameters

StartRow	The start row of the window.
EndRow	The end row of the window.
StartCol	The start colour of the window.
EndCol	The end colour of the window.
Vals	A supposed array (only a single value in .NET).

Returns

True on success and false otherwise.

PutFloatWindow2()

bool Grid.PutFloatWindow2	(	int	StartRow,
		int	EndRow,
		int	StartCol,
		int	EndCol,
		ref double	Vals
	)

Sets an array of values for a given region of the grid. Double overload of Grid.PutFloatWindow.

Parameters

StartRow	The start row of the window.
EndRow	The end row of the window.
StartCol	The start colour of the window.
EndCol	The end colour of the window.
Vals	A supposed array (only a single value in .NET).

Returns

True on success and false otherwise.

New API 4.9.1:

Added in version 4.9.1

PutRow()

bool Grid.PutRow	(	int	Row,
		ref float	Vals
	)

Provides The faster way to write the array values that are of a specific size.

The row is the integer row to read from the grid object. The vals variable is actually the first element of the array of floats that you want to be populated with the values from the grid. Since arrays are stored sequentially in memory, passing the first element allows the prediction of where the other values must go. It is very important that you always dimension the array as being of type float, and always make sure that you dimension it from 0 to numCols - 1.

Parameters

Row	The Integer value of the row to retrieve values for.
Vals	Reference to the first element of the array of floats that will hold the row of values.

Returns

True on success.

PutRow2()

bool Grid.PutRow2	(	int	Row,
		ref double	Vals
	)

Provides The faster way to write the array values that are of a specific size. Double overload of Grid.PutRow.

The row is the integer row to read from the grid object. The vals variable is actually the first element of the array of floats that you want to be populated with the values from the grid. Since arrays are stored sequentially in memory, passing the first element allows the prediction of where the other values must go. It is very important that you always dimension the array as being of type float, and always make sure that you dimension it from 0 to numCols - 1.

Parameters

Row	The Integer value of the row to retrieve values for.
Vals	Reference to the first element of the array of doubles that will hold the row of values.

Returns

True on success.

New API 4.9.1:

Added in version 4.9.1

RemoveImageProxy()

bool Grid.RemoveImageProxy

(

)

Removes proxy image file created for grid display.

Returns

True on success or if there is no image proxy and false if the operation failed.

Only the proxy format set in GlobalSettings.GridProxyFormat will be removed.

New API 4.9.1:

Added in version 4.9.1

Resource()

bool Grid.Resource

(

string

newSrcPath

)

Changes the grid source without closing it.

Parameters

newSrcPath

The name of the new file source.

Returns

True on success and false otherwise.

RetrieveColorScheme()

GridColorScheme Grid.RetrieveColorScheme

(

tkGridSchemeRetrieval

Method

)

Retrieves colour scheme from the grid.

Parameters

Method

Retrieval method. Use Auto to try all the available method.

Returns

Colour scheme object or null if the operation failed.

Is different from Grid.GenerateColorScheme, as it get colour scheme already stored in the grid itself or as an external .mwleg file rather than creating a completely new one.

New API 4.9.1:

Added in version 4.9.1

RetrieveOrGenerateColorScheme()

GridColorScheme Grid.RetrieveOrGenerateColorScheme	(	tkGridSchemeRetrieval	retrievalMethod,
		tkGridSchemeGeneration	generateMethod,
		PredefinedColorScheme	Colors
	)

Tries to retrieve any existing color scheme associated with grid or generates a new one if none is found.

Parameters

retrievalMethod	Colour scheme retrieval method.
generateMethod	Colour scheme generation method
Colors	Predefined set of colours to be mapped to grid values during generation process.

Returns

Color scheme or null if both retrieval and generation failed.

New API 4.9.1:

Added in version 4.9.1

Save()

bool Grid.Save	(	string	Filename,
		GridFileType	GridFileType,
		ICallback	cBack
	)

Saves the grid.

Parameters

Filename	Optional. The filename the grid will be saved under. If no filename is specified the filename in the grid's Filename property is used.
GridFileType	Optional. The file type to save the grid as. If no type is specified, the type stored in the grid object is used.
cBack	Optional. The ICallback object that will receive the progress and error events during the creation of the new grid.

Returns

A boolean value representing the success or failure of saving the grid.

set_Value()

void Grid.set_Value	(	int	Column,
		int	Row,
		object	pVal
	)

Sets the value of the specified cell of the grid.

Parameters

Column	The index of the cell's column.
Row	The index of the cell's row.
pVal	The new value as variant data type.

SetInvalidValuesToNodata()

bool Grid.SetInvalidValuesToNodata	(	double	MinThresholdValue,
		double	MaxThresholdValue
	)

Sets invalid values to no data values.

Parameters

MinThresholdValue	The minimum valid value.
MaxThresholdValue	The maximum valid value.

Returns

True in success and false otherwise.

Property Documentation

ActiveBand

GdalRasterBand Grid.ActiveBand

get

Gets the active band of the datasource.

New API 4.9.4:

Added in version 4.9.4

ActiveBandIndex

int Grid.ActiveBandIndex

get

The index of the active band within grid.

Active band will be used on data extraction operation like Grid.get_Value, Grid.GetFloatWindow and during creation of image proxy.

New API 4.9.0:

Added in version 4.9.0

CanDisplayWithoutProxy

tkCanDisplayGridWoProxy Grid.CanDisplayWithoutProxy

get

Gets the value indicating whether grid source can be displayed by Image class without creation of proxy file.

Check return value for the reason whey such rendering isn't possible.

New API 4.9.1:

Added in version 4.9.1

CdlgFilter

string Grid.CdlgFilter

get

Returns the common dialog filter containing all supported file extensions in string format.

DataType

GridDataType Grid.DataType

get

Returns the data type of the values stored in the grid.

Extents

Extents Grid.Extents

get

Gets extents of the grid.

New API 4.9.0:

Added in version 4.9.0

Filename

string Grid.Filename

get

The filename associated with the object.

GlobalCallback

ICallback Grid.GlobalCallback

getset

The global callback is the interface used by MapWinGIS to pass progress and error events to interested applications.

Deprecated:

v4.9.3 Use GlobalSettings.ApplicationCallback instead.

HasValidImageProxy

bool Grid.HasValidImageProxy

get

Gets the value indicating whether grid has a valid image proxy for visualization.

To be considered valid the proxy must have proper name (with "_proxy" postfix) and colour scheme file (.mwleg). Both this files must have older creation date than the grid source file itself.

New API 4.9.1:

Added in version 4.9.1

Header

GridHeader Grid.Header

get

Returns the header of the grid.

InRam

bool Grid.InRam

get

Returns whether the grid is loaded in to RAM memory or not.

Key

string Grid.Key

getset

The key may be used by the programmer to store any string data associated with the object.

LastErrorCode

int Grid.LastErrorCode

get

Retrieves the last error generated in the object.

Maximum

object Grid.Maximum

get

Returns the maximum value stored in the grid.

Minimum

object Grid.Minimum

get

Returns the minimum value stored in the grid.

NumBands

int Grid.NumBands

get

Gets the number of within the grid.

New API 4.9.0:

Added in version 4.9.0

PreferedDisplayMode

tkGridProxyMode Grid.PreferedDisplayMode

getset

Gets or sets the value indicating how the grid should be displayed.

This value will be used in AxMap.AddLayer and Grid.OpenAsImage methods.

New API 4.9.1:

Added in version 4.9.1

RasterColorTableColoringScheme

GridColorScheme Grid.RasterColorTableColoringScheme

get

Gets grid colour scheme object used for rendering of the image representation of the grid, in case the datasource has a color table (GTiff with indexed colors, for example).

SourceType

tkGridSourceType Grid.SourceType

get

Gets the type of grid source, which defines a) whether any grid source is opened and b) if so, what the inner representation of grid by MapWinGIS.

The functionality and behaviour of various source types may differ.

New API 4.9.0:

Added in version 4.9.0