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.
Starting at v4.9.5 some specific GDAL methods are moved to GdalUtils. More...

Collaboration diagram for Utils:
Collaboration graph

Public Member Functions

bool BufferByDistance (Shapefile subject, double Distance, int nSegments, bool SelectedOnly, bool MergeResults, string outputFilename, bool Overwrite)
 
bool CalculateRaster (Array filenames, string Expression, string outputFilename, string gdalOutputFormat, float NodataValue, ICallback cBack, out string ErrorMsg)
 Creates a new raster dataset based on the array of input datasets and an arbitrary formula to calculate values of output dataset. More...
 
bool ClipGridWithPolygon (string inputGridfile, Shape poly, string resultGridfile, bool keepExtents)
 Creates a new grid from the input one in which all values outside the specified polygon are set to no data value. More...
 
bool ClipGridWithPolygon2 (Grid inputGrid, Shape poly, string resultGridfile, bool keepExtents)
 Creates a new grid from the input one in which all values outside the specified polygon are set to no data value. More...
 
Shape ClipPolygon (PolygonOperation op, Shape SubjectPolygon, Shape ClipPolygon)
 Modifies a polygon using the specified method. More...
 
uint ColorByName (tkMapColor Name)
 Returns the numeric representation for the specified color. More...
 
bool ConvertDistance (tkUnitsOfMeasure sourceUnit, tkUnitsOfMeasure targetUnit, ref double Value)
 Converts distance from one units of measuring to another. More...
 
bool CopyNodataValues (string sourceFilename, string destFilename)
 Copies no data values from one grid datasource to another. More...
 
object CreateInstance (tkInterface interfaceId)
 Creates an instance of specified COM CoClass implementing specified interface. More...
 
tkUnitsOfMeasure EPSGUnitConversion (int EPSGUnitCode)
 Gets the tkUnitsOfMeasure enumeration associated with the specified EPSG Unit Code More...
 
string ErrorMsgFromObject (object comClass)
 Displays error message for the last error that took place within object passed as parameter. More...
 
bool ExplodeShapes (Shapefile subject, bool SelectedOnly, string outputFilename, bool Overwrite)
 
bool ExportSelection (Shapefile subject, string outputFilename, bool Overwrite)
 
bool FixUpShapes (Shapefile subject, bool SelectedOnly, string outputFilename, bool Overwrite)
 
bool GDALAddOverviews (string bstrSrcFilename, string bstrOptions, string bstrLevels, ICallback cBack=null)
 The same as GDAL's gdaladdo.exe utility. More...
 
bool GDALBuildVrt (string bstrDstFilename, string bstrOptions, ICallback cBack=null)
 The same as GDAL's gdalbuildvert.exe utility. More...
 
string GDALInfo (string bstrSrcFilename, string bstrOptions, ICallback cBack=null)
 The same as GDAL's gdalinfo.exe utility. More...
 
bool GDALRasterize (string bstrSrcFilename, string bstrDstFilename, string bstrOptions, ICallback cBack=null)
 The same as GDAL's gdal_rasterize.exe utility. More...
 
bool GDALWarp (string bstrSrcFilename, string bstrDstFilename, string bstrOptions, ICallback cBack=null)
 The same as GDAL's gdalwarp.exe utility More...
 
bool GenerateContour (string bstrSrcFilename, string bstrDstFilename, double dfInterval, double dfNoData, bool Is3D, object dblFLArray, ICallback cBack)
 This program generates a vector contour file from the input raster elevation model (DEM). More...
 
bool GenerateHillShade (string bstrGridFilename, string bstrShadeFilename, float Z, float scale, float az, float alt)
 Generates a hillshade image for a raster data source. More...
 
double GeodesicArea (Shape shapeWgs84)
 
double GeodesicDistance (double lat1, double lng1, double lat2, double lng2)
 Calculates geodesic distance between 2 points on Earth. More...
 
double get_Area (Shape Shape)
 Returns the area of the polygon shape. For multi-part polygons which may contain counter-clockwise holes, the area of the holes will be subtracted from that of the surrounding clockwise portions. More...
 
string get_ComUsageReport (bool unreleasedOnly)
 Gets report about COM objects that were created and released. More...
 
string get_ErrorMsg (int ErrorCode)
 Retrieves the error message associated with the specified error code. More...
 
double get_Length (Shape Shape)
 Gets the length of the line shape. More...
 
