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). More...

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). More...

double	AxMap.GeodesicArea (Shape polygon)
	Calculates area of polygon taking into account the shape of Earth. More...

double	AxMap.GeodesicDistance (double projX1, double projY1, double projX2, double projY2)
	Calculates geodesic distance between 2 points defined in map coordinate system. More...

double	AxMap.GeodesicLength (Shape polyline)
	Calculates length of polyline or perimeter of polygon taking into account the shape of Earth. More...

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). More...

void	AxMap.PixelToProj (double pixelX, double pixelY, ref double projX, ref double projY)
	Converts pixel coordinates to projected map coordinates More...

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). More...

void	AxMap.ProjToPixel (double projX, double projY, ref double pixelX, ref double pixelY)
	Converts projected map coordinates into screen pixel units More...

Properties
tkCustomDrawingFlags	AxMap.CustomDrawingFlags `[get, set]`
	Set custom drawing flags More...

DrawingRectangle	AxMap.FocusRectangle `[get]`
	For selection boxes or dragging operations, updated with tkRedrawType.Minimal More...

GeoProjection	AxMap.GeoProjection `[get, set]`
	Gets or sets projection for map. More...

bool	AxMap.GrabProjectionFromData `[get, set]`
	Gets or sets a value indicating whether projection for will be taken from the first datasource added to it. More...

SelectionList	AxMap.IdentifiedShapes `[get]`
	Get the identified shapes More...

tkUnitsOfMeasure	AxMap.MapUnits `[get, set]`
	Gets or sets the units of measure for the map. More...

Measuring	AxMap.Measuring `[get]`
	Gets measuring object associated with map. More...

double	AxMap.PixelsPerDegree `[get, set]`
	Gets the number of screen pixels per the decimal degree of the data. More...

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

tkScalebarUnits	AxMap.ScalebarUnits `[get, set]`
	Gets or sets units to be displayed for map scalebar. More...

bool	AxMap.ScalebarVisible `[get, set]`
	Gets or sets a value which indicate whether scalebar will be displayed on the map. More...

tkCoordinatesDisplay	AxMap.ShowCoordinates `[get, set]`
	Gets or sets a value indicating whether coordinates of the current mouse position will be displayed on map. More...

bool	AxMap.ShowCoordinatesBackground `[get, set]`
	Gets or sets a value indicating whether to display a white background behind the coordinates, for better contrast More...

tkAngleFormat	AxMap.ShowCoordinatesFormat `[get, set]`
	Allows to format coordinates in top right corner in degrees/minutes/seconds format; by default the former minutes format is used More...

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.

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.

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;

tkMapProjection

Commonly used map projections to be set in Form Designer (see AxMap.Projection property).

Definition: Enumerations.cs:1741

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

tkFileOpenStrategy

Possible open strategies for datasources.

Definition: Enumerations.cs:1799

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.

AxMap.Projection property is equal to PROJECTION_NONE (the default value);
map units should be set manually via AxMap.MapUnits;
calculation of distance and area will use Euclidean geometry with no account to the shape of Earth;
it won't be possible to display tiles from TMS servers.

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:

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.
What data you plan to display and what projection it's using. It's possible to do a reprojection with:

Utils.ReprojectShapefile for shapefiles;
GdalUtils.GdalRasterWarp for images and grids.

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

◆ DegreesToPixel()

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

degreesLngX	Longitude in decimal degrees.
degreesLatY	Latitude in decimal degrees.
pixelX	Converted X screen coordinate.
pixelY	Converted Y screen coordinate.

Returns: True on success.

New API 4.9.1:: Added in version 4.9.1

◆ DegreesToProj()

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

degreesLngX	Longitude in decimal degrees.
degreesLatY	Latitude in decimal degrees.
projX	Resulting projected X map coordinate.
projY	Resulting Projected Y map coordinate.

Returns: True on success.

New API 4.9.1:: Added in version 4.9.1

◆ GeodesicArea()

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

polygon Single 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

◆ GeodesicDistance()

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

projX1	X coordinate of the first point.
projY1	Y coordinate of the first point.
projX2	X coordinate of the second point.
projY2	Y 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

◆ GeodesicLength()

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

polyline Single 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

◆ PixelToDegrees()

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

pixelX	X screen coordinate.
pixelY	Y screen coordinate.
degreesLngX	Converted longitude in decimal degrees
degreesLatY	Converted latitude in decimal degrees

