Package com.luciad.text.mgrs

Class TLcdMGRSFormat

java.lang.Object
java.text.Format
com.luciad.text.mgrs.TLcdMGRSFormat
All Implemented Interfaces:
ILcdFormatter, ILcdParser, Serializable, Cloneable
public class TLcdMGRSFormat extends Format implements ILcdFormatter, ILcdParser
Class to format points as MGRS or UTM/UPS coordinates. It can also parse a MGRS or UTM/UPS coordinate String into a point object.

When creating a new TLcdMGRSFormat, an ellipsoid can be passed. The points converted from and to a MGRS string are lon lat points defined in a reference using this ellipsoid.

This class offers methods to format coordinates into either UTM MGRS, UPS MGRS, UTM or UPS notation. The UTM MGRS and UTM notations are used for coordinates within the UTM latitude bounds, see TLcdUTMGridSystem.NORTH_LAT_LIMIT and TLcdUTMGridSystem.SOUTH_LAT_LIMIT. For points in the polar regions, outside the UTM latitude bounds, the UPS MGRS and UPS notations are used.

Since:
11.0
See Also:

  • Constructor Details

    • TLcdMGRSFormat

      public TLcdMGRSFormat()
      Creates a new TLcdMGRSFormat that uses the WGS_84 ellipsoid for its calculations.

    • TLcdMGRSFormat

      public TLcdMGRSFormat(String aFormat)
      Creates a new TLcdGARSFormat that uses the WGS 84 ellipsoid and the given format to format an ILcdPoint.

      The format should be expressed in the following EBNF notation (expressions enclosed in [] brackets are optional, expressions enclosed in {} brackets may be omitted or repeated): 

       <pattern>             ::= <gridZone>, [[<zoneSeparator>] <100kmSquare>], [[<coordinateSeparator>] <easting>], [[<coordinateSeparator>] <northing>]
 <gridZone>            ::= "G"
 <100kmSquare>         ::= "S"
 <easting>             ::= "E" | "E", <precision>
 <northing>            ::= "N" | "N", <precision>
 <precision>           ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
 <zoneSeparator>       ::= { ? any character ? }
 <coordinateSeparator> ::= { ? any character ? }
      For example:
      • "17TPJ 30084 33438" has format "GS E5 N5"
      • "Z" has format "G"

      The easting and northing values are respective to the 100 km squares if they are present, or the grid zones otherwise.

      Parameters:
      aFormat - a format string, never null
      Throws:
      NullPointerException - if aFormat is null.
      Since:
      2021.1

    • TLcdMGRSFormat

      public TLcdMGRSFormat(ILcdEllipsoid aEllipsoid)
      Creates a new TLcdMGRSFormat that uses the given ellipsoid for its calculations.
      Parameters:
      aEllipsoid - a given ellipsoid.

  • Method Details

    • getPattern

      public String getPattern()
      Returns the MGRS pattern used as described in TLcdMGRSFormat(String).
      Returns:
      the current MGRS pattern in EBNF format
      Since:
      2021.1

    • getFormatType

      public TLcdMGRSFormat.FormatType getFormatType()
      Returns the used format type.
      Returns:
      the used format type.

    • setFormatType

      public void setFormatType(TLcdMGRSFormat.FormatType aFormatType)
      Sets the used format type.
      Parameters:
      aFormatType - the format type.

    • getCoordinateSeparator

      public char getCoordinateSeparator()
      Returns the character to separate the zone/grid letters and the coordinates.
      Returns:
      the character to separate the zone/grid letters and the coordinates.
      See Also:

    • setCoordinateSeparator

      public void setCoordinateSeparator(char aCoordinateSeparator)
      Set the character to separate the zone/grid letters and the coordinates and between the coordinates. Set the value 0 (not the character '0') to have no spaces between the zone and the coordinates.
      Parameters:
      aCoordinateSeparator - the character to separate the zone/grid letters and the coordinates and between the coordinates.
      See Also:

    • getZoneSeparator

      public char getZoneSeparator()
      Returns the character to separate the grid zone and the 100km squares when formatting MGRS strings.
      Returns:
      the character to separate the grid zone and the 100km squares when formatting MGRS strings.
      See Also:

    • setZoneSeparator

      public void setZoneSeparator(char aZoneSeparator)

      Sets the character to use as separator between the grid zone and the 100km squares when formatting MGRS strings. Set the value to 0 (not the character '0') to have no separator between the grid zone and the 100km squares.

      The default is 0.

      Parameters:
      aZoneSeparator - the character to separate the grid zone and the 100km squares.
      See Also:

    • getNumberOfDigits

      @Deprecated public int getNumberOfDigits()
      Deprecated.
      Use getPrecision()
      Returns the number of digits used to format a MGRS or UTM/UPS String.
      Returns:
      the number of digits used to format a MGRS String.

    • setNumberOfDigits

      @Deprecated public void setNumberOfDigits(int aNumberOfDigits)
      Deprecated.
      Use setPrecision(TLcdMGRSFormat.FormatPrecision)
      Sets the number of digits used to format a MGRS or UPS String.

      When formatting points as MGRS Strings, the number of digits used by default is 5. When the number of digits used is 5, the MGRS String has a precision of 1m. When the number of digits used is 4, the precision is 10m, etc...

      When formatting points as UTM/UPS Strings, the number of digits used by default is 7. When the number of digits used is 7, the MGRS String has a precision of 1m. When the number of digits used is 6, the precision is 10m, etc...

      Parameters:
      aNumberOfDigits - the number of digits used to format a MGRS or UPS/UTM String.

    • getPrecision

      public TLcdMGRSFormat.FormatPrecision getPrecision()
      Returns the precision used to format a MGRS or UTM/UPS String.
      Returns:
      the precision used to format a MGRS String.

    • setPrecision

      public void setPrecision(TLcdMGRSFormat.FormatPrecision aPrecision) throws IllegalArgumentException
      Sets the precision used to format a MGRS or UPS String. By default a precision of 1 meter is used. Precision of 1000KM and Zone precision can only be used to format UTM/UPS coordinates.
      Parameters:
      aPrecision - the precision used to format a MGRS or UPS/UTM String.
      Throws:
      IllegalArgumentException - If the format type is MGRS and the format precision is of 1000KM or zone precision.

    • format

      public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
      Specified by:
      format in class Format
      Parameters:
      obj - The object to format. This should be an ILcdPoint.

    • parseObject

      public Object parseObject(String source, ParsePosition pos)

      The parsed Object is an ILcdPoint.

      Specified by:
      parseObject in class Format
      Returns:
      An ILcdPoint parsed from the string. In case of error, returns null.

    • parse

      public Object parse(String aString) throws IllegalArgumentException
      Description copied from interface: ILcdParser
      Parses a given String and creates a new Object with the corresponding type/properties.
      Specified by:
      parse in interface ILcdParser
      Parameters:
      aString - the String to be parsed.
      Returns:
      the resulting new Object.
      Throws:
      IllegalArgumentException - if the String can't be parsed.