- Since:
- 100.1.0
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
Indicates the location of a point relative to a Global Area Reference System (GARS) cell.static enum
Supports the formats for representing latitude-longitude geographical coordinates as a string.static enum
Determines the lettering scheme and treatment of coordinates at 180 degrees longitude when converting Military Grid Reference System (MGRS) coordinates.static enum
Determines how latitude is designated in Universal Transverse Mercator (UTM) notation. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic Point
fromGars
(String coordinates, SpatialReference spatialReference, CoordinateFormatter.GarsConversionMode conversionMode) Parses coordinates in Global Area Reference System (GARS) notation, and returns a Point representing that location.static Point
fromGeoRef
(String coordinates, SpatialReference spatialReference) Parses coordinates in World Geographic Reference System (GEOREF) notation, and returns a Point representing that location.static Point
fromLatitudeLongitude
(String coordinates, SpatialReference spatialReference) Parses coordinates in latitude-longitude notation, and returns a Point representing that location.static Point
fromMgrs
(String coordinates, SpatialReference spatialReference, CoordinateFormatter.MgrsConversionMode conversionMode) Parses coordinates in Military Grid Reference System (MGRS) notation, and returns a Point representing that location.static Point
fromUsng
(String coordinates, SpatialReference spatialReference) Parses coordinates in United States National Grid (USNG) notation, and returns a Point representing that location.static Point
fromUtm
(String coordinates, SpatialReference spatialReference, CoordinateFormatter.UtmConversionMode conversionMode) Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location.static String
Returns formatted coordinates in Global Area Reference System (GARS) notation representing the given point's location.static String
Returns formatted coordinates in World Geographic Reference System (GEOREF) notation representing the given point's location.static String
toLatitudeLongitude
(Point point, CoordinateFormatter.LatitudeLongitudeFormat latitudeLongitudeFormat, int decimalPlaces) Returns formatted coordinates in latitude-longitude notation representing the given point's location.static String
toMgrs
(Point point, CoordinateFormatter.MgrsConversionMode conversionMode, int precision, boolean addSpace) Returns formatted coordinates in Military Grid Reference System (MGRS) notation representing the given point's location.static String
Returns formatted coordinates in United States National Grid (USNG) notation representing the given point's location.static String
toUtm
(Point point, CoordinateFormatter.UtmConversionMode conversionMode, boolean addSpace) Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location.
-
Constructor Details
-
CoordinateFormatter
public CoordinateFormatter()
-
-
Method Details
-
fromGars
public static Point fromGars(String coordinates, SpatialReference spatialReference, CoordinateFormatter.GarsConversionMode conversionMode) Parses coordinates in Global Area Reference System (GARS) notation, and returns a Point representing that location. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the GARS string. If no spatial reference is provided, it is assumed the GARS string is referenced to WGS84.The GARS string must not contain any whitespace. GARS notation examples:
- 354ND
- 354ND22
- Parameters:
coordinates
- a GARS notation string for the coordinatesspatialReference
- a spatial reference that defines the datum and ellipsoid referenced by the GARS coordinates If it is null, WGS84 will be used.conversionMode
- select whether the returned point's location represents the south-west corner of the GARS cell the coordinates lies within, or its center- Returns:
- a point with the location from the GARS string in the spatial reference provided
- Throws:
IllegalArgumentException
- if the coordinates or the conversionMode is nullArcGISRuntimeException
- if the given string is not valid GARS notation- Since:
- 100.1.0
-
fromGeoRef
Parses coordinates in World Geographic Reference System (GEOREF) notation, and returns a Point representing that location. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the GEOREF string. If no spatial reference is provided, it is assumed the GEOREF string is referenced to WGS84.The GEOREF string may contain leading and trailing whitespace. Here some GEOREF notation examples:
- MKML5056
- MKML50285665
- Parameters:
coordinates
- a GEOREF notation string for the coordinatesspatialReference
- a spatial reference that defines the datum and ellipsoid referenced by the GEOREF coordinates. If it is null, WGS84 will be used.- Returns:
- a point with the location from the GEOREF string in the spatial reference provided
- Throws:
IllegalArgumentException
- if the coordinates is nullArcGISRuntimeException
- if the given string is not valid GEOREF notation- Since:
- 100.1.0
-
fromLatitudeLongitude
Parses coordinates in latitude-longitude notation, and returns a Point representing that location.The coordinates may use decimal degrees, degrees and decimal minutes, or degrees, minutes, and seconds format. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the latitude-longitude string. If no spatial reference is provided, it is assumed the latitude-longitude coordinates are referenced to WGS84.
Supported characters Symbol Character Name Unicode number HTML code Degree * Asterisk U+002A * ^ Circumflex Accent U+005E ^ ~ Tilde U+007E ~ ° Degree Sign U+00B0 ° º Masculine Ordinal Indicator U+00BA º ˚ Ring Above U+02DA ˚ ⁰ Superscript Zero U+2070 ⁰ Minute ' Apostrophe U+0027 ' ’ Right Single Quotation Mark U+2019 ᾿ ′ Prime U+2032 ′ Second " Quotation Mark U+0022 " ˝ Double Acute Accent U+02DD ˝ ” Right Double Quotation Mark U+201D ” ″ Double Prime U+2033 ″ The latitude-longitude string may contain leading and trailing whitespace, and may also contain a space, comma, or vertical bar symbol to separate the latitude from the longitude. It may also contain the characters 'N', 'S', 'E' and 'W', or use a minus (-) symbol to indicate the hemisphere of each value.
Latitude-longitude notation examples:
- 55 56 39.123N 003 09 43.034W
- 55°56′39″N 3°09′43″W
- 55~56.65205', -003~09.71723'
- 55.9442008* | -3.1619539
- Parameters:
coordinates
- the latitude-longitude notation string for the coordinatesspatialReference
- a spatial reference that defines the datum and ellipsoid referenced by the latitude-longitude coordinates. If it is null, WGS84 will be used.- Returns:
- a point with the location from the coordinates string in the spatial reference provided
- Throws:
IllegalArgumentException
- if the coordinates is nullArcGISRuntimeException
- if the given string is not valid latitude-longitude notation- Since:
- 100.1.0
-
fromMgrs
public static Point fromMgrs(String coordinates, SpatialReference spatialReference, CoordinateFormatter.MgrsConversionMode conversionMode) Parses coordinates in Military Grid Reference System (MGRS) notation, and returns a Point representing that location. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the MGRS string. If no spatial reference is provided, it is assumed the MGRS string is referenced to WGS84.Note that the choice between zone 01 and 60 has no impact when reading from an MGRS notation string. The MGRS string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier, and the numerical eastings and northings.
MGRS notation examples:
- 30UVG898998
- 30UVG 89885 99877
- Parameters:
coordinates
- the MGRS notation string for the coordinatesspatialReference
- a spatial reference that defines the datum and ellipsoid referenced by the MGRS coordinates, if it is null, WGS84 will be usedconversionMode
- the mode used by the given MGRS coordinates- Returns:
- a point with the location from the MGRS string in the spatial reference provided
- Throws:
IllegalArgumentException
- if the coordinates or the conversionMode is nullArcGISRuntimeException
- if the given string is not valid MGRS notation- Since:
- 100.1.0
- See Also:
-
fromUsng
Parses coordinates in United States National Grid (USNG) notation, and returns a Point representing that location.The spatial reference provided must have an ellipsoid and datum matching those used by the source of the USNG string. If no spatial reference is provided and the USNG string is suffixed with "(NAD 27)", it is assumed the USNG string is referenced to NAD 27. If no spatial reference is provided and no such suffix exists, it is assumed the USNG string is referenced to WGS84. The USNG string can contain leading and trailing whitespace and can have whitespace between the grid zone designator, the 100km square identifier and the numerical eastings and northings.
USNG notation examples:
- 13TFJ 23 59
- 13TFJ2374159574
- Parameters:
coordinates
- the USNG notation string for the coordinatesspatialReference
- a spatial reference that defines the datum and ellipsoid referenced by the USNG coordinates, if it is null, WGS84 will be used- Returns:
- a point with the location from the USNG string in the spatial reference provided
- Throws:
IllegalArgumentException
- if the coordinates is nullArcGISRuntimeException
- if the given string is not valid USNG notation- Since:
- 100.1.0
-
fromUtm
public static Point fromUtm(String coordinates, SpatialReference spatialReference, CoordinateFormatter.UtmConversionMode conversionMode) Parses coordinates in Universal Transverse Mercator (UTM) notation, and returns a Point representing that location. The spatial reference provided must have an ellipsoid and datum matching those used by the source of the UTM string. If no spatial reference is provided, it is assumed the UTM string is referenced to WGS84. The UTM string can contain leading and trailing whitespace and can have whitespace between the zone and latitude designator and the numerical eastings and northings.UTM notation examples:
- 30U 489885 6199877
- 30U4898856199877
- 30N 489885 6199877 (using N/S indicator)
- 489885.32,6199877.36,30U (this form supports sub-meter precision)
- Parameters:
coordinates
- the UTM notation string for the coordinatesspatialReference
- a spatial reference that defines the datum and ellipsoid referenced by the UTM coordinates, if it is null, WGS84 will be used.conversionMode
- the latitude notation scheme used by the given UTM coordinates, either a latitudinal band, or a hemisphere designator- Returns:
- a point with the location from the UTM string in the spatial reference provided
- Throws:
IllegalArgumentException
- if the coordinates or the conversionMode is nullArcGISRuntimeException
- if the given string is not valid UTM notation- Since:
- 100.1.0
-
toGars
Returns formatted coordinates in Global Area Reference System (GARS) notation representing the given point's location.- Parameters:
point
- the location to be represented in GARS notation- Returns:
- a GARS notation string representing the GARS cell containing the given point
- Throws:
IllegalArgumentException
- if the point is nullArcGISRuntimeException
- if the point does not have a spatial reference- Since:
- 100.1.0
-
toGeoRef
Returns formatted coordinates in World Geographic Reference System (GEOREF) notation representing the given point's location.The precision value controls the number of digits used to represent the fractional part of coordinate's latitude and longitude, expressed in minutes.
For example:
precision Example output Angular precision Approximate precision 0 MKML5056 1min 2km 1 MKML5056 1min 2km 2 MKML5056 1min 2km 3 MKML502566 0.1min 200m 4 MKML50285665 0.01min 20m 5 MKML5028256652 0.001min 2m At the equator to 1 significant figure. The 'precision' should be in the interval [0, 9]. The point must have a spatial reference.
- Parameters:
point
- the location to be represented in GEOREF notationprecision
- the precision with which to represent the coordinates, it should be an integer from 0 to 9- Returns:
- a GEOREF notation string representing the position of the given point
- Throws:
IllegalArgumentException
- if the point is nullIllegalArgumentException
- if the precision is out of range from 0 to 9ArcGISRuntimeException
- if the point does not have a spatial reference- Since:
- 100.1.0
-
toLatitudeLongitude
public static String toLatitudeLongitude(Point point, CoordinateFormatter.LatitudeLongitudeFormat latitudeLongitudeFormat, int decimalPlaces) Returns formatted coordinates in latitude-longitude notation representing the given point's location.The latitude-longitude string will contain a space separating the latitude from the longitude value, and the characters 'N' or 'S', and 'E' and 'W', to indicate the hemisphere of each value. The string will also contain spaces separating the components (degrees, minutes, seconds) of each value. The precision of the output is controlled by both the
LatitudeLongitudeFormat
anddecimalPlaces
parameters.For example:
Decimal places format Example output Angular precision Approximate precision 0 DECIMAL_DEGREES 056N 0003W 1deg 100km 1 DECIMAL_DEGREES 55.9N 003.2W 0.1deg 10km 2 DECIMAL_DEGREES 55.94N 003.16W 0.01deg 1km 3 DECIMAL_DEGREES 55.944N 003.162W 0.001deg 100m 0 DEGREES_DECIMAL_MINUTES 55 057N 003 010W 1min 2km 1 DEGREES_DECIMAL_MINUTES 55 56.7N 003 09.7W 0.1min 200m 2 DEGREES_DECIMAL_MINUTES 55 56.65N 003 09.72W 0.01min 20m 3 DEGREES_DECIMAL_MINUTES 55 56.650N 003 09.717W 0.001min 2m 0 DEGREES_MINUTES_SECONDS 55 56 039N 003 09 043W 1sec 30m 1 DEGREES_MINUTES_SECONDS 55 56 39.1N 003 09 43.0W 0.1sec 3m 2 DEGREES_MINUTES_SECONDS 55 56 39.12N 003 09 43.03W 0.01sec 300mm 3 DEGREES_MINUTES_SECONDS 55 56 39.123N 003 09 43.034W 0.001sec 30mm At the equator to 1 significant figure. The 'decimal places' should be in the interval [0, 16]. The point must have a spatial reference.
- Parameters:
point
- the location to be represented as a formatted latitude-longitude stringlatitudeLongitudeFormat
- the mode to use when formatting the latitude-longitude stringdecimalPlaces
- the number of decimal places to use, it should be an integer from 0 to 16- Returns:
- a string representing the latitude-longitude of the given point
- Throws:
IllegalArgumentException
- if the point or latitudeLongitudeFormat is nullIllegalArgumentException
- if the decimal places is out of the range from 0 to 16ArcGISRuntimeException
- if the point does not have a spatial reference- Since:
- 100.1.0
-
toMgrs
public static String toMgrs(Point point, CoordinateFormatter.MgrsConversionMode conversionMode, int precision, boolean addSpace) Returns formatted coordinates in Military Grid Reference System (MGRS) notation representing the given point's location.Note that the choice between zone 01 and 60 has an impact only when generating the MGRS notation string for a point with longitude of exactly 180deg. The precision value controls the number of digits used to represent each numerical easting and northing value within the MGRS string. For example:
precision add_spaces Example output Approximate precision 0 false 30UVG 100km 1 false 30UVG89 10km 2 false 30UVG8999 1km 3 false 30UVG898998 100m 4 false 30UVG89889988 10m 5 false 30UVG8988499881 1m 0 true 30U VG 100km 1 true 30U VG 8 9 10km 2 true 30U VG 89 99 1km 3 true 30U VG 898 998 100m 4 true 30U VG 8988 9988 10m 5 true 30U VG 89884 99881 1m The 'precision' should be in the interval [0, 8]. The point must have a spatial reference.
- Parameters:
point
- the location to be represented in MGRS notationconversionMode
- the mode to use for the returned MGRS notation stringprecision
- the precision with which to represent the coordinates, it should be an integer from 0 to 8addSpace
- if it is false, the generated string will contain no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values- Returns:
- a MGRS notation string representing the position of the given point
- Throws:
IllegalArgumentException
- if the point or conversionMode is nullIllegalArgumentException
- if the precision is out of range from 0 to 8ArcGISRuntimeException
- if the point does not have a spatial reference- Since:
- 100.1.0
- See Also:
-
toUsng
Returns formatted coordinates in United States National Grid (USNG) notation representing the given point's location.The precision value controls the number of digits used to represent each numerical easting and northing value within the USNG string. For example:
Precision Add spaces Example output Approximate precision 0 false 13TFJ 100km 1 false 13TFJ25 10km 2 false 13TFJ2359 1km 3 false 13TFJ237595 100m 4 false 13TFJ23745951 10m 5 false 13TFJ2374359512 1m 0 true 13T FJ 100km 1 true 13T FJ 2 5 10km 2 true 13T FJ 23 59 1km 3 true 13T FJ 237 595 100m 4 true 13T FJ 2374 5951 10m 5 true 13T FJ 23743 59512 1m If the point's
SpatialReference
is NAD 27, then a suffix is added to the end of the formatted string. For example:Precision Add spaces Example output Approximate precision 4* false 13TFJ23795929 (NAD 27) 10m 2* true 13T FJ 23 59 (NAD 27) 1km * When the point's spatial reference is based on NAD 27. The 'precision' should in the interval [0, 8]. The point must have a spatial reference.
- Parameters:
point
- the location to be represented in USNG notationprecision
- the precision with which to represent the coordinates, it should be an integer from 0 to 8addSpace
- if false, the generated string will contain no spaces. If true, a space separates the grid zone designator, the 100km square identifier, and the numerical easting and northing values- Returns:
- a USNG notation string representing the position of the given point
- Throws:
IllegalArgumentException
- if the point is nullIllegalArgumentException
- if the precision is out of range from 0 to 8ArcGISRuntimeException
- if the point does not have a spatial reference- Since:
- 100.1.0
-
toUtm
public static String toUtm(Point point, CoordinateFormatter.UtmConversionMode conversionMode, boolean addSpace) Returns formatted coordinates in Universal Transverse Mercator (UTM) notation representing the given point's location.Example output for a point in the southern hemisphere:
utm_conversion_mode add_spaces Example output LATITUDE_BAND_INDICATORS false 30U4898846199881 LATITUDE_BAND_INDICATORS true 30U 489884 6199881 NORTH_SOUTH_INDICATORS false 30N4898846199881 NORTH_SOUTH_INDICATORS true 30N 489884 6199881 The point must have a spatial reference.
- Parameters:
point
- the location to be represented in UTM notationconversionMode
- the latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designatoraddSpace
- if false, the generated string will contain no spaces. If true, a space separates the UTM zone and latitude designator, and each numerical easting and northing value.- Returns:
- a UTM notation string representing the position of the given point
- Throws:
IllegalArgumentException
- if the point or conversionMode is nullArcGISRuntimeException
- if the point does not have a spatial reference- Since:
- 100.1.0
- See Also:
-