Package org.apache.sis.geometry

# Class CoordinateFormat

Object
Format
CompoundFormat<DirectPosition>
CoordinateFormat

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Localized`

public class CoordinateFormat extends CompoundFormat<DirectPosition>
Formats spatiotemporal coordinates using number, angle and date formats inferred from the coordinate system. The format for each coordinate is inferred from the coordinate system units using the following rules:

- Coordinate values in angular units are formatted as angles using `AngleFormat`.
- Coordinate values in temporal units are formatted as dates using `DateFormat`.
- Other values are formatted as numbers using `NumberFormat` followed by the unit symbol formatted by `UnitFormat`.

The format can be controlled by invoking the `applyPattern(Class, String)` public method, or by overriding the `CompoundFormat​.createFormat(Class)` protected method.

## Coordinate reference system

`CoordinateFormat` uses the `DirectPosition​.getCoordinateReferenceSystem()` value for determining how to format each coordinate value. If the position does not specify a coordinate reference system, then the default CRS is assumed. If no default CRS has been specified, then all coordinates are formatted as decimal numbers.

`CoordinateFormat` does not transform the given coordinates in a unique CRS. If the coordinates need to be formatted in a specific CRS, then the caller should transform the position before to format it.

Since:
  0.8
See Also:
  - `AngleFormat`
  - `UnitFormat`
  - `GeneralDirectPosition`
  - Serialized Form

Defined in the `sis-referencing` module

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Format

  `Format​.Field`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CoordinateFormat()`
  Constructs a new coordinate format with default locale and timezone.
  `CoordinateFormat(Locale locale, TimeZone timezone)`
  Constructs a new coordinate format for the specified locale and timezone.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `applyPattern(Class<?> valueType, String pattern)`
  Sets the pattern for number, angle or date fields.
  `CoordinateFormat`
  `clone()`
  Returns a clone of this format.
  `String`
  `format(DirectPosition position)`
  Formats the given coordinate.
  `void`
  `format(DirectPosition position, Appendable toAppendTo)`
  Formats the given coordinate and appends the resulting text to the given stream or buffer.
  `CoordinateReferenceSystem`
  `getDefaultCRS()`
  Returns the coordinate reference system to use if no CRS is explicitly associated to a given `DirectPosition`.
  `Quantity<?>`
  `getGroundAccuracy()`
  Returns the current ground accuracy value, or `null` if none.
  `Optional<String>`
  `getGroundAccuracyText()`
  Returns the textual representation of the current ground accuracy.
  `String`
  `getPattern(Class<?> valueType)`
  Returns the pattern for number, angle or date fields.
  `double[]`
  `getPrecisions()`
  Returns the precisions at which coordinate values are formatted in each dimension.
  `String`
  `getSeparator()`
  Returns the separator between each coordinate (number, angle or date).
  `final Class<DirectPosition>`
  `getValueType()`
  Returns the base type of values parsed and formatted by this `Format` instance.
  `DirectPosition`
  `parse(CharSequence text, ParsePosition pos)`
  Parses a coordinate from the given character sequence.
  `void`
  `setDefaultCRS(CoordinateReferenceSystem crs)`
  Sets the coordinate reference system to use if no CRS is explicitly associated to a given `DirectPosition`.
  `void`
  `setGroundAccuracy(Quantity<?> accuracy)`
  Specifies an uncertainty to append as "± accuracy" after the coordinate values.
  `void`
  `setGroundPrecision(Quantity<?> precision)`
  Adjusts the number of fraction digits to show in coordinates for achieving the given precision.
  `void`
  `setPrecision(double resolution, Unit<?> unit)`
  Deprecated.
  Renamed `setGroundPrecision(Quantity)` for avoiding confusion with `setPrecisions(double...)`.
  `void`
  `setPrecisions(double... precisions)`
  Sets the desired precisions at which to format coordinate values in each dimension.
  `void`
  `setSeparator(String separator)`
  Sets the separator between each coordinate.

  ### Methods inherited from class CompoundFormat

  `createFormat, format, getFormat, getLocale, getLocale, getTimeZone, parseObject, parseObject`

  ### Methods inherited from class Format

  `format, formatToCharacterIterator`

  ### Methods inherited from class Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### CoordinateFormat

    public CoordinateFormat()
    Constructs a new coordinate format with default locale and timezone.

  - ### CoordinateFormat

    public CoordinateFormat(Locale locale, TimeZone timezone)
    Constructs a new coordinate format for the specified locale and timezone.
    Parameters:
      `locale` - the locale for the new `Format`, or `null` for `Locale​.ROOT`.
      `timezone` - the timezone, or `null` for UTC.