double get_Perimeter (Shape Shape)
 Gets the perimeter of the polygon shape. More...
 
double GetAngle (Point firstPoint, Point secondPoint)
 Calculates the angle defined by the two specified coordinates More...
 
string GetNAD83ProjectionName (tkNad83Projection projectionID)
 Gets the name of the projection associated with the specified NAD83 enumeration More...
 
bool GetProjectionList (tkProjectionSet projectionSets, ref Object list)
 Gets a list of ID,Name pairs of Projected and/or Geographic coordinate systems More...
 
string GetProjectionNameByID (int SRID)
 Gets the name of the projected coordinate system associated with the specified SRID, which include the NAD83 and WGS84 codes, as well as those not specified by the enumerations, such as NAD27, NAD83 Harn, Beijing, Pulkova, etc. More...
 
string GetWGS84ProjectionName (tkWgs84Projection projectionID)
 Gets the name of the projection associated with the specified WGS84 enumeration More...
 
bool GridInterpolateNoData (Grid Grd, ICallback cBack)
 Uses valid data in a grid to replace grid cells containing no-data values with an interpolated value. More...
 
Grid GridMerge (object Grids, string MergeFilename, bool InRam, GridFileType GrdFileType, ICallback cBack)
 Merges multiple grids into a single output grid. More...
 
bool GridReplace (Grid Grd, object OldValue, object newValue, ICallback cBack)
 Replaces all occurrences of a value in the grid with a new value. More...
 
bool GridStatisticsForPolygon (Grid Grid, GridHeader Header, Extents gridExtents, Shape Shape, double NodataValue, ref double MeanValue, ref double MinValue, ref double MaxValue)
 Calculates statistics for portion of grid that is overlapped by specified polygon. More...
 
bool GridStatisticsToShapefile (Grid Grid, Shapefile sf, bool SelectedOnly, bool overwriteFields, bool useCenterWithinMethod=true)
 Calculates statistics for grid cells within each polygon of the specified shapefile. Writes results to attribute table of shapefile. More...
 
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. More...
 
Image GridToImage (Grid Grid, GridColorScheme cScheme, ICallback cBack)
 Creates an image from the grid using the given grid color scheme. More...
 
Image GridToImage2 (Grid Grid, GridColorScheme ci, tkGridProxyFormat imageFormat, bool InRam, ICallback cBack)
 Creates an image proxy for grid visualization. More...
 
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. More...
 
stdole.IPictureDisp hBitmapToPicture (int hBitmap)
 Converts an hBitmap to an IPictureDisp object. More...
 
bool IsTiffGrid (string Filename)
 Returns a boolean value which indicates whether the specified file holds tiff grid. More...
 
Point LineInterpolatePoint (Shape sourceLine, Point startPoint, double distance, bool normalized)
 Return a point at the specified distance (or percentage) along the specified line More...
 
bool MaskRaster (string Filename, byte newPerBandValue)
 Sets all the values inside datasource, which aren't equal to no data value, to a new value. More...
 
bool MergeImages (Array InputNames, string OutputName)
 Merges several images in a single image. More...
 
bool OGR2OGR (string bstrSrcFilename, string bstrDstFilename, string bstrOptions, ICallback cBack=null)
 The same as GDAL's ogr2ogr utility. More...
 
string OGRInfo (string bstrSrcFilename, string bstrOptions, string bstrLayers=null, ICallback cBack=null)
 The same as GDAL's OGRInfo utility. More...
 
Shapefile OGRLayerToShapefile (string Filename, ShpfileType ShpType, ICallback cBack)
 Partially implemented. Creates a shapefile from any vector format supported by OGR library. More...
 
bool PointInPolygon (Shape Shp, Point TestPoint)
 Gets whether or not a point lies within the specified polygon shape. More...
 
bool Polygonize (string pszSrcFilename, string pszDstFilename, int iSrcBand=1, bool NoMask=false, string pszMaskFilename="0", string pszOGRFormat="GML", string pszDstLayerName="out", string pszPixValFieldName="DN", ICallback cBack=null)
 The same as GDAL's gdal_polygonize utility. More...
 
Double ProjectDistanceTo (Shape sourceLine, Shape referenceShape)
 Return a distance along the source polyline to a Point nearest the reference Shape More...
 
