Class AuthalicConversion
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.projection.NormalizedProjection
org.apache.sis.referencing.operation.projection.AuthalicConversion
- All Implemented Interfaces:
Serializable
,Parameterized
,LenientComparable
,org.opengis.referencing.operation.MathTransform
,org.opengis.referencing.operation.MathTransform2D
- Direct Known Subclasses:
AlbersEqualArea
,AuthalicMercator
,CylindricalEqualArea
,LambertAzimuthalEqualArea
Base class of projections doing conversions between geodetic latitude and authalic latitude.
This is used by equal-area projections such as
AlbersEqualArea
and CylindricalEqualArea
.
However, not all equal-area projections extend this base class, and conversely not all sub-classes are equal-area.
For example, the Sinusoidal
projection, despite being equal-area, uses different formulas.
Note that no projection can be both conformal and equal-area. So the formulas in this class
are usually mutually exclusive with formulas in ConformalProjection
class.
Note on class naming
Lee (1944) defines an authalic map projection to be one in which at any point the scales in two orthogonal directions are inversely proportional. Those map projections have a constant areal scale. However, thisAuthalicConversion
is not necessarily an authalic projection.
Subclasses may want to use the latitude conversion formulas for other purposes.
References
Lee, L. P. "The Nomenclature and Classification of Map Projections." Empire Survey Review 7, 190-200, 1944.
- Since:
- 0.8
- Version:
- 1.2
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.sis.referencing.operation.projection.NormalizedProjection
NormalizedProjection.ParameterRole
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final double
Coefficients of the first terms in the series expansion of the reverse projection.private final double
Coefficients of the first terms in the series expansion of the reverse projection.private final double
Coefficients of the first terms in the series expansion of the reverse projection.private static final double
The threshold value ofNormalizedProjection.eccentricity
at which we consider the accuracy of the series expansion insufficient.(package private) final boolean
true
ifNormalizedProjection.eccentricity
is zero.(package private) final double
Value ofqm(double)
function (part of Snyder equation (3-12)) at pole (sinφ = 1).private static final long
For cross-version compatibility.private final boolean
true
if theNormalizedProjection.eccentricity
value is greater than or equals to the eccentricity threshold, in which case theφ(double)
method will need to use an iterative method.Fields inherited from class org.apache.sis.referencing.operation.projection.NormalizedProjection
ANGULAR_TOLERANCE, context, eccentricity, eccentricitySquared, ITERATION_TOLERANCE, LARGE_LONGITUDE_LIMIT, MAXIMUM_ITERATIONS, POLAR_AREA_LIMIT
Fields inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform2D
DIMENSION
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new projection initialized to the values of the given one.AuthalicConversion
(Initializer initializer, NormalizedProjection other) Creates a new normalized projection from the parameters computed by the given initializer, or from the parameters already computed by another projection. -
Method Summary
Modifier and TypeMethodDescription(package private) final double
dqm_dφ
(double sinφ, double cosφ) Gets the derivative of theqm(double)
method.(package private) final double
qm
(double sinφ) Calculates part of q from Snyder equation (3-12).(package private) final double
sinβ
(double sinφ) Converts the sine of geodetic latitude to the sin of authalic latitude.(package private) final double
φ
(double sinβ) Computes the latitude using equation 3-18 from Snyder, followed by iterative resolution of Snyder 3-16.Methods inherited from class org.apache.sis.referencing.operation.projection.NormalizedProjection
completeWithWraparound, computeHashCode, createMapProjection, delegate, equals, getContextualParameters, getInternalParameterNames, getInternalParameterValues, getParameterDescriptors, getParameterValues, getWraparoundLongitude, inverse, inverseTransform, transform, tryConcatenate, tryConcatenate, variant
Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform2D
createTransformedShape, derivative, getSourceDimensions, getTargetDimensions, transform
Methods inherited from class org.apache.sis.referencing.operation.transform.AbstractMathTransform
derivative, equals, formatTo, getDomain, hashCode, isIdentity, transform, transform, transform, transform, transform
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, isIdentity, toWKT, transform, transform, transform, transform, transform
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
ECCENTRICITY_THRESHOLD
private static final double ECCENTRICITY_THRESHOLDThe threshold value ofNormalizedProjection.eccentricity
at which we consider the accuracy of the series expansion insufficient. This threshold is determined empirically with the help of theEqualAreaProjectionTest.searchThreshold()
method in the test directory.Note: WGS84 eccentricity is about 0.082.
- See Also:
-
c2β
private final double c2βCoefficients of the first terms in the series expansion of the reverse projection. Values of those coefficients depend only on eccentricity value. The series expansion is published under the following form, where β is the authalic latitude:φ = c₂⋅sin(2β) + c₄⋅sin(4β) + c₈⋅sin(6β)
However, we rewrite above series expansion for taking advantage of trigonometric identities. The equation become (with different c values):sin(2β)⋅(c₂ + cos(2β)⋅(c₄ + cos(2β)⋅c₆))
Serialization note: we do not strictly need to serialize those fields since they could be computed after deserialization. But we serialize them anyway in order to simplify a little bit this class (it allows us to keep those fields final) and because values computed after deserialization could be slightly different than the ones computed after construction if a future version of the constructor uses the double-double values provided byInitializer
. -
c4β
private final double c4βCoefficients of the first terms in the series expansion of the reverse projection. Values of those coefficients depend only on eccentricity value. The series expansion is published under the following form, where β is the authalic latitude:φ = c₂⋅sin(2β) + c₄⋅sin(4β) + c₈⋅sin(6β)
However, we rewrite above series expansion for taking advantage of trigonometric identities. The equation become (with different c values):sin(2β)⋅(c₂ + cos(2β)⋅(c₄ + cos(2β)⋅c₆))
Serialization note: we do not strictly need to serialize those fields since they could be computed after deserialization. But we serialize them anyway in order to simplify a little bit this class (it allows us to keep those fields final) and because values computed after deserialization could be slightly different than the ones computed after construction if a future version of the constructor uses the double-double values provided byInitializer
. -
c6β
private final double c6βCoefficients of the first terms in the series expansion of the reverse projection. Values of those coefficients depend only on eccentricity value. The series expansion is published under the following form, where β is the authalic latitude:φ = c₂⋅sin(2β) + c₄⋅sin(4β) + c₈⋅sin(6β)
However, we rewrite above series expansion for taking advantage of trigonometric identities. The equation become (with different c values):sin(2β)⋅(c₂ + cos(2β)⋅(c₄ + cos(2β)⋅c₆))
Serialization note: we do not strictly need to serialize those fields since they could be computed after deserialization. But we serialize them anyway in order to simplify a little bit this class (it allows us to keep those fields final) and because values computed after deserialization could be slightly different than the ones computed after construction if a future version of the constructor uses the double-double values provided byInitializer
. -
qmPolar
final double qmPolarValue ofqm(double)
function (part of Snyder equation (3-12)) at pole (sinφ = 1). The qp constant is defined by EPSG guidance note as:(1 – ℯ²)⋅([1 / (1 – ℯ²)] – {[1/(2ℯ)] ln [(1 – ℯ) / (1 + ℯ)]})
But in this class, we omit the (1 – ℯ²) factor.Spherical case
In the spherical case (ℯ=0), the value is exactly 2. -
isSpherical
final boolean isSphericaltrue
ifNormalizedProjection.eccentricity
is zero. -
useIterations
private final boolean useIterationstrue
if theNormalizedProjection.eccentricity
value is greater than or equals to the eccentricity threshold, in which case theφ(double)
method will need to use an iterative method.
-
-
Constructor Details
-
AuthalicConversion
AuthalicConversion(Initializer initializer, NormalizedProjection other) Creates a new normalized projection from the parameters computed by the given initializer, or from the parameters already computed by another projection. Exactly one ofinitializer
orother
shall be non-null.- Parameters:
initializer
- the initializer for computing map projection internal parameters, ornull
.other
- the other projection from which to compute parameters, ornull
.
-
AuthalicConversion
AuthalicConversion(AuthalicConversion other) Creates a new projection initialized to the values of the given one. This constructor may be invoked after we determined that the default implementation can be replaced by another one, for example using spherical formulas instead of the ellipsoidal ones. This constructor allows to transfer all parameters to the new instance without recomputing them.
-
-
Method Details
-
qm
final double qm(double sinφ) Calculates part of q from Snyder equation (3-12). In order to get the q function, this method output must be multiplied by(1 - NormalizedProjection.eccentricitySquared)
.The q variable is named α in EPSG guidance notes.
This equation has the following properties:
- Input in the [-1 … +1] range
- Output multiplied by
(1 - ℯ²)
in the [-2 … +2] range - Output of the same sign than input
- q(-sinφ) = -q(sinφ)
- q(0) = 0
Spherical case
In the spherical case, q = 2⋅sinφ. We pay the cost of checking for the spherical case in each method invocation because otherwise, users creating their own map projection subclasses could get a non-working implementation.- Parameters:
sin\u03c6
- the sine of the geodetic latitude for which q is calculated.- Returns:
- q from Snyder equation (3-12).
-
dqm_dφ
final double dqm_dφ(double sinφ, double cosφ) Gets the derivative of theqm(double)
method. Callers must multiply the returned value by(1 - NormalizedProjection.eccentricitySquared)
in order to get the derivative of Snyder equation (3-12).- Parameters:
sin\u03c6
- the sine of latitude.cos\u03c6
- the cosines of latitude.- Returns:
- the
qm
derivative at the specified latitude.
-
sinβ
final double sinβ(double sinφ) Converts the sine of geodetic latitude to the sin of authalic latitude. This is defined byqm(sinφ) / qmPolar
.- Parameters:
sin\u03c6
- the sine of the geodetic latitude.- Returns:
- the sine of the authalic latitude.
-
φ
Computes the latitude using equation 3-18 from Snyder, followed by iterative resolution of Snyder 3-16. In theory, the series expansion given by equation 3-18 (φ ≈ c₂⋅sin(2β) + c₄⋅sin(4β) + c₈⋅sin(8β)) should be used in replacement of the iterative method. However, in practice the series expansion seems to not have a sufficient amount of terms for achieving the centimetric precision, so we "finish" it by the iterative method. The series expansion is nevertheless useful for reducing the number of iterations.Relationship with northing
The simplest projection using this formula is theCylindricalEqualArea
projection. In that case, sin(β) = y /qmPolar
.Spherical case
In the spherical case, this method returnsβ = asin(sinβ)
. This method does not check for that simplification for the spherical case. This optimization is left to the caller if desired.- Parameters:
sin\u03b2
- sine of the authalic latitude.- Returns:
- the geodetic latitude in radians.
- Throws:
ProjectionException
-