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 <martin.desruisse...@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;
