Class MilitaryGridReferenceSystem
java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.referencing.AbstractIdentifiedObject
org.apache.sis.referencing.AbstractReferenceSystem
org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers
org.apache.sis.referencing.gazetteer.MilitaryGridReferenceSystem
- All Implemented Interfaces:
Serializable
,Formattable
,Deprecable
,LenientComparable
,org.opengis.referencing.IdentifiedObject
,org.opengis.referencing.ReferenceSystem
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, theCoder
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionclass
Conversions between direct positions and references in the Military Grid Reference System (MGRS).(package private) static final class
The result of decoding a MGRS reference.(package private) static final class
Conversions from direct positions to Military Grid Reference System (MGRS) references.private final class
Iterator over the cells in a single UTM or UPS zone. -
Field Summary
FieldsModifier and TypeFieldDescription(package private) final boolean
WhetherMilitaryGridReferenceSystem.Encoder
should infer the datum from the given coordinates instead of usingdatum
.(package private) final CommonCRS
The datum to which to transform the coordinate before formatting the MGRS reference.private static final char
The first of the two letters ('I'
and'O'
) excluded in MGRS notation.private static final char
The second of the two letters ('I'
and'O'
) excluded in MGRS notation.(package private) static final int
Number of letters available for grid rows.(package private) static final double
Size of the 100 kilometres squares, in metres.(package private) static final String
Identifier for this reference system.private static MilitaryGridReferenceSystem
The unique instance, created when first requested.(package private) static final double
Height of latitude bands, in degrees.(package private) static final int
The number of digits in a one-meter precision when formatting MGRS references.private short
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.private static final byte[]
The column letters used in Polar Stereographic Projections.private static final long
For cross-version compatibility.private short
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.private static final TransverseMercator.Zoner
The object to use for computing zone number and central meridian.Fields inherited from class org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers
locationTypes, OVERALL_OWNER_KEY, THEME_KEY
Fields inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
DEPRECATED_KEY, LOCALE_KEY
Fields inherited from interface org.opengis.referencing.IdentifiedObject
ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
Fields inherited from interface org.opengis.referencing.ReferenceSystem
DOMAIN_OF_VALIDITY_KEY, SCOPE_KEY
-
Constructor Summary
ConstructorsConstructorDescriptionCreates 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
Modifier and TypeMethodDescriptionReturns a new object performing conversions betweenDirectPosition
and MGRS references.(package private) static MilitaryGridReferenceSystem
Returns the unique instance.(package private) final int
polarOffset
(boolean south) 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.Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors").private static ModifiableLocationType[]
types()
Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors").Methods inherited from class org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers
computeHashCode, equals, formatTo, getLocationTypes, getOverallOwner, getTheme, properties, rootType
Methods inherited from class org.apache.sis.referencing.AbstractReferenceSystem
getDomainOfValidity, getInterface, getScope
Methods inherited from class org.apache.sis.referencing.AbstractIdentifiedObject
castOrCopy, equals, formatTo, getAlias, getDescription, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.referencing.IdentifiedObject
getAlias, getIdentifiers, getName, getRemarks, toWKT
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
IDENTIFIER
Identifier for this reference system.- See Also:
-
LATITUDE_BAND_HEIGHT
static final double LATITUDE_BAND_HEIGHTHeight 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_SIZESize of the 100 kilometres squares, in metres.- See Also:
-
GRID_ROW_COUNT
static final int GRID_ROW_COUNTNumber 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_DIGITSThe 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_IThe 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_OThe second of the two letters ('I'
and'O'
) excluded in MGRS notation.- See Also:
-
POLAR_COLUMNS
private static final byte[] POLAR_COLUMNSThe column letters used in Polar Stereographic Projections. They are letters A to Z but omitting I, O, D, E, M, N, V, W. -
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
The datum to which to transform the coordinate before formatting the MGRS reference. Only the datums enumerated inCommonCRS
are currently supported. -
avoidDatumChange
final boolean avoidDatumChangeWhetherMilitaryGridReferenceSystem.Encoder
should infer the datum from the given coordinates instead of usingdatum
. -
southOffset
private transient short southOffsetValue 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 northOffsetValue 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
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
Creates a new Military Grid Reference System (MGRS) using the specified datum. Only the datums enumerated inCommonCRS
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, ornull
for inferring the datum from the CRS associated to each coordinate.
-
-
Method Details
-
getInstance
Returns the unique instance. -
properties
Work around for RFE #4093999 in Sun's bug database ("Relax constraint on placement of this()/super() call in constructors"). -
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. Ifsouth
istrue
, 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
Returns a new object performing conversions betweenDirectPosition
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 classReferencingByIdentifiers
- Returns:
- a new object performing conversions between
DirectPosition
and MGRS references.
-