Class Normalizer

java.lang.Object
org.apache.sis.referencing.cs.Normalizer
All Implemented Interfaces:
Comparable<Normalizer>

final class Normalizer extends Object implements Comparable<Normalizer>
Derives an coordinate system from an existing one for AxesConvention. The main usage for this class is to reorder the axes in some fixed order like (x, y, z) or (longitude, latitude).

The normalization performed by this class shall be compatible with axis order expected by various MathTransform implementations in the org.apache.sis.referencing.operation.transform package. In particular:

  • EllipsoidToCentricTransform input:
    1. Geodetic longitude (λ) in degrees
    2. Geodetic latitude (φ) in degrees
    3. Height in units of semi-axes
  • SphericalToCartesian input:
    1. Spherical longitude in degrees
    2. Spherical latitude in degrees
    3. Spherical radius (r) in any units
  • CartesianToSpherical input:
    1. X in units of the above radius
    2. Y in units of the above radius
    3. Z in units of the above radius
  • CylindricalToCartesian input:
    1. Radius (r) in any units
    2. Angle (θ) in degrees
    3. Height (z) in any units

This class implements Comparable for opportunist reasons. This should be considered as an implementation details.

Since:
0.4
Version:
1.0
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final org.opengis.referencing.cs.CoordinateSystemAxis
    The axis to be compared by compareTo(Normalizer).
    private static final String[]
    The direction along meridian, or null if none.
    private static final Map<org.opengis.referencing.cs.AxisDirection,Integer>
    Custom code list values to handle as if the where defined between two GeoAPI values.
    private static final int
    Number of bits by which to shift the CodeList.ordinal() value in order to make room for inserting intermediate values between them.
    private final int
    Angular units order relative to other units.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Normalizer(org.opengis.referencing.cs.CoordinateSystemAxis axis, int angularUnitOrder)
    For internal usage by sort(CoordinateSystemAxis[], int) only.
  • Method Summary

    Modifier and Type
    Method
    Description
    private static AbstractCS
    castOrCopy(org.opengis.referencing.cs.CoordinateSystem cs)
    Returns the given coordinate system as an AbstractCS instance.
    int
    Compares two axis for an order that try to favor right-handed coordinate systems.
    (package private) static AbstractCS
    forConvention(org.opengis.referencing.cs.CoordinateSystem cs, AxesConvention convention)
    Returns a coordinate system equivalent to the given one but with axes rearranged according the given convention.
    private static org.opengis.referencing.cs.CoordinateSystemAxis
    forRange(org.opengis.referencing.cs.CoordinateSystemAxis axis, double min, double max)
    Returns a new axis with the same properties than the given axis except the identifiers which are omitted, and the minimum and maximum values which are set to the given values.
    private static boolean
    isLengthAndAngle(org.opengis.referencing.cs.CoordinateSystemAxis[] axes, int p)
    Returns true if the units of measurement at the given position is a linear unit, followed by an angular unit on the next axis.
    (package private) static org.opengis.referencing.cs.CoordinateSystemAxis
    normalize(org.opengis.referencing.cs.CoordinateSystemAxis axis, AxisFilter changes)
    Returns a new axis with the same properties (except identifiers) than given axis, but with normalized axis direction and unit of measurement.
    (package private) static AbstractCS
    normalize(org.opengis.referencing.cs.CoordinateSystem cs, AxisFilter changes, boolean reorder)
    Optionally normalizes and reorders the axes in an attempt to get a right-handed system.
    private static int
    order(org.opengis.referencing.cs.AxisDirection dir)
    Returns the order of the given axis direction.
    private static AbstractCS
    shiftAxisRange(org.opengis.referencing.cs.CoordinateSystem cs)
    Returns a coordinate system with the same axes than the given CS, except that the wraparound axes are shifted to a range of positive values.
    (package private) static boolean
    sort(org.opengis.referencing.cs.CoordinateSystemAxis[] axes, int angularUnitOrder)
    Sorts the specified axes in an attempt to create a right-handed system.

    Methods inherited from class java.lang.Object

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

    • EXCLUDES

      private static final String[] EXCLUDES
    • SHIFT

      private static final int SHIFT
      Number of bits by which to shift the CodeList.ordinal() value in order to make room for inserting intermediate values between them. A shift of 2 make room for 1 << 2 intermediate values. Those intermediate values are declared in the ORDER map.
      See Also:
    • ORDER

      private static final Map<org.opengis.referencing.cs.AxisDirection,Integer> ORDER
      Custom code list values to handle as if the where defined between two GeoAPI values.
      See Also:
    • axis

      private final org.opengis.referencing.cs.CoordinateSystemAxis axis
      The axis to be compared by compareTo(Normalizer).
    • meridian

      private final DirectionAlongMeridian meridian
      The direction along meridian, or null if none. This is inferred from axis at construction time in order to compute it only once before to sort an array of axes.
    • unitOrder

      private final int unitOrder
      Angular units order relative to other units. A value of -1 means that angular units should be first. A value of +1 means than angular units should be last. A value of 0 means to not use this criterion.
  • Constructor Details

    • Normalizer

      private Normalizer(org.opengis.referencing.cs.CoordinateSystemAxis axis, int angularUnitOrder)
      For internal usage by sort(CoordinateSystemAxis[], int) only.
  • Method Details

    • order

      private static int order(org.opengis.referencing.cs.AxisDirection dir)
      Returns the order of the given axis direction.
    • compareTo

      public int compareTo(Normalizer that)
      Compares two axis for an order that try to favor right-handed coordinate systems. Compass directions like North and East are first. Vertical directions like Up or Down are next.
      Specified by:
      compareTo in interface Comparable<Normalizer>
    • sort

      static boolean sort(org.opengis.referencing.cs.CoordinateSystemAxis[] axes, int angularUnitOrder)
      Sorts the specified axes in an attempt to create a right-handed system. The sorting is performed in place. This method returns true if at least one axis moved as result of this method call.
      Parameters:
      axes - the axes to sort.
      angularUnitOrder - -1 for sorting angular units first, +1 for sorting them last, or 0 if neutral.
    • normalize

      static org.opengis.referencing.cs.CoordinateSystemAxis normalize(org.opengis.referencing.cs.CoordinateSystemAxis axis, AxisFilter changes)
      Returns a new axis with the same properties (except identifiers) than given axis, but with normalized axis direction and unit of measurement.
      Parameters:
      axis - the axis to normalize.
      changes - the change to apply on axis direction and units.
      Returns:
      an axis using normalized direction and units, or axis if there is no change.
    • normalize

      static AbstractCS normalize(org.opengis.referencing.cs.CoordinateSystem cs, AxisFilter changes, boolean reorder)
      Optionally normalizes and reorders the axes in an attempt to get a right-handed system. If no axis change is needed, then this method returns null.
      Parameters:
      cs - the coordinate system to normalize.
      changes - the change to apply on axis direction and units.
      reorder - true for reordering the axis for a right-handed coordinate system.
      Returns:
      the normalized coordinate system, or null if no normalization is needed.
    • isLengthAndAngle

      private static boolean isLengthAndAngle(org.opengis.referencing.cs.CoordinateSystemAxis[] axes, int p)
      Returns true if the units of measurement at the given position is a linear unit, followed by an angular unit on the next axis.
    • shiftAxisRange

      private static AbstractCS shiftAxisRange(org.opengis.referencing.cs.CoordinateSystem cs)
      Returns a coordinate system with the same axes than the given CS, except that the wraparound axes are shifted to a range of positive values. This method can be used in order to shift between the [-180 … +180]° and [0 … 360]° ranges of longitude values.

      This method shifts the axis minimum and maximum values by a multiple of half the range (typically 180°). This method does not change the meaning of coordinate values. For example, a longitude of -60° still locate the same point in the old and the new coordinate system. But the preferred way to locate that point become the 300° value if the longitude range has been shifted to positive values.

      Returns:
      a coordinate system using the given kind of longitude range, or null if no change is needed.
    • forRange

      private static org.opengis.referencing.cs.CoordinateSystemAxis forRange(org.opengis.referencing.cs.CoordinateSystemAxis axis, double min, double max)
      Returns a new axis with the same properties than the given axis except the identifiers which are omitted, and the minimum and maximum values which are set to the given values.
    • castOrCopy

      private static AbstractCS castOrCopy(org.opengis.referencing.cs.CoordinateSystem cs)
      Returns the given coordinate system as an AbstractCS instance. This method performs an instanceof check before to delegate to AbstractCS.castOrCopy(CoordinateSystem) because there is no need to check for all interfaces before the implementation class here. Checking the implementation class first is usually more efficient in this particular case.
    • forConvention

      static AbstractCS forConvention(org.opengis.referencing.cs.CoordinateSystem cs, AxesConvention convention)
      Returns a coordinate system equivalent to the given one but with axes rearranged according the given convention. If the given coordinate system is already compatible with the given convention, then returns null.
      Parameters:
      convention - the axes convention for which a coordinate system is desired.
      Returns:
      a coordinate system compatible with the given convention, or null if no change is needed.
      See Also: