Defense Solutions coordinate API input-output formats

Summary The Defense Solutions Coordinate API supports several input and output formats used to convert coordinate values that a user, program, or data feed provides. You can adjust the Coordinate API’s input and output formats to suit your needs. This topic describes the formats that are used with the Coordinate API. For information on how to use the Defense Solutions Coordinate API, see the topic Converting Coordinates in the Defense Solutions Library Overview.

Many of the ArcGIS Military Analyst and MOLE extension application programming interface (API) objects you have used in the past have equivalent or near equivalent objects in the ArcGIS 10 ArcObjects API. These new objects should now be used and do not require a Military Analyst extension or MOLE extension license. See Migrating from Military Analyst and MOLE for information on how to accomplish tasks in ArcGIS 10 that previously required the Military Analyst and MOLE APIs.

Input and Output Formats

An input format is the arrangement of data that the Coordinate API can accept and use. The normalized output format is the default format that the Coordinate API produces as output. These formats can be modified by various settings or even completely changed by setting the Parsing and Formatting expressions.
The input format descriptions in this section are in a version of Extended Backus–Naur form (EBNF).
 
Key EBNF Notations
 
Usage
Notation
optional
[ ]
or
|
group
( )
0 or more
{}
n times
n *       affects the item following
m to n times
m..n *   affects the item following
text description of a non-simple terminal
??
The formats are discussed in the following sections.

Decimal Degrees (DD)

Input

The DDCoordinate object will validate and accept input of the following form:
<dd> ::= <latitude> <coord-pair-separator>+ <longitude>
 
<coord-pair-separator> ::= "space" | "/" | "\" | "|"
 
<latitude> ::= ["+"|"-"|"N"|"S"] <lat-DD-DD> ["+"|"-"|"N"|"S"]
 
<longitude> ::= ["+"|"-"|"E"|"W"] <lon-DD-DD> ["+"|"-"|"E"|"W"]
 
<lat-DD-DD>   ::= <lat-degrees> [["." <decimal>] [<degree-mark>]]
 
<lat-DD-DD>   ::= <lon-degrees> [["." <decimal>] [<degree-mark>]]
 
<lat-degrees> ::= ? 0-90 ? (<decimal>)
 
<lon-degrees> ::= ? 0-360 ? (<decimal>)
 
<decimal> ::= {digit}
 
<separator>::= "space" | "underscore" | "hyphen"
 
<degree-mark> ::= "Degree Sign °" | "Caret ^" | "Asterisk *"
 
Note:
 
<separator> can also appear before and after <latitude> and <longitude>
 
 
Examples:
 
All of the following are equivalent, and valid:
 
27.00N 087.00W
27.00N 087W
+27.00 087W
27N -87
N27.00 W087
27.00N/87W
27.00°N 087.00°W
 
 
Output
 
The normalized output is of the form DD.ddY DDD.ddX where Y = N or S and X = E or W.
 
Example:
 
27.00N 087.00W
  • You can mix and match +/- and N/S or E/W. If there is any conflict, these rules apply:
N/S/E/W beats +/- indicator after the coordinate overrides the one in front.
So for this poorly formed input:
S20.45+ W65.12E
the output would be:
20.56S 65.12E 
  • Latitude is followed by longitude.
  • Integer parts are padded with zeroes on the left. Decimal parts, i.e. the decimal seconds, are padded with zeroes on the right.
  • Default precision is 2 decimal places (esriCPOneHundredthSecond).
  • Y = N or S (unless localized)
    X = E or W (ditto)

Degrees Minutes Seconds (DMS)

Input
 
The DMS format includes the DD format and also covers DD MM.mm and DD MM SS.ss forms as well:
 
<dms> ::= <latitude> <coord-pair-separator>+ <longitude>
 
<coord-pair-separator> := "space" | "/" | "\" | "|"
 
<latitude> ::= ["+"|"-"|"N"|"S"] <latitude-coordinate-part> ["+"|"-"|"N"|"S"]
 
<longitude> ::= ["+"|"-"|"E"|"W"] <longitude-coordinate-part> ["+"|"-"|"E"|"W"]
 
<latitude-coordinate-part> ::= <lat-DD-DD> | <lat-DDMM-MM> | <lat-DDMMSS-SS>
 
<longitude-coordinate-part> ::= <lon-DD-DD> | <lon-DDMM-MM> | <lon-DDMMSS-SS>
 
<lat-DD-DD> ::= <lat-degrees> ["." <decimal>] [<degree-mark>]
 
<lat-DDMM-MM> ::= <lat-degrees> [<degree-mark>] <separator>
                            <minutes> [<minute-mark>] ["." <decimal>]
 
<lat-DDMMSS-SS> ::= <lat-degrees> [<degree-mark>] <separator>
                               <minutes> [<minute-mark>] <separator>
                               <seconds> [<second-mark>] ["." <decimal>]
 
<lat-degrees> ::= ? 0-90 ? (<decimal>)
 
<lon-degrees> ::= ? 0-360 ? (<decimal>)
 
<minutes> ::= ? 0-60 ?
 
<seconds> ::= ? 0-60 ?
 
