Public Member Functions | Properties
GeoProjection Class Reference

Holds information about coordinate system and projection of the data. More...

List of all members.

Public Member Functions

bool Clear ()
 Returns object to initial empty state.
GeoProjection Clone ()
 Creates a copy GeoProjection object.
bool CopyFrom (GeoProjection sourceProj)
 Copies information from another GeoProjection object.
string ExportToEsri ()
 Exports projection string to ESRI WKT format.
string ExportToProj4 ()
 Exports information to the proj4 format.
string ExportToWKT ()
 Exports information to the WKT format.
string get_ErrorMsg (int ErrorCode)
 Gets the description of the specific error code.
bool get_GeogCSParam (tkGeogCSParameter Name, ref double pVal)
 Gets specified parameter of the geographic coordinate system.
bool get_IsSame (GeoProjection proj)
 Returns a boolean value which indicates whether 2 projections are identical.
bool get_IsSameExt (GeoProjection proj, Extents bounds, int numSamplingPoints)
 Performs a test of identity for 2 projections.
bool get_IsSameGeogCS (GeoProjection proj)
 Returns a boolean value which indicates whether 2 projections belong to the same geographic coordinate system.
bool get_ProjectionParam (tkProjectionParameter Name, ref double Value)
 Returns specified parameter of the projection.
bool ImportFromAutoDetect (string proj)
 Initializes geoprojection from the input string of arbitrary format.
bool ImportFromEPSG (int projCode)
 Initializes geoprojection object from EPSG numeric code.
bool ImportFromESRI (string proj)
 Initializes geoprojection object from ESRI WKT format.
bool ImportFromProj4 (string proj)
 Initializes geoprojection object from proj4 format.
bool ImportFromWKT (string proj)
 Initializes geoprojection object from OGC WKT format.
bool ReadFromFile (string Filename)
 Initializes geoprojection from the specified file.
bool ReadFromFileEx (string Filename, bool esri)
 Reads projection string from a file.
bool SetGoogleMercator ()
 Sets so called Google Mercator projection (aka Spherical Mercator; EPSG:3857), commonly used by tile servers.
void SetNad83Projection (tkNad83Projection Projection)
 Initializes the object with NAD83 projection specified by enumerated constant.
void SetWellKnownGeogCS (tkCoordinateSystem newVal)
 Initializes the object with well known geographic coordinate system.
bool SetWgs84 ()
 Sets WGS84 geographic coordinates system (EPSG:4326).
void SetWgs84Projection (tkWgs84Projection Projection)
 Initializes the object with WGS84 projection specified by enumerated constant.
bool StartTransform (GeoProjection target)
 Opens transformation to the specified target projection. The transformation will be used by GeoProjection. Transform calls until GeoProjection.StopTransform is called.
void StopTransform ()
 Stops transformation created by GeoProjection.StartTransform call.
bool Transform (ref double x, ref double y)
 Transforms a single point from this projection to target projection specified in GeoProjection.StartTransform call.
bool TryAutoDetectEpsg (out int epsgCode)
 Tries to determine EPSG code projection currently stored in the object.
bool WriteToFile (string Filename)
 Writes projection string in ESRI WKT format to the specified file.
bool WriteToFileEx (string Filename, bool esri)
 Writes projection string to a file.

Properties

string GeogCSName [get]
 Returns the name of the coordinate system.
ICallback GlobalCallback [get, set]
 Gets or sets a callback object which is used to report errors.
bool HasTransformation [get]
 Gets a value indicating whether transformation to some target projection was opened with GeoProjection.StartTransform() call.
double InverseFlattening [get]
 Returns the inverse flattening of the reference ellipsoid of the coordinate system.
bool IsEmpty [get]
 Gets a boolean value which indicates whether any projection definition is stored in the object.
bool IsFrozen [get]
 Gets a value indicating whether the object can be changed.
bool IsGeographic [get]
 Gets a boolean value which indicates whether the coordinate system stored in the object is the geographic one.
bool IsLocal [get]
 Gets a boolean value which indicates whether the coordinate system stored in the object is the local one.
bool IsProjected [get]
 Gets a boolean value which indicates whether the coordinate system stored in the object is the projected one.
string Key [get, set]
 A text string associated with the instance of the class. Any value can be stored by developer in this property.
int LastErrorCode [get]
 Retrieves the numeric code of the last error that took place in the class.
tkUnitsOfMeasure LinearUnits [get, set]
 Gets the linear units from projection definition.
string Name [get]
 Returns the name of the coordinate system.
string ProjectionName [get]
 The name of the projected coordinate system.
double SemiMajor [get]
 Returns the half of the major axis of the reference ellipsoid.