bool ReclassifyRaster (string Filename, int bandIndex, string OutputName, Array LowerBounds, Array UpperBounds, Array NewValues, string gdalOutputFormat, ICallback cBack)
 Creates a new datasource by mapping data ranges of the specified band of input datasource to new values. More...
 
bool RemoveColinearPoints (Shapefile Shapes, double LinearTolerance, ICallback cBack)
 Removes colinear points from a shapefile. More...
 
Shapefile ReprojectShapefile (Shapefile sf, GeoProjection source, GeoProjection target)
 Reprojects a shapefile. More...
 
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. More...
 
Shape ShapeMerge (Shapefile Shapes, int IndexOne, int IndexTwo, ICallback cBack)
 Merges two shapes in a shapefile to create a new shape. More...
 
Shapefile ShapeToShapeZ (Shapefile Shapefile, Grid Grid, ICallback cBack)
 Creates a new shapefile with z values added from an elevation grid. More...
 
GeoProjection TileProjectionToGeoProjection (tkTileProjection Projection)
 Initializes GeoProjection object with projection used by specific tile service. More...
 
Shapefile TinToShapefile (Tin Tin, ShpfileType Type, ICallback cBack)
 Creates a shapefile from a TIN object. More...
 
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. More...
 

Properties

ICallback GlobalCallback [get, set]
 The global callback is the interface used by MapWinGIS to pass progress and error events to interested applications. 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...
 

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.
Starting at v4.9.5 some specific GDAL methods are moved to GdalUtils.

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

Member Function Documentation

◆ BufferByDistance()

bool Utils.BufferByDistance ( Shapefile  subject,
double  Distance,
int  nSegments,
bool  SelectedOnly,
bool  MergeResults,
string  outputFilename,
bool  Overwrite 
)

◆ CalculateRaster()

bool Utils.CalculateRaster ( Array  filenames,
string  Expression,
string  outputFilename,
string  gdalOutputFormat,
float  NodataValue,
ICallback  cBack,
out string  ErrorMsg 
)

Creates a new raster dataset based on the array of input datasets and an arbitrary formula to calculate values of output dataset.

Parameters
filenamesArray of filenames.
ExpressionFormula to calculate.
outputFilenameName of output dataset.
gdalOutputFormatGDAL format. See list here: http://www.gdal.org/formats_list.html. Not all of them are necessarily support creation and writing operations.
NodataValueNo data value for output datasource.
cBackCallback to report progress and errors.
ErrorMsgError description to be returned when method fails.
Returns
True on success.