<decimal> ::= {digit}
 
<separator>::= "space" | "underscore" | "hyphen"
 
<degree-mark> ::=   "Degree Sign °" | "Caret ^" | "Asterisk *"
 
<minute-mark> ::= "Minute Sign ' " | "Apostrophe ' "
 
<second-mark> ::= "Quotation Mark " "
 
Note:
 
<separator> can also appear before and after <latitude> and <longitude>
 
 
Examples of valid inputs:
 
27 18 00.00N 087 00 00.00W
27 18.00N 087 00.00W
27.3°N 87.0°W
27.3° -87.0°
 
 
Output
 
The normalized output for DMS is
DD MM SS.ssY DDD MM SS.ssX
Example:
27 18 00.00N 087 00 00.00W
NOTE:
  • Latitude is followed by longitude.
  • Integer parts are padded with zeroes on the left. Decimal parts, i.e., the decimal seconds, are padded with zeroes on the right.
  • Default precision is 2 decimal places (esriCPOneHundredthSecond).
  • Y = N or S (unless localized)
X = E or W (ditto)

Universal Transverse Mercator (UTM)

Input

Valid UTM input is specified as follows.

<utm> ::= <utm-zone> [<separator>+]
               <lat-band> [<separator>+]
               <easting>[<separator>+]
               <northing>
<utm-zone> ::= <digit><digit>
<lat-band> ::= <alpha-IO>
<easting> ::= 1..9 * <digit>
 
<northing> ::= 1..9 * <digit>         Note - easting size must match northing size
 
<ABC-minus-IO> ::= ? A-HJ-NP-Z ?
 
<separator> := "space"
 
<digit> ::= ? 0 - 9 ?
 
 
Examples:
 
15S 580817 4251205
35S 337123 3689239
NOTE:
  • Spaces are allowed in UTM format.
  • Leading zeroes are required (e.g., "08", not "8").
  • Setting the flag esriCTFlags_UTM_UseHemiIndicator will replace the <lat-band> with a hemisphere indicator "N" or "S". The hemisphere indicator can be localized as described above.
Output
Normalized output is:
ZZBGGEEEEENNNNN
ZZ = UTMZone    }  together these are sometimes called
B = LatBand        }  the Grid Zone Designator.
GG = ID100K      - grid square (UPS area for polar regions)
EEEEE = Coords (Eastings)
NNNNN = Coords (Northings)
UPS Version
ZAK4500045522
ZGG7902863771 
ATN2097136228

Military Grid Reference System (MGRS)

Input
 
MGRS uses a UTM-like format for most of the globe and UPS (Universal Polar Stereographic) for the polar regions.
 
<mgrs> ::= <mgrs-utm> | <ups>
 
<mgrs-utm> ::= <utm-zone> [<separator>+]
                       <lat-band> [<separator>+]
                       <id100k> [<separator>+]
                       <easting>[<separator>+]
                       <northing>
 
<utm-zone> ::= <digit><digit>
 
<lat-band> ::= <ABC-minus-IO>
 
<id100k> ::= <ABC-minus-IO><ABC-minus-IO>
 
<easting> ::= 1..9 * <digit>
 
<northing> ::= 1..9 * <digit>         Note - easting size must match northing size
 
<ABC-minus-IO> ::= ? A-HJ-NP-Z ?
 
<separator> := "space"
 
<digit> ::= ? 0 - 9 ?
 
<ups> ::= <ups-semicircular-zone-and hemisphere> [<separator>+]
              <id100k> [<separator>+]
              <easting><northing>
              <ups-semicircular-zone-and hemisphere> ::= "A" | "B" | "Y" | "X"
 
<id100k> ::= <ABC-minus-IO><ABC-minus-IO>
 
<easting> ::= 1..9 * <digit>
 
<northing> ::= 1..9 * <digit>         Note - easting size must match northing size
 
<ABC-minus-IO> ::= ? A-HJ-NP-Z ?
 
<separator> := "space"
 
<digit> ::= ? 0 - 9 ?
 
 
Examples of valid inputs:
 
MGRS (UTM Version)
15SWC8081751205
15S WC 80817 51205
35SLS37123468923872
 
MGRS (UPS Version)
Z AK 45000 45522
Z_GG_79028 63771
ATN2097136228
NOTE:
  • Spaces are allowed on input but not used for output.
  • MGRS really represents a square, the size of this square increases as the number of digits in the coordinate pair decrease. The Coordinate API returns the bottom-left coordinate of that square, for example:
 
30U WD 0171102591
x = -2.9748669185870140
y = 52.373584812851462
 
30U WD 017 025
x = -2.9750289602724944
y = 52.372766722000684
 
