Class PoleRotation
java.lang.Object
org.apache.sis.io.wkt.FormattableObject
org.apache.sis.referencing.operation.transform.AbstractMathTransform
org.apache.sis.referencing.operation.transform.AbstractMathTransform2D
org.apache.sis.referencing.operation.transform.PoleRotation
- All Implemented Interfaces:
Serializable
,Parameterized
,LenientComparable
,org.opengis.referencing.operation.MathTransform
,org.opengis.referencing.operation.MathTransform2D
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):
- φ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.
- Angle of rotation in degrees about the new polar axis measured clockwise when looking from the rotated pole to the Earth center.
Coordinate order
Source and target axis order intransform(…)
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:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform2D
AbstractMathTransform2D.Inverse
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Index of parameter declared inSouthPoleRotation
andNorthPoleRotation
.private final ContextualParameters
The parameters used for creating this transform.private final double
Sine and cosine of the geographic latitude of the southern pole of the coordinate system.private org.opengis.referencing.operation.MathTransform2D
The inverse of this operation, computed when first needed.private static final double
The maximal value of axis rotation before switching to a different algorithm which will reduce that rotation.private static final int
Index of parameter declared inSouthPoleRotation
andNorthPoleRotation
.private static final int
Index of parameter declared inSouthPoleRotation
andNorthPoleRotation
.private static final long
For cross-version compatibility.private final double
Sine and cosine of the geographic latitude of the southern pole of the coordinate system.Fields inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform2D
DIMENSION
Fields inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform
MAXIMUM_BUFFER_SIZE, MAXIMUM_FAILURES
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
PoleRotation
(boolean south, double φp, double λp, double θp) Creates the non-linear part of a rotated pole operation.private
PoleRotation
(PoleRotation forward) Creates the inverse of the given forward operation. -
Method Summary
Modifier and TypeMethodDescriptionprotected int
Computes a hash value for this transform.private static org.opengis.referencing.operation.MathTransform2D
concatenate
(ContextualParameters p1, ContextualParameters.MatrixRole r1, ContextualParameters p2, ContextualParameters.MatrixRole r2) Returns the concatenation of transformp1.r1
followed byp2.r2
.boolean
equals
(Object object, ComparisonMode mode) Compares the specified object with this math transform for equality.protected ContextualParameters
Returns the parameters used for creating the complete operation.org.opengis.parameter.ParameterDescriptorGroup
Returns a description of the parameters of this transform.org.opengis.parameter.ParameterValueGroup
Returns a copy of the parameter values of this transform.private static Number
getValue
(Parameters context, int index) Returns the value for the parameter at the given index.org.opengis.referencing.operation.MathTransform2D
inverse()
Returns the inverse transform of this object.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".boolean
Tests whether this transform does not move any points.static org.opengis.referencing.operation.MathTransform
rotateNorthPole
(org.opengis.referencing.operation.MathTransformFactory factory, double φp, double λp, double θp) Creates a new rotated north pole operation.static org.opengis.referencing.operation.MathTransform
rotateSouthPole
(org.opengis.referencing.operation.MathTransformFactory factory, double φp, double λp, double θp) Creates a new rotated south pole operation.private void
setValue
(int index, double value) Sets the value of the parameter at the given index.org.opengis.referencing.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 org.apache.sis.referencing.operation.transform.AbstractMathTransform2D
createTransformedShape, createTransformedShape, derivative, derivative, getSourceDimensions, getTargetDimensions, transform, transform
Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform
beforeFormat, derivative, equals, formatTo, getDomain, hashCode, isInverseEquals, mismatchedDimension, transform, transform, transform, transform, tryConcatenate
Methods inherited from class org.apache.sis.io.wkt.FormattableObject
print, toString, toString, toWKT
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.opengis.referencing.operation.MathTransform
derivative, toWKT, transform, transform, transform, transform
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
POLE_LATITUDE
private static final int POLE_LATITUDEIndex of parameter declared inSouthPoleRotation
andNorthPoleRotation
.- See Also:
-
POLE_LONGITUDE
private static final int POLE_LONGITUDEIndex of parameter declared inSouthPoleRotation
andNorthPoleRotation
.- See Also:
-
AXIS_ANGLE
private static final int AXIS_ANGLEIndex of parameter declared inSouthPoleRotation
andNorthPoleRotation
.- See Also:
-
MAX_AXIS_ROTATION
private static final double MAX_AXIS_ROTATIONThe 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
The parameters used for creating this transform. They are used for formatting Well Known Text (WKT).- See Also:
-
sinφp
private final double sinφpSine 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(φ)
-
cosφp
private final double cosφpSine 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(φ)
-
inverse
private org.opengis.referencing.operation.MathTransform2D inverseThe inverse of this operation, computed when first needed.- See Also:
-
-
Constructor Details
-
PoleRotation
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 theinverseParameter(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 ofcosφp
while keepingsinφp
unchanged. Note that this is compatible withisIdentity()
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, orfalse
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
Returns the value for the parameter at the given index. This is the converse ofsetValue(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
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 interfaceParameterized
- Overrides:
getParameterDescriptors
in classAbstractMathTransform
- Returns:
- the parameter descriptors for this math transform.
- See Also:
-
getParameterValues
Returns a copy of the parameter values of this transform. The group contains the values of the parameters described bygetParameterDescriptors()
. This method is mostly for debugging purposes; most GIS applications will instead be interested in the contextual parameters instead.- Specified by:
getParameterValues
in interfaceParameterized
- Overrides:
getParameterValues
in classAbstractMathTransform
- Returns:
- the parameter values for this math transform.
- See Also:
-
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 classAbstractMathTransform
- Returns:
- the parameter values for the sequence of normalize →
this
→ denormalize 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 classAbstractMathTransform
- Parameters:
srcPts
- the array containing the source coordinates (cannot benull
).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 thansrcPts
. May benull
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, orfalse
if not needed.- Returns:
- the matrix of the transform derivative at the given source position,
or
null
if thederivate
argument isfalse
. - 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 abovetransform(double[], int, double[], int, boolean)
method, but is overridden for efficiency.- Specified by:
transform
in interfaceorg.opengis.referencing.operation.MathTransform
- Overrides:
transform
in classAbstractMathTransform
- 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 thansrcPts
.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 interfaceorg.opengis.referencing.operation.MathTransform
- Specified by:
inverse
in interfaceorg.opengis.referencing.operation.MathTransform2D
- Overrides:
inverse
in classAbstractMathTransform2D
- 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 transformp1.r1
followed byp2.r2
. -
isIdentity
public boolean isIdentity()Tests whether this transform does not move any points.- Specified by:
isIdentity
in interfaceorg.opengis.referencing.operation.MathTransform
- Overrides:
isIdentity
in classAbstractMathTransform
- Returns:
true
if this transform is (at least approximately) the identity transform.
-
equals
Compares the specified object with this math transform for equality.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classAbstractMathTransform
- 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 byAbstractMathTransform.hashCode()
when first needed.- Overrides:
computeHashCode
in classAbstractMathTransform
- Returns:
- the hash code value. This value may change between different execution of the Apache SIS library.
-