Input datasets must have the same size in pixels (projection and transformation parameters will be copied to output from first datasource, but won't be used during calculation process). Names of datasources in formula must match their filenames without path. Additionally @X postfix must be added to mark index of band to be used (1-based). The following operation are supported in formula: arithmetic (+, -, *, /, ^); comparisons (>, <, <=, >=, <>, =) both for raster values and scalar constants.

string[] names = { @"d:\Clip_L7_20000423_B2.tif", @"d:\Clip_L7_20000423_B5.tif" };
string formula = "[Clip_L7_20000423_B5.tif@1] + [Clip_L7_20000423_B2.tif@1] + 5"; // @1 = first band is used in both cases
string errorMsg;
var ut = new Utils();
bool result = ut.CalculateRaster(names, formula, @"d:\output.tif", "GTiff",
0f /* no data value */, this /*callback */, out errorMsg);
A utils object provides access to a set of utility functions to perform a variety of tasks on other o...
Definition: Utils.cs:20
New API 4.9.2:
Added in version 4.9.2

◆ ClipGridWithPolygon()

bool Utils.ClipGridWithPolygon ( string  inputGridfile,
Shape  poly,
string  resultGridfile,
bool  keepExtents 
)

Creates a new grid from the input one in which all values outside the specified polygon are set to no data value.

Parameters
inputGridfileFilename of input grid.
polyClipping polygon.
resultGridfileFilename of the results grid.
keepExtentsTrue in case grid must not be clipped using polygon extents.
Returns
True on success.
New API 4.9.0:
Added in version 4.9.0

◆ ClipGridWithPolygon2()

bool Utils.ClipGridWithPolygon2 ( Grid  inputGrid,
Shape  poly,
string  resultGridfile,
bool  keepExtents 
)

Creates a new grid from the input one in which all values outside the specified polygon are set to no data value.

Parameters
inputGridINput grid.
polyClipping polygon.
resultGridfileFilename of the results grid.
keepExtentsTrue in case grid must not be clipped using polygon extents.
Returns
True on success.
New API 4.9.0:
Added in version 4.9.0

◆ ClipPolygon()

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 specified polygon operation on.
ClipPolygonThe second polygon to perform the specified polygon operation with.
Returns
The polygon shape created using the specified polygon operation.

◆ ColorByName()

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, IntersectionLength.cs, LabelSelection.cs, MinimalDistance.cs, and Tracking.cs.

◆ ConvertDistance()

bool Utils.ConvertDistance ( tkUnitsOfMeasure  sourceUnit,
tkUnitsOfMeasure  targetUnit,
ref double  Value 
)

Converts distance from one units of measuring to another.

Parameters
sourceUnitSource units of measuring.
targetUnitTarget units of measuring.
ValueThe value in source units to be converted.
Returns
The value in target units.
New API 4.9.0:
Added in version 4.9.0

◆ CopyNodataValues()

bool Utils.CopyNodataValues ( string  sourceFilename,
string  destFilename 
)

Copies no data values from one grid datasource to another.

Parameters
sourceFilenameFilename of the source.
destFilenameFilename of the target.
Returns
True on success.

Datasources must have the same size, number of bands, byte data type and must both be supported by GDAL.

New API 4.9.1:
Added in version 4.9.1

◆ CreateInstance()

object Utils.CreateInstance ( tkInterface  interfaceId)

Creates an instance of specified COM CoClass implementing specified interface.

Parameters
interfaceIdInterface to be created.
Returns
Requested interface.

This method might be slightly faster than direct object creation when mass creation of objects is needed./remarks>

New API 4.9.0:
Added in version 4.9.0

◆ EPSGUnitConversion()

tkUnitsOfMeasure Utils.EPSGUnitConversion ( int  EPSGUnitCode)

Gets the tkUnitsOfMeasure enumeration associated with the specified EPSG Unit Code

Parameters
EPSGUnitCodeEPSG-defined Unit of Measure constant
Returns
The internal enumeration associated with the specified EPSG code

Supports the more common EPSG-defined Unit constants; specifically those that can be mapped to the currently defined tkUnitsOfMeasure enumeration values. If the EPSG code cannot be mapped, an Error will be submitted to the global callback with error code tkINVALID_PARAMETER_VALUE, and return the default value of umDecimalDegrees.

New API 4.9.5:
Added in version 4.9.5

◆ ErrorMsgFromObject()

string Utils.ErrorMsgFromObject ( object  comClass)

Displays error message for the last error that took place within object passed as parameter.

Parameters
comClassAny MapWinGIS COM class which has LastErrorCode and get_ErrorMsg properties.

The methods is alternative syntax of calling:

shapefile.get_ErrorMsg(shapefile.LastErrorCode);

Now it also can be done like:

utils.ErrorMsgFromObject(shapefile);
Returns
Error description.
New API 4.9.1:
Added in version 4.9.1

◆ ExplodeShapes()

bool Utils.ExplodeShapes ( Shapefile  subject,
bool  SelectedOnly,
string  outputFilename,
bool  Overwrite 
)

◆ ExportSelection()

bool Utils.ExportSelection ( Shapefile  subject,
string  outputFilename,
bool  Overwrite 
)

◆ FixUpShapes()

bool Utils.FixUpShapes ( Shapefile  subject,
bool  SelectedOnly,
string  outputFilename,
bool  Overwrite 
)

◆ GDALAddOverviews()

bool Utils.GDALAddOverviews ( string  bstrSrcFilename,
string  bstrOptions,
string  bstrLevels,
ICallback  cBack = null 
)

The same as GDAL's gdaladdo.exe utility.

See documentation here: http://www.gdal.org/gdaladdo.html

New API 4.9.0:
Added in version 4.9.0
Deprecated:
v5.1.0 Use GdalUtils.GdalBuildOverviews instead.

◆ GDALBuildVrt()

bool Utils.GDALBuildVrt ( string  bstrDstFilename,
string  bstrOptions,
ICallback  cBack = null 
)

The same as GDAL's gdalbuildvert.exe utility.

See documentation here: http://www.gdal.org/gdalbuildvert.html

New API 4.9.0:
Added in version 4.9.0

◆ GDALInfo()

string Utils.GDALInfo ( string  bstrSrcFilename,
string  bstrOptions,
ICallback  cBack = null 
)

The same as GDAL's gdalinfo.exe utility.

See documentation here: http://www.gdal.org/gdalinfo.html

New API 4.9.0:
Added in version 4.9.0

◆ GDALRasterize()

bool Utils.GDALRasterize ( string  bstrSrcFilename,
string  bstrDstFilename,
string  bstrOptions,
ICallback  cBack = null 
)

The same as GDAL's gdal_rasterize.exe utility.

See documentation here: http://www.gdal.org/gdal_rasterize.html

New API 4.9.0:
Added in version 4.9.0

◆ GDALWarp()

bool Utils.GDALWarp ( string  bstrSrcFilename,
string  bstrDstFilename,
string  bstrOptions,
ICallback  cBack = null 
)

The same as GDAL's gdalwarp.exe utility

See documentation here: http://www.gdal.org/gdalwarp.html

New API 4.9.0:
Added in version 4.9.0
Deprecated:
v4.9.5 Use GdalUtils.GdalRasterWarp instead.

◆ GenerateContour()

bool Utils.GenerateContour ( string  bstrSrcFilename,
string  bstrDstFilename,
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 documentation here: http://www.gdal.org/gdal_contour.html

◆ GenerateHillShade()

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, perry.nosp@m.geo@.nosp@m.gmail.nosp@m..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

◆ GeodesicArea()

double Utils.GeodesicArea ( Shape  shapeWgs84)

◆ GeodesicDistance()

double Utils.GeodesicDistance ( double  lat1,
double  lng1,
double  lat2,
double  lng2 
)

Calculates geodesic distance between 2 points on Earth.

Parameters
lat1Latitude of the first point in decimal degrees.
lng1Longitude of the first point in decimal degrees.
lat2Latitude of the second point in decimal degrees.
lng2Longitude of the second point in decimal degrees.
Returns
Geodesic distance between 2 points in meters.
New API 4.9.0:
Added in version 4.9.0

◆ get_Area()

double Utils.get_Area ( Shape  Shape)

Returns the area of the polygon shape. For multi-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.

◆ get_ComUsageReport()

string Utils.get_ComUsageReport ( bool  unreleasedOnly)

Gets report about COM objects that were created and released.

Parameters
unreleasedOnlyIndicates whether report must include information about already released objects.
Returns
String with report.

This method can be used to find memory leaking in MapWinGIS native code (forgotten object->Release call). The most vulnerable spots are geoprocessing functions, where thousands of Shape or Point objects may be created in a single API call. Before calling this make sure that:

  • objects are no longer referenced anywhere in your code;
  • in case of .NET, that garbage collection was performed.
    Note
    AxMap control uses several instances of COM objects (GeoProjection, Shape) as a part of normal functioning. This doesn't amount to memory leakage.
New API 4.9.2:
Added in version 4.9.2

◆ get_ErrorMsg()

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.

◆ get_Length()

double Utils.get_Length ( Shape  Shape)

Gets the length of the line shape.

Parameters
Shape
Returns

◆ get_Perimeter()

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.

◆ GetAngle()

double Utils.GetAngle ( Point  firstPoint,
Point  secondPoint 
)

Calculates the angle defined by the two specified coordinates

Parameters
firstPoint
secondPoint
Returns
Geographic Angle (in degrees) of the vector measured from the first point to the second point

The angle returned is the so-called Geographic angle, measured in a clockwise direction from the positive Y-axis, as opposed to the Arithmetic (Cartesian) angle measured in a counter-clockwise direction from the positive X-axis. The returned value can be used as-is to specify Shape or Label Rotation, which expect the Geographic angle for input.

See also
Shapefile.set_ShapeRotation
New API 5.0:
Added in version 5.0.0

◆ GetNAD83ProjectionName()

string Utils.GetNAD83ProjectionName ( tkNad83Projection  projectionID)

Gets the name of the projection associated with the specified NAD83 enumeration

Parameters
projectionIDValue from the the NAD83 projection enumeration tkNad83Projection
Returns
GDAL-provided projection name, or an empty string on error

If an error occurs, either because an invalid ID is specified, or the projection string could not be loaded, a descriptive error will be raised to the Callback function (if one is specified).

New API 4.9.5:
Added in version 4.9.5

◆ GetProjectionList()

bool Utils.GetProjectionList ( tkProjectionSet  projectionSets,
ref Object  list 
)

Gets a list of ID,Name pairs of Projected and/or Geographic coordinate systems

Parameters
projectionSetsOne or a combination of values from the tkProjectionSet enumeration
listReference to an Object that will be filled with an array of strings
Returns
True if successful (list will contain an array of strings containing the ID/Name pairs associated with the specified Projection Sets), or False on failure (list will be empty)

Each string will contain one pair of values, an ID and a Name, separated by a comma (e.g. "32611,WGS 84 / UTM zone 11N"). These can be parsed and used, for example, to populate a ComboBox control for user selection of a Projection. If an error occurs, or if the projection strings could not be loaded, a descriptive error will be raised to the Callback function (if one is specified).

New API 4.9.5:
Added in version 4.9.5

◆ GetProjectionNameByID()

string Utils.GetProjectionNameByID ( int  SRID)

Gets the name of the projected coordinate system associated with the specified SRID, which include the NAD83 and WGS84 codes, as well as those not specified by the enumerations, such as NAD27, NAD83 Harn, Beijing, Pulkova, etc.

Parameters
SRIDSpatial Reference identifier, could refer to any valid Projected or Geographic coordinate system
Returns
GDAL-provided name of a projected or geographic coordinate system, or an empty string on error

If an error occurs, either because an invalid ID is specified, or the projection string could not be loaded, a descriptive error will be raised to the Callback function (if one is specified).

New API 4.9.5:
Added in version 4.9.5

◆ GetWGS84ProjectionName()

string Utils.GetWGS84ProjectionName ( tkWgs84Projection  projectionID)

Gets the name of the projection associated with the specified WGS84 enumeration

Parameters
projectionIDValue from the the NAD83 projection enumeration tkNad83Projection
Returns
GDAL-provided projection name, or an empty string on error

If an error occurs, either because an invalid ID is specified, or the projection string could not be loaded, a descriptive error will be raised to the Callback function (if one is specified).

New API 4.9.5:
Added in version 4.9.5

◆ GridInterpolateNoData()

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.

◆ GridMerge()

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.

◆ GridReplace()

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

Replaces all occurrences 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.

◆ GridStatisticsForPolygon()

bool Utils.GridStatisticsForPolygon ( Grid  Grid,
GridHeader  Header,
Extents  gridExtents,
Shape  Shape,
double  NodataValue,
ref double  MeanValue,
ref double  MinValue,
ref double  MaxValue 
)

Calculates statistics for portion of grid that is overlapped by specified polygon.

Parameters
GridInput grid
HeaderGrid header. Can be retrieved with Grid.Header property.
gridExtentsGrid extents. Can be retrieved with Grid.Extents property.
ShapePolygon shape within borders of which the statistics will be calculated.
NodataValueNo data value for grid. Can be retrieved from header.
MeanValueCalculated mean value.
MinValueCalculated min value.
MaxValueCalculated max value
Returns
True on success.

Header, gridExtents, NodataValue parameters are added, so that these properties can be retrieved only ones in case the function is called multiple times for each polygon in shapefile.

New API 4.9.0:
Added in version 4.9.0

◆ GridStatisticsToShapefile()

bool Utils.GridStatisticsToShapefile ( Grid  Grid,
Shapefile  sf,
bool  SelectedOnly,
bool  overwriteFields,
bool  useCenterWithinMethod = true 
)

Calculates statistics for grid cells within each polygon of the specified shapefile. Writes results to attribute table of shapefile.

Parameters
GridInput grid.
sfPolygon shapefile.
SelectedOnlyA value indicating whether calculation will be made for selected polygons only. When set to false, calculation will be made for all polygons in shapefile.
overwriteFieldsIf true output fields will be overwritten (if the fields with such names already exist). Otherwise new set of output fields will be created with numerical indices added to their names.
useCenterWithinMethodIf true (default) the center of the pixel needs to be inside the polygon. If set to false Intersection method is used meaning each pixel boundary that intersects with the polygon is used. Added in v4.9.4.3.
Returns
True on success.

The default names for output fields: "Mean", "Median", "Majority", "Minority", "Minimum", "Maximum", "Range", "StD", "Sum", "MinX", "MinY", "Variety", "Count"

New API 4.9.0:
Added in version 4.9.0

◆ GridToGrid()

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

◆ GridToImage()

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

Creates 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 messages while the image is being created from the grid.
Returns
The image created from the grid.

◆ GridToImage2()

Image Utils.GridToImage2 ( Grid  Grid,
GridColorScheme  ci,
tkGridProxyFormat  imageFormat,
bool  InRam,
ICallback  cBack 
)

Creates an image proxy for grid visualization.

Parameters
GridGrid to create proxy for.
ciColor scheme which defines the mapping of values to colors.
imageFormatThe format of output image.
InRamTrue in case in-memory image should be created, otherwise it will saved to the drive.
cBackCallback interface.
Returns
Resulting image.

The filename of the resulting image (inRam = false) is set automatically: for example, grid.asc -> grid_proxy.bmp. In case of multi-band grids an image will be created for the active band, determined from Grid.ActiveBandIndex property. For bmp output format a world file will be written along with resulting file. For GTiff format the same values will be embedded in the file itself.

New API 4.9.1:
Added in version 4.9.1

◆ GridToShapefile()

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 messages while the grid is being converted to the shapefile.
Returns

◆ hBitmapToPicture()

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.

◆ IsTiffGrid()

bool Utils.IsTiffGrid ( string  Filename)

Returns a boolean value which indicates whether the specified file holds tiff grid.

Parameters
FilenameThe name of the file.
Returns
True on success and false otherwise.
New API 4.9.3:
Added in version 4.9.3 (is moved from AxMap.IsTiffGrid)

◆ LineInterpolatePoint()

Point Utils.LineInterpolatePoint ( Shape  sourceLine,
Point  startPoint,
double  distance,
bool  normalized 
)

Return a point at the specified distance (or percentage) along the specified line

Parameters
sourceLinePolyline shape to traverse
startPointStarting point along 'sourceLine' (specify Point[0] for beginning of line)
distanceDistance along line (or percentage of line length; if a percentage, specify a number between 0.0 and 1.0)
normalizedOptional value; if FALSE, 'distance' is actual distance; if TRUE, distance is percentage of length; defaults to FALSE
Returns
Returns a Point class representing the point along the sourceLine that is the specified distance (or percentage) along the line.

'sourceLine' must be a Polyline Shape. If 'distance' is greater than the source line length, the line's endpoint is returned.

'startPoint' does not have to be on 'sourceLine'. If not on the line, actual starting point will be the nearest point to 'startPoint' that is on 'sourceline'.

See also
Shape.InterpolatePoint
New API 5.0:
Added in version 5.0.0

◆ MaskRaster()

bool Utils.MaskRaster ( string  Filename,
byte  newPerBandValue 
)

Sets all the values inside datasource, which aren't equal to no data value, to a new value.

Parameters
FilenameFilename of the input datasource.
newPerBandValueThe new value set for all cells of each band which aren't equal to no data value.
Returns
True on success.

Datasource format must be supported by GDAL. Byte data type for values is expected.

New API 4.9.0:
Added in version 4.9.0

◆ MergeImages()

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 MapWinGIS;
namespace Examples
{
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");
}
}
}
}
}
}
bool MergeImages(Array InputNames, string OutputName)
Merges several images in a single image.
Definition: Utils.cs:169
New API 4.8:
Added in version 4.8

