A utils object provides access to a set of utility functions to perform a variety of tasks on other objects such as grids, images, points, shapes, shapefiles, tins, etc. More...

Public Member Functions
Shape	ClipPolygon (PolygonOperation op, Shape SubjectPolygon, Shape ClipPolygon)
	Modifies a polygon using the specified method.
uint	ColorByName (tkMapColor Name)
	Returns the numeric representation for the specified color.
bool	GenerateContour (string pszSrcFilename, string pszDstFilename, double dfInterval, double dfNoData, bool Is3D, object dblFLArray, ICallback cBack)
	This program generates a vector contour file from the input raster elevation model (DEM).
bool	GenerateHillShade (string bstrGridFilename, string bstrShadeFilename, float Z, float scale, float az, float alt)
	Generates a hillshade image for a raster data source.
double	get_Area (Shape Shape)
	Returns the area of the polygon shape. For mulit-part polygons which may contain counter-clockwise holes, the area of the holes will be subtracted from that of the surrounding clockwise portions.
string	get_ErrorMsg (int ErrorCode)
	Retrieves the error message associated with the specified error code.
double	get_Length (Shape Shape)
	Gets the length of the line shape.
double	get_Perimeter (Shape Shape)
	Gets the perimeter of the polygon shape.
bool	GridInterpolateNoData (Grid Grd, ICallback cBack)
	Uses valid data in a grid to replace grid cells containing no-data values with an interpolated value.
Grid	GridMerge (object Grids, string MergeFilename, bool InRam, GridFileType GrdFileType, ICallback cBack)
	Merges multiple grids into a single output grid.
bool	GridReplace (Grid Grd, object OldValue, object newValue, ICallback cBack)
	Replaces all occurances of a value in the grid with a new value.
Grid	GridToGrid (Grid Grid, GridDataType OutDataType, ICallback cBack)
	Creates a new grid of the same size as the original grid, converting the values of the original grid into a different data type in the new grid.
Image	GridToImage (Grid Grid, GridColorScheme cScheme, ICallback cBack)
	Create an image from the grid using the given grid color scheme.
Shapefile	GridToShapefile (Grid Grid, Grid ConnectionGrid, ICallback cBack)
	Creates a new shapefile from the grid. Note: It is important that the flow grid is used when there are any ambiguous parts of the grid.
stdole.IPictureDisp	hBitmapToPicture (int hBitmap)
	Converts an hBitmap to an IPictureDisp object.
bool	MergeImages (Array InputNames, string OutputName)
	Merges several images in a single image.
Shapefile	OGRLayerToShapefile (string Filename, ShpfileType ShpType, ICallback cBack)
	Partially implemented. Creates a shapefile from any vector format supported by OGR library.
bool	PointInPolygon (Shape Shp, Point TestPoint)
	Gets whether or not a point lies within the specified polygon shape.
bool	RemoveColinearPoints (Shapefile Shapes, double LinearTolerance, ICallback cBack)
	Removes colinear points from a shapefile.
Shapefile	ReprojectShapefile (Shapefile sf, GeoProjection source, GeoProjection target)
	Repojects a shapefile.
Grid	ShapefileToGrid (Shapefile Shpfile, bool UseShapefileBounds, GridHeader GrdHeader, double Cellsize, bool UseShapeNumber, short SingleValue)
	This function is not implemented. Converts a shapefile to a grid.
Shape	ShapeMerge (Shapefile Shapes, int IndexOne, int IndexTwo, ICallback cBack)
	Merges two shapes in a shapefile to create a new shape.
Shapefile	ShapeToShapeZ (Shapefile Shapefile, Grid Grid, ICallback cBack)
	Creates a new shapefile with z values added from an elevation grid.
Shapefile	TinToShapefile (Tin Tin, ShpfileType Type, ICallback cBack)
	Creates a shapefile from a TIN object.
bool	TranslateRaster (string bstrSrcFilename, string bstrDstFilename, string bstrOptions, ICallback cBack)
	Converts raster data between different formats, potentially performing some operations like subsettings, resampling, and rescaling pixels in the process.
Properties
ICallback	GlobalCallback `[get, set]`
	The global callback is the interface used by MapWinGIS to pass progress and error events to interested applications.
string	Key `[get, set]`
	The key may be used by the programmer to store any string data associated with the object.
int	LastErrorCode `[get]`
	Retrieves the last error generated in the object.

Detailed Description