double SemiMinor [get]
 Returns the half of the minor axis of the reference ellipsoid.

Detailed Description

Holds information about coordinate system and projection of the data.

1. Formats and initialization. Information about coordinate system and projection can be represented in several formats:

EPSG codes represent a standardization effort to map each projection to the unique code. It's recommended to use these codes whenever possible. GeoProjection.ImportFromAutoDetect() method implements logic to discern the format of the provided projection string.

 GeoProjection proj = new GeoProjection(); 
 // EPSG code
 proj.ImportFromEPSG(4326);  // WGS84
     
 // proj 4 string
 proj.ImportFromProj4("+proj=longlat +datum=WGS84 +no_defs");  // WGS84
 
 //autodetect the format
 string unknown_format = "4326";
 proj.ImportFromAutoDetect(unknown_format);
 
 // from file
 string filename = "some_name";
 proj.ReadFromFile(filename);
 
 // show the name of the loaded projection
 Debug.Print("Projection loaded: " + proj.Name);
 
 // show proj 4 representation
 Debug.Print("Proj4 representation: " + proj.ExportToProj4());

Projection is usually stored in a separate file with .prj extension which accompany the data file. GeoProjection.ReadFromFile() and GeoProjection.WriteToFile() to interact with projection file.

2. Classification and parameters. Coordinate systems are split in 2 broad categories:

  1. Geographical:
    • the data is specified in decimal degrees as a pair of latitude and longitude value;
    • it implies the usage of equirectangular projection for displaying the data on the screen;
  2. Projected:
    • the Earth surface data is projected to the plane according to specific rule (projection);
    • a number of projections can be used (Mercator, Transverse Mercator, Lambert conformal conic, etc), each of the them characterized with certain distortions and certain properties of the data which are preserved (like angles, directions, area, etc.);
    • usually the data is specified in meters or feet;
    Normally spatial reference holds the information about:


Use GeoProjection.IsGeographic, GeoProjection.IsProjected properties to distinguish geographical and projected coordinate systems. To retrieve parameters of geographic coordinate system - GeoProjection.get_GeogCSParam. To extract parameters of the projection use GeoProjection.get_ProjectionParam.

3. Well-known coordinate systems. The most widely spread geographic coordinate system is so called WGS84. It is based on WGS84 datum and uses GRS80 ellipsoid. Universal Transverse Mercator is the most widely used projection of this coordinate system, which defines sixty 6-degree zones which cover the whole globe. There are several methods to setup the widely used coordinate systems and projections: GeoProjection.SetWellKnownGeogCS(), GeoProjection.SetWgs84Projection(), GeoProjection.SetNad83Projection().

The definition of WGS84 coordinate system and projection in different formats can be as following:

  1. proj4:
    • geographic WGS84: +proj=longlat +datum=WGS84 +no_defs
    • WGS84/UTM 10: +proj=utm +zone=10 +datum=WGS84 +units=m +no_defs
  2. EPSG code:
    • geographic: 4326
    • WGS84/UTM 10: 32610
  3. ESRI WKT WGS84:
    wgs.png
    See http://spatialreference.org/ for specification of coordinate systems and projections.

    4. Standardization issues. Because of the lack of standardization it's not guaranteed that subsequent exporting and importing operations for the certain projection format (proj4, WKT, etc.) will yield the same state of the geoprojection object. Therefore it's no guaranteed way to copy the state of the object unless knowing the way it was initialized.

    The different variants for specification of the same projection even in the same format became quite a problem for GIS software. GeoProjection.get_IsSame and GeoProjection.get_IsSameExt perform the comparison of 2 projections. The task is critical when one need to determine whether the data from several sources will be displayed correctly on the screen.
New API 4.8:
Added in version 4.8
Examples:
GeoProjection.cs, and Segmentation.cs.

Member Function Documentation

Returns object to initial empty state.

See also:
GeoProjection.IsFrozen
New API 4.9.1:
Added in version 4.9.1

Creates a copy GeoProjection object.

Returns:
A copy of GeoProjection object.

It's not guaranteed that exact clone will be created. The method uses GeoProjection.ExportFromWKT and GeoProjection.ImportFromWKT pair of methods which may yield slightly different result, as ExportToWKT may add defaults for parameters missing in initial Proj4 definition.

New API 4.9.1:
Added in version 4.9.1
Examples:
ShapefileToDrawingLayer.cs.
bool GeoProjection.CopyFrom ( GeoProjection  sourceProj)

Copies information from another GeoProjection object.

Parameters:
sourceProjThe geoprojection to copy information from.
Returns:
True on success and false otherwise.
Examples:
Segmentation.cs.