- ## Method Details

  - ### getSeparator

    public String getSeparator()
    Returns the separator between each coordinate (number, angle or date). The default value is a single space.
    Returns:
      the current coordinate separator.

  - ### setSeparator

    public void setSeparator(String separator)
    Sets the separator between each coordinate. The default value is a single space.
    Parameters:
      `separator` - the new coordinate separator.

  - ### getDefaultCRS

    public CoordinateReferenceSystem getDefaultCRS()
    Returns the coordinate reference system to use if no CRS is explicitly associated to a given `DirectPosition`. This CRS determines the type of format to use for each coordinate (number, angle or date) and the number of fraction digits to use for achieving a specified precision on ground.
    Returns:
      the default coordinate reference system, or `null` if none.

  - ### setDefaultCRS

    public void setDefaultCRS(CoordinateReferenceSystem crs)
    Sets the coordinate reference system to use if no CRS is explicitly associated to a given `DirectPosition`. This CRS is only a default; positions given in another CRS are not automatically transformed to that CRS before formatting.
    Parameters:
      `crs` - the default coordinate reference system, or `null` if none.

  - ### getPrecisions

    public double[] getPrecisions()
    Returns the precisions at which coordinate values are formatted in each dimension. For example if coordinates in dimension i are formatted with two fraction digits, then the precision reported in `precisions[i]` will be 0.01. If the precision can not be determined for some dimensions, the corresponding values in the returned array will be 0.

    The values returned by this method are not necessarily equal to the values specified in the last call to `setPrecisions(double...)`. For example if a precision of 0.03 has been requested for a dimension whose coordinates are formatted as decimal numbers, then the actual precision returned by this method for that dimension will be 0.01.

    Returns:
      precision of coordinate values in each dimension (may contain 0 values for unknown precisions).
    Since:
      1.1
    See Also:
      - `AngleFormat​.getPrecision()`
      - `DecimalFormat​.getMaximumFractionDigits()`

  - ### setPrecisions

    public void setPrecisions(double... precisions)
    Sets the desired precisions at which to format coordinate values in each dimension. For example if `precisions[i]` is 0.05, then coordinates in dimension i will be shown with two fraction digits when formatted as decimal numbers, or with "D°MM" pattern when formatted as angles.

    This precision does not have a direct relationship to the precision on the ground. For example a precision of 0.01 could be one centimeter or 10 meters, depending if the units of measurement in that dimension is meter or kilometer. For a precision related to the ground, use `setGroundPrecision(Quantity)` instead.

    If any value in the given array is 0 or `Double​.NaN`, then there is a choice: if `setGroundPrecision(Quantity)` has been invoked, the precision specified to that method will apply (if possible). Otherwise an implementation-specific default precision is used. A typical use case is to use `setGroundPrecision(Quantity)` for specifying an horizontal precision in "real world" units and to use this `setPrecisions(double...)` method for adjusting the precision of the vertical axis only.

    Parameters:
      `precisions` - desired precision at which to format coordinate values in each dimension (may have 0 or `Double​.NaN` values for unspecified precisions in some of those dimensions), or `null` for restoring the default values.
    Since:
      1.1
    See Also:
      - `AngleFormat​.setPrecision(double, boolean)`
      - `DecimalFormat​.setMaximumFractionDigits(int)`

  - ### setPrecision

    @Deprecated public void setPrecision(double resolution, Unit<?> unit)
    Deprecated.
    Renamed `setGroundPrecision(Quantity)` for avoiding confusion with `setPrecisions(double...)`.
    Parameters:
      `resolution` - the desired resolution.
      `unit` - unit of the desired resolution.
    Since:
      1.0

  - ### setGroundPrecision

    public void setGroundPrecision(Quantity<?> precision)
    Adjusts the number of fraction digits to show in coordinates for achieving the given precision. The `NumberFormat` and `AngleFormat` are configured for coordinates expressed in the coordinate reference system of the position to format. The given resolution will be converted to the units used by coordinate system axes. For example if a 10 metres resolution is specified but the default CRS axes use kilometres, then this method converts the resolution to 0.01 kilometre and uses that value for inferring that coordinates should be formatted with 2 fraction digits. If the resolution is specified in an angular units such as degrees, this method uses the ellipsoid authalic radius for computing an equivalent resolution in linear units. For example if the ellipsoid of default CRS is WGS84, then this method considers a resolution of 1 second of angle as equivalent to a resolution of about 31 meters. Conversions work also in the opposite direction (from linear to angular units) and are also used for choosing which angle fields (degrees, minutes or seconds) to show.

    If both `setPrecisions(double...)` and `setGroundPrecision(Quantity)` are used, then the values specified with `setPrecisions(…)` have precedence and this ground precision is used only as a fallback. A typical use case is to specify the ground precision for horizontal dimensions, then to specify a different precision dz for the vertical axis only with `setPrecisions(NaN, NaN, dz)`.

    Parameters:
      `precision` - the desired precision together with its linear or angular unit.
    Since:
      1.1
    See Also:
      - `DecimalFormat​.setMaximumFractionDigits(int)`
      - `AngleFormat​.setPrecision(double, boolean)`
      - `Quantities​.create(double, Unit)`

  - ### setGroundAccuracy

    public void setGroundAccuracy(Quantity<?> accuracy)
    Specifies an uncertainty to append as "± accuracy" after the coordinate values. If no precisions have been specified, the accuracy will be always shown. But if precisions have been specified, then the accuracy will be shown only if equals or greater than the precision.
    Parameters:
      `accuracy` - the accuracy to append after the coordinate values, or `null` if none.
    Since:
      1.1
    See Also:
      - `getGroundAccuracy()`
      - `getGroundAccuracyText()`
      - `Quantities​.create(double, Unit)`

  - ### getGroundAccuracy

    public Quantity<?> getGroundAccuracy()
    Returns the current ground accuracy value, or `null` if none. This is the value given to the last call to `setGroundAccuracy(Quantity)`.
    Returns:
      the current ground accuracy value, or `null` if none.
    See Also:
      - `setGroundAccuracy(Quantity)`

  - ### getGroundAccuracyText

    public Optional<String> getGroundAccuracyText()
    Returns the textual representation of the current ground accuracy. Example: " ± 3 m" (note the leading space).
    Returns:
      textual representation of current ground accuracy.
    See Also:
      - `setGroundAccuracy(Quantity)`

  - ### getPattern

    public String getPattern(Class<?> valueType)
    Returns the pattern for number, angle or date fields. The given `valueType` should be `Number​.class`, `Angle​.class`, `Date​.class` or a sub-type of the above. This method may return `null` if the underlying format can not provide a pattern.

    Pattern availability for type of value
    Value type | Base format class | Format with pattern
    --- | --- | ---
    `Number` | `NumberFormat` | `DecimalFormat`
    `Angle` | `AngleFormat` | `AngleFormat`
    `Date` | `DateFormat` | `SimpleDateFormat`

    Parameters:
      `valueType` - the base type of coordinate values to parse and format: `Number​.class`, `Angle​.class` or `Date​.class`.
    Returns:
      the pattern for fields of the given type, or `null` if not applicable.
    See Also:
      - `CompoundFormat​.getFormat(Class)`

  - ### applyPattern

    public boolean applyPattern(Class<?> valueType, String pattern)
    Sets the pattern for number, angle or date fields. The pattern syntax depends on the `valueType` argument:
    - If `valueType` is `Number​.class`, then the pattern syntax shall be as described in the `DecimalFormat` class. This pattern may be used for any coordinate to be formatted as plain number, for example in Cartesian coordinate system.
    - If `valueType` is `Angle​.class`, then the pattern syntax shall be as described in the `AngleFormat` class. This pattern may be used for any coordinate to be formatted as latitude or longitude, for example in ellipsoidal coordinate system.
    - If `valueType` is `Date​.class`, then the pattern syntax shall be as described in the `SimpleDateFormat` class. This pattern may be used for any coordinate to be formatted as date and time, for example in time coordinate system.
    Parameters:
      `valueType` - the base type of coordinate values to parse and format: `Number​.class`, `Angle​.class` or `Date​.class`.
      `pattern` - the pattern as specified in `DecimalFormat`, `AngleFormat` or `SimpleDateFormat` javadoc.
    Returns:
      `true` if the pattern has been applied, or `false` if `valueType` does not specify a known type or if the format associated to that type does not support patterns.
    Throws:
      `IllegalArgumentException` - if the given pattern is invalid.

  - ### getValueType

    public final Class<DirectPosition> getValueType()
    Returns the base type of values parsed and formatted by this `Format` instance.
    Specified by:
      `getValueType` in class `CompoundFormat<DirectPosition>`
    Returns:
      `DirectPosition​.class`.

  - ### format

    public String format(DirectPosition position)
    Formats the given coordinate. The type of each coordinate value (number, angle or date) is determined by the CRS of the given position if such CRS is defined, or from the default CRS otherwise.
    Parameters:
      `position` - the coordinate to format.
    Returns:
      the formatted position.

  - ### format

    public void format(DirectPosition position, Appendable toAppendTo) throws IOException
    Formats the given coordinate and appends the resulting text to the given stream or buffer. The type of each coordinate value (number, angle or date) is determined by the CRS of the given position if such CRS is defined, or from the default CRS otherwise.
    Specified by:
      `format` in class `CompoundFormat<DirectPosition>`
    Parameters:
      `position` - the coordinate to format.
      `toAppendTo` - where the text is to be appended.
    Throws:
      `IOException` - if an error occurred while writing to the given appendable.

  - ### parse

    public DirectPosition parse(CharSequence text, ParsePosition pos) throws ParseException
    Parses a coordinate from the given character sequence. This method presumes that the coordinate reference system is the default CRS. The parsing begins at the index given by the `pos` argument. If parsing succeeds, then the `pos` index is updated to the index after the last coordinate value and the parsed coordinate is returned. Otherwise (if parsing fails), the `pos` index is left unchanged, the `pos` error index is set to the index of the first unparsable character and an exception is thrown with a similar error index.
    Specified by:
      `parse` in class `CompoundFormat<DirectPosition>`
    Parameters:
      `text` - the character sequence for the coordinate to parse.
      `pos` - the index where to start the parsing.
    Returns:
      the parsed coordinate (never `null`).
    Throws:
      `ParseException` - if an error occurred while parsing the coordinate.

  - ### clone

    public CoordinateFormat clone()
    Returns a clone of this format.
    Overrides:
      `clone` in class `CompoundFormat<DirectPosition>`
    Returns:
      a clone of this format.