Functions | Properties
Map projection and coordinates
Map modules

Functions

bool AxMap.DegreesToPixel (double degreesLngX, double degreesLatY, ref double pixelX, ref double pixelY)
 Converts pixel coordinates to decimal degrees (map projection must be specified for this method to work).
bool AxMap.DegreesToProj (double degreesLngX, double degreesLatY, ref double projX, ref double projY)
 Converts coordinates in decimal degrees to projected map coordinates (map projection must be specified for this method to work).
double AxMap.GeodesicArea (Shape polygon)
 Calculates area of polygon taking into account the shape of Earth.
double AxMap.GeodesicDistance (double projX1, double projY1, double projX2, double projY2)
 Calculates geodesic distance between 2 points defined in map coordinate system.
double AxMap.GeodesicLength (Shape polyline)
 Calculates length of polyline or perimeter of polygon taking into account the shape of Earth.
bool AxMap.PixelToDegrees (double pixelX, double pixelY, ref double degreesLngX, ref double degreesLatY)
 Converts coordinates in decimal degrees to pixel coordinates (map projection must be specified for this method to work).
void AxMap.PixelToProj (double pixelX, double pixelY, ref double projX, ref double projY)
 Converts pixel coordinates to projected map coordinates.
bool AxMap.ProjToDegrees (double projX, double projY, ref double degreesLngX, ref double degreesLatY)
 Converts projected map coordinates to decimal degrees (map projection must be specified for this method to work).
void AxMap.ProjToPixel (double projX, double projY, ref double pixelX, ref double pixelY)
 Converts projected map coordinates into screen pixel units.

Properties

GeoProjection AxMap.GeoProjection [get, set]
 Gets or sets projection for map.
bool AxMap.GrabProjectionFromData [get, set]
 Gets or sets a value indicating whether projection for will be taken from the first datasource added to it.
MapWinGIS.tkUnitsOfMeasure AxMap.MapUnits [get, set]
 Gets or sets the units of measure for the map.
Measuring AxMap.Measuring [get]
 Gets measuring object associated with map.
double AxMap.PixelsPerDegree [get, set]
 Gets the number of screen pixels per the decimal degree of the data.
tkMapProjection AxMap.Projection [get, set]
 Sets projection of the map. It providers 2 most commonly used coordinate system/projections to be easily set from Form Designer. To set other projections initialize GeoProjection object manually and use AxMap.GeoProjection property.
tkScalebarUnits AxMap.ScalebarUnits [get, set]
 Gets or sets units to be displayed for map scalebar.
bool AxMap.ScalebarVisible [get, set]
 Gets or sets a value which indicate whether scalebar will be displayed on the map.
tkCoordinatesDisplay AxMap.ShowCoordinates [get, set]
 Gets or sets a value indicating whether coordinates of the current mouse position will be displayed on map.

Detailed Description

Here is list of properties and methods which are related to coordinate system, projection of map and units conversion. This module is a part of the documentation of AxMap class.

dot_inline_dotgraph_10.png

Graph description

A. Setting projection for the map.

No matter what type of GIS application you are going to write, the decision about map coordinate system and projection is one of the first to be made. MapWinGIS provides the following options.

dot_inline_dotgraph_11.png

Let's consider each of the approaches.

1. Settings projection manually.

It can be done using one of the following approaches:

a) AxMap.Projection property - provides only most common projections (Spherical Mercator, WGS84) but available in Properties Window of Form designer.

 axMap1.Projection = tkMapProjection.PROJECTION_WGS84;

b) For all other projections - GeoProjection class and AxMap.GeoProjection property:

 var gp = new GeoProjection();

 // one of the following methods can be used; see more in GeoProjection class
 // - use projections provided by MapWinGIS enumerations:
 gp.SetWgs84Projection(tkWgs84Projection.Wgs84_UTM_zone_22N);    
 gp.SetWellKnownGeogCS(tkCoordinateSystem.csNAD83);

 // - EPSG code of coordinate system; in this example Pulkovo 1942(83) / 3-degree Gauss-Kruger zone 5; see wwww.spatialreference.org for EPSG codes
 gp.ImportFromEPSG(2399);                                        

 // - importing from proj4 or WKT string; in this example proj4 string for Amersfoort / RD New projection for Netherlands
 gp.ImportFromAutoDetect("+proj=sterea +lat_0=52.15616055555555 +lon_0=5.38763888888889 +k=0.9999079 +x_0=155000 +y_0=463000 +ellps=bessel +units=m +no_defs ");

 // applying projection
 axMap1.GeoProjection = gp;

2. Grabbing coordinate system and projection from data.

 axMap1.GrabProjectionFromData = true;   // default value
 axMap1.AddLayerFromFilename(@"d:\some_shapefile.shp", tkFileOpenStrategy.fosVectorLayer, true);

