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

Collaboration diagram for GeoProjection:

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.

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:

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;
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:

proj4:
- geographic WGS84: +proj=longlat +datum=WGS84 +no_defs
- WGS84/UTM 10: +proj=utm +zone=10 +datum=WGS84 +units=m +no_defs
EPSG code:
- geographic: 4326
- WGS84/UTM 10: 32610
ESRI WKT WGS84:

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

sourceProj The 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

ErrorCode The 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

Name	The parameter to return.
pVal	The 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

proj	The 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

proj	The compared projection definition.
bounds	The bounding box to take random points for comparison from.
numSamplingPoints	Number 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

proj	The 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

Name	The parameter to return.
Value	The 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

proj	The 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

projCode EPSG 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

proj	The 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

proj	The 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

proj	The 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

Filename The 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

Filename	The filename.
esri	If 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

Projection Numeric code of the projection (EPSG code).

◆ SetWellKnownGeogCS()

void GeoProjection.SetWellKnownGeogCS ( tkCoordinateSystem newVal )

Initializes the object with well known geographic coordinate system.

Parameters

newVal Numeric 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

Projection Numeric 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

target The 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

x	X coordinate of point to transform.
y	Y 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

epsgCode Determined 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

Filename The 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

Filename	The filename.
esri	If 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.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ Clear()

◆ Clone()

◆ CopyFrom()

◆ ExportToEsri()

◆ ExportToProj4()

◆ ExportToWKT()

◆ get_ErrorMsg()

◆ get_GeogCSParam()

◆ get_IsSame()

◆ get_IsSameExt()

◆ get_IsSameGeogCS()

◆ get_ProjectionParam()

◆ ImportFromAutoDetect()

◆ ImportFromEPSG()

◆ ImportFromESRI()

◆ ImportFromProj4()

◆ ImportFromWKT()

◆ ReadFromFile()

◆ ReadFromFileEx()

◆ SetGoogleMercator()

◆ SetNad83Projection()

◆ SetWellKnownGeogCS()

◆ SetWgs84()

◆ SetWgs84Projection()

◆ StartTransform()

◆ StopTransform()

◆ Transform()

◆ TryAutoDetectEpsg()

◆ WriteToFile()

◆ WriteToFileEx()

Property Documentation

◆ GeogCSName

◆ GlobalCallback

◆ HasTransformation

◆ InverseFlattening

◆ IsEmpty

◆ IsFrozen

◆ IsGeographic

◆ IsLocal

◆ IsProjected

◆ Key

◆ LastErrorCode

◆ LinearUnits

◆ Name

◆ ProjectionName

◆ SemiMajor

◆ SemiMinor