java.lang.Object
org.apache.sis.referencing.operation.projection.Initializer

final class Initializer extends Object
Helper class for map projection constructions, providing formulas normally needed only at construction time. Since map projection constructions should not happen very often, we afford using some double-double arithmetic. The main intent is not to provide more accurate coordinate conversions (while it may be a nice side-effect), but to improve the result of matrix multiplications when the map projection is part of a more complex chain of transformations. More specifically we want to be able:
  • To convert degrees to radians, than back to degrees and find the original value.
  • To convert axis length (optionally with flattening factor) to eccentricity, then back to axis length and find the original value.
This has visible effects on WKT formatting among others, but also in our capability to detect simplification opportunities in relatively complex chains of transformations.

As a general rule, we stop storing result with double-double precision after the point where we need transcendental functions (sine, logarithm, etc.), since we do not have double-double versions of those functions. Digits after the double part are usually not significant in such cases, except in some relatively rare scenarios like 1 ± x where x is much smaller than 1.

Since:
0.6
Version:
1.3
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final ContextualParameters
    The parameters used for creating the map projection.
    (package private) final DoubleDouble
    The square of eccentricity: ℯ² = (a²-b²)/a² where is the eccentricity, a is the semi-major axis length and b is the semi-minor axis length.
    (package private) final Parameters
    The user supplied parameters, stored temporarily while we transfer the information to context.
    private final byte
    Sign of central meridian: -1 if negative, 0 if zero, +1 if positive.
    (package private) final ProjectionVariant
    Map projection variant, or null if none.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Initializer(org.opengis.referencing.operation.OperationMethod method, Parameters parameters, Map<NormalizedProjection.ParameterRole,? extends org.opengis.parameter.ParameterDescriptor<? extends Number>> roles, ProjectionVariant variant)
    Creates a new initializer.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) final DoubleDouble
    Returns b/a where a is the semi-major axis length and b the semi-minor axis length.
    (package private) final double
    getAndStore(org.opengis.parameter.ParameterDescriptor<? extends Number> descriptor)
    Gets a parameter value identified by the given descriptor and stores it in the context.
    (package private) final double
    getAndStore(org.opengis.parameter.ParameterDescriptor<Double> descriptor, double defaultValue)
    Same as getAndStore(ParameterDescriptor), but returns the given default value if the parameter is not specified.
    (package private) final int
    getAndStore(org.opengis.parameter.ParameterDescriptor<Integer> descriptor, int defaultValue)
    Same as getAndStore(ParameterDescriptor, double) but working on integer values.
    (package private) final double
    Returns the radius of the conformal sphere (assuming a semi-major axis length of 1) at a given latitude.
    (package private) final double
    radiusOfCurvature(double sinφ)
    Returns the radius of curvature of the ellipsoid perpendicular to the meridian at latitude φ.
    (package private) final DoubleDouble
    rν2(double sinφ)
    Computes the square of the reciprocal of the radius of curvature of the ellipsoid perpendicular to the meridian at latitude φ.
    (package private) final double
    scaleAtφ(double sinφ, double cosφ)
    Returns the scale factor at latitude φ (Snyder 14-15).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • context

      final ContextualParameters context
      The parameters used for creating the map projection. This object will be stored in the map projection.
      See Also:
    • parameters

      final Parameters parameters
      The user supplied parameters, stored temporarily while we transfer the information to context.
    • eccentricitySquared

      final DoubleDouble eccentricitySquared
      The square of eccentricity: ℯ² = (a²-b²)/a² where is the eccentricity, a is the semi-major axis length and b is the semi-minor axis length.

      This is stored as a double-double value because this parameter is sometimes used for computing back the semi-minor axis length or the inverse flattening factor. In such case we wish to find the original double parameter value without rounding errors. This wish usually do not apply to other internal NormalizedProjection parameters.

    • signum_λ0

      private final byte signum_λ0
      Sign of central meridian: -1 if negative, 0 if zero, +1 if positive.
    • variant

      final ProjectionVariant variant
      Map projection variant, or null if none.
  • Constructor Details

    • Initializer

      Initializer(org.opengis.referencing.operation.OperationMethod method, Parameters parameters, Map<NormalizedProjection.ParameterRole,? extends org.opengis.parameter.ParameterDescriptor<? extends Number>> roles, ProjectionVariant variant)
      Creates a new initializer. The parameters are described in NormalizedProjection(OperationMethod, Parameters, Map).
      Parameters:
      method - description of the map projection parameters.
      parameters - the parameters of the projection to be created.
      roles - parameters to look for central meridian, scale factor, false easting, false northing and other values.
      variant - the map projection variant, or null if none.
  • Method Details

    • getAndStore

      final double getAndStore(org.opengis.parameter.ParameterDescriptor<? extends Number> descriptor)
      Gets a parameter value identified by the given descriptor and stores it in the context. A "contextual parameter" is a parameter that apply to the normalize → this → denormalize chain as a whole. It does not really apply to a NormalizedProjection instance taken alone.

      This method performs the following actions:

      • Convert the value to the units specified by the descriptor.
      • Ensure that the value is contained in the range specified by the descriptor.
      • Store the value only if different than the default value.
    • getAndStore

      final double getAndStore(org.opengis.parameter.ParameterDescriptor<Double> descriptor, double defaultValue)
      Same as getAndStore(ParameterDescriptor), but returns the given default value if the parameter is not specified. This method shall be used only for parameters having a default value more complex than what we can represent in ParameterDescriptor.getDefaultValue().
    • getAndStore

      final int getAndStore(org.opengis.parameter.ParameterDescriptor<Integer> descriptor, int defaultValue)
      Same as getAndStore(ParameterDescriptor, double) but working on integer values.
    • axisLengthRatio

      final DoubleDouble axisLengthRatio()
      Returns b/a where a is the semi-major axis length and b the semi-minor axis length. We retrieve this value from the eccentricity with b/a = sqrt(1-ℯ²).

      Tip: for ℯ₁ = [1 - √(1 - ℯ²)] / [1 + √(1 - ℯ²)] (Snyder 3-24), invoke DoubleDouble.ratio_1m_1p() on the returned value.

    • rν2

      final DoubleDouble rν2(double sinφ)
      Computes the square of the reciprocal of the radius of curvature of the ellipsoid perpendicular to the meridian at latitude φ. That radius of curvature is:
      ν = 1 / √(1 - ℯ²⋅sin²φ)
      This method returns 1/ν², which is the (1 - ℯ²⋅sin²φ) part of above equation. Special cases:
      • If φ is 0°, then m is 1.
      • If φ is ±90°, then m is 0 provided that we are not in the spherical case (otherwise we get Double.NaN).
      Parameters:
      sinφ - the sine of the φ latitude.
      Returns:
      reciprocal squared of the radius of curvature of the ellipsoid perpendicular to the meridian at latitude φ.
    • radiusOfCurvature

      final double radiusOfCurvature(double sinφ)
      Returns the radius of curvature of the ellipsoid perpendicular to the meridian at latitude φ. This is 1/sqrt(rν2(sinφ)).
      Parameters:
      sinφ - the sine of the φ latitude.
      Returns:
      radius of curvature of the ellipsoid perpendicular to the meridian at latitude φ.
    • radiusOfConformalSphere

      final double radiusOfConformalSphere(double sinφ)
      Returns the radius of the conformal sphere (assuming a semi-major axis length of 1) at a given latitude. The radius of conformal sphere is computed from ρ, which is the radius of curvature in the meridian at latitude φ, and ν which is the radius of curvature in the prime vertical, as below:
      Rc = √(ρ⋅ν) = √(1 – ℯ²) / (1 – ℯ²sin²φ)
      This is a function of latitude and therefore not constant. When used for spherical projections the use of φ₀ (or φ₁ as relevant to method) for φ is suggested, except if the projection is equal area when the radius of authalic sphere should be used.
      Parameters:
      sinφ - the sine of the φ latitude.
      Returns:
      radius of the conformal sphere at latitude φ.
    • scaleAtφ

      final double scaleAtφ(double sinφ, double cosφ)
      Returns the scale factor at latitude φ (Snyder 14-15). This is computed as:
      cosφ / sqrt(rν2(sinφ))
      The result is returned as a double because the limited precision of sinφ and cosφ makes the error term meaningless. We use double-double arithmetic only for intermediate calculation.
      Parameters:
      sinφ - the sine of the φ latitude.
      cosφ - the cosine of the φ latitude.
      Returns:
      scale factor at latitude φ.