Class DefaultCoordinateSystemAxis

  • All Implemented Interfaces:
    Serializable, CoordinateSystemAxis, IdentifiedObject

    public class DefaultCoordinateSystemAxis
    extends AbstractIdentifiedObject
    implements CoordinateSystemAxis
    Definition of a coordinate system axis. This is used to label axes, and indicate the orientation. See axis name constraints.

    In some case, the axis name is constrained by ISO 19111 depending on the coordinate reference system type. These constraints are identified in the javadoc by "ISO 19111 name is..." sentences. This constraint works in two directions; for example the names "geodetic latitude" and "geodetic longitude" shall be used to designate the coordinate axis names associated with a geographic coordinate reference system. Conversely, these names shall not be used in any other context.

    Since:
    2.1
    Author:
    Martin Desruisseaux (IRD)
    See Also:
    AbstractCS, Unit, Serialized Form
    • Constructor Detail

      • DefaultCoordinateSystemAxis

        public DefaultCoordinateSystemAxis​(CoordinateSystemAxis axis)
        Constructs a new coordinate system axis with the same values than the specified one. This copy constructor provides a way to wrap an arbitrary implementation into a Geotools one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API. This constructor performs a shallow copy, i.e. the properties are not cloned.
        Parameters:
        axis - The coordinate system axis to copy.
        Since:
        2.2
      • DefaultCoordinateSystemAxis

        public DefaultCoordinateSystemAxis​(Map<String,​?> properties,
                                           String abbreviation,
                                           AxisDirection direction,
                                           Unit<?> unit,
                                           double minimum,
                                           double maximum,
                                           RangeMeaning rangeMeaning)
        Constructs an axis from a set of properties. The properties map is given unchanged to the super-class constructor.
        Parameters:
        properties - Set of properties. Should contains at least "name".
        abbreviation - The abbreviation used for this coordinate system axes.
        direction - The direction of this coordinate system axis.
        unit - The unit of measure used for this coordinate system axis.
        minimum - The minimum value normally allowed for this axis.
        maximum - The maximum value normally allowed for this axis.
        rangeMeaning - The meaning of axis value range specified by the minimum and maximum values.
        Since:
        2.3
      • DefaultCoordinateSystemAxis

        public DefaultCoordinateSystemAxis​(Map<String,​?> properties,
                                           String abbreviation,
                                           AxisDirection direction,
                                           Unit<?> unit)
        Constructs an unbounded axis from a set of properties. The properties map is given unchanged to the super-class constructor. The minimum and maximum values are inferred from the axis unit and direction.
        Parameters:
        properties - Set of properties. Should contains at least "name".
        abbreviation - The abbreviation used for this coordinate system axes.
        direction - The direction of this coordinate system axis.
        unit - The unit of measure used for this coordinate system axis.
      • DefaultCoordinateSystemAxis

        public DefaultCoordinateSystemAxis​(String abbreviation,
                                           AxisDirection direction,
                                           Unit<?> unit)
        Constructs an axis with the same name as the abbreviation.
        Parameters:
        abbreviation - The abbreviation used for this coordinate system axes.
        direction - The direction of this coordinate system axis.
        unit - The unit of measure used for this coordinate system axis.
      • DefaultCoordinateSystemAxis

        public DefaultCoordinateSystemAxis​(InternationalString name,
                                           String abbreviation,
                                           AxisDirection direction,
                                           Unit<?> unit)
        Constructs an axis with a name as an international string and an abbreviation. The name of this identified object is set to the unlocalized version of the name argument, as given by name.toString(null). The same name argument is also stored as an alias, which allows fetching localized versions of the name.
        Parameters:
        name - The name of this axis. Also stored as an alias for localization purpose.
        abbreviation - The abbreviation used for this coordinate system axis.
        direction - The direction of this coordinate system axis.
        unit - The unit of measure used for this coordinate system axis.
    • Method Detail

      • getPredefined

        public static DefaultCoordinateSystemAxis getPredefined​(String name,
                                                                AxisDirection direction)
        Returns one of the predefined axis for the given name and direction, or null if none. This method searchs only in predefined constants like GEODETIC_LATITUDE, not in any custom axis instantiated by a public constructor. The name of those constants match ISO 19111 names or some names commonly found in Well Known Text (WKT) formats.

        This method first checks if the specified name matches the abbreviation of a predefined axis. The comparaison is case-sensitive (for example the GEOCENTRIC_X abbreviation is uppercase "X", while the abbreviation for the generic X axis is lowercase "x").

        If the specified name doesn't match any abbreviation, then this method compares the name against predefined axis name in a case-insensitive manner. Examples of valid names are "Geodetic latitude" and "Northing".

        The direction argument is optional and can be used in order to resolve ambiguity like X and DISPLAY_X axis. If this argument is null, then the first axis with a matching name or abbreviation will be returned.

        Parameters:
        name - The axis name or abbreviation.
        direction - An optional direction, or null.
        Returns:
        One of the constants declared in this class, or null.
        Since:
        2.4
      • getDirection

        public static AxisDirection getDirection​(String direction)
                                          throws NoSuchElementException
        Returns an axis direction constants from its name.
        Parameters:
        direction - The direction name (e.g. "north", "east", etc.).
        Returns:
        The axis direction for the given name.
        Throws:
        NoSuchElementException - if the given name is not a know axis direction.
      • getDirection

        public AxisDirection getDirection()
        Direction of this coordinate system axis. In the case of Cartesian projected coordinates, this is the direction of this coordinate system axis locally. Examples: north or south, east or west, up or down.

        Within any set of coordinate system axes, only one of each pair of terms can be used. For earth-fixed coordinate reference systems, this direction is often approximate and intended to provide a human interpretable meaning to the axis. When a geodetic datum is used, the precise directions of the axes may therefore vary slightly from this approximate direction.

        Note that an DefaultEngineeringCRS often requires specific descriptions of the directions of its coordinate system axes.

        Specified by:
        getDirection in interface CoordinateSystemAxis
        Returns:
        The coordinate system axis direction.
      • getAbbreviation

        public String getAbbreviation()
        The abbreviation used for this coordinate system axes. This abbreviation is also used to identify the ordinates in coordinate tuple. Examples are "X" and "Y".
        Specified by:
        getAbbreviation in interface CoordinateSystemAxis
        Returns:
        The coordinate system axis abbreviation.
      • getUnit

        public Unit<?> getUnit()
        The unit of measure used for this coordinate system axis. The value of this coordinate in a coordinate tuple shall be recorded using this unit of measure, whenever those coordinates use a coordinate reference system that uses a coordinate system that uses this axis.
        Specified by:
        getUnit in interface CoordinateSystemAxis
        Returns:
        The coordinate system axis unit.
      • getMinimumValue

        public double getMinimumValue()
        Returns the minimum value normally allowed for this axis, in the unit of measure for the axis. If there is no minimum value, then this method returns negative infinity.
        Specified by:
        getMinimumValue in interface CoordinateSystemAxis
        Returns:
        The minimum value, or Double.NEGATIVE_INFINITY if none.
        Since:
        2.3
      • getMaximumValue

        public double getMaximumValue()
        Returns the maximum value normally allowed for this axis, in the unit of measure for the axis. If there is no maximum value, then this method returns negative infinity.
        Specified by:
        getMaximumValue in interface CoordinateSystemAxis
        Returns:
        The maximum value, or Double.POSITIVE_INFINITY if none.
        Since:
        2.3
      • getRangeMeaning

        public RangeMeaning getRangeMeaning()
        Returns the meaning of axis value range specified by the minimum and maximum values. This element shall be omitted when both minimum and maximum values are omitted. It may be included when minimum and/or maximum values are included. If this element is omitted when minimum or maximum values are included, the meaning is unspecified.
        Specified by:
        getRangeMeaning in interface CoordinateSystemAxis
        Returns:
        The range meaning, or null in none.
        Since:
        2.3
      • isCompassDirection

        public static boolean isCompassDirection​(AxisDirection direction)
        Returns true if the specified direction is a compass direction. Compass directions include "North", "North-North-East", "North-East", etc.
        Parameters:
        direction - The axis direction to test.
        Returns:
        true if the given direction is a compass direction.
        Since:
        2.4
      • getAngle

        public static double getAngle​(AxisDirection source,
                                      AxisDirection target)
        Returns the arithmetic (counterclockwise) angle from the first direction to the second direction, in decimal degrees. This method returns a value between -180° and +180°, or NaN if no angle can be computed.

        A positive angle denotes a right-handed system, while a negative angle denotes a left-handed system. Example:

        • The angle from EAST to NORTH is 90°
        • The angle from SOUTH to WEST is -90°
        • The angle from "North along 90 deg East" to "North along 0 deg" is 90°.
        Parameters:
        source - The source axis direction.
        target - The target axis direction.
        Returns:
        The arithmetic angle (in degrees) of the rotation to apply on a line pointing toward the source direction in order to make it point toward the target direction, or Double.NaN if this value can't be computed.
        Since:
        2.4
      • perpendicular

        public static boolean perpendicular​(AxisDirection first,
                                            AxisDirection second)
        Returns true if the specified directions are perpendicular.
        Parameters:
        first - The first axis direction to test.
        second - The second axis direction to test.
        Returns:
        true if the given axis direction are perpendicular.
        Since:
        2.4
      • nameMatches

        public boolean nameMatches​(String name)
        Returns true if either the primary name or at least one alias matches the specified string. This method performs all the searh done by the super-class, with the addition of special processing for latitudes and longitudes:

        • "Lat", "Latitude" and "Geodetic latitude" are considered equivalent.
        • "Lon", "Longitude" and "Geodetic longitude" are considered equivalent.

        The above special cases are needed in order to workaround a conflict in specifications: ISO 19111 explicitly state that the latitude and longitude axis names shall be "Geodetic latitude" and "Geodetic longitude", will legacy OGC 01-009 (where WKT is defined) said that the default values shall be "Lat" and "Lon".

        Overrides:
        nameMatches in class AbstractIdentifiedObject
        Parameters:
        name - The name to compare.
        Returns:
        true if the primary name of at least one alias matches the specified name.
      • equals

        public boolean equals​(AbstractIdentifiedObject object,
                              boolean compareMetadata)
        Compares the specified object with this axis for equality.
        Overrides:
        equals in class AbstractIdentifiedObject
        Parameters:
        object - The object to compare to this.
        compareMetadata - true for performing a strict comparaison, or false for comparing only properties relevant to transformations.
        Returns:
        true if both objects are equal.
      • hashCode

        public int hashCode()
        Returns a hash value for this axis. This value doesn't need to be the same in past or future versions of this class.
        Overrides:
        hashCode in class AbstractIdentifiedObject
        Returns:
        The hash code value. This value doesn't need to be the same in past or future versions of this class.