Class AuthalicConversion

All Implemented Interfaces:
Serializable, Parameterized, LenientComparable, org.opengis.referencing.operation.MathTransform, org.opengis.referencing.operation.MathTransform2D
Direct Known Subclasses:
AlbersEqualArea, AuthalicMercator, CylindricalEqualArea, LambertAzimuthalEqualArea

abstract class AuthalicConversion extends NormalizedProjection
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, this AuthalicConversion 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
  • Field Details

    • serialVersionUID

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

      private static final double ECCENTRICITY_THRESHOLD
      The threshold value of NormalizedProjection.eccentricity at which we consider the accuracy of the series expansion insufficient. This threshold is determined empirically with the help of the EqualAreaProjectionTest.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 by Initializer.
    • 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 by Initializer.
    • 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 by Initializer.
    • qmPolar

      final double qmPolar
      Value of qm(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 isSpherical
    • useIterations

      private final boolean useIterations
      true if the NormalizedProjection.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 of initializer or other shall be non-null.
      Parameters:
      initializer - the initializer for computing map projection internal parameters, or null.
      other - the other projection from which to compute parameters, or null.
    • 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φ - 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 the qm(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φ - the sine of latitude.
      cosφ - 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 by qm(sinφ) / qmPolar.
      Parameters:
      sinφ - the sine of the geodetic latitude.
      Returns:
      the sine of the authalic latitude.
    • φ

      final double φ(double sinβ) throws ProjectionException
      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 the CylindricalEqualArea 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β - sine of the authalic latitude.
      Returns:
      the geodetic latitude in radians.
      Throws:
      ProjectionException