Exports projection string to ESRI WKT format.

Returns:
Resulting string.
New API 4.9.4:
Added in version 4.9.4

Exports information to the proj4 format.

Returns:
The string with proj4 projection.
Examples:
GeoProjection.cs.

Exports information to the WKT format.

Returns:
The string with WKT projection.
Examples:
TrackCars.cs.
string GeoProjection.get_ErrorMsg ( int  ErrorCode)

Gets the description of the specific error code.

Parameters:
ErrorCodeThe error code returned by ShapefileCategories.LastErrorCode.
Returns:
The string with the description.
bool GeoProjection.get_GeogCSParam ( tkGeogCSParameter  Name,
ref double  pVal 
)

Gets specified parameter of the geographic coordinate system.

Parameters:
NameThe parameter to return.
pValThe returned value of the parameter.
Returns:
True on success and false otherwise.
 GeoProjection proj = some_proj;
 
 // shows well-known text representation
 Debug.Print("WKT representation: " + proj.ExportToWKT());
 // the output: WKT representation: GEOGCS["WGS 84",DATUM["WGS_1984"...
 
 // let's show the properties of the geographic projection
 string s = "";
 double[] arr = new double[5];
 for (int i = 0; i < 5; i++)
 {
     // extract parameter in the element of array
     proj.get_GeogCSParam((tkGeogCSParameter)i, ref arr[i]);
    
     // append the name of parameter and the value to the string
     s += ((tkGeogCSParameter)i).ToString() + ": " + arr[i] + Environment.NewLine;
 }
 Debug.Print("Parameters of geographic coordinate system: " + Environment.NewLine + s);
 // The output: 
 // SemiMajor: 6356752,31424518
 // SemiMinor: 6356752,31424518
 // InverseFlattening: 298,257223563
 // PrimeMeridian: 0
 // AngularUnit: 0,0174532925199433
Examples:
GeoProjection.cs.

Returns a boolean value which indicates whether 2 projections are identical.

Projections will be reported as non-identical if at least one of parameters differ between them, even if it doesn't affect the reprojection process. For example, different name of the datums, while all the parameters of the datums match.

Parameters:
projThe projection object to compare the current projection with.
Returns:
True in case the projection definitions are identical and false otherwise.
bool GeoProjection.get_IsSameExt ( GeoProjection  proj,
Extents  bounds,
int  numSamplingPoints 
)

Performs a test of identity for 2 projections.

The method perform reprojection of the random points in the given extents to WGS84 coordinate system (EPSG:4326) for both projections being compared. In case the coordinates of the projected points match - projections are considered the same. This doesn't mean that result of test will be the same for some other extents or that projection definitions are completely identical. But it ensures that data layers with these 2 projection can be displayed jointly within the tested extents.

Parameters:
projThe compared projection definition.
boundsThe bounding box to take random points for comparison from.
numSamplingPointsNumber of the random points to take for sampling.
Returns:
True in case the projections proved to be identical and false otherwise.

Returns a boolean value which indicates whether 2 projections belong to the same geographic coordinate system.

Parameters:
projThe compared projection definition.
Returns:
True in case projection share the same geographic coordinate system and false otherwise.
bool GeoProjection.get_ProjectionParam ( tkProjectionParameter  Name,
ref double  Value 
)

Returns specified parameter of the projection.

Parameters:
NameThe parameter to return.
ValueThe returned value of the parameter.
Returns:
True on success and false otherwise.
bool GeoProjection.ImportFromAutoDetect ( string  proj)

Initializes geoprojection from the input string of arbitrary format.

See GDAL documentation on particular formats supported.

Parameters:
projThe string to initialize projection from.
Returns:
True on success and false otherwise.
Examples:
GeoProjection.cs.
bool GeoProjection.ImportFromEPSG ( int  projCode)

Initializes geoprojection object from EPSG numeric code.

Parameters:
projCodeEPSG code.
Returns:
True on success and false otherwise.
Examples:
GeoProjection.cs.
bool GeoProjection.ImportFromESRI ( string  proj)

Initializes geoprojection object from ESRI WKT format.

Parameters:
projThe string in the ESRI WKT format.
Returns:
True on success and false otherwise.
bool GeoProjection.ImportFromProj4 ( string  proj)

Initializes geoprojection object from proj4 format.

Parameters:
projThe string in the proj4 format.
Returns:
True on success and false otherwise.
Examples:
GeoProjection.cs.
bool GeoProjection.ImportFromWKT ( string  proj)

Initializes geoprojection object from OGC WKT format.