30U WD 00
x = -3.0000000000000004
y = 52.350293348850890
Output
Normalized output for MGRS (UTM version) is:
ZZBGGEEEEENNNNN
ZZ = UTMZone    }  together these are sometimes called
B = LatBand        }  the Grid Zone Designator
GG = ID100K       - grid square
EEEEE = Coords (Eastings)
NNNNN = Coords (Northings)
Examples:
19UET2572145169
37VCE5530543246
15XWJ2636381974
Normalized output for MGRS (UPS version) is:
ZZBGGEEEEENNNNN
Z = UPSZone   
GG = ID100K     (UPS Area/grid)
EEEEE = Coords (Eastings)
NNNNN = Coords (Northings)
Examples:
XWK4063625263
AXP8585015591
NOTE:
  • No spaces allowed on output, per standard.
  • Spaces are allowed on input.
  • Eastings are followed by Northings. The number of digits used for eastings must match the number for northings.

United States National Grid (USNG)

USNG is the same as MGRS with the following exceptions:
1. By default the output string uses spaces. Set the options flag esriCTFlags_USNG_AllowSpacesInOutput to false to change this.
2. There is an optional datum indicator at the end of the coordinate.
<datum> ::= "(N" {<any-char>]} <space> ("27" | "83") ")"
These are all valid datum indicators,
(Nad 1927)
(n27)
(NAD 27)
(NAD 83) this is the default
USNG examples:
15 S WC 80817 51205
15SWC8081751205
35S LS 37123 89239 (NAD 27)
Z AK 45 000 45 522

Output Modifiers
This section applies to all, or a number of, output formats.
Precision
Set the Precision property of the ICoordinate interface. This property affects only formatted string output. Specify the precision with one of these values of the esriCoordinatePrecision enumeration:
Enumeration Value
Description
Decimal places
esriCPOneDegree
1 degree
0
esriCPOneTenthDegree
0.1 degree
1
esriCPOneHundredthDegree
0.01 degree
2
esriCPOneThousandthDegree
0.001 degree
3
esriCPOneTenthThousandthDegree
0.0001 degree
4
 
 
 
esriCPOneSecond
1 second
0
esriCPOneTenthSecond
0.1 second
1
esriCPOneHundredthSecond
0.01 second
2
esriCPOneThousandthSecond
0.001 second
3
esriCPOneTenThousandthSecond
0.0001 second
4
 
 
 
esriCPOneHundredThousandMeter
100000m
-5
esriCPTenThousandMeter
10000m
-4
esriCPOneThousandMeter
1000m
-3
esriCPOneHundredMeter
100m
-2
esriCPTenMeter
10m
-1
 
 
 
esriCPOneMeter
1m
0
esriCPOneDecimeter
0.1m
1
esriCPOneCentimeter
0.01m
2
esriCPOneMillimeter
0.001m
3
NOTE:
Using these precision settings does not guarantee the accuracy of the output. Accuracy is dependent on the precision of the input data and any projections and datums used in the conversion.
Internationalization
You can change the characters used for some parts of the output through the resource-only DLL for your locale. The following characters are used throughout the Coordinate API:
IDS_N
IDS_S
IDS_E
IDS_W
IDS_MINUS
Custom Formatting
 
The FormattingExpression property of the ICoordinate interface can be used to modify the format of the output string.
For example, given the following formatting expression for DMS:
" %|1$02|° %|2$02| %|3$02|.%|4$|%|5$| %|6$03|° %|7$02| %|8$02|.%|9$|%|10$|"
an input coordinate string of “27.3N 87.0W” produces an output of:
27° 18' 00.00"N 087° 00' 00.00"W
Where:
1$, 2$, 3$, etc., represent the ordinal of the components of the coordinate format.
If the input has been successfully parsed then the arguments will be ordered as follows:
DD
1. Lat. Degrees
2. Lat. Decimal Degrees
3. Lat. Hemi
4. Lon. Degrees
5. Lon. Decimal Degrees
6. Lon. Hemisphere indicator
DMS
1. Lat. Degrees
2. Lat. Minutes
3. Lat. Seconds
4. Lat. Decimal Seconds
5. Lat. Hemi
6. Lon. Degrees
7. Lon. Minutes
8. Lon. Seconds
9. Lon. Decimal Seconds
10. Lon. Hemisphere indicator
UTM
1. UTM Zone
2. Lat Band
3. Easting
4. Northing
MGRS
1. UTM Zone
2. Lat Band
3. ID 100k
4. Coordinates(Easting Northing)
USNG
1. UTM Zone
2. Lat Band
3. ID 100k
4. Easting
5. Northing
6. Datum           Note - only populated if the datum is NAD 27.
02 = Indicates that the value will be padded with zeroes to a width of 2 characters. The result will be "05" instead of "5" or "00" instead of "0".
03  = Indicates that the value will be padded with zeroes to a width of 3 characters. Used for longitude degrees. For example, the result will be "087" instead of "87".
N.B.  You cannot change the number of decimal digits with the formatting expression.
The formatting expression follows the Boost Format specification (for details, go to http://www.boost.org/libs/format/doc/format.html).
It is also possible to modify the parsing regular expression. However the relative order of the capture groups must be maintained.


See Also:

Defense Solutions Library Overview - Converting Coordinates
United States Military Grid Reference System (MGRS)
White Paper: United States National Grid
Universal Transverse Mercator Grid (UTM)



Development licensing Deployment licensing
Engine Developer Kit: Military Analyst Engine Runtime: Military Analyst