You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2022/05/03 17:25:14 UTC
[sis] 01/05: Rename `EqualAreaProjection` as `AuthalicConversion`.
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
commit b318c2161a48eb3abcdf30812d678b94199a5008
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Tue May 3 12:02:01 2022 +0200
Rename `EqualAreaProjection` as `AuthalicConversion`.
---
.../operation/projection/AlbersEqualArea.java | 2 +-
...AreaProjection.java => AuthalicConversion.java} | 25 +++++++++++++++-------
.../operation/projection/ConformalProjection.java | 4 ++--
.../operation/projection/CylindricalEqualArea.java | 4 ++--
.../projection/LambertAzimuthalEqualArea.java | 13 ++++++++---
...ectionTest.java => AuthalicConversionTest.java} | 18 ++++++++--------
.../sis/test/suite/ReferencingTestSuite.java | 2 +-
7 files changed, 42 insertions(+), 26 deletions(-)
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AlbersEqualArea.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AlbersEqualArea.java
index 575da204f1..d32c47c518 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AlbersEqualArea.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AlbersEqualArea.java
@@ -54,7 +54,7 @@ import static org.apache.sis.internal.referencing.provider.AlbersEqualArea.*;
* @since 0.8
* @module
*/
-public class AlbersEqualArea extends EqualAreaProjection {
+public class AlbersEqualArea extends AuthalicConversion {
/**
* For cross-version compatibility.
*/
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/EqualAreaProjection.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AuthalicConversion.java
similarity index 90%
rename from core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/EqualAreaProjection.java
rename to core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AuthalicConversion.java
index 06691ef8c3..38a373aace 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/EqualAreaProjection.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AuthalicConversion.java
@@ -23,20 +23,29 @@ import static org.apache.sis.math.MathFunctions.atanh;
/**
- * Base class of {@link AlbersEqualArea} and {@link CylindricalEqualArea} projections.
- * Those projections have in common the property of being <cite>equal-area</cite>.
- * However we do not put this base class in public API because not all equal-area projections extend this base class.
+ * Base class of projections doing conversions between <cite>geodetic</cite> latitude and <cite>authalic</cite> latitude.
+ * This is used by <cite>equal-area</cite> projections such as {@link AlbersEqualArea} and {@link CylindricalEqualArea}.
+ * However not all equal-area projections extend this base class, and conversely not all sub-classes are equal-area.
* For example the {@link Sinusoidal} projection, despite being equal-area, uses different formulas.
*
- * <p>Note that no projection can be both conformal and equal-area. This restriction is implemented in class
- * hierarchy with {@link ConformalProjection} and {@link EqualAreaProjection} being two distinct classes.</p>
+ * <p>Note that no projection can be both conformal and equal-area. So the formulas in this class
+ * are usually mutually exclusive with formulas in {@link ConformalProjection} class.</p>
+ *
+ * <h2>Note on class naming</h2>
+ * Lee (1944) defines an <cite>authalic map projection</cite> 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 {@code AuthalicConversion} is <strong>not</strong> necessarily an authalic projection.
+ * Subclasses may want to use the latitude conversion formulas for other purposes.
+ *
+ * <h3>References</h3>
+ * <p>Lee, L. P. "The Nomenclature and Classification of Map Projections." Empire Survey Review 7, 190-200, 1944.</p>
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.2
* @since 0.8
* @module
*/
-abstract class EqualAreaProjection extends NormalizedProjection {
+abstract class AuthalicConversion extends NormalizedProjection {
/**
* For cross-version compatibility.
*/
@@ -101,7 +110,7 @@ abstract class EqualAreaProjection extends NormalizedProjection {
*
* @param initializer the initializer for computing map projection internal parameters.
*/
- EqualAreaProjection(final Initializer initializer) {
+ AuthalicConversion(final Initializer initializer) {
super(initializer);
isSpherical = (eccentricitySquared == 0);
final double e2 = eccentricitySquared;
@@ -143,7 +152,7 @@ abstract class EqualAreaProjection extends NormalizedProjection {
* formulas instead of the ellipsoidal ones. This constructor allows to transfer all parameters to the new
* instance without recomputing them.
*/
- EqualAreaProjection(final EqualAreaProjection other) {
+ AuthalicConversion(final AuthalicConversion other) {
super(other);
c2β = other.c2β;
c4β = other.c4β;
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ConformalProjection.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ConformalProjection.java
index e606f9b635..997c5c5ea8 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ConformalProjection.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ConformalProjection.java
@@ -27,8 +27,8 @@ import static java.lang.Math.*;
* However we do not put this base class in public API because not all conformal projections extend this base class.
* For example the {@link TransverseMercator} projection, despite being conformal, uses very different formulas.
*
- * <p>Note that no projection can be both conformal and equal-area. This restriction is implemented in class
- * hierarchy with {@link ConformalProjection} and {@link EqualAreaProjection} being two distinct classes.</p>
+ * <p>Note that no projection can be both conformal and equal-area. So the formulas in this class are usually
+ * mutually exclusive with formulas in {@link AuthalicConversion} class (used for equal-area projections).</p>
*
* <p>This base class can been seen as a generalization of <cite>Lambert Conic Conformal</cite> projection,
* which includes some other projections like Mercator and Polar Stereographic as special cases.
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/CylindricalEqualArea.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/CylindricalEqualArea.java
index b669140786..ed85a6e3d7 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/CylindricalEqualArea.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/CylindricalEqualArea.java
@@ -63,7 +63,7 @@ import static org.apache.sis.internal.referencing.provider.LambertCylindricalEqu
* @since 0.8
* @module
*/
-public class CylindricalEqualArea extends EqualAreaProjection {
+public class CylindricalEqualArea extends AuthalicConversion {
/**
* For cross-version compatibility.
*/
@@ -327,7 +327,7 @@ public class CylindricalEqualArea extends EqualAreaProjection {
*/
Spherical(final CylindricalEqualArea other) {
super(other);
- context.getMatrix(ContextualParameters.MatrixRole.DENORMALIZATION).convertAfter(1, DIMENSION, null);
+ context.getMatrix(ContextualParameters.MatrixRole.DENORMALIZATION).convertAfter(1, 2, null);
}
/**
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/LambertAzimuthalEqualArea.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/LambertAzimuthalEqualArea.java
index 8a4cac76ee..c56446e768 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/LambertAzimuthalEqualArea.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/LambertAzimuthalEqualArea.java
@@ -46,7 +46,7 @@ import static org.apache.sis.internal.referencing.provider.LambertAzimuthalEqual
* @since 1.2
* @module
*/
-public class LambertAzimuthalEqualArea extends EqualAreaProjection {
+public class LambertAzimuthalEqualArea extends AuthalicConversion {
/**
* For cross-version compatibility.
*/
@@ -182,6 +182,13 @@ public class LambertAzimuthalEqualArea extends EqualAreaProjection {
final double sinφ = sin(φ);
final double qm = qm(sinφ);
if (!polar) {
+ /*
+ * Note: in the spherical case, ß = φ (ß is the authalic radius).
+ * We could do an optimization, but it would be a cost for the ellipsoidal
+ * case without saving a lot for the spherical case. The general path is:
+ *
+ * sinß = qm(sinφ) / qmPolar = 2*sinφ / 2 = sinφ
+ */
final double sinß = qm / qmPolar;
final double cosß = sqrt(1 - sinß*sinß);
final double c = sinß0*sinß + cosß0*cosß*cosλ + 1;
@@ -277,7 +284,7 @@ public class LambertAzimuthalEqualArea extends EqualAreaProjection {
}
/*
- * We do not provide a specialized sub-class for the spherical case
- * because the simplifications are too small.
+ * We do not provide a specialized sub-class for the spherical case because
+ * simplifications are too small. We only need to skip the φ ↔ ß conversion.
*/
}
diff --git a/core/sis-referencing/src/test/java/org/apache/sis/referencing/operation/projection/EqualAreaProjectionTest.java b/core/sis-referencing/src/test/java/org/apache/sis/referencing/operation/projection/AuthalicConversionTest.java
similarity index 87%
rename from core/sis-referencing/src/test/java/org/apache/sis/referencing/operation/projection/EqualAreaProjectionTest.java
rename to core/sis-referencing/src/test/java/org/apache/sis/referencing/operation/projection/AuthalicConversionTest.java
index 40953a450e..213b7decd8 100644
--- a/core/sis-referencing/src/test/java/org/apache/sis/referencing/operation/projection/EqualAreaProjectionTest.java
+++ b/core/sis-referencing/src/test/java/org/apache/sis/referencing/operation/projection/AuthalicConversionTest.java
@@ -31,7 +31,7 @@ import static org.junit.Assert.assertEquals;
/**
- * Tests {@link EqualAreaProjection}.
+ * Tests {@link AuthalicConversion}.
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.0
@@ -39,14 +39,14 @@ import static org.junit.Assert.assertEquals;
* @module
*/
@DependsOn(NormalizedProjectionTest.class)
-public final strictfp class EqualAreaProjectionTest extends MapProjectionTestCase {
+public final strictfp class AuthalicConversionTest extends MapProjectionTestCase {
/**
* Creates the projection to be tested.
*
* @param ellipsoidal {@code false} for a sphere, or {@code true} for WGS84 ellipsoid.
* @return a test instance of the projection.
*/
- private EqualAreaProjection create(final boolean ellipsoidal) {
+ private AuthalicConversion create(final boolean ellipsoidal) {
final DefaultOperationMethod provider = new LambertCylindricalEqualArea();
final CylindricalEqualArea projection = new CylindricalEqualArea(provider, parameters(provider, ellipsoidal));
tolerance = NormalizedProjection.ANGULAR_TOLERANCE; // = linear tolerance on a sphere of radius 1.
@@ -60,7 +60,7 @@ public final strictfp class EqualAreaProjectionTest extends MapProjectionTestCas
* @param y in the cylindrical case, this is northing on the normalized ellipsoid.
* @return the latitude in radians.
*/
- private static double reference(final EqualAreaProjection projection, final double y) {
+ private static double reference(final AuthalicConversion projection, final double y) {
final double e = projection.eccentricity;
final double e2 = projection.eccentricitySquared;
final double e4 = e2 * e2;
@@ -78,13 +78,13 @@ public final strictfp class EqualAreaProjectionTest extends MapProjectionTestCas
}
/**
- * Compares {@link EqualAreaProjection#φ(double)} with formula taken as references.
+ * Compares {@link AuthalicConversion#φ(double)} with formula taken as references.
*
* @throws ProjectionException if the function does not converge.
*/
@Test
public void compareWithReference() throws ProjectionException {
- final EqualAreaProjection projection = create(true);
+ final AuthalicConversion projection = create(true);
final Random random = TestUtilities.createRandomNumberGenerator();
for (int i=0; i<100; i++) {
final double y = random.nextDouble() * 3 - 1.5;
@@ -95,15 +95,15 @@ public final strictfp class EqualAreaProjectionTest extends MapProjectionTestCas
}
/**
- * Searches a value for {@link EqualAreaProjection#ECCENTRICITY_THRESHOLD}.
+ * Searches a value for {@link AuthalicConversion#ECCENTRICITY_THRESHOLD}.
* This method is not part of test suite. Steps to enable:
*
* <ol>
- * <li>In {@link EqualAreaProjection#φ(double)} method, for {@code useIterations} to {@code false}.</li>
+ * <li>In {@link AuthalicConversion#φ(double)} method, for {@code useIterations} to {@code false}.</li>
* <li>Add a {@link Test} annotation on this method.
* </ol>
*
- * @throws ProjectionException if {@link EqualAreaProjection#φ(double)} did not converge.
+ * @throws ProjectionException if {@link AuthalicConversion#φ(double)} did not converge.
*/
@SuppressWarnings("UseOfSystemOutOrSystemErr")
public void searchThreshold() throws ProjectionException {
diff --git a/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java b/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
index 9417060f15..4fc71d699b 100644
--- a/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
+++ b/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
@@ -189,7 +189,7 @@ import org.junit.BeforeClass;
org.apache.sis.referencing.operation.projection.PolarStereographicTest.class,
org.apache.sis.referencing.operation.projection.ObliqueStereographicTest.class,
org.apache.sis.referencing.operation.projection.ObliqueMercatorTest.class,
- org.apache.sis.referencing.operation.projection.EqualAreaProjectionTest.class,
+ org.apache.sis.referencing.operation.projection.AuthalicConversionTest.class,
org.apache.sis.referencing.operation.projection.CylindricalEqualAreaTest.class,
org.apache.sis.referencing.operation.projection.AlbersEqualAreaTest.class,
org.apache.sis.referencing.operation.projection.LambertAzimuthalEqualAreaTest.class,