All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform, org.opengis.referencing.operation.MathTransform2D

public class PoleRotation extends AbstractMathTransform2D implements Serializable
Computes latitudes and longitudes on a sphere where the south pole has been moved to given geographic coordinates. The parameter values of this transform use the conventions defined in template 3.1 of GRIB2 format published by the World Meteorological Organization (WMO):
  1. φp: geographic latitude in degrees of the southern pole of the coordinate system.
  2. λp: geographic longitude in degrees of the southern pole of the coordinate system.
  3. Angle of rotation in degrees about the new polar axis measured clockwise when looking from the rotated pole to the Earth center.
The rotations are applied by first rotating the sphere through λp about the geographic polar axis, and then rotating through (φp − (−90°)) degrees so that the southern pole moved along the (previously rotated) Greenwich meridian.

Coordinate order

Source and target axis order in transform(…) methods is (longitude, latitude). This is the usual axis order used by Apache SIS for internal calculations (but not the parameter order in factory methods). If a different axis order is desired (for example for showing coordinates to the user), an affine transform can be concatenated to this transform.
Since:
1.2
Version:
1.2
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • POLE_LATITUDE

      private static final int POLE_LATITUDE
      Index of parameter declared in SouthPoleRotation and NorthPoleRotation.
      See Also:
    • POLE_LONGITUDE

      private static final int POLE_LONGITUDE
      Index of parameter declared in SouthPoleRotation and NorthPoleRotation.
      See Also:
    • AXIS_ANGLE

      private static final int AXIS_ANGLE
      Index of parameter declared in SouthPoleRotation and NorthPoleRotation.
      See Also:
    • MAX_AXIS_ROTATION

      private static final double MAX_AXIS_ROTATION
      The maximal value of axis rotation before switching to a different algorithm which will reduce that rotation. The intent it to have axis rotation (applied on longitude values) small enough for increasing the chances that output longitudes are in [-180 … 180]° range.
      See Also:
    • context

      private final ContextualParameters context
      The parameters used for creating this transform. They are used for formatting Well Known Text (WKT).
      See Also:
    • sinφp

      private final double sinφp
      Sine and cosine of the geographic latitude of the southern pole of the coordinate system. The rotation angle to apply is (φp − (−90°)) degrees for the south pole (−90°), but we use the following trigonometric identities:

      For the south pole:

      • sin(φ + 90°) = cos(φ)
      • cos(φ + 90°) = −sin(φ)

      For the north pole:

      • sin(φ − 90°) = −cos(φ)
      • cos(φ − 90°) = sin(φ)
      By convention those fields contain the sine and cosine for the south pole case, and values with opposite sign for the north pole case.
    • cosφp

      private final double cosφp
      Sine and cosine of the geographic latitude of the southern pole of the coordinate system. The rotation angle to apply is (φp − (−90°)) degrees for the south pole (−90°), but we use the following trigonometric identities:

      For the south pole:

      • sin(φ + 90°) = cos(φ)
      • cos(φ + 90°) = −sin(φ)

      For the north pole:

      • sin(φ − 90°) = −cos(φ)
      • cos(φ − 90°) = sin(φ)
      By convention those fields contain the sine and cosine for the south pole case, and values with opposite sign for the north pole case.
    • inverse

      private org.opengis.referencing.operation.MathTransform2D inverse
      The inverse of this operation, computed when first needed.
      See Also:
  • Constructor Details

    • PoleRotation

      private PoleRotation(PoleRotation forward)
      Creates the inverse of the given forward operation. In principle, the latitude φp should be unchanged and the longitude λp should be 180° (ignoring the axis angle) in order to go back in the direction of geographical South pole. The longitudes computed by this approach have an offset of 180°, which can be compensated with the axis angle (see the inverseParameter(Parameters, ParameterValue) method for more details). However, we can get a mathematically equivalent effect without the 180° longitude offset by setting the new pole latitude to unrealistic φp = (180° − φforward) value. We get this effect be inverting the sign of cosφp while keeping sinφp unchanged. Note that this is compatible with isIdentity() implementation.
      See Also:
    • PoleRotation

      protected PoleRotation(boolean south, double φp, double λp, double θp)
      Creates the non-linear part of a rotated pole operation. This transform does not include the conversion between degrees and radians and the longitude rotations. For a complete transform, use one of the static factory methods.
      Parameters:
      south - true for a south pole rotation, or false for a north pole rotation.
      \u03c6p - geographic latitude in degrees of the southern pole of the coordinate system.
      \u03bbp - geographic longitude in degrees of the southern pole of the coordinate system.
      \u03b8p - angle of rotation in degrees about the new polar axis measured clockwise when looking from the rotated pole to the Earth center.
  • Method Details

    • inverseParameter

      private static boolean inverseParameter(Parameters forward, org.opengis.parameter.ParameterValue<?> target)
      Computes the value of the given parameter for the inverse of "South pole rotation". This method is invoked for each parameter of the inverse transform to initialize. The parameters of the inverse transform is defined as below:
      • Latitude is unchanged. For example if the rotated pole was located at 60° of latitude relative to the geographic pole, then conversely the geographic pole is still located at 60° of latitude relative to the rotated pole.
      • Longitude is 180° (ignoring axis rotation) in the South pole case because by definition the 180° rotated meridian runs through both the geographical and the rotated South pole.
      • Axis rotation is 180° (ignoring λp in forward transform) in the South pole case for compensating the 180° offset of λp in the inverse transform.
      • If a non-zero λp was specified in the forward transform, then an axis rotation in opposite direction must be added to the inverse transform. Conversely if an axis rotation was defined in the forward transform, then a λp rotation in opposite direction must be added to the inverse transform.
      Parameters:
      forward - the forward operation.
      target - parameter to initialize.
      Returns:
      whether to accept the parameter (always true).
      See Also:
    • getValue

      private static Number getValue(Parameters context, int index)
      Returns the value for the parameter at the given index. This is the converse of setValue(int, double).
    • setValue

      private void setValue(int index, double value)
      Sets the value of the parameter at the given index. In the rotated south pole case, parameter 0 to 2 (inclusive) are: "grid_south_pole_latitude", "grid_south_pole_longitude" and "grid_south_pole_angle" in that order.
    • rotateSouthPole

      public static org.opengis.referencing.operation.MathTransform rotateSouthPole(org.opengis.referencing.operation.MathTransformFactory factory, double φp, double λp, double θp) throws org.opengis.util.FactoryException
      Creates a new rotated south pole operation. The rotations are applied by first rotating the sphere through λp about the geographic polar axis, then rotating through (φp − (−90°)) degrees so that the southern pole moved along the (previously rotated) Greenwich meridian, and finally by rotating θp degrees clockwise when looking from the southern to the northern rotated pole. In the case where θp=0, the 180° rotated meridian runs through both the geographical and the rotated South pole.
      Parameters:
      factory - the factory to use for creating the transform.
      \u03c6p - geographic latitude in degrees of the southern pole of the coordinate system.
      \u03bbp - geographic longitude in degrees of the southern pole of the coordinate system.
      \u03b8p - angle of rotation in degrees about the new polar axis measured clockwise when looking from the southern to the northern pole.
      Returns:
      the conversion doing a south pole rotation.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while creating a transform.
    • rotateNorthPole

      public static org.opengis.referencing.operation.MathTransform rotateNorthPole(org.opengis.referencing.operation.MathTransformFactory factory, double φp, double λp, double θp) throws org.opengis.util.FactoryException
      Creates a new rotated north pole operation. The rotations are applied by first rotating the sphere through λp about the geographic polar axis, then rotating through (φp − 90°) degrees so that the northern pole moved along the (previously rotated) Greenwich meridian, and finally by rotating θp degrees clockwise when looking from the northern to the southern rotated pole. In the case where θp=0, the 0° rotated meridian is defined as the meridian that runs through both the geographical and the rotated North pole.
      The sign of the θp argument is not yet well determined. Should it be a rotation clockwise or anti-clockwise? Looking from northern to southern pole or the opposite direction? The sign may change in the future if we find an authoritative definition. In the meantime, it is safer to keep the θp value equal to zero.
      Parameters:
      factory - the factory to use for creating the transform.
      \u03c6p - geographic latitude in degrees of the northern pole of the coordinate system.
      \u03bbp - geographic longitude in degrees of the northern pole of the coordinate system.
      \u03b8p - angle of rotation in degrees about the new polar axis measured clockwise when looking from the northern to the southern pole.
      Returns:
      the conversion doing a north pole rotation.
      Throws:
      org.opengis.util.FactoryException - if an error occurred while creating a transform.
    • getParameterDescriptors

      @Debug public org.opengis.parameter.ParameterDescriptorGroup getParameterDescriptors()
      Returns a description of the parameters of this transform. The group of parameters contains only the grid (north or south) pole latitude. It does not contain the grid pole longitude or the grid angle of rotation because those parameters are handled by affine transforms pre- or post-concatenated to this transform.
      Specified by:
      getParameterDescriptors in interface Parameterized
      Overrides:
      getParameterDescriptors in class AbstractMathTransform
      Returns:
      the parameter descriptors for this math transform.
      See Also:
    • getParameterValues

      @Debug public org.opengis.parameter.ParameterValueGroup getParameterValues()
      Returns a copy of the parameter values of this transform. The group contains the values of the parameters described by getParameterDescriptors(). This method is mostly for debugging purposes; most GIS applications will instead be interested in the contextual parameters instead.
      Specified by:
      getParameterValues in interface Parameterized
      Overrides:
      getParameterValues in class AbstractMathTransform
      Returns:
      the parameter values for this math transform.
      See Also:
    • getContextualParameters

      protected ContextualParameters getContextualParameters()
      Returns the parameters used for creating the complete operation. The returned group contains not only the grid pole latitude (which is handled by this transform), but also the grid pole longitude and the grid angle of rotation (which are handled by affine transforms before or after this transform).
      Overrides:
      getContextualParameters in class AbstractMathTransform
      Returns:
      the parameter values for the sequence of normalizethisdenormalize transforms.
    • transform

      public org.opengis.referencing.operation.Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws org.opengis.referencing.operation.TransformException
      Transforms a single coordinate tuple in an array, and optionally computes the transform derivative at that location. Source and target axis order is (longitude, latitude).
      Specified by:
      transform in class AbstractMathTransform
      Parameters:
      srcPts - the array containing the source coordinates (cannot be null).
      srcOff - the offset to the point to be transformed in the source array.
      dstPts - the array into which the transformed coordinates is returned. May be the same than srcPts. May be null if only the derivative matrix is desired.
      dstOff - the offset to the location of the transformed point that is stored in the destination array.
      derivate - true for computing the derivative, or false if not needed.
      Returns:
      the matrix of the transform derivative at the given source position, or null if the derivate argument is false.
      Throws:
      org.opengis.referencing.operation.TransformException - if the point cannot be transformed or if a problem occurred while calculating the derivative.
      See Also:
    • transform

      public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws org.opengis.referencing.operation.TransformException
      Converts a list of coordinate tuples. This method performs the same calculation than above transform(double[], int, double[], int, boolean) method, but is overridden for efficiency.
      Specified by:
      transform in interface org.opengis.referencing.operation.MathTransform
      Overrides:
      transform in class AbstractMathTransform
      Parameters:
      srcPts - the array containing the source point coordinates.
      srcOff - the offset to the first point to be transformed in the source array.
      dstPts - the array into which the transformed point coordinates are returned. May be the same than srcPts.
      dstOff - the offset to the location of the first transformed point that is stored in the destination array.
      numPts - the number of point objects to be transformed.
      Throws:
      org.opengis.referencing.operation.TransformException - if a point cannot be converted.
    • inverse

      public org.opengis.referencing.operation.MathTransform2D inverse()
      Returns the inverse transform of this object.
      Specified by:
      inverse in interface org.opengis.referencing.operation.MathTransform
      Specified by:
      inverse in interface org.opengis.referencing.operation.MathTransform2D
      Overrides:
      inverse in class AbstractMathTransform2D
      Returns:
      the inverse of this transform.
    • concatenate

      private static org.opengis.referencing.operation.MathTransform2D concatenate(ContextualParameters p1, ContextualParameters.MatrixRole r1, ContextualParameters p2, ContextualParameters.MatrixRole r2)
      Returns the concatenation of transform p1.r1 followed by p2.r2.
    • isIdentity

      public boolean isIdentity()
      Tests whether this transform does not move any points.
      Specified by:
      isIdentity in interface org.opengis.referencing.operation.MathTransform
      Overrides:
      isIdentity in class AbstractMathTransform
      Returns:
      true if this transform is (at least approximately) the identity transform.
    • equals

      public boolean equals(Object object, ComparisonMode mode)
      Compares the specified object with this math transform for equality.
      Specified by:
      equals in interface LenientComparable
      Overrides:
      equals in class AbstractMathTransform
      Parameters:
      object - the object to compare with this transform.
      mode - the strictness level of the comparison.
      Returns:
      true if the given object is considered equals to this math transform.
      See Also:
    • computeHashCode

      protected int computeHashCode()
      Computes a hash value for this transform. This method is invoked by AbstractMathTransform.hashCode() when first needed.
      Overrides:
      computeHashCode in class AbstractMathTransform
      Returns:
      the hash code value. This value may change between different execution of the Apache SIS library.