Defense solutions coordinate API input-output formats

Summary The Defense Solutions coordinate application programming interface (API) supports several input and output formats used to convert coordinate values that a user, program, or data feed provides. 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 more information on how to use the Defense Solutions coordinate API, see Converting coordinates in the Defense Solutions library overview referenced in the See Also section at the bottom of this topic.

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.

In this topic

Input and output formats

An input format is the arrangement of data that the coordinate API accepts and uses. The normalized output format is the default format that the coordinate API produces as output. These formats can be modified by various settings or changed by setting the parsing and formatting expressions.

Key EBNF notations

The following table shows input format descriptions in a version of the Extended Backus–Naur form (EBNF):
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
??

Decimal degrees (DD)

  • Input—The DDCoordinate object validates and accepts input in 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 *"
The <separator> input form can also appear before and after <latitude> and <longitude>.
The following examples 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); for example, 27.00N 087.00W.
  • Mix and match +/- and N/S or E/W. If there are conflicts, the following rules apply:
    • N/S/E/W beats +/- indicator after the coordinate overrides the one in front; therefore, for the poorly formed input of S20.45+ W65.12E, the output is 20.56S 65.12E.
  • Latitude is followed by longitude.
  • Integer parts are padded with zeroes on the left. Decimal parts, that is, decimal seconds, are padded with zeroes on the right.
  • Default precision is two 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 the following DD MM.mm and DD MM SS.ss forms:
<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 " "
The <separator> input form can also appear before and after <latitude> and <longitude>.
The following are 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; for example, 27 18 00.00N 087 00 00.00W.
  • Latitude is followed by longitude.
  • Integer parts are padded with zeroes on the left. Decimal parts, that is, the decimal seconds, are padded with zeroes on the right.
  • Default precision is two decimal places (esriCPOneHundredthSecond).
  • Y = N or S (unless localized)
    X = E or W (ditto)

Universal Transverse Mercator (UTM)

  • Input—The following specifies the valid UTM input:

    <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>        
 
<ABC-minus-IO> ::= ? A-HJ-NP-Z ?
 
<separator> := "space"
 
<digit> ::= ? 0 - 9 ?
 
The following are examples of valid input:
 
15S 580817 4251205
35S 337123 3689239
Easting size must match the northing size.
  • Spaces are allowed in UTM format.
  • Leading zeroes are required; for example, "08", not "8".
  • Setting the flag esriCTFlags_UTM_UseHemiIndicator replaces the <lat-band> with a hemisphere indicator "N" or "S". The hemisphere indicator can be localized as previously shown.
  • Output—The following shows the normalized output for 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 the following UTM type format for most of the globe and Universal Polar Stereographic (UPS) 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>        

<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>        

<ABC-minus-IO> ::= ? A-HJ-NP-Z ?

<separator> := "space"

<digit> ::= ? 0 - 9 ?
 
The following are 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
Easting size must match the northing size.
  • Spaces are allowed on input, but not used for output.
  • MGRS represents a square. The size of the square increases as the number of digits in the coordinate pair decreases. The coordinate API returns the bottom-left coordinate of the square as shown in the following 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. See the following:

    ZZ = UTMZone    }  Together, these are sometimes called
    B = LatBand        }  the Grid Zone Designator.
    GG = ID100K       - grid square
    EEEEE = Coords (eastings)
    NNNNN = Coords (northings)

    The following are examples of valid output:

    19UET2572145169
    37VCE5530543246
    15XWJ2636381974

    Normalized output for MGRS (UPS version) is ZZBGGEEEEENNNNN. See the following:

    Z = UPSZone   
    GG = ID100K     (UPS Area/grid)
    EEEEE = Coords (eastings)
    NNNNN = Coords (northings)

    The following are examples of valid input:

    XWK4063625263
    AXP8585015591
  • 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:
  • By default the output string uses spaces. To change, set the options flag esriCTFlags_USNG_AllowSpacesInOutput to false.
  • The following is an optional datum indicator at the end of the coordinate:

    <datum> ::= "(N" {<any-char>]} <space> ("27" | "83") ")"

    The following are valid datum indicators:

    (Nad 1927)
    (n27)
    (NAD 27)
    (NAD 83) the default

    The following are USNG examples:

    15 S WC 80817 51205
    15SWC8081751205
    35S LS 37123 89239 (NAD 27)
    Z AK 45 000 45 522

Output modifiers

The following subsection 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 the values for the esriCoordinatePrecision enumeration. See the following table:
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
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 dynamic-link library (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 the following output of,
27° 18' 00.00"N 087° 00' 00.00"W,
where 1$, 2$, 3$, and so on, represent the ordinal of the components of the coordinate format.
If the input has been successfully parsed, 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. D 100k
  4. Coordinates (EastingNorthing)
USNG
  1. UTM zone
  2. Lat band
  1. ID 100k
  2. Easting
  3. Northing
  4. Datum           (Only populated if the datum is NAD 27.)
  • 02 = Indicates the value is padded with zeroes to a width of two characters. The result is "05" instead of "5", or "00" instead of "0".
  • 03 = Indicates the value is padded with zeroes to a width of three characters. Used for longitude degrees; for example, the result is "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 more information, see The Boost Format library.
It is also possible to modify the parsing regular expression; however, the relative order of the capture groups must be maintained.


See Also:

DefenseSolutions library overview - Converting coordinates
United States Military Grid Reference System (MGRS)
White Paper: United States National Grid
Universal Transverse Mercator (UTM) Grid



To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
Engine Developer Kit: Military Analyst Engine Runtime: Military Analyst
ArcView: Military Analyst
ArcEditor: Military Analyst
ArcInfo: Military Analyst