GeoProjection will be taken from the first layer added to the map which has metadata about projection. AxMap.GeoProjection property will be updated from this metadata. When last layer is removed from map AxMap.GeoProjection property will be cleared (set to empty projection).

3. Don't specify coordinate system at all.

To setup map to work without geoprojection use the code:

 axMap1.Projection = tkMapProjection.PROJECTION_NONE;
 axMap1.GrabProjectionFromData = false;
 axMap1.MapUnits = tkUnitsOfMeasure.umMeters;    // or another, depending on the data you display

B. Interaction with already set projection

To check that map actually has a projection:

 Debug.WriteLine("Map has projection:" + (axMap1.Projection != tkMapProjection.PROJECTION_NONE));
 // or with mode details
 Debug.WriteLine("Projection of the map: " + (axMap1.GeoProjection.IsEmpty() ? "None" : axMap1.GeoProjection.ExportToWKT());

Another way to check whether map has geoprojection is to see how coordinates are displayed when AxMap.ShowCoordinates is set to cdmAuto. In case decimal degrees are displayed (Lat/Lng) - map has geoprojection, if x/y pair is shown - no geoprojection was set.

All of these methods will result in updating AxMap.GeoProjection property. GeoProjection object assigned to map is protected from changes, i.e. GeoProjection.IsFrozen = true. To change already assigned projection, a new instance of GeoProjection object must be created:

 // this one will fail, because projection is frozen
 if (!axMap1.GeoProjection.ImportFromEPSG(2399))
 {
          Debug.WriteLine("Projection wasn't set: " + axMap1.GeoProjection.get_ErrorMsg(axMap1.GeoProjection.LastErrorCode));
 }
 // this one will succeed as a new GeoProjection instance is created by Clone method:
 var gp = axMap1.GeoProjection.Clone();
 if (gp.ImportFromEPSG(2399))
 {
          axMap1.GeoProjection = gp;
 }

Regardless of the method for settings projection MapWinGIS will update AxMap.MapUnits. IF coordinate system is geographic one umDecimalDegrees will be set, otherwise umMeters. This will ensure that scalebar and measuring will work correctly.

C. Choosing projection

When making decision about coordinate system and projection consider:

1. Whether it's important to display tiles from online services. Most TMS servers use Shperical Mercator projection (EPSG:3857), therefore to avoid distortions of tiles map projection should be set to GoogleMercator as well:

 axMap1.Projection = tkMapProjection.PROJECTION_GOOGLE_MERCATOR;
Note:
See more details on the issue in description of Tiles class.

2. What data you plan to display and what projection it's using. It's possible to do a reprojection with:

But it should be considered whether it is worth the effort.

Starting from version 4.9.2. built-in projection mismatch testing is implemented + optional transformation for shapefiles. See GlobalSettings.AllowProjectionMismatch, GlobalSettings.ReprojectLayersOnAdding.


Function Documentation

bool AxMap.DegreesToPixel ( double  degreesLngX,
double  degreesLatY,
ref double  pixelX,
ref double  pixelY 
)

Converts pixel coordinates to decimal degrees (map projection must be specified for this method to work).

Parameters:
degreesLngXLongitude in decimal degrees.
degreesLatYLatitude in decimal degrees.
pixelXConverted X screen coordinate.
pixelYConverted Y screen coordinate.
Returns:
True on success.
New API 4.9.1:
Added in version 4.9.1
bool AxMap.DegreesToProj ( double  degreesLngX,
double  degreesLatY,
ref double  projX,
ref double  projY 
)

Converts coordinates in decimal degrees to projected map coordinates (map projection must be specified for this method to work).

Parameters:
degreesLngXLongitude in decimal degrees.
degreesLatYLatitude in decimal degrees.
projXResulting projected X map coordinate.
projYResulting Projected Y map coordinate.
Returns:
True on success.
New API 4.9.1:
Added in version 4.9.1
double AxMap.GeodesicArea ( Shape  polygon)

Calculates area of polygon taking into account the shape of Earth.

For the time being only single-part polygons are accepted as input. Calculation are made using GeographicLib.

Parameters:
polygonSingle part polygon shape defined in coordinates of map.
Returns:
Area of shape in square meters or 0.0 if current map projection doesn't support transformation to WGS84.
New API 4.9.3:
Added in version 4.9.3
double AxMap.GeodesicDistance ( double  projX1,
double  projY1,
double  projX2,
double  projY2 
)

Calculates geodesic distance between 2 points defined in map coordinate system.

To calculate geodesic distance between 2 points in screen coordinates use AxMap.PixelToProj first. Calculation are made using GeographicLib.

Parameters:
projX1X coordinate of the first point.
projY1Y coordinate of the first point.
projX2X coordinate of the second point.
projY2Y coordinate of the second point.
Returns:
Distance between 2 points in meters 0.0 if current map projection doesn't support transformation to WGS84
New API 4.9.3:
Added in version 4.9.3
double AxMap.GeodesicLength ( Shape  polyline)

Calculates length of polyline or perimeter of polygon taking into account the shape of Earth.

For the time being only single-part shapes are accepted as input. Calculation are made using GeographicLib.

Parameters:
polylineSingle part polygon or polyline shape defined in coordinates of map.
Returns:
Length of polyline or perimeter of polygon in meters or 0.0 if current map projection doesn't support transformation to WGS84.
New API 4.9.3:
Added in version 4.9.3
bool AxMap.PixelToDegrees ( double  pixelX,
double  pixelY,
ref double  degreesLngX,
ref double  degreesLatY 
)

Converts coordinates in decimal degrees to pixel coordinates (map projection must be specified for this method to work).

Parameters:
pixelXX screen coordinate.
pixelYY screen coordinate.
degreesLngXConverted longitude in decimal degrees
degreesLatYConverted latitude in decimal degrees
Returns:
True on success.
New API 4.9.1:
Added in version 4.9.1
void AxMap.PixelToProj ( double  pixelX,
double  pixelY,
ref double  projX,
ref double  projY 
)

Converts pixel coordinates to projected map coordinates.

Parameters:
pixelXThe x pixel coordinate to be converted into the projected x map coordinate.
pixelYThe y pixel coordinate to be converted into the projected y map coordinate
projXThe projected x map coordinate is returned through this reference parameter.
projYThe projected y map coordinate is returned through this reference parameter.
Examples:
EditAttributes.cs, MarkPoints.cs, RemoveShape.cs, SelectBox.cs, and ToolTip.cs.
bool AxMap.ProjToDegrees ( double  projX,
double  projY,
ref double  degreesLngX,
ref double  degreesLatY 
)

Converts projected map coordinates to decimal degrees (map projection must be specified for this method to work).

Parameters:
projXProjected X map coordinate.
projYProjected Y map coordinate.
degreesLngXConverted longitude in decimal degrees
degreesLatYConverted latitude in decimal degrees
Returns:
True on success.
New API 4.9.1:
Added in version 4.9.1
void AxMap.ProjToPixel ( double  projX,
double  projY,
ref double  pixelX,
ref double  pixelY 
)

Converts projected map coordinates into screen pixel units.

Parameters:
projXThe projected x map coordinate to be converted into the x pixel coordinate.
projYThe projected y map coordinate to be converted into the y pixel coordinate.
pixelXThe pixel x coordinate is returned through this reference parameter
pixelYThe pixel y coordinate is returned through this reference parameter.
Examples:
Tracking.cs.

Properties

Gets or sets projection for map.

Projection layered set to map must not be changed, but rather a new instance of GeoProjection should be created (GeoProjection.Clone) and set to the property. This property must be set in order for certain functionality to work (tiles, for example).

New API 4.9.0:
Added in version 4.9.0
Examples:
ShapefileToDrawingLayer.cs, and TrackCars.cs.

Gets or sets a value indicating whether projection for will be taken from the first datasource added to it.

If set to true projection will be taken from the first layer added to the map which has a projection. On removing the last layer projection of the map will be cleared (set to an empty one).

New API 4.9.1:
Added in version 4.9.1
Examples:
ImageLabels.cs, IntersectionLength.cs, MinimalDistance.cs, Segmentation.cs, SelectByDistance.cs, ShapefileToDrawingLayer.cs, SplitByAttribute.cs, TrackCars.cs, and Tracking.cs.

Gets or sets the units of measure for the map.

This units must be the same as the units of the datasources being displayed. This method affects the calculation of map scale (see AxMap.CurrentScale).

New API 4.8:
Added in version 4.8
Examples:
EditAttributes.cs, RemoveShape.cs, SelectBox.cs, ToolTip.cs, Tracking.cs, and ZoomToValues.cs.

Gets measuring object associated with map.

New API 4.9.1:
Added in version 4.9.1
double AxMap.PixelsPerDegree [get, set]

Gets the number of screen pixels per the decimal degree of the data.

The set part of this property isn't supported. The correctness of results depends on AxMap.MapUnits property.

New API 4.8:
Added in version 4.8

Gets or sets units to be displayed for map scalebar.

New API 4.9.1:
Added in version 4.9.1
bool AxMap.ScalebarVisible [get, set]

Gets or sets a value which indicate whether scalebar will be displayed on the map.

New API 4.9.0:
Added in version 4.9.0

Gets or sets a value indicating whether coordinates of the current mouse position will be displayed on map.

New API 4.9.1:
Added in version 4.9.1
 All Classes Files Functions Enumerations Properties Events