Returns: True on success.

New API 4.9.1:: Added in version 4.9.1

◆ PixelToProj()

void AxMap.PixelToProj	(	double	pixelX,
		double	pixelY,
		ref double	projX,
		ref double	projY
	)

Converts pixel coordinates to projected map coordinates

Parameters

pixelX	The x pixel coordinate to be converted into the projected x map coordinate.
pixelY	The y pixel coordinate to be converted into the projected y map coordinate
projX	The projected x map coordinate is returned through this reference parameter.
projY	The projected y map coordinate is returned through this reference parameter.

Examples: EditAttributes.cs, MarkPoints.cs, RemoveShape.cs, SelectBox.cs, and ToolTip.cs.

◆ ProjToDegrees()

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

projX	Projected X map coordinate.
projY	Projected Y map coordinate.
degreesLngX	Converted longitude in decimal degrees
degreesLatY	Converted latitude in decimal degrees

Returns: True on success.

New API 4.9.1:: Added in version 4.9.1

◆ ProjToPixel()

void AxMap.ProjToPixel	(	double	projX,
		double	projY,
		ref double	pixelX,
		ref double	pixelY
	)

Converts projected map coordinates into screen pixel units

Parameters

projX	The projected x map coordinate to be converted into the x pixel coordinate.
projY	The projected y map coordinate to be converted into the y pixel coordinate.
pixelX	The pixel x coordinate is returned through this reference parameter
pixelY	The pixel y coordinate is returned through this reference parameter.

Examples: Tracking.cs.

Properties

◆ CustomDrawingFlags

tkCustomDrawingFlags AxMap.CustomDrawingFlags

getset

Set custom drawing flags

◆ FocusRectangle

DrawingRectangle AxMap.FocusRectangle

get

For selection boxes or dragging operations, updated with tkRedrawType.Minimal

◆ GeoProjection

GeoProjection AxMap.GeoProjection

getset

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.

◆ GrabProjectionFromData

bool AxMap.GrabProjectionFromData

getset

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.

◆ IdentifiedShapes

SelectionList AxMap.IdentifiedShapes

get

Get the identified shapes

◆ MapUnits

tkUnitsOfMeasure AxMap.MapUnits

getset

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.

◆ Measuring

Measuring AxMap.Measuring

get

Gets measuring object associated with map.

New API 4.9.1:: Added in version 4.9.1

◆ PixelsPerDegree

double AxMap.PixelsPerDegree

getset

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

◆ Projection

tkMapProjection AxMap.Projection

getset

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.

New API 4.9.1:: Added in version 4.9.1

◆ ScalebarUnits

tkScalebarUnits AxMap.ScalebarUnits

getset

Gets or sets units to be displayed for map scalebar.

New API 4.9.1:: Added in version 4.9.1

◆ ScalebarVisible

bool AxMap.ScalebarVisible

getset

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

◆ ShowCoordinates

tkCoordinatesDisplay AxMap.ShowCoordinates

getset

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

◆ ShowCoordinatesBackground

bool AxMap.ShowCoordinatesBackground

getset

Gets or sets a value indicating whether to display a white background behind the coordinates, for better contrast

New API 5.2:: Added in version 5.2

◆ ShowCoordinatesFormat

tkAngleFormat AxMap.ShowCoordinatesFormat

getset

Allows to format coordinates in top right corner in degrees/minutes/seconds format; by default the former minutes format is used

Functions

Properties

Detailed Description

A. Setting projection for the map.

B. Interaction with already set projection

C. Choosing projection

Function Documentation

◆ DegreesToPixel()

◆ DegreesToProj()

◆ GeodesicArea()

◆ GeodesicDistance()

◆ GeodesicLength()

◆ PixelToDegrees()

◆ PixelToProj()

◆ ProjToDegrees()

◆ ProjToPixel()

Properties

◆ CustomDrawingFlags

◆ FocusRectangle

◆ GeoProjection

◆ GrabProjectionFromData

◆ IdentifiedShapes

◆ MapUnits

◆ Measuring

◆ PixelsPerDegree

◆ Projection

◆ ScalebarUnits

◆ ScalebarVisible

◆ ShowCoordinates

◆ ShowCoordinatesBackground

◆ ShowCoordinatesFormat