Parameters:
projThe string in the OGC WKT format.
Returns:
True on success and false otherwise.
bool GeoProjection.ReadFromFile ( string  Filename)

Initializes geoprojection from the specified file.

The method is used by MapWinGIS for reading projection of the data layer. The file with projection must have the same name as the name of the data file and .prj extension.

Parameters:
FilenameThe name of the file to read projection string from.
Returns:
True on success and false otherwise.
Examples:
GeoProjection.cs.
bool GeoProjection.ReadFromFileEx ( string  Filename,
bool  esri 
)

Reads projection string from a file.

Parameters:
FilenameThe filename.
esriIf set to true ESRI WKT format is used.
Returns:
True on success.
New API 4.9.4:
Added in version 4.9.4

Sets so called Google Mercator projection (aka Spherical Mercator; EPSG:3857), commonly used by tile servers.

Returns:
True on success.
New API 4.9.0:
Added in version 4.9.0

Initializes the object with NAD83 projection specified by enumerated constant.

Parameters:
ProjectionNumeric code of the projection (EPSG code).

Initializes the object with well known geographic coordinate system.

Parameters:
newValNumeric code of the projection (EPSG code).

Sets WGS84 geographic coordinates system (EPSG:4326).

Equirectangular projection will be implicitly used during rendering.

Returns:
True on success.
New API 4.9.1:
Added in version 4.9.1

Initializes the object with WGS84 projection specified by enumerated constant.

Parameters:
ProjectionNumeric code of the projection (EPSG code).

Opens transformation to the specified target projection. The transformation will be used by GeoProjection. Transform calls until GeoProjection.StopTransform is called.

Parameters:
targetThe target projection.
Returns:
True if transformation is created and false on failure.

Stops transformation created by GeoProjection.StartTransform call.

bool GeoProjection.Transform ( ref double  x,
ref double  y 
)

Transforms a single point from this projection to target projection specified in GeoProjection.StartTransform call.

Parameters:
xX coordinate of point to transform.
yY coordinate of point to transform.
Returns:
True on success.
bool GeoProjection.TryAutoDetectEpsg ( out int  epsgCode)

Tries to determine EPSG code projection currently stored in the object.

Parameters:
epsgCodeDetermined epsgCode or -1 on failure.

It uses GDAL's OGRSpatialReference.AutoIdentifyEPSG method and recognized limited number of commonly used coordinate systems (WGS84, NAD83, etc) and their zonal projections, plus information stored in Authority node for WKT format will be used as well.

Returns:
True on success.
New API 4.9.1:
Added in version 4.9.1
bool GeoProjection.WriteToFile ( string  Filename)

Writes projection string in ESRI WKT format to the specified file.

Parameters:
FilenameThe name of the file to write the string in.
Returns:
True on success and false otherwise.
bool GeoProjection.WriteToFileEx ( string  Filename,
bool  esri 
)

Writes projection string to a file.

Parameters:
FilenameThe filename.
esriIf set to true ESRI WKT format is used.
Returns:
True on success.
New API 4.9.4:
Added in version 4.9.4

Property Documentation

Returns the name of the coordinate system.

An empty string will be returned unless GeoProjection.IsGeographic property returns true.

Gets or sets a callback object which is used to report errors.

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.

Gets a value indicating whether transformation to some target projection was opened with GeoProjection.StartTransform() call.

Returns the inverse flattening of the reference ellipsoid of the coordinate system.

Gets a boolean value which indicates whether any projection definition is stored in the object.

Gets a value indicating whether the object can be changed.

When frozen all the methods which can change the inner state of object will fail. The property is set to true for map projection applied with AxMap.SetGeoProjection (see details there).

New API 4.9.1:
Added in version 4.9.1

Gets a boolean value which indicates whether the coordinate system stored in the object is the geographic one.

Gets a boolean value which indicates whether the coordinate system stored in the object is the local one.

Gets a boolean value which indicates whether the coordinate system stored in the object is the projected one.

string GeoProjection.Key [get, set]

A text string associated with the instance of the class. Any value can be stored by developer in this property.

Retrieves the numeric code of the last error that took place in the class.

The usage of this property clears the error code.

Gets the linear units from projection definition.

string GeoProjection.Name [get]

Returns the name of the coordinate system.

Either GeoProjection.GeogCSName or GeoProjection.ProjectionName will be returned depending on the type of coordinate system.

Examples:
GeoProjection.cs.

The name of the projected coordinate system.

An empty string will be returned unless GeoProjection.IsProjected property returns true.

Returns the half of the major axis of the reference ellipsoid.

Returns the half of the minor axis of the reference ellipsoid.

 All Classes Files Functions Enumerations Properties Events