Class CoordinateFormat

java.lang.Object
java.text.Format
org.apache.sis.io.CompoundFormat<org.opengis.geometry.DirectPosition>
org.apache.sis.geometry.CoordinateFormat
All Implemented Interfaces:
Serializable, Cloneable, Localized

public class CoordinateFormat extends CompoundFormat<org.opengis.geometry.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 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
Version:
1.3
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    Desired resolution in a given units, together with methods for converting to the units of a coordinate system axis.

    Nested classes/interfaces inherited from class java.text.Format

    Format.Field
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private String
    Text to append to the coordinate values for giving an indication about accuracy, or null if none.
    private double
    Value of desiredPrecisions which cause accuracyText to be shown.
    private static final byte
    Constants for the types array.
    private StringBuffer
    Temporary buffer to use if the toAppendTo argument given to format(DirectPosition, Appendable) is not an instance of StringBuffer.
    private static final byte
    Constants for the types array.
    private static final int
    Maximal number of dimensions to use when parsing a coordinate without defaultCRS.
    private org.opengis.referencing.crs.CoordinateReferenceSystem
    The coordinate reference system to assume if no CRS is attached to the position to format.
    private double[]
    The desired precisions for each coordinate, or null if unspecified.
    private String[]
    Directions symbols ("E", "N", "SW", etc.) to append after coordinate values for some dimensions, including leading space.
    Dummy field position.
    private long[]
    The time epochs.
    private Format[]
    The formats to use for formatting each coordinate value, or null if not yet computed.
    private javax.measure.Quantity<?>
    The declared accuracy on ground, or null if unspecified.
    private long
    The dimensions on which groundPrecision applies, specified as a bitmask.
    private javax.measure.Quantity<?>
    The desired ground precision, or null if unspecified.
    private static final byte
    Constants for the types array.
    private boolean
    Whether to append the accuracy after coordinate values.
    private boolean
    Whether this CoordinateFormat instance has been configured for the precision and accuracy specified by groundPrecision, desiredPrecisions and groundAccuracy.
    private org.opengis.referencing.crs.CoordinateReferenceSystem
    The coordinate reference system of the last DirectPosition that we parsed or formatted.
    private static final byte
    Constants for the types array.
    private static final byte
    Constants for the types array.
    private long
    Flags the coordinate values that need to be inverted before to be formatted.
    private String
    The separator without spaces, or an empty string if the separator contains only white spaces.
    private static final int
    Maximal number of characters to convert to String if the text to parse is not a string instance.
    private static final Set<javax.measure.Unit<?>>
    Units of measurement which are allowed to be automatically scaled to a larger unit.
    private String
    The separator between each coordinate values to be formatted.
    private static final long
    Serial number for cross-version compatibility.
    private Format[]
    The format instances given by CompoundFormat.getFormat(Class), to use by default when we have not been able to configure the precision.
    private static final byte
    Constants for the types array.
    private javax.measure.UnitConverter[]
    Conversions from arbitrary units to the unit used by formatter, or null if none.
    private byte[]
    The type for each value in the formats array, or null if not yet computed.
    private javax.measure.Unit<?>[]
    The units for each dimension to be formatted as a number with an unit of measurement.
    private String[]
    Units symbols to append after coordinate values for each dimension, including leading space.
    private String[]
    Same as unitSymbols but without the changes applied by setPrecisions(double...).
  • Constructor Summary

    Constructors
    Constructor
    Description
    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
    private void
    applyGroundAccuracy(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Updates the accuracyThreshold for the current groundAccuracy value (which may be null) and the given coordinate reference system.
    private void
    applyGroundPrecision(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Configures the formats for groundPrecision value.
    boolean
    applyPattern(Class<?> valueType, String pattern)
    Sets the pattern for number, angle or date fields.
    private void
    applyPrecision(int dim)
    Sets the pattern of the format for the specified dimension according the desired precision.
    Returns a clone of this format.
    private void
    configure(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Computes the values of transient fields from the given CRS and configure the format precisions.
    protected Format
    createFormat(Class<?> valueType)
    Creates a new format to use for parsing and formatting values of the given type.
    private void
    createFormats(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Computes the values of transient fields from the given CRS.
    format(org.opengis.geometry.DirectPosition position)
    Formats the given coordinate.
    void
    format(org.opengis.geometry.DirectPosition position, Appendable toAppendTo)
    Formats the given coordinate and appends the resulting text to the given stream or buffer.
    org.opengis.referencing.crs.CoordinateReferenceSystem
    Returns the coordinate reference system to use if no CRS is explicitly associated to a given DirectPosition.
    private Format
    The default format to use when no CRS or no axis information is available.
    private Format
    getFormatClone(int dim)
    Returns a clone of the format at the specified dimension.
    javax.measure.Quantity<?>
    Returns the current ground accuracy value, or null if none.
    Returns the textual representation of the current ground accuracy.
    getPattern(Class<?> valueType)
    Returns the pattern for number, angle or date fields.
    double[]
    Returns the precisions at which coordinate values are formatted in each dimension.
    Returns the separator between each coordinate (number, angle or date).
    final Class<org.opengis.geometry.DirectPosition>
    Returns the base type of values parsed and formatted by this Format instance.
    private boolean
    isNegative(int dimension)
    Returns true if the value at the given dimension needs to have its sign reversed.
    private void
    negate(int dimension)
    Remembers that coordinate values at the given dimension will need to have their sign reverted.
    org.opengis.geometry.DirectPosition
    Parses a coordinate from the given character sequence.
    private void
    Invoked on deserialization for restoring some transient fields.
    private <Q extends javax.measure.Quantity<Q>>
    void
    scaleUnit(int i, javax.measure.Unit<Q> unit)
    Replaces the "m" or "Pa" units of measurement in the given dimension by "km" or "kPa" or other units.
    private void
    setConverter(int dimension, int i, javax.measure.UnitConverter c)
    Sets at the given index a conversion from CRS units to units used by this formatter.
    void
    setDefaultCRS(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Sets the coordinate reference system to use if no CRS is explicitly associated to a given DirectPosition.
    void
    setGroundAccuracy(javax.measure.Quantity<?> accuracy)
    Specifies an uncertainty to append as "± accuracy" after the coordinate values.
    void
    setGroundPrecision(javax.measure.Quantity<?> precision)
    Adjusts the number of fraction digits to show in coordinates for achieving the given precision.
    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.
    private static String
    symbol(org.opengis.referencing.cs.AxisDirection direction)
    Returns the symbol ("E", "N", "SW", etc.) for given axis direction.
    private static void
    Invoked when an expected error occurred but continuation is still possible.
    private void
    Updates the isAccuracyVisible flag according current values of accuracyText, accuracyThreshold and desiredPrecisions.

    Methods inherited from class org.apache.sis.io.CompoundFormat

    format, getFormat, getLocale, getLocale, getTimeZone, parseObject, parseObject

    Methods inherited from class java.text.Format

    format, formatToCharacterIterator

    Methods inherited from class java.lang.Object

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

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for cross-version compatibility.
      See Also:
    • READ_AHEAD_LIMIT

      private static final int READ_AHEAD_LIMIT
      Maximal number of characters to convert to String if the text to parse is not a string instance. This is an arbitrary limit that may change (or be removed) in any future SIS version.
      See Also:
    • DEFAULT_DIMENSION

      private static final int DEFAULT_DIMENSION
      Maximal number of dimensions to use when parsing a coordinate without defaultCRS. This is an arbitrary limit that may change (or be removed) in any future SIS version. To avoid this limitation, users are encouraged to specify a default CRS.
      See Also:
    • SCALABLES

      private static final Set<javax.measure.Unit<?>> SCALABLES
      Units of measurement which are allowed to be automatically scaled to a larger unit. For example if the unit of measurement of an axis is meter but the precision is 1000 metres, then CoordinateFormat will automatically uses kilometres units instead of metres.
    • separator

      private String separator
      The separator between each coordinate values to be formatted. The default value is a EM space space (U+2003).
      See Also:
    • parseSeparator

      private transient String parseSeparator
      The separator without spaces, or an empty string if the separator contains only white spaces. This is used at parsing time only.
    • groundPrecision

      private javax.measure.Quantity<?> groundPrecision
      The desired ground precision, or null if unspecified. This precision may not apply to all axes. The "ground axes" dimensions are identified by the bits set in the groundDimensions bitmask.
      See Also:
    • groundAccuracy

      private javax.measure.Quantity<?> groundAccuracy
      The declared accuracy on ground, or null if unspecified. The accuracy applies to the same axes than groundPrecision. But contrarily to groundPrecision, the accuracy does not change the number of fraction digits used by NumberFormat. Instead, it causes a text such as "± 30 m" to be appended after the coordinates.
      See Also:
    • accuracyThreshold

      private transient double accuracyThreshold
      Value of desiredPrecisions which cause accuracyText to be shown. For each dimension identified by groundDimensions, if the corresponding value in desiredPrecisions is equal or smaller to this threshold, then accuracyText will be appended after the formatted coordinates.
      See Also:
    • groundDimensions

      private transient long groundDimensions
      The dimensions on which groundPrecision applies, specified as a bitmask. This bitmask is computed by applyGroundPrecision(CoordinateReferenceSystem) when first needed. The current heuristic rules are:
      • All axes having a compass direction if at least one of those axes uses an unit of measurement compatible with the unit of groundPrecision (possibly after conversion between linear and angular units on a sphere).
      • Otherwise all axes using compatible units, regardless their direction and without conversion between linear and angular units.
    • desiredPrecisions

      private double[] desiredPrecisions
      The desired precisions for each coordinate, or null if unspecified. The unit of measurement is given by CoordinateSystemAxis.getUnit(). The length of this array does not need to be equal to the number of dimensions; extraneous values are ignored and missing values are assumed equal to 0. A value of 0 means to use the default precision for that dimension.

      Note that this is the precision specified by the user, which may differ from the precision returned by getPrecisions().

      See Also:
    • isPrecisionApplied

      private transient boolean isPrecisionApplied
      Whether this CoordinateFormat instance has been configured for the precision and accuracy specified by groundPrecision, desiredPrecisions and groundAccuracy. We use a field separated from lastCRS because precision and accuracy threshold need to be set only for formatting, not for parsing.
      See Also:
    • isAccuracyVisible

      private transient boolean isAccuracyVisible
      Whether to append the accuracy after coordinate values. This flag is true if accuracyText is non-null and one of the following conditions is true: This flag is valid only if isPrecisionApplied is true.
    • defaultCRS

      private org.opengis.referencing.crs.CoordinateReferenceSystem defaultCRS
      The coordinate reference system to assume if no CRS is attached to the position to format. May be null.
      See Also:
    • lastCRS

      private transient org.opengis.referencing.crs.CoordinateReferenceSystem lastCRS
      The coordinate reference system of the last DirectPosition that we parsed or formatted. This is used for determining if we need to recompute all other transient fields in this class.
      See Also:
    • LONGITUDE

      private static final byte LONGITUDE
      Constants for the types array.
      See Also:
    • LATITUDE

      private static final byte LATITUDE
      Constants for the types array.
      See Also:
    • ANGLE

      private static final byte ANGLE
      Constants for the types array.
      See Also:
    • DATE

      private static final byte DATE
      Constants for the types array.
      See Also:
    • TIME

      private static final byte TIME
      Constants for the types array.
      See Also:
    • INDEX

      private static final byte INDEX
      Constants for the types array.
      See Also:
    • types

      private transient byte[] types
      The type for each value in the formats array, or null if not yet computed. Types are: 0=number, 1=longitude, 2=latitude, 3=other angle, 4=date, 5=elapsed time, 6=index.

      This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation, and stay unmodified after creation.

      See Also:
    • sharedFormats

      private transient Format[] sharedFormats
      The format instances given by CompoundFormat.getFormat(Class), to use by default when we have not been able to configure the precision. This is the same array than formats, unless setPrecisions(double...) has been invoked. Values at different indices may reference the same Format instance.
      See Also:
    • formats

      private transient Format[] formats
      The formats to use for formatting each coordinate value, or null if not yet computed. The length of this array should be equal to the number of dimensions in lastCRS. Values at different indices may reference the same Format instance.
      See Also:
    • units

      private transient javax.measure.Unit<?>[] units
      The units for each dimension to be formatted as a number with an unit of measurement. We do not store Unit instances for dimensions to be formatted as angles or dates because those quantities are formatted with specialized Format instances working in fixed units; no unit symbol should appear after dates or DD°MM′SS″ angles.

      We use this units array at parsing time for converting numbers from the units of measurement in the parsed text to units expected by this CoordinateFormat. Whether an element is non-null determines whether an unit symbol is allowed to appear in the text to parse for the corresponding dimension.

      All non-null elements in this array are CoordinateSystemAxis.getUnit() return values. This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation, and stay unmodified after creation.

      See Also:
    • toFormatUnit

      private transient javax.measure.UnitConverter[] toFormatUnit
      Conversions from arbitrary units to the unit used by formatter, or null if none. For example if coordinate at dimension i is formatted as an angle, then toFormatUnit[i] is the conversion from angular axis units to decimal degrees before those degrees are formatted as DD°MM′SS″ with AngleFormat. Note that in this case, units[i] == null for telling that no unit symbol should appear after the coordinate formatted in dimension i (because degree, minute and second symbols are handled by AngleFormat instead).

      In addition to conversions required by formatters expecting values in fixed units of measurement, toFormatUnit[i] may also be non-null for some coordinates formatted as numbers if a different unit of measurement is desired. For example, the converter may be non-null if some coordinates in metres should be shown in kilometres. In those cases, units[i] != null.

      This array is used in slightly different ways at parsing time and formatting time. At formatting time, coordinate values and unconditionally converted using all converters and the units array is ignored. At parsing time, toFormatUnit[i] converters are used only in dimensions i where the parser requires a fixed unit which is implicit in the text (units[i] == null). For other dimensions accepting various units (units[i] != null), the converter to use is determined by the unit of measurement written in the text.

      This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation. It may be modified after creation as a result of setPrecisions(double...) calls, for example for replacing a "m" unit by "km".

      See Also:
    • unitSymbols

      private transient String[] unitSymbols
      Units symbols to append after coordinate values for each dimension, including leading space. This is used only for coordinates to be formatted as ordinary numbers with NumberFormat. This array is non-null only if at least one dimension needs to format its coordinates that way.

      Units symbols may be followed by axis direction symbols used for axes on the ground ("E", "N", "SW", etc.) so the complete symbol may be for example "km E". Those direction symbols are stored in a separated array; they are not part of elements of this unitSymbols array.

      This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation. It may be modified after creation as a result of setPrecisions(double...) calls, for example for replacing a "m" unit by "km".

    • unitSymbolsUnscaled

      private transient String[] unitSymbolsUnscaled
      Same as unitSymbols but without the changes applied by setPrecisions(double...). This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation, and stay unmodified after creation.
      See Also:
    • directionSymbols

      private transient String[] directionSymbols
      Directions symbols ("E", "N", "SW", etc.) to append after coordinate values for some dimensions, including leading space. This is used only for some coordinates formatted with NumberFormat. This array is non-null only if at least one dimension needs to format its coordinates that way. The length of this array is twice the number of dimensions. The array contains this tuple:
      1. Symbol of axis direction (at even indices)
      2. Symbol in the direction opposite to axis direction (at odd indices)

      This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation, and stay unmodified after creation.

    • accuracyText

      private transient String accuracyText
      Text to append to the coordinate values for giving an indication about accuracy, or null if none. Example: " ± 1 m" (note the leading space). This is determined by the groundAccuracy value. If desiredPrecisions array is non-null, then accuracy is shown only if a precision is smaller.
      See Also:
    • negate

      private transient long negate
      Flags the coordinate values that need to be inverted before to be formatted. This is needed for example if the axis is oriented toward past instead of future, or toward west instead of east.
      See Also:
    • epochs

      private transient long[] epochs
      The time epochs. Non-null only if the at least on coordinate is to be formatted as a date.

      This array is created by createFormats(CoordinateReferenceSystem), which is invoked before parsing or formatting in a different CRS than last operation, and stay unmodified after creation.

    • dummy

      private transient FieldPosition dummy
      Dummy field position.
    • buffer

      private transient StringBuffer buffer
      Temporary buffer to use if the toAppendTo argument given to format(DirectPosition, Appendable) is not an instance of StringBuffer.
  • 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 org.opengis.referencing.crs.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(org.opengis.referencing.crs.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.
    • createFormats

      private void createFormats(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Computes the values of transient fields from the given CRS. The lastCRS field is set to the given CRS for allowing callers to check if this method needs to be invoked again (this method does not check by itself). This method does not configure the formats for precisions specified by setPrecisions(double...) and related methods; that work is done by configure(CoordinateReferenceSystem) at formatting time (it is not needed at parsing time).
      Parameters:
      crs - the CRS for which to create the Format instances.
      See Also:
    • symbol

      private static String symbol(org.opengis.referencing.cs.AxisDirection direction)
      Returns the symbol ("E", "N", "SW", etc.) for given axis direction.
    • getFormatClone

      private Format getFormatClone(int dim)
      Returns a clone of the format at the specified dimension. Format instances are cloned only when first needed. The clones are needed when we want to change the format pattern (number of fraction digits, etc.) for only one dimension, without impacting other dimensions that may use the same format.
    • getDefaultFormat

      private Format getDefaultFormat()
      The default format to use when no CRS or no axis information is available. The coordinate type could be anything (a date, an angle, …), but since we have no information we assume a number. This method is defined for making clearer when such fallback is used.
    • setConverter

      private void setConverter(int dimension, int i, javax.measure.UnitConverter c)
      Sets at the given index a conversion from CRS units to units used by this formatter.
      Parameters:
      dimension - number of dimensions of the coordinate system.
      i - index of the dimension for which to set the converter.
      c - the converter to set at the given dimension.
    • scaleUnit

      private <Q extends javax.measure.Quantity<Q>> void scaleUnit(int i, javax.measure.Unit<Q> unit)
      Replaces the "m" or "Pa" units of measurement in the given dimension by "km" or "kPa" or other units. This is invoked for modifying the format created by createFormats(CoordinateReferenceSystem) according the value given to setPrecisions(double...).

      Limitation

      Current implementation assumes that there is only one scale factor allowed by CoordinateFormat, which is 1000. If a future SIS version allows different scale factors, then we would need to make the if (toFormatUnit[i] == null) check more accurate in applyPrecision(int) method.
      Parameters:
      i - index of the dimension for which to change the unit.
      unit - value of units[dimension].
    • negate

      private void negate(int dimension)
      Remembers that coordinate values at the given dimension will need to have their sign reverted.
    • isNegative

      private boolean isNegative(int dimension)
      Returns true if the value at the given dimension needs to have its sign reversed.
    • 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 cannot 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:
    • 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:
    • applyPrecision

      private void applyPrecision(int dim)
      Sets the pattern of the format for the specified dimension according the desired precision. The format to configure is formats[dim] and the pattern will be constructed from the desiredPrecisions[dim] value. Caller must ensure that the given dimension is valid for both formats and desiredPrecisions arrays.
    • configure

      private void configure(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Computes the values of transient fields from the given CRS and configure the format precisions. This method updates the lastCRS and isPrecisionApplied fields. This method does nothing if above-cited fields are already up to date.
      Parameters:
      crs - the CRS for which to create and configure the Format instances.
      See Also:
    • setGroundPrecision

      public void setGroundPrecision(javax.measure.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:
    • setGroundAccuracy

      public void setGroundAccuracy(javax.measure.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:
    • applyGroundPrecision

      private void applyGroundPrecision(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Configures the formats for groundPrecision value. Contrarily to applyPrecision(int), this method modifies the default formats provided by CompoundFormat.getFormat(Class). They are the formats stored in the sharedFormats array. Those formats are used as fallback when the formats array does not provide more specific format.

      It is caller responsibility to ensure that groundPrecision is non-null before to invoke this method.

      Parameters:
      crs - the target CRS in the conversion from ground units to CRS units.
    • applyGroundAccuracy

      private void applyGroundAccuracy(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Updates the accuracyThreshold for the current groundAccuracy value (which may be null) and the given coordinate reference system.
    • updateAccuracyVisibility

      private void updateAccuracyVisibility()
      Updates the isAccuracyVisible flag according current values of accuracyText, accuracyThreshold and desiredPrecisions.
    • getGroundAccuracy

      public javax.measure.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:
    • 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:
    • 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 cannot 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:
    • 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<org.opengis.geometry.DirectPosition> getValueType()
      Returns the base type of values parsed and formatted by this Format instance.
      Specified by:
      getValueType in class CompoundFormat<org.opengis.geometry.DirectPosition>
      Returns:
      DirectPosition.class.
    • createFormat

      protected Format createFormat(Class<?> valueType)
      Creates a new format to use for parsing and formatting values of the given type. This method is invoked by CompoundFormat.getFormat(Class) the first time that a format is needed for the given type.

      See super-class for a description of recognized types. This method override uses the short date pattern instead of the (longer) default one.

      Overrides:
      createFormat in class CompoundFormat<org.opengis.geometry.DirectPosition>
      Parameters:
      valueType - the base type of values to parse or format.
      Returns:
      the format to use for parsing of formatting values of the given type, or null if none.
    • format

      public String format(org.opengis.geometry.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(org.opengis.geometry.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<org.opengis.geometry.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.
      ArithmeticException - if a date value exceed the capacity of long type.
    • parse

      public org.opengis.geometry.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<org.opengis.geometry.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.
    • unexpectedException

      private static void unexpectedException(String method, Exception error)
      Invoked when an expected error occurred but continuation is still possible.
      Parameters:
      method - the public method to report as the source of the log record.
      error - the error that occurred.
    • clone

      public CoordinateFormat clone()
      Returns a clone of this format.
      Overrides:
      clone in class CompoundFormat<org.opengis.geometry.DirectPosition>
      Returns:
      a clone of this format.
    • readObject

      private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException
      Invoked on deserialization for restoring some transient fields.
      Parameters:
      in - the input stream from which to deserialize a coordinate format
      Throws:
      IOException - if an I/O error occurred while reading or if the stream contains invalid data.
      ClassNotFoundException - if the class serialized on the stream is not on the classpath.