Public Member Functions | Properties
Utils Class Reference

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

List of all members.

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:
opThe operation to use on the subject polygon.
SubjectPolygonThe first polygon to perform the specifed polygon operation on.
ClipPolygonThe 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:
NameThe 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:
bstrSrcFilenameThe name of the source file.
bstrDstFilenameThe name of the output file.
bstrOptionsOptions of the routine.
cBackThe 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:
bstrGridFilenameThe input raster data. This can be in virtually any raster data format.
bstrShadeFilenameThe output image filename. This can be virtually any image format, the extension will determine the format.
ZZ Factor. Defaults to 1.
scaleScale Factor. Defaults to 1.
azAzimuth. Defaults to 315.
altAltitude. 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:
ShapeThe 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:
ErrorCodeThe 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:
ShapeThe 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:
GrdThe grid for which no-data cells will be replaced with interpolated values.
cBackThe 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:
GridsAn array of grid objects to be merged into one grid.
MergeFilenameThe filename to use for the new merged grid.
InRamOptional. A boolean value representing whether to create the merged grid in RAM or on disk
GrdFileTypeOptional. The file type of the new merged grid.
cBackOptional. 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:
GrdThe grid to replace the specified value in.
OldValueThe value in the grid to be replaced with the new value.
newValueThe value to replace the old values with.
cBackThe 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:
GridThe original grid.
OutDataTypeThe data type to convert the original grid values to for the new grid values.
cBackThe 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:
GridThe grid to use to create the image.
cSchemeThe grid color scheme to use to create an image from the grid.
cBackThe 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:
GridThe grid to be converted to a shapefile.
ConnectionGridOptional. The flow grid that is used to resolve any ambiguity. Without this flow grid the output results are somewhat unpredictable.
cBackThe 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:
hBitmapA 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:
InputNamesAn array of string type with the filenames of the images.
OutputNameThe 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:
FilenameThe name of the vector data source.
ShpTypeThe type of the output shapefile.
cBackThe 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:
ShpThe polygon shape to perform the test on.
TestPointThe 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:
ShapesThe shapefile to remove colinear points from.
LinearTolerancePoints will be considered colinear if the distance in between them is with in this tolerance. This distance is measured in projected map coordinates.
cBackThe 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.

Repojects a shapefile.

Parameters:
sfThe input shapefile.
sourceThe source projection.
targetThe 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:
ShpfileThe shapefile to be converted into a grid.
UseShapefileBoundsOptional. A boolean value representing whether or not the grid will have the same extents as the shapefile. The default is True
GrdHeaderOptional. 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.
CellsizeOptional. The cell size of the new grid. The default cell size is 30.
UseShapeNumberOptional. Specifies that the value of each cell in the grid should be the shape index. The default value is true.
SingleValueOptional. 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:
ShapesThe shapefile containing the two shapes to be merged to create the new shape.
IndexOneThe index of the first shape to be merged.
IndexTwoThe index of the second shape to be merged.
cBackThe 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:
ShapefileThe shapefile to be converted to a new shapefile with z values.
GridThe elevation grid to get the z values from.
cBackThe 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:
TinThe TIN object to be used to create a new shapefile.
TypeThe type of the shapefile to be created.
cBackThe 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:
bstrSrcFilenameThe name of the source file.
bstrDstFilenameThe name of the destination file.
bstrOptionsOptions of the routine.
cBackThe callback object.
Returns:
True on success and false otherwise.

Property Documentation

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.

Retrieves the last error generated in the object.

 All Classes Files Functions Enumerations Properties