◆ OGR2OGR()

bool Utils.OGR2OGR ( string  bstrSrcFilename,
string  bstrDstFilename,
string  bstrOptions,
ICallback  cBack = null 
)

The same as GDAL's ogr2ogr utility.

See documentation here: http://www.gdal.org/ogr2ogr.html

New API 4.9.0:
Added in version 4.9.0
Deprecated:
v4.9.5 Use GdalUtils.GdalVectorTranslate instead.

◆ OGRInfo()

string Utils.OGRInfo ( string  bstrSrcFilename,
string  bstrOptions,
string  bstrLayers = null,
ICallback  cBack = null 
)

The same as GDAL's OGRInfo utility.

See documentation here: http://www.gdal.org/ogrinfo.html

New API 4.9.0:
Added in version 4.9.0

◆ OGRLayerToShapefile()

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

◆ PointInPolygon()

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.

◆ Polygonize()

bool Utils.Polygonize ( string  pszSrcFilename,
string  pszDstFilename,
int  iSrcBand = 1,
bool  NoMask = false,
string  pszMaskFilename = "0",
string  pszOGRFormat = "GML",
string  pszDstLayerName = "out",
string  pszPixValFieldName = "DN",
ICallback  cBack = null 
)

The same as GDAL's gdal_polygonize utility.

