Package org.apache.sis.referencing.gazetteer

## Class MilitaryGridReferenceSystem

- Object
- - FormattableObject
  - - AbstractIdentifiedObject
    - - AbstractReferenceSystem
      - - ReferencingByIdentifiers
        - - MilitaryGridReferenceSystem

- All Implemented Interfaces:
    `Serializable`, `Deprecable`, `LenientComparable`, `IdentifiedObject`, `ReferenceSystem`

      public class MilitaryGridReferenceSystem
      extends ReferencingByIdentifiers

  The Military Grid Reference System (MGRS). The MGRS is the geocoordinate standard used by NATO militaries for locating points on the earth. It is based on the Universal Transverse Mercator (UTM) and the Universal Polar Stereographic (UPS) projections. Despite its name, MGRS is used not only for military purposes; it is used also for organizing Earth Observation data in directory trees for example.

  MGRS references are sequences of digits and letters like “4Q FJ 12345 67890” (a reference with 1 metre accuracy), optionally written with reduced resolution as in “4Q FJ 123 678” (a reference with 100 metres accuracy). Those references form a hierarchy of 3 location types:

  > Grid zone designator (example: “4Q”)
  > └─100 km square identifier (example: “FJ”)
  > └─Grid coordinate (example: “12345 67890”)

  Conversions between MGRS references and spatial coordinates can be performed by the `Coder` inner class. The result of decoding a MGRS reference is an envelope rather than a point, but a representative point can be obtained. The encoding and decoding processes take in account Norway and Svalbard special cases (they have wider UTM zones for historical reasons).

  Example: the following code:

  >     MilitaryGridReferenceSystem system = new MilitaryGridReferenceSystem();
  >     MilitaryGridReferenceSystem.Coder coder = system.createCoder();
  >     Location loc = coder.decode("32TNL83");
  >     System.out.println(loc);

  should display (locale may vary):

  >     ┌─────────────────────────────────────────────────────────────────┐
  >     │ Location type:               Grid coordinate                    │
  >     │ Geographic identifier:       32TNL83                            │
  >     │ West bound:                    580,000 m    —     9°57′00″E     │
  >     │ Representative value:          585,000 m    —    10°00′36″E     │
  >     │ East bound:                    590,000 m    —    10°04′13″E     │
  >     │ South bound:                 4,530,000 m    —    40°54′58″N     │
  >     │ Representative value:        4,535,000 m    —    40°57′42″N     │
  >     │ North bound:                 4,540,000 m    —    41°00′27″N     │
  >     │ Coordinate reference system: WGS 84 / UTM zone 32N              │
  >     │ Administrator:               North Atlantic Treaty Organization │
  >     └─────────────────────────────────────────────────────────────────┘

  Immutability and thread safety
  This class is immutable and thus thread-safe. However the `Coder` instances performing conversions between references and coordinates are not thread-safe; it is recommended to create a new `Coder` instance for each thread.
  Since:
    0.8
  See Also:
    `CommonCRS​.universal(double, double)`, Military Grid Reference System on Wikipedia, Serialized Form

  Defined in the `sis-referencing-by-identifiers` module

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `class` | `MilitaryGridReferenceSystem.Coder` | Conversions between direct positions and references in the Military Grid Reference System (MGRS).

  - ### Field Summary

    - ### Fields inherited from class ReferencingByIdentifiers

      `OVERALL_OWNER_KEY, THEME_KEY`

    - ### Fields inherited from class AbstractIdentifiedObject

      `DEPRECATED_KEY, LOCALE_KEY`

    - ### Fields inherited from interface IdentifiedObject

      `ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY`

    - ### Fields inherited from interface ReferenceSystem

      `DOMAIN_OF_VALIDITY_KEY, SCOPE_KEY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MilitaryGridReferenceSystem()` | Creates a new Military Grid Reference System (MGRS) using the default datum.
    `MilitaryGridReferenceSystem​(Map<String,​?> properties, CommonCRS datum)` | Creates a new Military Grid Reference System (MGRS) using the specified datum.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `MilitaryGridReferenceSystem.Coder` | `createCoder()` | Returns a new object performing conversions between `DirectPosition` and MGRS references.

    - ### Methods inherited from class ReferencingByIdentifiers

      `computeHashCode, equals, formatTo, getLocationTypes, getOverallOwner, getTheme`

    - ### Methods inherited from class AbstractReferenceSystem

      `getDomainOfValidity, getInterface, getScope`

    - ### Methods inherited from class AbstractIdentifiedObject

      `castOrCopy, equals, getAlias, getDescription, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName`

    - ### Methods inherited from class FormattableObject

      `print, toString, toString, toWKT`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface IdentifiedObject

      `getAlias, getIdentifiers, getName, getRemarks, toWKT`

- - ### Constructor Detail

    - #### MilitaryGridReferenceSystem

          public MilitaryGridReferenceSystem()

      Creates a new Military Grid Reference System (MGRS) using the default datum. The current Apache SIS version uses the WGS84 datum, but this choice may change in the future if there is a need to adapt to new MGRS specifications.

    - #### MilitaryGridReferenceSystem

          public MilitaryGridReferenceSystem​(Map<String,​?> properties,
                                             CommonCRS datum)

      Creates a new Military Grid Reference System (MGRS) using the specified datum. Only the datums enumerated in `CommonCRS` are currently supported.
      Parameters:
        `properties` - the properties to be given to the reference system.
        `datum` - the datum to which to transform coordinates before formatting the MGRS references, or `null` for inferring the datum from the CRS associated to each coordinate.

  - ### Method Detail

    - #### createCoder

          public MilitaryGridReferenceSystem.Coder createCoder()

      Returns a new object performing conversions between `DirectPosition` and MGRS references. The returned object is not thread-safe; a new instance must be created for each thread, or synchronization must be applied by the caller.
      Returns:
        a new object performing conversions between `DirectPosition` and MGRS references.