Class MilitaryGridReferenceSystem

All Implemented Interfaces:
Serializable, Formattable, Deprecable, LenientComparable, org.opengis.referencing.IdentifiedObject, org.opengis.referencing.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: should display (locale may vary):

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
Version:
1.3
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • IDENTIFIER

      static final String IDENTIFIER
      Identifier for this reference system.
      See Also:
    • LATITUDE_BAND_HEIGHT

      static final double LATITUDE_BAND_HEIGHT
      Height of latitude bands, in degrees. Those bands are labeled from 'C' to 'X' inclusive, excluding 'I' and 'O'.
      See Also:
    • GRID_SQUARE_SIZE

      static final double GRID_SQUARE_SIZE
      Size of the 100 kilometres squares, in metres.
      See Also:
    • GRID_ROW_COUNT

      static final int GRID_ROW_COUNT
      Number of letters available for grid rows. Those letters are "ABCDEFGHJKLMNPQRSTUV" (starting at letter F for zones of even number), repeated in a cycle. Each row is 100000.0 metres height.
      See Also:
    • METRE_PRECISION_DIGITS

      static final int METRE_PRECISION_DIGITS
      The number of digits in a one-meter precision when formatting MGRS references.

      Invariant: the following relationship must hold: GRID_SQUARE_SIZE == Math.pow(10, METRE_PRECISION_DIGITS)

      See Also:
    • EXCLUDE_I

      private static final char EXCLUDE_I
      The first of the two letters ('I' and 'O') excluded in MGRS notation. This letter and all following letters shall be shifted by one character. Example: or equivalently:
      See Also:
    • EXCLUDE_O

      private static final char EXCLUDE_O
      The second of the two letters ('I' and 'O') excluded in MGRS notation.
      See Also:
    • POLAR_COLUMNS

      private static final byte[] POLAR_COLUMNS
      The column letters used in Polar Stereographic Projections. They are letters A to Z but omitting I, O, D, E, M, N, V, W.
    • ZONER

      private static final TransverseMercator.Zoner ZONER
      The object to use for computing zone number and central meridian. This is a static final field in current Apache SIS version, but could become configurable in a future version.
    • datum

      final CommonCRS datum
      The datum to which to transform the coordinate before formatting the MGRS reference. Only the datums enumerated in CommonCRS are currently supported.
    • avoidDatumChange

      final boolean avoidDatumChange
      Whether MilitaryGridReferenceSystem.Encoder should infer the datum from the given coordinates instead of using datum.
    • southOffset

      private transient short southOffset
      Value to add to the row number in order to have the "A" letter on the northernmost value on Greenwich meridian of the Universal Polar Stereographic (UPS) South projection. Value is initially zero and computed when first needed. This is derived from the bottom of the 100 kilometres square labeled "A" in Grid Zone Designations A and B.
    • northOffset

      private transient short northOffset
      Value to add to the row number in order to have the "A" letter on the southernmost value on Greenwich meridian of the Universal Polar Stereographic (UPS) North projection. Value is initially zero and computed when first needed. This is derived from the bottom of the 100 kilometres square labeled "A" in Grid Zone Designations Y and Z.
    • INSTANCE

      private static MilitaryGridReferenceSystem INSTANCE
      The unique instance, created when first requested.
  • Constructor Details

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

    • getInstance

      static MilitaryGridReferenceSystem getInstance()
      Returns the unique instance.
    • properties

      @Workaround(library="JDK", version="1.8") private static Map<String,?> properties()
      Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors").
    • types

      @Workaround(library="JDK", version="1.8") private static ModifiableLocationType[] types()
      Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors").
    • polarOffset

      final int polarOffset(boolean south) throws org.opengis.referencing.operation.TransformException
      Returns the value to add to the row number in order to have the "A" letter on the southernmost or northernmost value on Greenwich meridian of the Universal Polar Stereographic (UPS) projection. If south is true, then this is computed from the northernmost value of UPS South; otherwise this is computed from the southernmost value of UPS North. This value is derived from the bottom of the 100 kilometres square labeled "A" in Grid Zone Designations A, B, Y and Z.
      Throws:
      org.opengis.referencing.operation.TransformException
    • 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.
      Specified by:
      createCoder in class ReferencingByIdentifiers
      Returns:
      a new object performing conversions between DirectPosition and MGRS references.