See documentation here: http://www.gdal.org/gdal_polygonize.html

New API 4.9.0:
Added in version 4.9.0

◆ ProjectDistanceTo()

Double Utils.ProjectDistanceTo ( Shape  sourceLine,
Shape  referenceShape 
)

Return a distance along the source polyline to a Point nearest the reference Shape

Parameters
sourceLineSource Shape, must be a polyline
referenceShapeAnother Shape of any Shapetype
Returns
Returns the distance along sourceline to the point nearest the specified referenceShape.

sourceLine must be a Polyline Shape. Returned Distance is measured from Point[0]. If resulting 'distance' would be greater than the length of sourceLine, then sourceLine's length is returned.

See also
Shape.ProjectDistanceTo
New API 5.0:
Added in version 5.0.0

◆ ReclassifyRaster()

bool Utils.ReclassifyRaster ( string  Filename,
int  bandIndex,
string  OutputName,
Array  LowerBounds,
Array  UpperBounds,
Array  NewValues,
string  gdalOutputFormat,
ICallback  cBack 
)

Creates a new datasource by mapping data ranges of the specified band of input datasource to new values.

Parameters
FilenameFilename of input GDAL raster datasource.
bandIndexBand index of input datasource to be processed.
OutputNameFilename of output datasource.
LowerBoundsArray of double type with lower bounds of mapping ranges. These values will be compared with values of input datasource. Must be sorted in ascending order.
UpperBoundsArray of double type with upper bounds of mapping ranges. These values will be compared with values of input datasource.
NewValuesArray of double type with values to be set for output datasource for each mapping range.
gdalOutputFormatGDAL format. See list here: http://www.gdal.org/formats_list.html. Not all of them are necessarily support creation and writing operations.
cBackCallback to report progress and errors.
Returns
True on success.

