sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 02/02: Update the link to Proj4 and improve documentation about the NormalizedProjection.transform(…) expected inputs and outputs.
Date Fri, 27 Jul 2018 15:06:58 GMT
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 c874fbe93f40ef0744b148e30e4dcc8e425bb51c
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Fri Jul 27 16:51:28 2018 +0200

    Update the link to Proj4 and improve documentation about the NormalizedProjection.transform(…)
expected inputs and outputs.
---
 .../sis/metadata/iso/citation/Citations.java       |  2 +-
 .../operation/projection/NormalizedProjection.java | 33 ++++++++++++++++------
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
index ba4874a..fca7a17 100644
--- a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
+++ b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/Citations.java
@@ -336,7 +336,7 @@ public final class Citations extends Static {
     public static final IdentifierSpace<Integer> GEOTIFF = new CitationConstant.Authority<>(Constants.GEOTIFF);
 
     /**
-     * The authority for identifiers of objects defined by the <a href="http://trac.osgeo.org/proj/">Proj.4</a>
project.
+     * The authority for identifiers of objects defined by the <a href="https://proj4.org/">Proj.4</a>
project.
      *
      * <div class="section">Main usage</div>
      * This value can be returned by:
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 c76c036..d7e1ea2 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
@@ -69,15 +69,22 @@ import static java.lang.Math.*;
  *
  * <ul class="verbose">
  *   <li>On input, the {@link #transform(double[], int, double[], int, boolean) transform(…)}
method
- *   expects (<var>longitude</var>, <var>latitude</var>) angles in
<strong>radians</strong>.
+ *   expects (<var>longitude</var>, <var>latitude</var>) angles in
<strong>radians</strong>,
+ *   sometime pre-multiplied by other projection-specific factors (see point #3 below).
  *   Longitudes have the <cite>central meridian</cite> (λ₀) removed before
the transform method is invoked.
  *   The conversion from degrees to radians and the longitude rotation are applied by the
  *   {@linkplain ContextualParameters#normalizeGeographicInputs normalization} affine transform.</li>
  *
  *   <li>On output, the {@link #transform(double[],int,double[],int,boolean) transform(…)}
method returns
- *   (<var>x</var>, <var>y</var>) values on a sphere or ellipse having
a semi-major axis length (<var>a</var>) of 1.
+ *   (<var>x</var>, <var>y</var>) values on a sphere or ellipse having
a semi-major axis length (<var>a</var>) of 1,
+ *   sometime divided by other projection-specific factors (see point #3 below).
  *   The multiplication by the scale factor (<var>k₀</var>) and the translation
by false easting (FE) and false
  *   northing (FN) are applied by the {@linkplain ContextualParameters#getMatrix denormalization}
affine transform.</li>
+ *
+ *   <li>In addition to above-cited conversions, subclasses may opportunistically concatenate
other linear operations
+ *   (scales and translations). They do that by changing the normalization and denormalization
matrices shown below.
+ *   When such changes are applied, the {@code transform(…)} inputs are no longer angles
in radians but some other
+ *   derived values.</li>
  * </ul>
  *
  * The normalization and denormalization steps are represented below by the matrices immediately
on the left and right
@@ -651,16 +658,23 @@ public abstract class NormalizedProjection extends AbstractMathTransform2D
imple
      *
      * <div class="section">Normalization</div>
      * The input ordinates are (<var>λ</var>,<var>φ</var>) (the
variable names for <var>longitude</var> and
-     * <var>latitude</var> respectively) angles in radians.
+     * <var>latitude</var> respectively) angles in radians, eventually pre-multiplied
by projection-specific factors.
      * Input coordinate shall have the <cite>central meridian</cite> removed
from the longitude by the caller
      * before this method is invoked. After this method is invoked, the caller will need
to multiply the output
-     * coordinate by the global <cite>scale factor</cite>
-     * and apply the (<cite>false easting</cite>, <cite>false northing</cite>)
offset.
+     * coordinate by the global <cite>scale factor</cite>,
+     * apply the (<cite>false easting</cite>, <cite>false northing</cite>)
offset
+     * and eventually other projection-specific factors.
      * This means that projections that implement this method are performed on a sphere or
ellipse
      * having a semi-major axis length of 1.
      *
-     * <div class="note"><b>Note:</b> in <a href="http://trac.osgeo.org/proj/">Proj.4</a>,
the same standardization,
-     * described above, is handled by {@code pj_fwd.c}.</div>
+     * <div class="note"><b>Note 1:</b> it is generally not necessary to
know the projection-specific additional
+     * factors applied by subclasses on the input and output values, because {@code NormalizedProjection}
should
+     * never be used directly. {@code NormalizedProjection} instances are used only indirectly
as a step in a
+     * concatenated transform that include the <cite>normalization</cite> and
<cite>denormalization</cite>
+     * matrices documented in this class javadoc.</div>
+     *
+     * <div class="note"><b>Note 2:</b> in <a href="https://proj4.org/">Proj.4</a>,
the same standardization,
+     * described above, is handled by {@code pj_fwd.c}, except for the projection-specific
additional factors.</div>
      *
      * <div class="section">Argument checks</div>
      * The input longitude and latitude are usually (but not always) in the range [-π …
π] and [-π/2 … π/2] respectively.
@@ -695,9 +709,10 @@ public abstract class NormalizedProjection extends AbstractMathTransform2D
imple
      * After this method is invoked, the caller will need to add the <cite>central
meridian</cite> to the longitude
      * in the output coordinate. This means that projections that implement this method are
performed on a sphere
      * or ellipse having a semi-major axis of 1.
+     * Additional projection-specific factors may also need to be applied (see class javadoc).
      *
-     * <div class="note"><b>Note:</b> in <a href="http://trac.osgeo.org/proj/">Proj.4</a>,
the same standardization,
-     * described above, is handled by {@code pj_inv.c}.</div>
+     * <div class="note"><b>Note:</b> in <a href="https://proj4.org/">Proj.4</a>,
the same standardization,
+     * described above, is handled by {@code pj_inv.c}, except for the projection-specific
additional factors.</div>
      *
      * @param  srcPts  the array containing the source point coordinate, as linear distance
on a unit sphere or ellipse.
      * @param  srcOff  the offset of the point to be converted in the source array.


Mime
View raw message