Module org.apache.sis.referencing
Package org.apache.sis.referencing.operation.transform

# Class PoleRotation

Object
FormattableObject
AbstractMathTransform
AbstractMathTransform2D
PoleRotation

All Implemented Interfaces:
  `Serializable`, `Parameterized`, `LenientComparable`, `MathTransform`, `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
See Also:
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class AbstractMathTransform2D

  `AbstractMathTransform2D​.Inverse`

- ## Field Summary

  ### Fields inherited from class AbstractMathTransform2D

  `DIMENSION`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PoleRotation(boolean south, double φp, double λp, double θp)`
  Creates the non-linear part of a rotated pole operation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected int`
  `computeHashCode()`
  Computes a hash value for this transform.
  `boolean`
  `equals(Object object, ComparisonMode mode)`
  Compares the specified object with this math transform for equality.
  `protected ContextualParameters`
  `getContextualParameters()`
  Returns the parameters used for creating the complete operation.
  `ParameterDescriptorGroup`
  `getParameterDescriptors()`
  Returns a description of the parameters of this transform.
  `ParameterValueGroup`
  `getParameterValues()`
  Returns a copy of the parameter values of this transform.
  `MathTransform2D`
  `inverse()`
  Returns the inverse transform of this object.
  `boolean`
  `isIdentity()`
  Tests whether this transform does not move any points.
  `static MathTransform`
  `rotateNorthPole(MathTransformFactory factory, double φp, double λp, double θp)`
  Creates a new rotated north pole operation.
  `static MathTransform`
  `rotateSouthPole(MathTransformFactory factory, double φp, double λp, double θp)`
  Creates a new rotated south pole operation.
  `Matrix`
  `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate)`
  Transforms a single coordinate tuple in an array, and optionally computes the transform derivative at that location.
  `void`
  `transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts)`
  Converts a list of coordinate tuples.

  ### Methods inherited from class AbstractMathTransform2D

  `createTransformedShape, derivative, getSourceDimensions, getTargetDimensions, transform`

  ### Methods inherited from class AbstractMathTransform

  `derivative, equals, formatTo, getDomain, hashCode, transform, transform, transform, transform, tryConcatenate`

  ### Methods inherited from class FormattableObject

  `print, toString, toString, toWKT`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface MathTransform

  `derivative, toWKT, transform, transform, transform, transform`

- ## Constructor Details

  - ### 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.
      `φp` - geographic latitude in degrees of the southern pole of the coordinate system.
      `λp` - geographic longitude in degrees of the southern pole of the coordinate system.
      `θp` - angle of rotation in degrees about the new polar axis measured clockwise when looking from the rotated pole to the Earth center.

- ## Method Details

  - ### rotateSouthPole

    public static MathTransform rotateSouthPole(MathTransformFactory factory, double φp, double λp, double θp) throws 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.
      `φp` - geographic latitude in degrees of the southern pole of the coordinate system.
      `λp` - geographic longitude in degrees of the southern pole of the coordinate system.
      `θp` - 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:
      `FactoryException` - if an error occurred while creating a transform.

  - ### rotateNorthPole

    public static MathTransform rotateNorthPole(MathTransformFactory factory, double φp, double λp, double θp) throws 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.
      `φp` - geographic latitude in degrees of the northern pole of the coordinate system.
      `λp` - geographic longitude in degrees of the northern pole of the coordinate system.
      `θp` - 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:
      `FactoryException` - if an error occurred while creating a transform.

  - ### getParameterDescriptors

    @Debug public 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:
      - `DefaultOperationMethod​.getParameters()`

  - ### getParameterValues

    @Debug public 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:
      - `AbstractMathTransform​.getContextualParameters()`
      - `SingleOperation​.getParameterValues()`

  - ### 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 normalize → `this` → denormalize transforms.

  - ### transform

    public Matrix transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, boolean derivate) throws 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:
      `TransformException` - if the point cannot be transformed or if a problem occurred while calculating the derivative.
    See Also:
      - `AbstractMathTransform​.derivative(DirectPosition)`
      - `AbstractMathTransform​.transform(DirectPosition, DirectPosition)`
      - `MathTransforms​.derivativeAndTransform(MathTransform, double[], int, double[], int)`

  - ### transform

    public void transform(double[] srcPts, int srcOff, double[] dstPts, int dstOff, int numPts) throws 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 `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:
      `TransformException` - if a point cannot be converted.

  - ### inverse

    public MathTransform2D inverse()
    Returns the inverse transform of this object.
    Specified by:
      `inverse` in interface `MathTransform`
    Specified by:
      `inverse` in interface `MathTransform2D`
    Overrides:
      `inverse` in class `AbstractMathTransform2D`
    Returns:
      the inverse of this transform.

  - ### isIdentity

    public boolean isIdentity()
    Tests whether this transform does not move any points.
    Specified by:
      `isIdentity` in interface `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:
      - `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  - ### 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.