Class MilitaryGridReferenceSystem.Coder

java.lang.Object
org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers.Coder
org.apache.sis.referencing.gazetteer.MilitaryGridReferenceSystem.Coder
Direct Known Subclasses:
MilitaryGridReferenceSystem.IteratorOneZone
Enclosing class:
MilitaryGridReferenceSystem

public class MilitaryGridReferenceSystem.Coder extends ReferencingByIdentifiers.Coder
Conversions between direct positions and references in the Military Grid Reference System (MGRS). Each Coder instance can read references at arbitrary precision, but formats at the specified precision. The same Coder instance can be reused for reading or writing many MGRS references.

See the MilitaryGridReferenceSystem enclosing class for usage example.

Immutability and thread safety

This class is not thread-safe. A new instance must be created for each thread, or synchronization must be applied by the caller.
Since:
0.8
Version:
1.3
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private final class 
    Iterator over the cells inside all UPS and UTM zones inside a given area of interest.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final StringBuilder
    A buffer where to create reference, to be reused for each new reference.
    private boolean
    Whether the decoded locations should be clipped to the valid area of MGRS cell.
    private byte
    Number of digits to use for formatting the numerical part of a MGRS reference.
    private final Map<org.opengis.referencing.crs.CoordinateReferenceSystem,MilitaryGridReferenceSystem.Encoder>
    Cached information needed for building a MGRS reference from a direct position in the given CRS.
    (package private) org.opengis.geometry.DirectPosition
    Temporary positions used for encoding.
    (package private) org.opengis.geometry.DirectPosition
    Temporary positions used for encoding.
    private String
    The separator to insert between each component of the MGRS identifier, or an empty string if none.
    private String
    Same separator, but without leading and trailing spaces.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Creates a new coder initialized to the default precision and separator.
    (package private)
    Creates a new coder initialized to the same setting than the given separator.
  • Method Summary

    Modifier and Type
    Method
    Description
    decode(CharSequence reference)
    Decodes the given MGRS reference into a position and an envelope.
    (package private) final int
    For internal use by other internal classes in this Java source file.
    encode(org.opengis.geometry.DirectPosition position)
    Encodes the given position into a MGRS reference.
    encode(org.opengis.geometry.DirectPosition position, javax.measure.Quantity<?> precision)
    Encodes the given position into a MGRS reference with the given precision.
    encode(org.opengis.geometry.Envelope areaOfInterest)
    Returns an iterator over all MGRS references that intersect the given envelope.
    encode(org.opengis.geometry.Envelope areaOfInterest, boolean parallel)
    Returns a stream of all MGRS references that intersect the given envelope.
    (package private) final MilitaryGridReferenceSystem.Encoder
    encoder(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Returns the encoder for the given coordinate reference system.
    boolean
    Returns whether the decoded locations should be clipped to the valid area.
    (package private) final org.opengis.referencing.datum.Ellipsoid
    Returns the ellipsoid of the geodetic datum of MGRS identifiers.
    double
    Returns the precision of the references formatted by this coder.
    javax.measure.Quantity<javax.measure.quantity.Length>
    getPrecision(org.opengis.geometry.DirectPosition position)
    Returns the precision of the references formatted by this coder.
    Returns the reference system for which MGRS references will be encoded or decoded.
    Returns the separator to insert between each component of the MGRS identifier.
    (package private) final org.opengis.referencing.crs.ProjectedCRS
    projection(double latitude, double longitude)
    void
    setClipToValidArea(boolean clip)
    Sets whether the decoded locations should be clipped to the valid area.
    void
    setPrecision(double precision)
    Sets the desired precision of the references formatted by this coder.
    void
    setPrecision(javax.measure.Quantity<?> precision, org.opengis.geometry.DirectPosition position)
    Sets the desired precision of the references formatted by this coder.
    void
    setSeparator(String separator)
    Sets the separator to insert between each component of the MGRS identifier.

    Methods inherited from class org.apache.sis.referencing.gazetteer.ReferencingByIdentifiers.Coder

    recoverableException

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • digits

      private byte digits
      Number of digits to use for formatting the numerical part of a MGRS reference.
      See Also:
    • separator

      private String separator
      The separator to insert between each component of the MGRS identifier, or an empty string if none.
    • trimmedSeparator

      private String trimmedSeparator
      Same separator, but without leading and trailing spaces.
    • clipToValidArea

      private boolean clipToValidArea
      Whether the decoded locations should be clipped to the valid area of MGRS cell.
      See Also:
    • encoders

      private final Map<org.opengis.referencing.crs.CoordinateReferenceSystem,MilitaryGridReferenceSystem.Encoder> encoders
      Cached information needed for building a MGRS reference from a direct position in the given CRS.
    • normalized

      transient org.opengis.geometry.DirectPosition normalized
      Temporary positions used for encoding. References are kept for avoiding to recreate those temporary objects for every reference to parse or format.
    • geographic

      transient org.opengis.geometry.DirectPosition geographic
      Temporary positions used for encoding. References are kept for avoiding to recreate those temporary objects for every reference to parse or format.
    • buffer

      final StringBuilder buffer
      A buffer where to create reference, to be reused for each new reference.
  • Constructor Details

  • Method Details

    • getReferenceSystem

      public final MilitaryGridReferenceSystem getReferenceSystem()
      Returns the reference system for which MGRS references will be encoded or decoded.
      Specified by:
      getReferenceSystem in class ReferencingByIdentifiers.Coder
      Returns:
      the enclosing reference system.
      Since:
      1.3
    • getPrecision

      public double getPrecision()
      Returns the precision of the references formatted by this coder. This method returns one of the following values:
      MGRS reference precisions
      Precision (m) Reference example
      1 4 Q FJ 12345 67890
      10 4 Q FJ 1234 6789
      100 4 Q FJ 123 678
      1000 4 Q FJ 12 67
      10 000 4 Q FJ 1 6
      100 000 4 Q FJ
      (approximated) 1 000 000 4 Q
      Values smaller than 1 (e.g. 0.01 for a centimetre precision) may also be returned if that value has been explicitly set, but sub-metric precision are usually not used with MGRS.
      Returns:
      precision of formatted references in metres.
    • setPrecision

      public void setPrecision(double precision)
      Sets the desired precision of the references formatted by this coder. This method rounds the given precision to one of the power of 10 documented in the getPrecision() method.
      Parameters:
      precision - the desired precision in metres.
      Throws:
      ArithmeticException - if the given precision is zero, negative, infinity or NaN.
    • digits

      final int digits()
      For internal use by other internal classes in this Java source file.
    • getPrecision

      public javax.measure.Quantity<javax.measure.quantity.Length> getPrecision(org.opengis.geometry.DirectPosition position)
      Returns the precision of the references formatted by this coder. This method returns the same value as getPrecision() but as a quantity.
      Specified by:
      getPrecision in class ReferencingByIdentifiers.Coder
      Parameters:
      position - ignored (can be null).
      Returns:
      precision of formatted references in metres.
      Since:
      1.3
    • setPrecision

      public void setPrecision(javax.measure.Quantity<?> precision, org.opengis.geometry.DirectPosition position) throws javax.measure.IncommensurableException
      Sets the desired precision of the references formatted by this coder. If the given quantity uses angular units, it is converted to an approximate precision in metres at the latitude of given position. Then this method delegates to setPrecision(double).
      Specified by:
      setPrecision in class ReferencingByIdentifiers.Coder
      Parameters:
      precision - the desired precision in a linear or angular unit.
      position - location where the specified precision is desired, or null for the equator.
      Throws:
      javax.measure.IncommensurableException - if the given precision does not use linear or angular units.
      ArithmeticException - if the precision is zero, negative, infinity or NaN.
      Since:
      1.3
    • getEllipsoid

      final org.opengis.referencing.datum.Ellipsoid getEllipsoid()
      Returns the ellipsoid of the geodetic datum of MGRS identifiers.
    • getSeparator

      public String getSeparator()
      Returns the separator to insert between each component of the MGRS identifier. Components are zone number, latitude band, 100 000-metres square identifier and numerical values. By default the separator is an empty string, which produce references like "4QFJ12345678".
      Returns:
      the separator to insert between each component of the MGRS identifier, or an empty string if none.
    • setSeparator

      public void setSeparator(String separator)
      Sets the separator to insert between each component of the MGRS identifier. Components are zone number, latitude band, 100 000-metres square identifier and numerical values. By default the separator is an empty string, which produce references like "4QFJ12345678". If the separator is set to a space, then the references will be formatted like "4 Q FJ 1234 5678".

      Note that a MGRS reference is normally written as an entity without spaces, parentheses, dashes, or decimal points. Invoking this method with a non-empty separator produces non-conform MGRS, but is sometimes convenient for readability or for use in file systems (with the '/' separator).

      Parameters:
      separator - the separator to insert between each component of the MGRS identifier.
    • getClipToValidArea

      public boolean getClipToValidArea()
      Returns whether the decoded locations should be clipped to the valid area. The default value is true.
      Returns:
      true if decoded locations are clipped to the valid area.
    • setClipToValidArea

      public void setClipToValidArea(boolean clip)
      Sets whether the decoded locations should be clipped to the valid area. MGRS 100 km squares can actually be smaller than 100 km when the square overlaps two UTM zones or two latitude bands. We may have half of a square in a zone and the other half in the other zone. By default, the decode(CharSequence) method clips the square to the zone where it belongs. Invoking this method with the false value disables this behavior.
      Parameters:
      clip - whether the decoded locations should be clipped to the valid area.
    • projection

      final org.opengis.referencing.crs.ProjectedCRS projection(double latitude, double longitude)
    • encoder

      final MilitaryGridReferenceSystem.Encoder encoder(org.opengis.referencing.crs.CoordinateReferenceSystem crs) throws org.opengis.util.FactoryException, org.opengis.referencing.operation.TransformException
      Returns the encoder for the given coordinate reference system. All calls to this method must be done in the same thread.
      Throws:
      IllegalArgumentException - if the given CRS does not use one of the supported datums.
      org.opengis.util.FactoryException - if the creation of a coordinate operation failed.
      org.opengis.referencing.operation.TransformException - if the creation of an inverse operation failed.
    • encode

      public String encode(org.opengis.geometry.DirectPosition position) throws org.opengis.referencing.operation.TransformException
      Encodes the given position into a MGRS reference. The given position must have a Coordinate Reference System (CRS) associated to it.
      Specified by:
      encode in class ReferencingByIdentifiers.Coder
      Parameters:
      position - the coordinate to encode.
      Returns:
      MGRS encoding of the given position.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the given coordinate to a MGRS reference.
    • encode

      public String encode(org.opengis.geometry.DirectPosition position, javax.measure.Quantity<?> precision) throws javax.measure.IncommensurableException, org.opengis.referencing.operation.TransformException
      Encodes the given position into a MGRS reference with the given precision. This is equivalent to invoking setPrecision(Quantity, DirectPosition) before encode(DirectPosition), except that it is potentially more efficient.
      Overrides:
      encode in class ReferencingByIdentifiers.Coder
      Parameters:
      position - the coordinate to encode.
      precision - the desired precision in a linear or angular unit.
      Returns:
      MGRS encoding of the given position.
      Throws:
      ArithmeticException - if the precision is zero, negative, infinity or NaN.
      javax.measure.IncommensurableException - if the given precision does not use linear or angular units.
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the given coordinate to a MGRS reference.
      Since:
      1.3
    • encode

      public Iterator<String> encode(org.opengis.geometry.Envelope areaOfInterest) throws org.opengis.referencing.operation.TransformException
      Returns an iterator over all MGRS references that intersect the given envelope. The given envelope must have a Coordinate Reference System (CRS) associated to it. If the CRS is geographic, the envelope is allowed to span the anti-meridian. The MGRS references may be returned in any iteration order.
      Possible evolution: current implementation does not clip the cells to UPS/UTM valid areas before to test for intersection with areaOfInterest. Consequently, the iterator may return slightly more cells than expected. A future version may filter the cells more accurately. If an application needs the same set of cells than what current the implementation returns, it can invoke setClipToValidArea(false) for preserving current behavior in future Apache SIS versions.
      Parameters:
      areaOfInterest - envelope of desired MGRS references.
      Returns:
      an iterator over MGRS references intersecting the given area of interest.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the area of interest.
    • encode

      public Stream<String> encode(org.opengis.geometry.Envelope areaOfInterest, boolean parallel) throws org.opengis.referencing.operation.TransformException
      Returns a stream of all MGRS references that intersect the given envelope. The given envelope must have a Coordinate Reference System (CRS) associated to it. If the CRS is geographic, the envelope is allowed to span the anti-meridian. The MGRS references may be returned in any order.
      Possible evolution: current implementation does not clip the cells to UPS/UTM valid areas before to test for intersection with areaOfInterest. Consequently, the iterator may return slightly more cells than expected. A future version may filter the cells more accurately. If an application needs the same set of cells than what current the implementation returns, it can invoke setClipToValidArea(false) for preserving current behavior in future Apache SIS versions.
      Parameters:
      areaOfInterest - envelope of desired MGRS references.
      parallel - true for a parallel stream, or false for a sequential stream.
      Returns:
      a stream of MGRS references intersecting the given area of interest.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while transforming the area of interest.
    • decode

      public AbstractLocation decode(CharSequence reference) throws org.opengis.referencing.operation.TransformException
      Decodes the given MGRS reference into a position and an envelope. The Coordinate Reference System (CRS) associated to the returned position depends on the given reference.
      Upcoming API change — generalization
      in a future SIS version, the type of returned element may be generalized to the org.opengis.referencing.gazetteer.Location interface. This change is pending GeoAPI revision.
      Specified by:
      decode in class ReferencingByIdentifiers.Coder
      Parameters:
      reference - MGRS string to decode.
      Returns:
      a new position with the longitude at coordinate 0 and latitude at coordinate 1.
      Throws:
      org.opengis.referencing.operation.TransformException - if an error occurred while parsing the given string.