Format coordinates
Format coordinates in a variety of common notations.
Use case
The coordinate formatter can format a map location in WGS84 in a number of common coordinate notations. Parsing one of these formats to a location is also supported. Formats include decimal degrees; degrees, minutes, seconds; Universal Transverse Mercator (UTM), and United States National Grid (USNG).
How to use the sample
Tap on the map to see a callout with the clicked location's coordinate formatted in 4 different ways. You can also put a coordinate string in any of these formats in the text field. Hit Enter and the coordinate string will be parsed to a map location which the callout will move to.
How it works
- Get or create a
MapPoint
with a spatial reference. - Use one of the static "to" methods on
CoordinateFormatter
such asCoordinateFormatter.ToLatitudeLongitude(point, CoordinateFormatter.LatitudeLongitudeFormat.DecimalDegrees, 4)
to get the formatted string. - To go from a formatted string to a
Point
, use one of the "from" static methods likeCoordinateFormatter.FromUtm(coordinateString, map.SpatialReference, CoordinateFormatter.UtmConversionMode.NorthSouthIndicators)
.
Relevant API
- CoordinateFormatter
- CoordinateFormatter.LatitudeLongitudeFormat
- CoordinateFormatter.UtmConversionMode
Tags
convert, coordinate, decimal degrees, degree minutes seconds, format, latitude, longitude, USNG, UTM
Sample Code
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:esriUI="clr-namespace:Esri.ArcGISRuntime.Xamarin.Forms;assembly=Esri.ArcGISRuntime.Xamarin.Forms"
x:Class="ArcGISRuntime.Samples.FormatCoordinates.FormatCoordinates">
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="*" />
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*" />
<ColumnDefinition Width="*" />
</Grid.ColumnDefinitions>
<Label Grid.Row="0" Grid.Column="0" HorizontalTextAlignment="End">Decimal Degrees</Label>
<Entry Grid.Row="0" Grid.Column="1" Placeholder="Decimal Degrees" x:Name="DecimalDegreesTextField" />
<Label Grid.Row="1" Grid.Column="0" HorizontalTextAlignment="End">Degrees, Minutes, Seconds</Label>
<Entry Grid.Row="1" Grid.Column="1" Placeholder="Degrees, Minutes, Seconds" x:Name="DmsTextField" />
<Label Grid.Row="2" Grid.Column="0" HorizontalTextAlignment="End">UTM</Label>
<Entry Grid.Row="2" Grid.Column="1" Placeholder="UTM" x:Name="UtmTextField" />
<Label Grid.Row="3" Grid.Column="0" HorizontalTextAlignment="End">USNG</Label>
<Entry Grid.Row="3" Grid.Column="1" Placeholder="USNG" x:Name="UsngTextField" />
<Button Grid.Row="4" Grid.Column="0" Grid.ColumnSpan="2" Clicked="RecalculateFields" Text="Recalculate" />
<esriUI:MapView Grid.Row="5" Grid.Column="0" Grid.ColumnSpan="2" x:Name="MyMapView" />
</Grid>
</ContentPage>
// Copyright 2018 Esri.
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
// You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
// language governing permissions and limitations under the License.
using Esri.ArcGISRuntime.Geometry;
using Esri.ArcGISRuntime.Mapping;
using Esri.ArcGISRuntime.Symbology;
using Esri.ArcGISRuntime.UI;
using System;
using Xamarin.Forms;
using Colors = System.Drawing.Color;
namespace ArcGISRuntime.Samples.FormatCoordinates
{
[ArcGISRuntime.Samples.Shared.Attributes.Sample(
name: "Format coordinates",
category: "Geometry",
description: "Format coordinates in a variety of common notations.",
instructions: "Tap on the map to see a callout with the clicked location's coordinate formatted in 4 different ways. You can also put a coordinate string in any of these formats in the text field. Hit Enter and the coordinate string will be parsed to a map location which the callout will move to.",
tags: new[] { "USNG", "UTM", "convert", "coordinate", "decimal degrees", "degree minutes seconds", "format", "latitude", "longitude" })]
public partial class FormatCoordinates : ContentPage
{
// Hold a reference to the most recently updated field
private Entry _selectedEntry;
public FormatCoordinates()
{
InitializeComponent();
// Create the UI, setup the control references and execute initialization
Initialize();
}
private void Initialize()
{
// Set the initial field selection
_selectedEntry = DecimalDegreesTextField;
// Create the map
MyMapView.Map = new Map(Basemap.CreateNavigationVector());
// Add the graphics overlay to the map
MyMapView.GraphicsOverlays.Add(new GraphicsOverlay());
// Create the starting point
MapPoint startingPoint = new MapPoint(0, 0, SpatialReferences.WebMercator);
// Update the UI with the initial point
UpdateUIFromMapPoint(startingPoint);
// Subscribe to text change events
UtmTextField.TextChanged += InputTextChanged;
DmsTextField.TextChanged += InputTextChanged;
DecimalDegreesTextField.TextChanged += InputTextChanged;
UsngTextField.TextChanged += InputTextChanged;
// Subscribe to map tap events to enable tapping on map to update coordinates
MyMapView.GeoViewTapped += (sender, args) => { UpdateUIFromMapPoint(args.Location); };
}
private void InputTextChanged(object sender, EventArgs e)
{
// Keep track of the last edited field
_selectedEntry = (Entry)sender;
}
private void UpdateUIFromMapPoint(MapPoint selectedPoint)
{
// Remove event handlers temporarily
UtmTextField.TextChanged -= InputTextChanged;
DmsTextField.TextChanged -= InputTextChanged;
DecimalDegreesTextField.TextChanged -= InputTextChanged;
UsngTextField.TextChanged -= InputTextChanged;
try
{
// Check if the selected point can be formatted into coordinates.
CoordinateFormatter.ToLatitudeLongitude(selectedPoint, LatitudeLongitudeFormat.DecimalDegrees, 0);
}
catch (Exception e)
{
// Check if the excpetion is because the coordinates are out of range.
if (e.Message == "Invalid argument: coordinates are out of range")
{
// Set all of the text fields to contain the error message.
DecimalDegreesTextField.Text = "Out of range";
DmsTextField.Text = "Out of range";
UtmTextField.Text = "Out of range";
UsngTextField.Text = "Out of range";
// Clear the selectionss symbol.
MyMapView.GraphicsOverlays[0].Graphics.Clear();
// Restore event handlers
UtmTextField.TextChanged += InputTextChanged;
DmsTextField.TextChanged += InputTextChanged;
DecimalDegreesTextField.TextChanged += InputTextChanged;
UsngTextField.TextChanged += InputTextChanged;
}
return;
}
// Update the decimal degrees text
DecimalDegreesTextField.Text =
CoordinateFormatter.ToLatitudeLongitude(selectedPoint, LatitudeLongitudeFormat.DecimalDegrees, 4);
// Update the degrees, minutes, seconds text
DmsTextField.Text = CoordinateFormatter.ToLatitudeLongitude(selectedPoint,
LatitudeLongitudeFormat.DegreesMinutesSeconds, 1);
// Update the UTM text
UtmTextField.Text = CoordinateFormatter.ToUtm(selectedPoint, UtmConversionMode.NorthSouthIndicators, true);
// Update the USNG text
UsngTextField.Text = CoordinateFormatter.ToUsng(selectedPoint, 4, true);
// Clear existing graphics overlays
MyMapView.GraphicsOverlays[0].Graphics.Clear();
// Create a symbol to symbolize the point
SimpleMarkerSymbol symbol = new SimpleMarkerSymbol(SimpleMarkerSymbolStyle.X, Colors.Yellow, 20);
// Create the graphic
Graphic symbolGraphic = new Graphic(selectedPoint, symbol);
// Add the graphic to the graphics overlay
MyMapView.GraphicsOverlays[0].Graphics.Add(symbolGraphic);
// Restore event handlers
UtmTextField.TextChanged += InputTextChanged;
DmsTextField.TextChanged += InputTextChanged;
DecimalDegreesTextField.TextChanged += InputTextChanged;
UsngTextField.TextChanged += InputTextChanged;
}
private void RecalculateFields(object sender, EventArgs e)
{
// Hold the entered point
MapPoint enteredPoint = null;
// Update the point based on which text sent the event
try
{
switch (_selectedEntry.Placeholder)
{
case "Decimal Degrees":
case "Degrees, Minutes, Seconds":
enteredPoint =
CoordinateFormatter.FromLatitudeLongitude(_selectedEntry.Text, MyMapView.SpatialReference);
break;
case "UTM":
enteredPoint =
CoordinateFormatter.FromUtm(_selectedEntry.Text, MyMapView.SpatialReference, UtmConversionMode.NorthSouthIndicators);
break;
case "USNG":
enteredPoint =
CoordinateFormatter.FromUsng(_selectedEntry.Text, MyMapView.SpatialReference);
break;
}
}
catch (Exception ex)
{
// The coordinate is malformed, warn and return
Application.Current.MainPage.DisplayAlert("Invalid Format", ex.Message, "OK");
return;
}
// Update the UI from the MapPoint
UpdateUIFromMapPoint(enteredPoint);
}
}
}