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/09/28 11:12:59 UTC
[sis] 01/04: Do not export the `org.apache.sis.referencing.operation.projection` package. It does not need to be used directly, and its design is non-trivial.
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 a0cf252abed764910725553f9e8fb9d94f08d0a1
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Thu Sep 28 11:16:31 2023 +0200
Do not export the `org.apache.sis.referencing.operation.projection` package.
It does not need to be used directly, and its design is non-trivial.
---
.../main/module-info.java | 1 -
.../main/org/apache/sis/io/wkt/Convention.java | 2 -
.../apache/sis/referencing/GeodeticCalculator.java | 1 -
.../sis/referencing/cs/CoordinateSystems.java | 6 +--
.../sis/referencing/operation/package-info.java | 9 +----
.../operation/projection/package-info.java | 7 +---
.../operation/transform/ContextualParameters.java | 47 ++++++++--------------
.../operation/transform/package-info.java | 2 +-
.../main/org/apache/sis/util/ComparisonMode.java | 9 ++---
.../gui/referencing/PositionableProjection.java | 8 ----
10 files changed, 27 insertions(+), 65 deletions(-)
diff --git a/endorsed/src/org.apache.sis.referencing/main/module-info.java b/endorsed/src/org.apache.sis.referencing/main/module-info.java
index 0f58149356..6b668db7a6 100644
--- a/endorsed/src/org.apache.sis.referencing/main/module-info.java
+++ b/endorsed/src/org.apache.sis.referencing/main/module-info.java
@@ -165,7 +165,6 @@ module org.apache.sis.referencing {
exports org.apache.sis.referencing.operation;
exports org.apache.sis.referencing.operation.builder;
exports org.apache.sis.referencing.operation.matrix;
- exports org.apache.sis.referencing.operation.projection;
exports org.apache.sis.referencing.operation.transform;
exports org.apache.sis.referencing.util to
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/io/wkt/Convention.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/io/wkt/Convention.java
index 0810cbbc84..7b563387b8 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/io/wkt/Convention.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/io/wkt/Convention.java
@@ -206,8 +206,6 @@ public enum Convention {
* </ul>
*
* This convention is used only for debugging purpose.
- *
- * @see org.apache.sis.referencing.operation.projection.NormalizedProjection#getParameterValues()
*/
@Debug
INTERNAL(false, false, false);
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/GeodeticCalculator.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/GeodeticCalculator.java
index c17e1dbcca..27d2f1d978 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/GeodeticCalculator.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/GeodeticCalculator.java
@@ -1168,7 +1168,6 @@ public class GeodeticCalculator {
* @throws GeodeticException if the projection cannot be computed.
*
* @see #moveToEndPoint()
- * @see org.apache.sis.referencing.operation.projection.AzimuthalEquidistant
*
* @since 1.1
*/
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/CoordinateSystems.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/CoordinateSystems.java
index 60503e213e..af4cc47552 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/CoordinateSystems.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/cs/CoordinateSystems.java
@@ -448,9 +448,8 @@ next: for (final CoordinateSystem cs : targets) {
* <h4>Coordinate system normalization</h4>
* This method is often used together with {@link #swapAndScaleAxes swapAndScaleAxes(…)} for normalizing the
* coordinate values given to a {@linkplain org.apache.sis.referencing.operation.transform.AbstractMathTransform
- * math transform}.
+ * math transform}. For example:
*
- * <h4>Example</h4>
* {@snippet lang="java" :
* CoordinateSystem sourceCS = ...;
* CoordinateSystem targetCS = ...;
@@ -459,9 +458,6 @@ next: for (final CoordinateSystem cs : targets) {
* Matrix step3 = swapAndScaleAxes(replaceAxes(targetCS, AxisConvention.NORMALIZED), targetCS);
* }
*
- * A rational for normalized axis order and units is explained in the <cite>Axis units and direction</cite> section
- * in the description of the {@linkplain org.apache.sis.referencing.operation.projection map projection package}.
- *
* @param cs the coordinate system, or {@code null}.
* @param filter the modifications to apply on coordinate system axes.
* @return the modified coordinate system as a new instance,
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/package-info.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/package-info.java
index 7968ce345d..d0c563dffa 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/package-info.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/package-info.java
@@ -21,13 +21,8 @@
* The remaining discussion on this page is specific to the Apache SIS implementation.
*
* <p>This package provides an ISO 19111 {@linkplain org.apache.sis.referencing.operation.AbstractCoordinateOperation
- * Coordinate Operation implementation} and support classes. The actual transform work is performed by the following
- * sub-packages, but most users will not need to deal with them directly:</p>
- *
- * <ul>
- * <li>{@link org.apache.sis.referencing.operation.projection} — map projections,</li>
- * <li>{@link org.apache.sis.referencing.operation.transform} — any transform other than map projections.</li>
- * </ul>
+ * Coordinate Operation implementation} and support classes. The actual transform work is performed by the sub-packages,
+ * but most users will not need to deal with them directly.</p>
*
* <h2>Apache SIS extensions</h2>
* Some SIS implementations provide additional methods that are not part of OGC/ISO specifications:
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/package-info.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/package-info.java
index 0fc98bd16b..2ec31c63a0 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/package-info.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/package-info.java
@@ -17,14 +17,11 @@
/**
* Map projection implementations.
- * This package is mostly for documentation purpose (each projection documents its name and parameters)
- * and for implementers who want to extend a map projection. This package should usually not be used directly.
- *
- * <p>The best way to get a projection is to use the
+ * This package should usually not be used directly. The best way to get a projection is to use the
* {@linkplain org.apache.sis.referencing.operation.DefaultCoordinateOperationFactory coordinate operation factory}
* with the source and target CRS. That factory can bundle the projections defined in this package, together with any
* affine transform required for handling unit conversions and axis swapping, in a single (potentially concatenated)
- * operation.</p>
+ * operation.
*
* <p>Users wanting to build their transforms directly should also avoid instantiating objects directly from this
* package and use a {@linkplain org.apache.sis.referencing.operation.transform.DefaultMathTransformFactory math
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/ContextualParameters.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/ContextualParameters.java
index 31ce26e09a..bc5f95b4f5 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/ContextualParameters.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/ContextualParameters.java
@@ -62,20 +62,18 @@ import static org.apache.sis.referencing.util.WKTUtilities.LOGGER;
* The parameters that describe a sequence of
* <cite>normalize</cite> → <cite>non-linear kernel</cite> → <cite>denormalize</cite> transforms as a whole.
* The normalize and denormalize steps must be affine transforms, while the non-linear kernel is arbitrary.
+ * This separation is useful for doing in the linear steps any unit conversions and axis swapping necessary
+ * for allowing the non-linear step to work in some predefined (implementation specific) coordinate system.
*
- * <div class="note"><b>Note:</b> actually there is nothing in this class which force the kernel to be non-linear.
- * But this class is useless if the kernel is linear, because 3 linear steps can be efficiently
- * {@linkplain java.awt.geom.AffineTransform#concatenate concatenated} in a single affine transform.</div>
- *
- * <p>Contextual parameters can be {@linkplain AbstractMathTransform#getContextualParameters() associated}
- * to the <cite>non-linear kernel</cite> step of the above-cited sequence.
+ * <p>Contextual parameters are {@linkplain AbstractMathTransform#getContextualParameters() associated}
+ * to the <em>non-linear kernel</em> step of the above-cited sequence.
* Since the {@linkplain AbstractMathTransform#getParameterValues() parameter values} of the non-linear kernel contains
* only normalized parameters (e.g. a map projection on an ellipsoid having a <cite>semi-major</cite> axis length of 1),
* Apache SIS needs contextual information for reconstructing the parameters of the complete transforms chain.</p>
*
* <h2>Usage in map projections</h2>
- * This object is used mostly for Apache SIS implementation of map projections, where the non-linear kernel is a
- * {@linkplain org.apache.sis.referencing.operation.projection.NormalizedProjection normalized projection}.
+ * This object is used mostly for Apache SIS implementation of map projections, where the non-linear kernel
+ * is a normalized projection working on (<var>longitude</var>, <var>latitude</var>) coordinates in radians.
* The {@linkplain #completeTransform(MathTransformFactory, MathTransform) complete map projection}
* (ignoring {@linkplain org.apache.sis.referencing.cs.CoordinateSystems#swapAndScaleAxes changes of axis order})
* is a chain of 3 transforms as shown below:
@@ -91,12 +89,10 @@ import static org.apache.sis.referencing.util.WKTUtilities.LOGGER;
* {@code ContextualParameters} is typically created and used as below:
*
* <ol class="verbose">
- * <li>A {@link MathTransformProvider} instantiates a class from the
- * {@linkplain org.apache.sis.referencing.operation.projection map projection package}.
- * Note that different providers may instantiate the same map projection class.
- * For example, both <cite>"Mercator (variant A)"</cite> and <cite>"Mercator (variant B)"</cite> methods
- * instantiate the same {@link org.apache.sis.referencing.operation.projection.Mercator} class,
- * but with different ways to represent the parameters.</li>
+ * <li>A {@link MathTransformProvider} instantiates a non-linear transform working in a predefined coordinate system.
+ * Note that different providers may instantiate the same transform class but with different parameters.
+ * For example, both <cite>"Mercator (variant A)"</cite> and <cite>"Mercator (variant B)"</cite> operation methods
+ * instantiate the same Mercator projection class, but with different ways to represent the parameters.</li>
*
* <li>The map projection constructor fetches all parameters that it needs from the user supplied
* {@link org.apache.sis.parameter.Parameters}, initializes the projection, then saves the parameter values that
@@ -125,7 +121,6 @@ import static org.apache.sis.referencing.util.WKTUtilities.LOGGER;
* @author Martin Desruisseaux (Geomatys)
* @version 1.4
*
- * @see org.apache.sis.referencing.operation.projection.NormalizedProjection
* @see AbstractMathTransform#getContextualParameters()
*
* @since 0.6
@@ -337,14 +332,9 @@ public class ContextualParameters extends Parameters implements Serializable {
* {@linkplain org.apache.sis.referencing.operation.DefaultOperationMethod operation method}
* given to the constructor.
*
- * <p>The values for those parameters is given by the {@link #values()} method. Those values may be used in
- * the {@linkplain #getMatrix(MatrixRole) normalization / denormalization} transforms, in the kernel, or both.</p>
- *
- * <div class="note"><b>Note:</b>
- * The definition of "kernel" is left to implementers.
- * In the particular case of Apache SIS implementation of map projections,
- * kernels are instances of {@link org.apache.sis.referencing.operation.projection.NormalizedProjection}.
- * Other "kernels" in SIS are {@link EllipsoidToCentricTransform} and {@link MolodenskyTransform}.</div>
+ * <p>The values for those parameters are given by the {@link #values()} method.
+ * Those values may be used by the {@linkplain #getMatrix(MatrixRole) normalization / denormalization}
+ * linear steps, by the non-linear kernel, or both.</p>
*
* @return the description of the parameters.
*/
@@ -391,9 +381,9 @@ public class ContextualParameters extends Parameters implements Serializable {
*
*
* <h4>Application to map projections</h4>
- * After {@link org.apache.sis.referencing.operation.projection.NormalizedProjection} construction, the matrices
- * returned by {@code projection.getContextualParameters().getMatrix(…)} are initialized to the values shown below.
- * Note that some {@code NormalizedProjection} subclasses apply further modifications to those matrices.
+ * After the construction of a non-linear kernel working on (<var>longitude</var>, <var>latitude</var>)
+ * coordinates in radians, the matrices returned by {@code projection.getContextualParameters().getMatrix(…)}
+ * are initialized to the values shown below.
*
* <table class="sis">
* <caption>Initial matrix coefficients after {@code NormalizedProjection} construction</caption>
@@ -511,13 +501,10 @@ public class ContextualParameters extends Parameters implements Serializable {
* the hood".</p>
*
* @param factory the factory to use for creating math transform instances.
- * @param kernel the (usually non-linear) kernel.
- * This is often a {@link org.apache.sis.referencing.operation.projection.NormalizedProjection}.
+ * @param kernel the non-linear kernel which expects "normalized" coordinates in a predefined coordinate system.
* @return the concatenation of <cite>normalize</cite> → <cite>the given kernel</cite> → <cite>denormalize</cite>
* transforms.
* @throws FactoryException if an error occurred while creating a math transform instance.
- *
- * @see org.apache.sis.referencing.operation.projection.NormalizedProjection#createMapProjection(MathTransformFactory)
*/
public MathTransform completeTransform(final MathTransformFactory factory, final MathTransform kernel)
throws FactoryException
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/package-info.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/package-info.java
index 8085dacdb1..23dc01ce24 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/package-info.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/transform/package-info.java
@@ -35,7 +35,7 @@
* class when possible.
*
* <p>This package does not include map projections, which are a special kind of transforms defined
- * in their own {@linkplain org.apache.sis.referencing.operation.projection projection} package.</p>
+ * in their own internal package.</p>
*
*
* <h2>Creating math transforms</h2>
diff --git a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ComparisonMode.java b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ComparisonMode.java
index 143abf332d..f7b9888466 100644
--- a/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ComparisonMode.java
+++ b/endorsed/src/org.apache.sis.util/main/org/apache/sis/util/ComparisonMode.java
@@ -103,9 +103,8 @@ public enum ComparisonMode {
* <h4>Application to coordinate operations</h4>
* If the objects being compared are {@link org.opengis.referencing.operation.MathTransform} instances,
* then two transforms defined in a different way may be considered equivalent. For example, it is possible
- * to define a {@linkplain org.apache.sis.referencing.operation.projection.Mercator Mercator} projection in
- * two different ways, as a <cite>"Mercator (1SP)"</cite> or as a <cite>"Mercator (2SP)"</cite> projection,
- * each having their own set of parameters.
+ * to define a Mercator projection in different ways, named "variant A", "variant B" and "variant C"
+ * in EPSG dataset, each having their own set of parameters.
* The {@link #STRICT} or {@link #BY_CONTRACT} modes shall consider two projections as equal only if their
* {@linkplain org.apache.sis.referencing.operation.transform.AbstractMathTransform#getParameterValues()
* parameter values} are strictly identical, while the {@code IGNORE_METADATA} mode can consider
@@ -113,8 +112,8 @@ public enum ComparisonMode {
* transformations still produce the same results.
*
* <h4>Example</h4>
- * A <cite>"Mercator (2SP)"</cite> projection with a <cite>standard parallel</cite> value of 60° produces the
- * same results than a <cite>"Mercator (1SP)"</cite> projection with a <cite>scale factor</cite> value of 0.5.
+ * A <cite>"Mercator (variant B)"</cite> projection with a <cite>standard parallel</cite> value of 60° produces the
+ * same results than a <cite>"Mercator (variant A)"</cite> projection with a <cite>scale factor</cite> value of 0.5.
*
* @see org.apache.sis.util.Utilities#equalsIgnoreMetadata(Object, Object)
*/
diff --git a/optional/src/org.apache.sis.gui/main/org/apache/sis/gui/referencing/PositionableProjection.java b/optional/src/org.apache.sis.gui/main/org/apache/sis/gui/referencing/PositionableProjection.java
index 903a4ebbc3..e274ffcec1 100644
--- a/optional/src/org.apache.sis.gui/main/org/apache/sis/gui/referencing/PositionableProjection.java
+++ b/optional/src/org.apache.sis.gui/main/org/apache/sis/gui/referencing/PositionableProjection.java
@@ -60,8 +60,6 @@ public abstract class PositionableProjection extends CodeList<PositionableProjec
/**
* Provides <cite>Orthographic</cite> projection centered on a point of interest.
- *
- * @see org.apache.sis.referencing.operation.projection.Orthographic
*/
public static final PositionableProjection ORTHOGRAPHIC =
new PositionableProjection("ORTHOGRAPHIC", Resources.Keys.Orthographic)
@@ -80,8 +78,6 @@ public abstract class PositionableProjection extends CodeList<PositionableProjec
/**
* Provides <cite>Azimuthal Equidistant</cite> projection centered on a point of interest.
* For projection on the ellipsoid, this is valid only under 800 km of the point of interest.
- *
- * @see org.apache.sis.referencing.operation.projection.AzimuthalEquidistant
*/
public static final PositionableProjection AZIMUTHAL_EQUIDISTANT =
new PositionableProjection("AZIMUTHAL_EQUIDISTANT", Resources.Keys.AzimuthalEquidistant)
@@ -99,8 +95,6 @@ public abstract class PositionableProjection extends CodeList<PositionableProjec
/**
* Provides <cite>Universal Transverse Mercator</cite> projection for the zone in the point of interest.
- *
- * @see org.apache.sis.referencing.operation.projection.Mercator
*/
public static final PositionableProjection UTM =
new PositionableProjection("UTM", Resources.Keys.UTM)
@@ -121,8 +115,6 @@ public abstract class PositionableProjection extends CodeList<PositionableProjec
/**
* Provides <cite>Mercator (variant C)</cite> projection centered on a point of interest.
- *
- * @see org.apache.sis.referencing.operation.projection.Mercator
*/
public static final PositionableProjection MERCATOR =
new PositionableProjection("MERCATOR", Resources.Keys.Mercator)