A utils object provides access to a set of utility functions to perform a variety of tasks on other objects such as grids, images, points, shapes, shapefiles, tins, etc.

Examples:: AddCategoryRange.cs, CreateBuffer.cs, IntersectionLength.cs, LabelSelection.cs, LinePattern.cs, MinimalDistance.cs, SelectByDistance.cs, and Tracking.cs.

Member Function Documentation

Shape Utils.ClipPolygon	(	PolygonOperation	op,
		Shape	SubjectPolygon,
		Shape	ClipPolygon
	)

Modifies a polygon using the specified method.

Parameters:

op	The operation to use on the subject polygon.
SubjectPolygon	The first polygon to perform the specifed polygon operation on.
ClipPolygon	The second polygon to perform the specified polygon operation with.

Returns:: The polygon shape created using the specified polygon operation.

uint Utils.ColorByName ( tkMapColor Name )

Returns the numeric representation for the specified color.

The return value can be used for all properties which require color specification as unsigned integer.

Parameters:

Name	The name of the color.

Returns:: The numeric code of the color.

New API 4.8:: Added in version 4.8

Examples:: AddCategoryRange.cs, CreateBuffer.cs, IntersectionLength.cs, LabelSelection.cs, LinePattern.cs, MinimalDistance.cs, SelectByDistance.cs, and Tracking.cs.

bool Utils.GenerateContour	(	string	pszSrcFilename,
		string	pszDstFilename,
		double	dfInterval,
		double	dfNoData,
		bool	Is3D,
		object	dblFLArray,
		ICallback	cBack
	)

This program generates a vector contour file from the input raster elevation model (DEM).

See the description of approriate routine in GDAL Tools.

Parameters:

bstrSrcFilename	The name of the source file.
bstrDstFilename	The name of the output file.
bstrOptions	Options of the routine.
cBack	The callback object.

Returns:: True on success and false otherwise.

bool Utils.GenerateHillShade	(	string	bstrGridFilename,
		string	bstrShadeFilename,
		float	Z,
		float	scale,
		float	az,
		float	alt
	)

Generates a hillshade image for a raster data source.

This code was written by Matt Perry, perrygeo@gmail.com, published in Gdal-dev Digest, Vol 19, Issue 20 Note: Scale for Feet/Latlong use scale=370400, for Meters/LatLong use scale=111120 (based on the GRASS GIS algorithm from r.shaded.relief)

Parameters:

bstrGridFilename	The input raster data. This can be in virtually any raster data format.
bstrShadeFilename	The output image filename. This can be virtually any image format, the extension will determine the format.
Z	Z Factor. Defaults to 1.
scale	Scale Factor. Defaults to 1.
az	Azimuth. Defaults to 315.
alt	Altitude. Defaults to 45.

Returns:

double Utils.get_Area ( Shape Shape )

Returns the area of the polygon shape. For mulit-part polygons which may contain counter-clockwise holes, the area of the holes will be subtracted from that of the surrounding clockwise portions.

Parameters:

Shape The polygon shape for which the area is required.

Returns:: The area of the polygon shape.

string Utils.get_ErrorMsg ( int ErrorCode )

Retrieves the error message associated with the specified error code.

Parameters:

ErrorCode The error code for which the error message is required.

Returns:: The error message description for the specified error code.

double Utils.get_Length ( Shape Shape )

Gets the length of the line shape.

Parameters:

Shape

Returns:

double Utils.get_Perimeter ( Shape Shape )

Gets the perimeter of the polygon shape.

Parameters:

Shape The polygon shape for which the perimeter is required.

Returns:: The perimeter of the polygon shape.

bool Utils.GridInterpolateNoData	(	Grid	Grd,
		ICallback	cBack
	)

Uses valid data in a grid to replace grid cells containing no-data values with an interpolated value.

Parameters:

Grd	The grid for which no-data cells will be replaced with interpolated values.
cBack	The ICallback object which will receive progress and error messages.

Returns:: A boolean value representing the success or failure of replacing no-data cells in the grid with interpolated values.

Grid Utils.GridMerge	(	object	Grids,
		string	MergeFilename,
		bool	InRam,
		GridFileType	GrdFileType,
		ICallback	cBack
	)

Merges multiple grids into a single output grid.

Parameters:

Grids	An array of grid objects to be merged into one grid.
MergeFilename	The filename to use for the new merged grid.
InRam	Optional. A boolean value representing whether to create the merged grid in RAM or on disk
GrdFileType	Optional. The file type of the new merged grid.
cBack	Optional. The ICallback object which will receive progress and error messages while the grids are being merged.

