CoordinateFormatter

Converts between Points and formatted coordinate notation strings such as decimal degrees; degrees, minutes, and seconds; U.S. National Grid (USNG); and Military Grid Reference System (MGRS).

Since

200.1.0

Functions

Link copied to clipboard
fun fromGarsOrNull(coordinates: String, spatialReference: SpatialReference?, garsConversionMode: GarsConversionMode): Point?

Parses a coordinate 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 WGS 84. The GARS string must not contain any whitespace.

Link copied to clipboard
fun fromGeoRefOrNull(coordinates: String, spatialReference: SpatialReference?): Point?

Parses a coordinate 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 WGS 84. The GEOREF string may contain leading and trailing whitespace.

Link copied to clipboard
fun fromLatitudeLongitudeOrNull(coordinates: String, spatialReference: SpatialReference?): Point?

Parses a coordinate in latitude-longitude notation, and returns a Point representing that location. The coordinate 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 WGS 84.

Link copied to clipboard
fun fromMgrsOrNull(coordinates: String, spatialReference: SpatialReference?, mgrsConversionMode: MgrsConversionMode): Point?

Parses a coordinate 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 WGS 84. For an explanation of the different modes for interpreting an MGRS notation string, please see MgrsConversionMode. 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.

Link copied to clipboard
fun fromUsngOrNull(coordinates: String, spatialReference: SpatialReference?): Point?

Parses a coordinate 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 WGS 84. 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.

Link copied to clipboard
fun fromUtmOrNull(coordinates: String, spatialReference: SpatialReference?, utmConversionMode: UtmConversionMode): Point?

Parses a coordinate 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 WGS 84. 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.

Link copied to clipboard
fun toGarsOrNull(point: Point): String?

Returns a formatted coordinate in Global Area Reference System (GARS) notation representing the given point's location. The point must have a spatial reference. Returns null on error.

Link copied to clipboard
fun toGeoRefOrNull(point: Point, precision: Int): String?

Returns a formatted coordinate 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 | Approx 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 |

Link copied to clipboard
fun toLatitudeLongitudeOrNull(point: Point, format: LatitudeLongitudeFormat, decimalPlaces: Int): String?

Returns a formatted coordinate in latitude-longitude notation representing the given point's location. The latitude-longitude string contains 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 also contains spaces separating the components (degrees, minutes, seconds) of each value. The precision of the output is controlled by both the 'format' and 'decimal_places' parameters. For example: decimal_places | format | Example output | Angular precision | Approx precision* -------------- | ------------------------------------------------- | ---------------------------- | ----------------- | ----------------- 0 | LatitudeLongitudeFormat.DecimalDegrees | 056N 0003W | 1deg | 100km 1 | LatitudeLongitudeFormat.DecimalDegrees | 55.9N 003.2W | 0.1deg | 10km 2 | LatitudeLongitudeFormat.DecimalDegrees | 55.94N 003.16W | 0.01deg | 1km 3 | LatitudeLongitudeFormat.DecimalDegrees | 55.944N 003.162W | 0.001deg | 100m 0 | LatitudeLongitudeFormat.DegreesDecimalMinutes | 55 057N 003 010W | 1min | 2km 1 | LatitudeLongitudeFormat.DegreesDecimalMinutes | 55 56.7N 003 09.7W | 0.1min | 200m 2 | LatitudeLongitudeFormat.DegreesDecimalMinutes | 55 56.65N 003 09.72W | 0.01min | 20m 3 | LatitudeLongitudeFormat.DegreesDecimalMinutes | 55 56.650N 003 09.717W | 0.001min | 2m 0 | LatitudeLongitudeFormat.DegreesMinutesSeconds | 55 56 039N 003 09 043W | 1sec | 30m 1 | LatitudeLongitudeFormat.DegreesMinutesSeconds | 55 56 39.1N 003 09 43.0W | 0.1sec | 3m 2 | LatitudeLongitudeFormat.DegreesMinutesSeconds | 55 56 39.12N 003 09 43.03W | 0.01sec | 300mm 3 | LatitudeLongitudeFormat.DegreesMinutesSeconds | 55 56 39.123N 003 09 43.034W | 0.001sec | 30mm

Link copied to clipboard
fun toMgrsOrNull(point: Point, mgrsConversionMode: MgrsConversionMode, precision: Int, addSpaces: Boolean): String?

Returns a formatted coordinate in Military Grid Reference System (MGRS) notation representing the given point's location. For an explanation of the different modes for interpreting an MGRS notation string, please see MgrsConversionMode. 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 | Approx 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

Link copied to clipboard
fun toUsngOrNull(point: Point, precision: Int, addSpaces: Boolean): String?

Returns a formatted coordinate 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:

Link copied to clipboard
fun toUtmOrNull(point: Point, utmConversionMode: UtmConversionMode, addSpaces: Boolean): String?

Returns a formatted coordinate 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 -------------------------------------------- | ------------------- | ------------------- UtmConversionMode.LatitudeBandIndicators | false | 30U4898846199881 UtmConversionMode.LatitudeBandIndicators | true | 30U 489884 6199881 UtmConversionMode.NorthSouthIndicators | false | 30N4898846199881 UtmConversionMode.NorthSouthIndicators | true | 30N 489884 6199881