AGSCoordinateFormatter Class Reference
Description
Formatter to convert between coordinates and their string representation.
Instances of this class represent a formatter than can convert between coordinates and their string representation in various formats such as decimal degrees; degrees, minutes, and seconds; U.S. National Grid (USNG); and Military Grid Reference System (MGRS).
- Since
- 100.1
Inheritance diagram for AGSCoordinateFormatter:
Class Methods | |
| (nullable NSString *) | + GARSStringFromPoint: |
| (nullable NSString *) | + GEOREFStringFromPoint:precision: |
| (nullable NSString *) | + LatitudeLongitudeStringFromPoint:format:decimalPlaces: |
| (nullable NSString *) | + MGRSStringFromPoint:conversionMode:precision:addSpaces: |
| (nullable AGSPoint *) | + pointFromGARSString:spatialReference:conversionMode: |
| (nullable AGSPoint *) | + pointFromGEOREFString:spatialReference: |
| (nullable AGSPoint *) | + pointFromLatitudeLongitudeString:spatialReference: |
| (nullable AGSPoint *) | + pointFromMGRSString:spatialReference:conversionMode: |
| (nullable AGSPoint *) | + pointFromUSNGString:spatialReference: |
| (nullable AGSPoint *) | + pointFromUTMString:spatialReference:conversionMode: |
| (nullable NSString *) | + USNGStringFromPoint:precision:addSpaces: |
| (nullable NSString *) | + UTMStringFromPoint:conversionMode:addSpaces: |
Method Documentation
◆ GARSStringFromPoint:
| + (nullable NSString*) GARSStringFromPoint: | (AGSPoint *) | point |
Returns a coordinate notation string in Global Area Reference System (GARS) format representing the given point's location.
- Parameters
-
point to be represented in GARS notation. The point must have a spatial reference.
- Returns
- A GARS notation string representing the GARS cell containing the given point.
- Since
- 100.1
◆ GEOREFStringFromPoint:precision:
| + (nullable NSString*) GEOREFStringFromPoint: | (AGSPoint *) | point | |
| precision: | (NSInteger) | precision | |
Returns a coordinate notation string in World Geographic Reference system (GEOREF) format 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 |
*At the equator to 1 significant figure.
- Parameters
-
point to be represented in GEOREF notation. The point must have a spatial reference. precision with which to represent the coordinate. It should be in the interval [0, 9].
- Returns
- A GEOREF notation string representing the position of the given point. Returns
nilon error.
- Since
- 100.1
◆ LatitudeLongitudeStringFromPoint:format:decimalPlaces:
| + (nullable NSString*) LatitudeLongitudeStringFromPoint: | (AGSPoint *) | point | |
| format: | (AGSLatitudeLongitudeFormat) | format | |
| decimalPlaces: | (NSInteger) | decimalPlaces | |
Returns a coordinate notation string in latitude-longitude format 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 decimalPlaces parameters. For example:
| DecimalPlaces | Format | Example output | Angular precision | Approx precision* |
|---|---|---|---|---|
| 0 | AGSLatitudeLongitudeFormatDecimalDegrees | 056N 0003W | 1deg | 100km |
| 1 | AGSLatitudeLongitudeFormatDecimalDegrees | 55.9N 003.2W | 0.1deg | 10km |
| 2 | AGSLatitudeLongitudeFormatDecimalDegrees | 55.94N 003.16W | 0.01deg | 1km |
| 3 | AGSLatitudeLongitudeFormatDecimalDegrees | 55.944N 003.162W | 0.001deg | 100m |
| 0 | AGSLatitudeLongitudeFormatDegreesDecimalMinutes | 55 057N 003 010W | 1min | 2km |
| 1 | AGSLatitudeLongitudeFormatDegreesDecimalMinutes | 55 56.7N 003 09.7W | 0.1min | 200m |
| 2 | AGSLatitudeLongitudeFormatDegreesDecimalMinutes | 55 56.65N 003 09.72W | 0.01min | 20m |
| 3 | AGSLatitudeLongitudeFormatDegreesDecimalMinutes | 55 56.650N 003 09.717W | 0.001min | 2m |
| 0 | AGSLatitudeLongitudeFormatDegreesMinutesSeconds | 55 56 039N 003 09 043W | 1sec | 30m |
| 1 | AGSLatitudeLongitudeFormatDegreesMinutesSeconds | 55 56 39.1N 003 09 43.0W | 0.1sec | 3m |
| 2 | AGSLatitudeLongitudeFormatDegreesMinutesSeconds | 55 56 39.12N 003 09 43.03W | 0.01sec | 300mm |
| 3 | AGSLatitudeLongitudeFormatDegreesMinutesSeconds | 55 56 39.123N 003 09 43.034W | 0.001sec | 30mm |
*At the equator to 1 significant figure.
- Parameters
-
point to be represented in latitude-longitude notation. The point must have a spatial reference. format The mode to use when formatting the latitude-longitude string. decimalPlaces The number of decimal places to use. It should be in the interval [0, 16].
- Returns
- A latitude-longitude notation string representing the position of the given point. Returns
nilon error.
- Since
- 100.1
◆ MGRSStringFromPoint:conversionMode:precision:addSpaces:
| + (nullable NSString*) MGRSStringFromPoint: | (AGSPoint *) | point | |
| conversionMode: | (AGSMGRSConversionMode) | conversionMode | |
| precision: | (NSInteger) | precision | |
| addSpaces: | (BOOL) | addSpaces | |
Returns a coordinate notation string in Military Grid Reference System (MGRS) format 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 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 |
- Parameters
-
point to be represented in MGRS notation. The point must have a spatial reference. conversionMode The mode to use for the returned MGRS notation string. precision The precision with which to represent the coordinate. It should be in the interval [0, 8]. addSpaces If false, the generated string contains 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. Returns
nilon error.
- Since
- 100.1
◆ pointFromGARSString:spatialReference:conversionMode:
| + (nullable AGSPoint*) pointFromGARSString: | (NSString *) | GARSString | |
| spatialReference: | (nullable AGSSpatialReference *) | spatialReference | |
| conversionMode: | (AGSGARSConversionMode) | conversionMode | |
Returns a point by parsing a coordinate notation string in the Global Area Reference System (GARS) format.
| GARS notation examples |
|---|
| 354ND |
| 354ND22 |
- Note
- 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.
- Parameters
-
GARSString the coordinate notation string in GARS format spatialReference in which the point should be returned conversionMode determining whether the returned point will represent the lower-left (south-west) or center of the GARS cell, quadrant or area.
- Returns
- A point with the location from the GARS string in the spatial reference provided.
- Since
- 100.1
◆ pointFromGEOREFString:spatialReference:
| + (nullable AGSPoint*) pointFromGEOREFString: | (NSString *) | GEOREFString | |
| spatialReference: | (nullable AGSSpatialReference *) | spatialReference | |
Returns a point by parsing a coordinate notation string in the World Geographic Reference system (GEOREF) format.
| GEOREF notation examples |
|---|
| MKML5056 |
| MKML50285665 |
- Note
- 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.
- Parameters
-
GEOREFString the coordinate notation string in GEOREF format spatialReference in which the point should be returned
- Returns
- A point with the location from the GEOREF string in the spatial reference provided.
- Since
- 100.1
◆ pointFromLatitudeLongitudeString:spatialReference:
| + (nullable AGSPoint*) pointFromLatitudeLongitudeString: | (NSString *) | latLongString | |
| spatialReference: | (nullable AGSSpatialReference *) | spatialReference | |
Returns a point by parsing a coordinate notation string in latitude-longitude format such as decimal degrees, degrees and decimal minutes, or degrees, minutes, and seconds. 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* |
| 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 | ″ |
- Note
- 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.
- Parameters
-
latLongString the coordinate notation string in latitude-longitude format spatialReference in which the point should be returned
- Returns
- A point with the location from the latitude-longitude string in the spatial reference provided.
- Since
- 100.1
◆ pointFromMGRSString:spatialReference:conversionMode:
| + (nullable AGSPoint*) pointFromMGRSString: | (NSString *) | MGRSString | |
| spatialReference: | (nullable AGSSpatialReference *) | spatialReference | |
| conversionMode: | (AGSMGRSConversionMode) | conversionMode | |
Returns a point by parsing a coordinate notation string in the Military Grid Reference System (MGRS) format.
| MGRS notation examples |
|---|
| 30UVG898998 |
| 30UVG 89885 99877 |
- Note
- 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
AGSMGRSConversionMode. 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.
- Parameters
-
MGRSString the coordinate notation string in MGRS format spatialReference in which the point should be returned conversionMode determining the lettering scheme and treatment of coordinates at 180 degrees longitude.
- Returns
- A point with the location from the MGRS string in the spatial reference provided.
- Since
- 100.1
◆ pointFromUSNGString:spatialReference:
| + (nullable AGSPoint*) pointFromUSNGString: | (NSString *) | USNGString | |
| spatialReference: | (nullable AGSSpatialReference *) | spatialReference | |
Returns a point by parsing a coordinate notation string in the United States National Grid (USNG) format.
| USNG notation examples |
|---|
| 13TFJ 23 59 |
| 13TFJ2374159574 |
- Note
- 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.
- Parameters
-
USNGString the coordinate notation string in USNG format spatialReference in which the point should be returned
- Returns
- A point with the location from the USNG string in the spatial reference provided.
- Since
- 100.1
◆ pointFromUTMString:spatialReference:conversionMode:
| + (nullable AGSPoint*) pointFromUTMString: | (NSString *) | UTMString | |
| spatialReference: | (nullable AGSSpatialReference *) | spatialReference | |
| conversionMode: | (AGSUTMConversionMode) | conversionMode | |
Returns a point by parsing a coordinate notation string in the Universal Transverse Mercator (UTM) format.
| UTM notation examples |
|---|
| 30U 489885 6199877 |
| 30U4898856199877 |
| 30N 489885 6199877 (using N/S indicator) |
- Note
- 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..
- Parameters
-
UTMString the coordinate notation string in UTM format spatialReference in which the point should be returned conversionMode indicating whether the coordinate string contains North or South Hemisphere indicators, or a latitude band identified with letters C through X (omitting I and O).
- Returns
- A point with the location from the UTM string in the spatial reference provided.
- Since
- 100.1
◆ USNGStringFromPoint:precision:addSpaces:
| + (nullable NSString*) USNGStringFromPoint: | (AGSPoint *) | point | |
| precision: | (NSInteger) | precision | |
| addSpaces: | (BOOL) | addSpaces | |
Returns a coordinate notation string in United States National Grid (USNG) format 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 | Approx 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 |
| *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
- Parameters
-
point to be represented in USNG notation. The point must have a spatial reference. precision The precision with which to represent the coordinate. It should be in the interval [0, 8]. addSpaces If false, the generated string contains 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. Returns
nilon error.
- Since
- 100.1
◆ UTMStringFromPoint:conversionMode:addSpaces:
| + (nullable NSString*) UTMStringFromPoint: | (AGSPoint *) | point | |
| conversionMode: | (AGSUTMConversionMode) | conversionMode | |
| addSpaces: | (BOOL) | addSpaces | |
Returns a coordinate notation string in Universal Transverse Mercator (UTM) format representing the given point's location.
| UTM Conversion Mode | add_spaces | Example output |
|---|---|---|
AGSUTMConversionModeLatitudeBandIndicators | false | 30U4898846199881 |
AGSUTMConversionModeLatitudeBandIndicators | true | 30U 489884 6199881 |
AGSUTMConversionModeNorthSouthIndicators | false | 30N4898846199881 |
AGSUTMConversionModeNorthSouthIndicators | true | 30N 489884 6199881 |
- Parameters
-
point to be represented in UTM notation. The point must have a spatial reference. conversionMode The latitude notation scheme to use in the returned UTM notation string, either a latitudinal band, or a hemisphere designator. addSpaces If false, the generated string contains 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.
- Since
- 100.1