Returns:: The new merged grid.

bool Utils.GridReplace	(	Grid	Grd,
		object	OldValue,
		object	newValue,
		ICallback	cBack
	)

Replaces all occurances of a value in the grid with a new value.

Parameters:

Grd	The grid to replace the specified value in.
OldValue	The value in the grid to be replaced with the new value.
newValue	The value to replace the old values with.
cBack	The ICallback object which will receive progress and error mesages while the old value is being replaced with the new values in the grid.

Returns:: A boolean value representing the success or failure of replacing the old value with the new value in the grid.

Grid Utils.GridToGrid	(	Grid	Grid,
		GridDataType	OutDataType,
		ICallback	cBack
	)

Creates a new grid of the same size as the original grid, converting the values of the original grid into a different data type in the new grid.

Parameters:

Grid	The original grid.
OutDataType	The data type to convert the original grid values to for the new grid values.
cBack	The ICallback object which will receive progress and error mesages while the original grid values are converted and copied into the new grid.

Returns:: The new grid filled with the converted values of the original grid.

Image Utils.GridToImage	(	Grid	Grid,
		GridColorScheme	cScheme,
		ICallback	cBack
	)

Create an image from the grid using the given grid color scheme.

Parameters:

Grid	The grid to use to create the image.
cScheme	The grid color scheme to use to create an image from the grid.
cBack	The ICallback object which will receive progress and error mesages while the image is being created from the grid.

Returns:: The image created from the grid.

Shapefile Utils.GridToShapefile	(	Grid	Grid,
		Grid	ConnectionGrid,
		ICallback	cBack
	)

Creates a new shapefile from the grid. Note: It is important that the flow grid is used when there are any ambiguous parts of the grid.

Parameters:

Grid	The grid to be converted to a shapefile.
ConnectionGrid	Optional. The flow grid that is used to resolve any ambiguity. Without this flow grid the output results are somewhat unpredictable.
cBack	The ICallback object which will receive progress and error mesages while the grid is being converted to the shapefile.

Returns:

stdole.IPictureDisp Utils.hBitmapToPicture ( int hBitmap )

Converts an hBitmap to an IPictureDisp object.

Parameters:

hBitmap A device context handle to a bitmap.

Returns:: An IPictureDisp object created from the bitmap.

bool Utils.MergeImages	(	Array	InputNames,
		string	OutputName
	)

Merges several images in a single image.

All the input images must be of the same size. The color marked in the input image as transparent won't be passed to the output.

Parameters:

InputNames	An array of string type with the filenames of the images.
OutputName	The name if te output file.

Returns:

using System;
using System.Collections;
using System.Windows.Forms;
using AxMapWinGIS;
using MapWinGIS;

public partial class MapExamples
{
    private void MergeImages(object sender, EventArgs e)
    {
        FolderBrowserDialog dlg = new FolderBrowserDialog();
        dlg.Description = "Select the directory with images to merge";
        if (dlg.ShowDialog() == DialogResult.OK)
        {
            System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(dlg.SelectedPath);
            System.IO.FileInfo[] files = dir.GetFiles();

            ArrayList list = new ArrayList();
            for (int i = 0; i < files.Length; i++)
            {
                if (files[i].Extension.ToLower() == ".png")
                {
                    list.Add(files[i].FullName);
                }
            }

            if (list.Count <= 1)
            {
                MessageBox.Show("There is no PNG files to merge in the specified directory");
                return;
            }
            else
            {
                string[] inputNames = (string[])list.ToArray(typeof(string));

                Utils utils = new Utils();
                if (utils.MergeImages(inputNames, "c:\\result.png"))
                {
                    MessageBox.Show("Success");
                }
            }
        }
    }
}

New API 4.8:: Added in version 4.8

Shapefile Utils.OGRLayerToShapefile	(	string	Filename,
		ShpfileType	ShpType,
		ICallback	cBack
	)

Partially implemented. Creates a shapefile from any vector format supported by OGR library.

The method needs testing and elaboration to handle the peculiarities of various data formats.

Parameters:

Filename	The name of the vector data source.
ShpType	The type of the output shapefile.
cBack	The callback object to return information about progress and errors.

Returns:: The reference to the resulting shapefile or NULL reference on failure.

New API 4.8:: Added in version 4.8

bool Utils.PointInPolygon	(	Shape	Shp,
		Point	TestPoint
	)

