GeoProjection Class Reference

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

Collaboration diagram for GeoProjection:
Collaboration graph

Public Member Functions

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

Properties

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

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:

  • ESRI WKT string;
  • proj 4 string;
  • EPSG code;

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.

// 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:
  • the reference ellipsoid (GRS80, Krasovski, etc.);
  • the name of datum, which defines coordinate system relative to the surface of ellipsoid (WGS84, NAD83, Pulkovo1942, etc.);
  • optionally projection, if the data isn't defined in decimal degrees (UTM, Gauss-Kruger, etc).


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

◆ Clear()

bool GeoProjection.Clear ( )

Returns object to initial empty state.

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

◆ Clone()

GeoProjection GeoProjection.Clone ( )

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.

◆ CopyFrom()

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.

◆ ExportToEsri()

string GeoProjection.ExportToEsri ( )

Exports projection string to ESRI WKT format.

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

◆ ExportToProj4()

string GeoProjection.ExportToProj4 ( )

Exports information to the proj4 format.

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

◆ ExportToWKT()

string GeoProjection.ExportToWKT ( )

Exports information to the WKT format.

Returns
The string with WKT projection.
Examples:
TrackCars.cs.

◆ get_ErrorMsg()

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.

◆ get_GeogCSParam()

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.

◆ get_IsSame()

bool GeoProjection.get_IsSame ( GeoProjection  proj)

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.

◆ get_IsSameExt()

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.

◆ get_IsSameGeogCS()

bool GeoProjection.get_IsSameGeogCS ( GeoProjection  proj)

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.

◆ get_ProjectionParam()

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.

◆ ImportFromAutoDetect()

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.

◆ ImportFromEPSG()

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.

◆ ImportFromESRI()

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.

◆ ImportFromProj4()

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.

◆ ImportFromWKT()

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.

◆ ReadFromFile()

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.

◆ ReadFromFileEx()

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

◆ SetGoogleMercator()

bool GeoProjection.SetGoogleMercator ( )

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

◆ SetNad83Projection()

void GeoProjection.SetNad83Projection ( tkNad83Projection  Projection)

Initializes the object with NAD83 projection specified by enumerated constant.

Parameters
ProjectionNumeric code of the projection (EPSG code).

◆ SetWellKnownGeogCS()

void GeoProjection.SetWellKnownGeogCS ( tkCoordinateSystem  newVal)

Initializes the object with well known geographic coordinate system.

Parameters
newValNumeric code of the projection (EPSG code).

◆ SetWgs84()

bool GeoProjection.SetWgs84 ( )

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

◆ SetWgs84Projection()

void GeoProjection.SetWgs84Projection ( tkWgs84Projection  Projection)

Initializes the object with WGS84 projection specified by enumerated constant.

Parameters
ProjectionNumeric code of the projection (EPSG code).

◆ StartTransform()

bool GeoProjection.StartTransform ( GeoProjection  target)

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.

◆ StopTransform()

void GeoProjection.StopTransform ( )

Stops transformation created by GeoProjection.StartTransform call.

◆ Transform()

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.

◆ TryAutoDetectEpsg()

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

◆ WriteToFile()

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.

◆ WriteToFileEx()

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

◆ GeogCSName

string GeoProjection.GeogCSName
get

Returns the name of the coordinate system.

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

◆ GlobalCallback

ICallback GeoProjection.GlobalCallback
getset

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

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.

◆ HasTransformation

bool GeoProjection.HasTransformation
get

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

◆ InverseFlattening

double GeoProjection.InverseFlattening
get

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

◆ IsEmpty

bool GeoProjection.IsEmpty
get

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

◆ IsFrozen

bool GeoProjection.IsFrozen
get

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

◆ IsGeographic

bool GeoProjection.IsGeographic
get

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

◆ IsLocal

bool GeoProjection.IsLocal
get

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

◆ IsProjected

bool GeoProjection.IsProjected
get

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

◆ Key

string GeoProjection.Key
getset

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

◆ LastErrorCode

int GeoProjection.LastErrorCode
get

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

The usage of this property clears the error code.

◆ LinearUnits

tkUnitsOfMeasure GeoProjection.LinearUnits
get

Gets the linear units from projection definition.

◆ Name

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.

◆ ProjectionName

string GeoProjection.ProjectionName
get

The name of the projected coordinate system.

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

◆ SemiMajor

double GeoProjection.SemiMajor
get

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

◆ SemiMinor

double GeoProjection.SemiMinor
get

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