Package org.apache.sis.internal.referencing

Class AxisDirections

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.referencing.AxisDirections
public final class AxisDirections extends Static
Utilities methods related to AxisDirection.
Since:
0.4
Version:
1.3

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final Map<org.opengis.referencing.cs.AxisDirection,String>
    ABBREVIATIONS
    Proposed abbreviations for some axis directions.
    static final org.opengis.referencing.cs.AxisDirection
    AWAY_FROM
    Distance from the origin in a polar coordinate system.
    static final org.opengis.referencing.cs.AxisDirection
    CLOCKWISE
    Direction of geographic angles (bearing).
    static final int
    COMPASS_COUNT
    Number of directions like "North", "North-North-East", "North-East", etc.
    static final org.opengis.referencing.cs.AxisDirection
    COUNTER_CLOCKWISE
    Direction of arithmetic angles.
    static final int
    DISPLAY_COUNT
    Number of directions like "Display right", "Display down", etc.
    private static final byte[]
    DISPLAY_ORDER
    Maps RIGHT, LEFT, UP, DOWN display order to UP, RIGHT, DOWN, LEFT.
    static final org.opengis.referencing.cs.AxisDirection
    FORWARD
    Forward direction.
    static final int
    GEOCENTRIC_COUNT
    Number of geocentric directions.
    private static final int
    LAST_ORDINAL
    Ordinal of the last element in the AxisDirection code list.
    private static final Map<org.opengis.referencing.cs.AxisDirection,org.opengis.referencing.cs.AxisDirection>
    OPPOSITES
    For each direction, the opposite direction.
    static final org.opengis.referencing.cs.AxisDirection
    STARBOARD
    Starboard direction.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    AxisDirections()
    Do not allow instantiation of this class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static org.opengis.referencing.cs.AxisDirection
    absolute(org.opengis.referencing.cs.AxisDirection dir)
    Returns the "absolute" direction of the given direction.
    static int
    angleForCompass(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
    Arithmetic angle between compass directions only (not for angle between direction along meridians).
    static int
    angleForDisplay(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
    Arithmetic angle between display directions only.
    static int
    angleForGeocentric(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
    Angle between geocentric directions only.
    static int
    angleForVehicle(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
    Arithmetic angle between forward/aft/port/starboard directions only.
    static String
    appendTo(StringBuilder buffer, org.opengis.referencing.cs.CoordinateSystemAxis[] axes)
    Builds a coordinate system name from the given array of axes.
    private static boolean
    contains(String name, String keyword, boolean end)
    Returns true if the given name starts or ends with the given keyword, ignoring case.
    private static boolean
    equalsIgnoreCase(String name, int lower, int upper, String keyword)
    Returns true if the given sub-sequence is equal to the given keyword, ignoring case.
    static org.opengis.referencing.cs.AxisDirection
    find(String name, org.opengis.referencing.cs.AxisDirection[] directions)
    Searches for an axis direction having the given name in the specified list of directions.
    static org.opengis.referencing.cs.AxisDirection
    fromAbbreviation(char abbreviation)
    Returns an axis direction for the given abbreviation.
    static javax.measure.Unit<javax.measure.quantity.Angle>
    getAngularUnit(org.opengis.referencing.cs.CoordinateSystem cs, javax.measure.Unit<javax.measure.quantity.Angle> fallback)
    Returns the angular unit of the specified coordinate system.
    static int
    indexOfColinear(org.opengis.referencing.cs.CoordinateSystem cs, org.opengis.referencing.cs.AxisDirection direction)
    Finds the dimension of an axis having the given direction or its opposite.
    static int
    indexOfColinear(org.opengis.referencing.cs.CoordinateSystem cs, org.opengis.referencing.cs.CoordinateSystem subCS)
    Returns the index of the first dimension in cs where axes are colinear with the subCS axes.
    static int[]
    indicesOfLenientMapping(org.opengis.referencing.cs.CoordinateSystem cs, org.opengis.referencing.cs.CoordinateSystem subCS)
    Returns the indices of cs axes presumed covariant with subCS axes.
    static boolean
    isCardinal(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the specified direction is cardinal direction.
    static boolean
    isColinear(org.opengis.referencing.cs.AxisDirection d1, org.opengis.referencing.cs.AxisDirection d2)
    Returns whether the second axis is colinear with the first axis.
    static boolean
    isCompass(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the specified direction is a compass direction.
    static boolean
    isGeocentric(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the given direction is GEOCENTRIC_X, GEOCENTRIC_Y or GEOCENTRIC_Z.
    static boolean
    isGrid(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the given direction is COLUMN_POSITIVE, COLUMN_NEGATIVE, ROW_POSITIVE or ROW_NEGATIVE.
    static boolean
    isIntercardinal(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the specified direction is an inter-cardinal direction.
    static boolean
    isOpposite(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the given direction is an "opposite" direction.
    static boolean
    isSpatialOrUserDefined(org.opengis.referencing.cs.AxisDirection dir, boolean image)
    Returns true if the given direction is a spatial axis direction (including vertical and geocentric axes).
    static boolean
    isTemporal(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the given direction is FUTURE or PAST.
    static boolean
    isUserDefined(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the given direction is a user-defined direction (i.e.
    static boolean
    isVertical(org.opengis.referencing.cs.AxisDirection dir)
    Returns true if the given direction is UP or DOWN.
    static org.opengis.referencing.cs.AxisDirection
    opposite(org.opengis.referencing.cs.AxisDirection dir)
    Returns the opposite direction of the given direction.
    private static void
    put(org.opengis.referencing.cs.AxisDirection dir, org.opengis.referencing.cs.AxisDirection opposite)
    Stores the given directions in the OPPOSITES array.
    static String
    suggestAbbreviation(String name, org.opengis.referencing.cs.AxisDirection direction, javax.measure.Unit<?> unit)
    Suggests an abbreviation for the given axis direction.
    static org.opengis.referencing.cs.AxisDirection
    valueOf(String name)
    Searches predefined AxisDirection for a given name.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • COMPASS_COUNT

      public static final int COMPASS_COUNT
      Number of directions like "North", "North-North-East", "North-East", etc. The first of those directions is AxisDirection.NORTH.
      See Also:

    • GEOCENTRIC_COUNT

      public static final int GEOCENTRIC_COUNT
      Number of geocentric directions. The first of those directions is AxisDirection.GEOCENTRIC_X.
      See Also:

    • DISPLAY_COUNT

      public static final int DISPLAY_COUNT
      Number of directions like "Display right", "Display down", etc. The first of those directions is AxisDirection.DISPLAY_RIGHT.
      See Also:

    • LAST_ORDINAL

      private static final int LAST_ORDINAL
      Ordinal of the last element in the AxisDirection code list. This is used for differentiating the standard codes from the user-defined ones.
      See Also:

    • FORWARD

      @UML(identifier="forward", obligation=CONDITIONAL, specification=UNSPECIFIED) public static final org.opengis.referencing.cs.AxisDirection FORWARD
      Forward direction. For an observer at the centre of the object this is will be towards its front, bow or nose. Added in ISO 19111:2019 (was not in ISO 19111:2007).
      Since:
      1.3

    • STARBOARD

      @UML(identifier="starboard", obligation=CONDITIONAL, specification=UNSPECIFIED) public static final org.opengis.referencing.cs.AxisDirection STARBOARD
      Starboard direction. For an observer at the centre of the object this will be towards its right. Added in ISO 19111:2019 (was not in ISO 19111:2007).
      Since:
      1.3

    • CLOCKWISE

      @UML(identifier="clockwise", obligation=CONDITIONAL, specification=UNSPECIFIED) public static final org.opengis.referencing.cs.AxisDirection CLOCKWISE
      Direction of geographic angles (bearing). Added in ISO 19111:2019 (was not in ISO 19111:2007).
      Since:
      0.7

    • COUNTER_CLOCKWISE

      @UML(identifier="counterClockwise", obligation=CONDITIONAL, specification=UNSPECIFIED) public static final org.opengis.referencing.cs.AxisDirection COUNTER_CLOCKWISE
      Direction of arithmetic angles. Used in polar coordinate systems. Added in ISO 19111:2019 (was not in ISO 19111:2007).
      Since:
      0.7

    • AWAY_FROM

      @UML(identifier="awayFrom", obligation=CONDITIONAL, specification=UNSPECIFIED) public static final org.opengis.referencing.cs.AxisDirection AWAY_FROM
      Distance from the origin in a polar coordinate system. Added in ISO 19111:2019 (was not in ISO 19111:2007).
      Since:
      0.7

    • OPPOSITES

      private static final Map<org.opengis.referencing.cs.AxisDirection,org.opengis.referencing.cs.AxisDirection> OPPOSITES
      For each direction, the opposite direction. This map shall be immutable after construction.

    • ABBREVIATIONS

      private static final Map<org.opengis.referencing.cs.AxisDirection,String> ABBREVIATIONS
      Proposed abbreviations for some axis directions. This map shall be immutable after construction.

    • DISPLAY_ORDER

      private static final byte[] DISPLAY_ORDER
      Maps RIGHT, LEFT, UP, DOWN display order to UP, RIGHT, DOWN, LEFT.

  • Constructor Details

    • AxisDirections

      private AxisDirections()
      Do not allow instantiation of this class.

  • Method Details

    • put

      private static void put(org.opengis.referencing.cs.AxisDirection dir, org.opengis.referencing.cs.AxisDirection opposite)
      Stores the given directions in the OPPOSITES array.

    • absolute

      public static org.opengis.referencing.cs.AxisDirection absolute(org.opengis.referencing.cs.AxisDirection dir)
      Returns the "absolute" direction of the given direction. This "absolute" operation is similar to the Math.abs(int) method in that "negative" directions like (SOUTH, WEST, DOWN, PAST) are changed for their "positive" counterparts (NORTH, EAST, UP, FUTURE). More specifically, the following conversion table is applied:
      Mapping to "absolute" directions
      Directions Absolute value
      NORTH, SOUTH NORTH
      EAST, WEST EAST
      UP, DOWN UP
      FUTURE, PAST FUTURE
      COLUMN_POSITIVE, COLUMN_NEGATIVE COLUMN_POSITIVE
      ROW_POSITIVE, ROW_NEGATIVE ROW_POSITIVE
      DISPLAY_RIGHT, DISPLAY_LEFT DISPLAY_RIGHT
      DISPLAY_UP, DISPLAY_DOWN DISPLAY_UP
      CLOCKWISE, COUNTERCLOCKWISE COUNTERCLOCKWISE
      OTHER OTHER
      Parameters:
      dir - the direction for which to return the absolute direction, or null.
      Returns:
      the direction from the above table, or null if the given direction was null.

    • opposite

      public static org.opengis.referencing.cs.AxisDirection opposite(org.opengis.referencing.cs.AxisDirection dir)
      Returns the opposite direction of the given direction. The opposite direction of NORTH is SOUTH, and the opposite direction of SOUTH is NORTH. The same applies to EAST-WEST, UP-DOWN and FUTURE-PAST, etc. If the given axis direction has no opposite, then this method returns null.
      Parameters:
      dir - the direction for which to return the opposite direction, or null.
      Returns:
      the opposite direction, or null if none or unknown.

    • isOpposite

      public static boolean isOpposite(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the given direction is an "opposite" direction. If the given argument is null or is not a known direction, then this method conservatively returns false.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is an "opposite".

    • isCompass

      public static boolean isCompass(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the specified direction is a compass direction. Compass directions are NORTH, EAST, NORTH_EAST, etc.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is a compass direction.
      See Also:

    • isCardinal

      public static boolean isCardinal(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the specified direction is cardinal direction. Cardinal directions are NORTH, SOUTH, EAST and WEST.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is a cardinal direction.
      Since:
      0.8

    • isIntercardinal

      public static boolean isIntercardinal(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the specified direction is an inter-cardinal direction. Inter-cardinal directions are NORTH_EAST, SOUTH_SOUTH_EAST, etc.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is an inter-cardinal direction.

    • isVertical

      public static boolean isVertical(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the given direction is UP or DOWN.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the direction is vertical, or false otherwise.

    • isTemporal

      public static boolean isTemporal(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the given direction is FUTURE or PAST.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the direction is temporal, or false otherwise.

    • isGeocentric

      public static boolean isGeocentric(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the given direction is GEOCENTRIC_X, GEOCENTRIC_Y or GEOCENTRIC_Z.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is one of geocentric directions.

    • isSpatialOrUserDefined

      public static boolean isSpatialOrUserDefined(org.opengis.referencing.cs.AxisDirection dir, boolean image)
      Returns true if the given direction is a spatial axis direction (including vertical and geocentric axes). The current implementation conservatively returns true for every non-null directions except a hard-coded set of directions which are known to be non-spatial. We conservatively accept unknown axis directions because some of them are created from strings like "South along 90°E".

      If the image argument is true, then this method additionally accepts grid and display axis directions.

      The rules implemented by this method may change in any future SIS version.

      Parameters:
      dir - the direction to test, or null.
      image - true for accepting grid and image axis directions in addition to spatial ones.
      Returns:
      true if the given direction is presumed for spatial CS.

    • isUserDefined

      public static boolean isUserDefined(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the given direction is a user-defined direction (i.e. is not defined by GeoAPI).
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is user-defined.

    • isGrid

      public static boolean isGrid(org.opengis.referencing.cs.AxisDirection dir)
      Returns true if the given direction is COLUMN_POSITIVE, COLUMN_NEGATIVE, ROW_POSITIVE or ROW_NEGATIVE.
      Parameters:
      dir - the direction to test, or null.
      Returns:
      true if the given direction is presumed for grid CS.

    • angleForVehicle

      public static int angleForVehicle(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
      Arithmetic angle between forward/aft/port/starboard directions only. This is the angle as viewed from above the vehicle.
      Parameters:
      source - the start direction.
      target - the final direction.
      Returns:
      the angle as a multiple of 90°, or Integer.MIN_VALUE if none.

    • angleForGeocentric

      public static int angleForGeocentric(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
      Angle between geocentric directions only.
      Parameters:
      source - the start direction.
      target - the final direction.
      Returns:
      the angle as a multiple of 90°, or Integer.MIN_VALUE if none.

    • angleForCompass

      public static int angleForCompass(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
      Arithmetic angle between compass directions only (not for angle between direction along meridians).
      Parameters:
      source - the start direction.
      target - the final direction.
      Returns:
      the arithmetic angle as a multiple of 360/COMPASS_COUNT, or Integer.MIN_VALUE if none.
      See Also:

    • angleForDisplay

      public static int angleForDisplay(org.opengis.referencing.cs.AxisDirection source, org.opengis.referencing.cs.AxisDirection target)
      Arithmetic angle between display directions only.
      Parameters:
      source - the start direction.
      target - the final direction.
      Returns:
      the arithmetic angle as a multiple of 360/DISPLAY_COUNT, or Integer.MIN_VALUE if none.

    • getAngularUnit

      public static javax.measure.Unit<javax.measure.quantity.Angle> getAngularUnit(org.opengis.referencing.cs.CoordinateSystem cs, javax.measure.Unit<javax.measure.quantity.Angle> fallback)
      Returns the angular unit of the specified coordinate system. The preference will be given to the longitude axis, if found.
      Parameters:
      cs - the coordinate system from which to get the angular unit, or null.
      fallback - the default unit to return if no angular unit is found.
      Returns:
      the angular unit, of unit if no angular unit was found.
      Since:
      0.6
      See Also:

    • indexOfColinear

      public static int indexOfColinear(org.opengis.referencing.cs.CoordinateSystem cs, org.opengis.referencing.cs.AxisDirection direction)
      Finds the dimension of an axis having the given direction or its opposite. If more than one axis has the given direction, only the first occurrence is returned. If both the given direction and its opposite exist, then the dimension for the given direction has precedence over the opposite direction.
      Parameters:
      cs - the coordinate system to inspect, or null.
      direction - the direction of the axis to search.
      Returns:
      the dimension of the axis using the given direction or its opposite, or -1 if none.

    • indexOfColinear

      public static int indexOfColinear(org.opengis.referencing.cs.CoordinateSystem cs, org.opengis.referencing.cs.CoordinateSystem subCS)
      Returns the index of the first dimension in cs where axes are colinear with the subCS axes. If no such dimension is found, returns -1. If more than one sequence of cs axes are colinear with all subCS axes, then the following rules apply:
      1. If a sequence of cs axes are equal to the subCS axes, that sequence has precedence.
      2. Otherwise if a sequence of cs axes have similar names than the subCS axes (as determined by heuristic match, that sequence has precedence.
      3. Otherwise the index of the first sequence is returned, regardless axis names.
      Note that colinear axes are normally not allowed, except in the case of TemporalCRS when one time axis is the runtime (the date where a numerical model has been executed) and the other time axis is the forecast time (the date at which a prevision is made).
      Parameters:
      cs - the coordinate system which contains all axes, or null.
      subCS - the coordinate system to search into cs.
      Returns:
      the first dimension of a sequence of axes colinear with subCS axes, or -1 if none.
      Since:
      0.5

    • isColinear

      public static boolean isColinear(org.opengis.referencing.cs.AxisDirection d1, org.opengis.referencing.cs.AxisDirection d2)
      Returns whether the second axis is colinear with the first axis. This method returns true if the absolute direction of the given directions are equal. For example, "down" is considered colinear with "up".
      Parameters:
      d1 - the first axis direction to compare.
      d2 - the second axis direction to compare.
      Returns:
      true if both directions are colinear.

    • indicesOfLenientMapping

      public static int[] indicesOfLenientMapping(org.opengis.referencing.cs.CoordinateSystem cs, org.opengis.referencing.cs.CoordinateSystem subCS)
      Returns the indices of cs axes presumed covariant with subCS axes. The mapping is based on axis directions only, with colinear axes mapped in priority. If some axes cannot be mapped using collinearity criterion, then directions from poles (e.g. "South along 90°E") are arbitrarily handled as if they were covariant with East and North directions, in that order.
      Parameters:
      cs - the coordinate system which contains all axes, or null.
      subCS - the coordinate system for which to search axes into cs.
      Returns:
      indices in cs of axes covariant with subCS axes in the order they appear in subCS, or null if at least one subCS axis cannot be mapped to a cs axis.
      Since:
      1.2
      See Also:

    • find

      public static org.opengis.referencing.cs.AxisDirection find(String name, org.opengis.referencing.cs.AxisDirection[] directions)
      Searches for an axis direction having the given name in the specified list of directions. This method compares the given name with the name of each AxisDirection in a lenient way:
      • Comparisons are case-insensitive.
      • Any character which is not a letter or a digit is ignored. For example, "NorthEast", "North-East" and "NORTH_EAST" are considered equivalent.
      • This method accepts abbreviations as well, for example if the given name is "W", then it will be considered equivalent to "WEST".
      Parameters:
      name - the name of the axis direction to search.
      directions - the list of axis directions in which to search.
      Returns:
      the first axis direction having a name matching the given one, or null if none.

    • valueOf

      public static org.opengis.referencing.cs.AxisDirection valueOf(String name)
      Searches predefined AxisDirection for a given name. This method searches for a match in the set of known axis directions as returned by AxisDirection.values(), plus a few special cases like "Geocentre > equator/90°E". The latter are used in the EPSG database for geocentric CRS.

      This method does not know about org.apache.sis.referencing.cs.DirectionAlongMeridian. The latter is a parser which may create new directions, while this method searches only in a set of predefined directions and never create new ones.

      Parameters:
      name - the name of the axis direction to search.
      Returns:
      the first axis direction having a name matching the given one, or null if none.

    • equalsIgnoreCase

      private static boolean equalsIgnoreCase(String name, int lower, int upper, String keyword)
      Returns true if the given sub-sequence is equal to the given keyword, ignoring case.

    • contains

      private static boolean contains(String name, String keyword, boolean end)
      Returns true if the given name starts or ends with the given keyword, ignoring case.
      Parameters:
      end - false if the given keyword is expected at the beginning of the name, or true if expected at the end.

    • suggestAbbreviation

      public static String suggestAbbreviation(String name, org.opengis.referencing.cs.AxisDirection direction, javax.measure.Unit<?> unit)
      Suggests an abbreviation for the given axis direction. The unit of measurement may be used for resolving some ambiguities like whether AxisDirection.EAST is for "x" (Easting) or "λ" (Longitude).
      Parameters:
      name - the axis name for which to suggest an abbreviation.
      direction - the axis direction for which to suggest an abbreviation.
      unit - the axis unit of measurement, for disambiguation.
      Returns:
      a suggested abbreviation.
      Since:
      0.6

    • fromAbbreviation

      public static org.opengis.referencing.cs.AxisDirection fromAbbreviation(char abbreviation)
      Returns an axis direction for the given abbreviation. This method is (partially) the converse of suggestAbbreviation(String, AxisDirection, Unit). Current implementation does not recognize all abbreviation generated by above method, but only the main ones. This method is defined here for making easier to maintain consistency with suggestAbbreviation(…).
      Parameters:
      abbreviation - the abbreviation.
      Returns:
      axis direction for the given abbreviation, or null if unrecognized.

    • appendTo

      public static String appendTo(StringBuilder buffer, org.opengis.referencing.cs.CoordinateSystemAxis[] axes)
      Builds a coordinate system name from the given array of axes. This method expects a StringBuilder pre-filled with the coordinate system name. The axis directions and abbreviations will be appended after the CS name. Examples:
      • Ellipsoidal CS: North (°), East (°).
      • Cartesian CS: East (km), North (km).
      • Compound CS: East (km), North (km), Up (m).
      Parameters:
      buffer - a buffer pre-filled with the name header.
      axes - the axes to append in the given buffer.
      Returns:
      a name for the given coordinate system type and axes.
      Since:
      0.6