Gets whether or not a point lies within the specified polygon shape.

There is a faster option available when working with shapefiles: PointInShape.

Parameters:

Shp	The polygon shape to perform the test on.
TestPoint	The point to test whether or not it lies within the specified polygon shape.

Returns:: A boolean value representing whether or not the point lies within the shape.

bool Utils.RemoveColinearPoints	(	Shapefile	Shapes,
		double	LinearTolerance,
		ICallback	cBack
	)

Removes colinear points from a shapefile.

A shapefile containing colinear points leads to the shapefile taking up unecessary space since some points in the shapefile add detail to the display of the shapes.

Parameters:

Shapes	The shapefile to remove colinear points from.
LinearTolerance	Points will be considered colinear if the distance in between them is with in this tolerance. This distance is measured in projected map coordinates.
cBack	The ICallback object which will receive progress and error mesages while colinear points are being removed.

Returns:: A boolean value representing the success or failure of removing colinear points from the shapefile.

Shapefile Utils.ReprojectShapefile	(	Shapefile	sf,
		GeoProjection	source,
		GeoProjection	target
	)

Repojects a shapefile.

Parameters:

sf	The input shapefile.
source	The source projection.
target	The target projection.

Returns:: The copy of shapefile with new projection or NULL reference on failure.

New API 4.8:: Added in version 4.8

Grid Utils.ShapefileToGrid	(	Shapefile	Shpfile,
		bool	UseShapefileBounds,
		GridHeader	GrdHeader,
		double	Cellsize,
		bool	UseShapeNumber,
		short	SingleValue
	)

This function is not implemented. Converts a shapefile to a grid.

Parameters:

Shpfile	The shapefile to be converted into a grid.
UseShapefileBounds	Optional. A boolean value representing whether or not the grid will have the same extents as the shapefile. The default is True
GrdHeader	Optional. The grid header to use to create the new grid. If UseShapefileBounds is set to true, the extents supplied in the grid header will be ignored when the grid is created.
Cellsize	Optional. The cell size of the new grid. The default cell size is 30.
UseShapeNumber	Optional. Specifies that the value of each cell in the grid should be the shape index. The default value is true.
SingleValue	Optional. The value to use when creating the grid. This only applies when UseShapeNumber is set to false. The default value is 1.

Returns:: The grid created from the shapefile.

Shape Utils.ShapeMerge	(	Shapefile	Shapes,
		int	IndexOne,
		int	IndexTwo,
		ICallback	cBack
	)

Merges two shapes in a shapefile to create a new shape.

Parameters:

Shapes	The shapefile containing the two shapes to be merged to create the new shape.
IndexOne	The index of the first shape to be merged.
IndexTwo	The index of the second shape to be merged.
cBack	The ICallback object which will receive progress and error mesages while the shapes are being merged.

Returns:: The resulting shape.

Shapefile Utils.ShapeToShapeZ	(	Shapefile	Shapefile,
		Grid	Grid,
		ICallback	cBack
	)

Creates a new shapefile with z values added from an elevation grid.

Parameters:

Shapefile	The shapefile to be converted to a new shapefile with z values.
Grid	The elevation grid to get the z values from.
cBack	The ICallback object which will receive progress and error mesages while z values are being added to the shapefile.

Returns:: The new shapefile containing z values obtained from the elevation grid.

Shapefile Utils.TinToShapefile	(	Tin	Tin,
		ShpfileType	Type,
		ICallback	cBack
	)

Creates a shapefile from a TIN object.

Parameters:

Tin	The TIN object to be used to create a new shapefile.
Type	The type of the shapefile to be created.
cBack	The ICallback object which will receive progress and error mesages while shapefile is being created from the TIN.

Returns:: The new shapefile created from the TIN.

bool Utils.TranslateRaster	(	string	bstrSrcFilename,
		string	bstrDstFilename,
		string	bstrOptions,
		ICallback	cBack
	)

Converts raster data between different formats, potentially performing some operations like subsettings, resampling, and rescaling pixels in the process.

See the description of approriate routine in GDAL Tools.

Parameters:

bstrSrcFilename	The name of the source file.
bstrDstFilename	The name of the destination file.
bstrOptions	Options of the routine.
cBack	The callback object.

Returns:: True on success and false otherwise.

Property Documentation

ICallback Utils.GlobalCallback [get, set]

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

string Utils.Key [get, set]

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

int Utils.LastErrorCode [get]

Retrieves the last error generated in the object.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

Property Documentation