All 3 input arrays must be of the same size. In case of overlapping ranges the one located first will be used. Here is code sample with 5 data ranges using anonymous data type:

var ut = new Utils();
var arr = new[]
{
new {Low = 0.0, High = 20.0, NewValue = 40.0},
new {Low = 20.0, High = 40.0, NewValue = 150.0},
new {Low = 40.0, High = 60.0, NewValue = 100.0},
new {Low = 60.0, High = 80.0, NewValue = 20.0},
new {Low = 80.0, High = 100.0, NewValue = 80.0},
};
if (!ut.ReclassifyRaster(@"d:\source.tiff", 1 /* band index */,
@"d:\output.tif",
arr.Select(i => i.Low).ToArray(),
arr.Select(i => i.High).ToArray(),
arr.Select(i => i.NewValue).ToArray(),
"GTiff", this /* callback */))
{
MessageBox.Show("Failed to reclassify: " + ut.get_ErrorMsg(ut.LastErrorCode));
}
else
{
MessageBox.Show("Reclassified successfully");
}
New API 4.9.2:
Added in version 4.9.2

◆ RemoveColinearPoints()

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 unnecessary 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 messages while colinear points are being removed.
Returns
A boolean value representing the success or failure of removing colinear points from the shapefile.

◆ ReprojectShapefile()

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

Reprojects 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

◆ ShapefileToGrid()

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.

◆ ShapeMerge()

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 messages while the shapes are being merged.
Returns
The resulting shape.

◆ ShapeToShapeZ()

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 messages while z values are being added to the shapefile.
Returns
The new shapefile containing z values obtained from the elevation grid.

◆ TileProjectionToGeoProjection()

GeoProjection Utils.TileProjectionToGeoProjection ( tkTileProjection  Projection)

Initializes GeoProjection object with projection used by specific tile service.

Parameters
ProjectionProjection used by tile service.
Returns
GeoProjection object or null if operation failed.
New API 4.9.1:
Added in version 4.9.1

◆ TinToShapefile()

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 messages while shapefile is being created from the TIN.
Returns
The new shapefile created from the TIN.

◆ TranslateRaster()

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 appropriate 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.
Deprecated:
v5.1.0 Use GdalUtils.GdalRasterTranslate instead.

Property Documentation

◆ GlobalCallback

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

◆ Key

string Utils.Key
getset

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

◆ LastErrorCode

int Utils.LastErrorCode
get

Retrieves the last error generated in the object.