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 2023/05/25 15:22:08 UTC
[sis] 02/03: Add clarification about the use of conformal radius. This is a change in documentation and symbols only.
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 a618f9af4d7219e83a9802f5cf7083997d0c85cd
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Thu May 25 16:57:55 2023 +0200
Add clarification about the use of conformal radius.
This is a change in documentation and symbols only.
---
.../operation/projection/AzimuthalEquidistant.java | 2 +-
.../sis/referencing/operation/projection/Initializer.java | 6 +++---
.../apache/sis/referencing/operation/projection/Mercator.java | 7 ++++---
.../operation/projection/NormalizedProjection.java | 11 +++++++----
.../referencing/operation/projection/ProjectionVariant.java | 6 ++++++
5 files changed, 21 insertions(+), 11 deletions(-)
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AzimuthalEquidistant.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AzimuthalEquidistant.java
index f964505823..8deb5c7306 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AzimuthalEquidistant.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/AzimuthalEquidistant.java
@@ -62,7 +62,7 @@ import static org.apache.sis.internal.referencing.provider.ModifiedAzimuthalEqui
*
* This base class is aimed to provide the general case valid for all distances;
* the fact that current version uses spherical formulas should be considered as an implementation limitation
- * that may change in future version. Subclasses are specialization for more restricted areas.
+ * that may change in future version. Subclasses are specializations for more restricted areas.
*
* @author Martin Desruisseaux (Geomatys)
* @author Maxime Gavens (Geomatys)
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Initializer.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Initializer.java
index 6fe0baa6b1..675360609b 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Initializer.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Initializer.java
@@ -166,8 +166,8 @@ final class Initializer {
} else {
eccentricitySquared = DoubleDouble.ONE.subtract(DoubleDouble.of(b, true).divide(k).square());
}
- final ParameterDescriptor<? extends Number> radius = roles.get(ParameterRole.LATITUDE_OF_CONFORMAL_SPHERE_RADIUS);
- if (radius != null) {
+ final ParameterDescriptor<? extends Number> φr = roles.get(ParameterRole.LATITUDE_OF_CONFORMAL_SPHERE_RADIUS);
+ if (φr != null) {
/*
* EPSG said: R is the radius of the sphere and will normally be one of the CRS parameters.
* If the figure of the earth used is an ellipsoid rather than a sphere then R should be calculated
@@ -184,7 +184,7 @@ final class Initializer {
* final double sinφ = sin(toRadians(parameters.doubleValue(radius)));
* k = b / (1 - eccentricitySquared * (sinφ*sinφ));
*/
- k = rν2(sin(toRadians(parameters.doubleValue(radius))));
+ k = rν2(sin(toRadians(parameters.doubleValue(φr))));
k = DoubleDouble.of(b, true).divide(k);
}
}
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
index e56fb54648..264d17576b 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
@@ -207,9 +207,10 @@ public class Mercator extends ConformalProjection {
case SPHERICAL: {
/*
* According to EPSG guide, the latitude of conformal sphere radius should be the latitude of origin.
- * However, that origin is fixed to 0° by EPSG guide, which makes radius calculation ineffective when
- * using the official parameters. We could fallback on the standard parallel (φ1) if φ0 is not set,
- * but for now we wait to see for real cases. Some arguments that may be worth consideration:
+ * However, that origin is fixed to 0° by EPSG guidance notes, which makes this radius equals to the
+ * semi-minor axis length. We could allow more flexibility by using the standard parallel (φ1) if φ0
+ * is not set, but for now we wait to see for real cases.
+ * Some arguments that may be worth consideration:
*
* - The standard parallel is not an EPSG parameter for Spherical case.
* - Users who set the standard parallel anyway may expect that latitude to be used for radius
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
index 754e4a7bcb..ae65fc71e7 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
@@ -284,10 +284,13 @@ public abstract class NormalizedProjection extends AbstractMathTransform2D imple
*
* <div style="text-align:center">{@include ../transform/formulas.html#DenormalizeCartesian}</div>
*
- * <p>This enumeration shall be used <strong>only</strong> when the user requested explicitly spherical
- * formulas, for example the <cite>"Mercator (Spherical)"</cite> projection (EPSG:1026), but the figure
- * of the Earth may be an ellipsoid rather than a sphere. In the majority of cases, this enumeration should
- * not be used.</p>
+ * <h4>When to use</h4>
+ * This enumeration value should be used only when the user requested explicitly the spherical formulas
+ * of a conformal projection, for example the <cite>"Mercator (Spherical)"</cite> projection (EPSG:1026),
+ * but the figure of the Earth may be an ellipsoid rather than a sphere.
+ * This enumeration value can also be used for other kinds of projection except Equal Area, in which case
+ * the {@linkplain org.apache.sis.referencing.datum.DefaultEllipsoid#getAuthalicRadius() authalic radius}
+ * is preferred. In the majority of cases, this enumeration value can be ignored.
*/
LATITUDE_OF_CONFORMAL_SPHERE_RADIUS,
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionVariant.java b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionVariant.java
index 518be5934b..3feb162cd9 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionVariant.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/ProjectionVariant.java
@@ -49,7 +49,13 @@ interface ProjectionVariant {
* This method can be overridden for handling authalic radius, but not conformance sphere radius.
* The latter is handled by {@link NormalizedProjection.ParameterRole#LATITUDE_OF_CONFORMAL_SPHERE_RADIUS}.
*
+ * <h4>When to use</h4>
+ * Authalic radius are used with Equal Area projections.
+ * For other kinds of projection, the radius of conformal sphere is preferred.
+ *
* @return whether this variant is a spherical variant using authalic radius.
+ *
+ * @see NormalizedProjection.ParameterRole#LATITUDE_OF_CONFORMAL_SPHERE_RADIUS
*/
default boolean useAuthalicRadius() {
return false;