sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1832670 - in /sis/branches/JDK8/core/sis-raster/src: main/java/org/apache/sis/coverage/grid/GridExtent.java main/java/org/apache/sis/coverage/grid/GridGeometry.java test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
Date Fri, 01 Jun 2018 09:04:31 GMT
Author: desruisseaux
Date: Fri Jun  1 09:04:30 2018
New Revision: 1832670

URL: http://svn.apache.org/viewvc?rev=1832670&view=rev
Log:
Method renaming and javadoc.

Modified:
    sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
    sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
    sis/branches/JDK8/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java

Modified: sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java?rev=1832670&r1=1832669&r2=1832670&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
[UTF-8] Fri Jun  1 09:04:30 2018
@@ -264,11 +264,14 @@ public class GridExtent implements GridE
     }
 
     /**
-     * Returns the median (or center) coordinates of this grid extent.
+     * Returns the grid coordinates of a representative point.
+     * This point may be used for estimating a {@linkplain GridGeometry#getResolution(boolean)
grid resolution}.
+     * The default implementation returns the median (or center) coordinates of this grid
extent,
+     * but subclasses can override this method if another point is considered more representative.
      *
-     * @return the coordinates of the grid center.
+     * @return the grid coordinates of a representative point.
      */
-    public DirectPosition getMedian() {
+    public DirectPosition getCentroid() {
         final int dimension = getDimension();
         final GeneralDirectPosition center = new GeneralDirectPosition(dimension);
         for (int i=0; i<dimension; i++) {
@@ -306,6 +309,7 @@ public class GridExtent implements GridE
      */
     public GridExtent subExtent(final int lower, final int upper) {
         final int dimension = getDimension();
+        if (lower == 0 && upper == dimension) return this;
         ArgumentChecks.ensureValidIndexRange(dimension, lower, upper);
         final int newDim = upper - lower;
         if (newDim == dimension && getClass() == GridExtent.class) {

Modified: sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java?rev=1832670&r1=1832669&r2=1832670&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
[UTF-8] Fri Jun  1 09:04:30 2018
@@ -53,7 +53,7 @@ import org.opengis.coverage.grid.GridEnv
  *   <li>An optional {@linkplain #getCoordinateReferenceSystem() Coordinate Reference
System} (CRS)
  *       specified as part of the georeferenced envelope.
  *       This CRS is the target of the <cite>grid to CRS</cite> transform.</li>
- *   <li>An <em>estimation</em> of {@linkplain #resolution(boolean) grid
resolution} along each CRS axes,
+ *   <li>An <em>estimation</em> of {@link #getResolution(boolean) grid
resolution} along each CRS axes,
  *       computed from the <cite>grid to CRS</cite> transform and eventually
from the grid extent.</li>
  *   <li>An {@linkplain #isConversionLinear indication of whether conversion for some
axes is linear or not}.</li>
  * </ul>
@@ -113,7 +113,7 @@ public class GridGeometry implements Ser
      * A bitmask to specify the validity of the grid resolution.
      *
      * @see #isDefined(int)
-     * @see #resolution(boolean)
+     * @see #getResolution(boolean)
      */
     public static final int RESOLUTION = 16;
 
@@ -162,7 +162,7 @@ public class GridGeometry implements Ser
      * Computed from {@link #gridToCRS}, eventually together with {@link #extent}.
      *
      * @see #RESOLUTION
-     * @see #resolution(boolean)
+     * @see #getResolution(boolean)
      */
     protected final double[] resolution;
 
@@ -212,6 +212,11 @@ public class GridGeometry implements Ser
      *       smallest values (closest to negative infinity).</li>
      * </ul>
      *
+     * <div class="note"><b>API note:</b>
+     * there is no default value for {@code anchor} because experience shows that images
shifted by ½ pixel
+     * (with pixels that may be tens of kilometres large) is a recurrent problem. We want
to encourage developers
+     * to always think about wether their <cite>grid to CRS</cite> transform
is mapping pixel corner or center.</div>
+     *
      * @param  extent     the valid extent of grid coordinates, or {@code null} if unknown.
      * @param  anchor     {@linkplain PixelInCell#CELL_CENTER Cell center} for OGC conventions
or
      *                    {@linkplain PixelInCell#CELL_CORNER cell corner} for Java2D/JAI
conventions.
@@ -257,7 +262,7 @@ public class GridGeometry implements Ser
         if (mat != null) {
             resolution = resolution(mat, 1);
         } else if (extent != null && gridToCRS != null) {
-            resolution = resolution(gridToCRS.derivative(this.extent.getMedian()), 0);
+            resolution = resolution(gridToCRS.derivative(this.extent.getCentroid()), 0);
         } else {
             resolution = null;
         }
@@ -395,6 +400,11 @@ public class GridGeometry implements Ser
      *       with inclusive lower coordinates and <strong>exclusive</strong>
upper coordinates.</li>
      * </ul>
      *
+     * <div class="note"><b>API note:</b>
+     * there is no default value for {@code anchor} because experience shows that images
shifted by ½ pixel
+     * (with pixels that may be tens of kilometres large) is a recurrent problem. We want
to encourage developers
+     * to always think about wether the desired <cite>grid to CRS</cite> transform
shall map pixel corner or center.</div>
+     *
      * @param  anchor  the pixel part to map.
      * @return the conversion from grid coordinates to "real world" coordinates (never {@code
null}).
      * @throws IllegalArgumentException if the given {@code anchor} is not a known code list
value.
@@ -417,26 +427,6 @@ public class GridGeometry implements Ser
     }
 
     /**
-     * Indicates whether the <cite>grid to CRS</cite> conversion is linear for
all the specified CRS axes.
-     * The conversion from grid coordinates to real world coordinates is often linear for
some dimensions,
-     * typically the horizontal ones at indices 0 and 1. But the vertical dimension (usually
at index 2)
-     * is often non-linear, for example with data at 0, 5, 10, 100 and 1000 metres.
-     *
-     * @param  targets  indices of CRS axes. This is not necessarily the same than indices
of grid axes.
-     * @return {@code true} if the conversion from grid coordinates to "real world" coordinates
is linear
-     *         for all the given CRS dimension.
-     */
-    public boolean isConversionLinear(final int... targets) {
-        final int dimension = getTargetDimension();
-        long mask = 0;
-        for (final int d : targets) {
-            ArgumentChecks.ensureValidIndex(dimension, d);
-            if (d < Long.SIZE) mask |= (1L << d);
-        }
-        return (nonLinears & mask) == 0;
-    }
-
-    /**
      * Returns an <em>estimation</em> of the grid resolution, in units of the
coordinate reference system axes.
      * The length of the returned array is the number of CRS dimensions, with {@code resolution[0]}
      * being the resolution along the first CRS axis, {@code resolution[1]} the resolution
along the second CRS
@@ -448,20 +438,17 @@ public class GridGeometry implements Ser
      *
      * <ul>
      *   <li>{@link Double#NaN} if {@code allowEstimates} is {@code false}.</li>
-     *   <li>An arbitrary representative resolution otherwise. This is currently the
resolution in the grid center,
-     *       but this arbitrary choice may change in any future Apache SIS version.</li>
+     *   <li>An arbitrary representative resolution otherwise.
+     *       Current implementation computes the resolution at {@linkplain GridExtent#getCentroid()
grid center},
+     *       but different implementations may use alternative algorithms.</li>
      * </ul>
      *
-     * <div class="note"><b>API note:</b>
-     * this method name does not have the {@code "get"} prefix because it does not return
a supplied value.
-     * The resolution is computed and may be representative of only a part of the grid.</div>
-     *
      * @param  allowEstimates  whether to provide some values even for resolutions that are
not constant factors.
      * @return an <em>estimation</em> of the grid resolution (never {@code null}).
      * @throws IncompleteGridGeometryException if this grid geometry has no resolution —
      *         i.e. <code>{@linkplain #isDefined(int) isDefined}({@linkplain #RESOLUTION})</code>
returned {@code false}.
      */
-    public double[] resolution(final boolean allowEstimates) {
+    public double[] getResolution(final boolean allowEstimates) {
         if (resolution != null) {
             final double[] res = resolution.clone();
             if (!allowEstimates) {
@@ -497,6 +484,26 @@ public class GridGeometry implements Ser
     }
 
     /**
+     * Indicates whether the <cite>grid to CRS</cite> conversion is linear for
all the specified CRS axes.
+     * The conversion from grid coordinates to real world coordinates is often linear for
some dimensions,
+     * typically the horizontal ones at indices 0 and 1. But the vertical dimension (usually
at index 2)
+     * is often non-linear, for example with data at 0, 5, 10, 100 and 1000 metres.
+     *
+     * @param  targets  indices of CRS axes. This is not necessarily the same than indices
of grid axes.
+     * @return {@code true} if the conversion from grid coordinates to "real world" coordinates
is linear
+     *         for all the given CRS dimension.
+     */
+    public boolean isConversionLinear(final int... targets) {
+        final int dimension = getTargetDimension();
+        long mask = 0;
+        for (final int d : targets) {
+            ArgumentChecks.ensureValidIndex(dimension, d);
+            if (d < Long.SIZE) mask |= (1L << d);
+        }
+        return (nonLinears & mask) == 0;
+    }
+
+    /**
      * Guesses which target dimensions may be non-linear. We currently don't have an API
for finding the non-linear dimensions.
      * Current implementation assumes that everything else than {@code LinearTransform} and
pass-through dimensions are non-linear.
      * This is not always true (e.g. in a Mercator projection, the "longitude → easting"
part is linear too), but should be okay

Modified: sis/branches/JDK8/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java?rev=1832670&r1=1832669&r2=1832670&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
[UTF-8] Fri Jun  1 09:04:30 2018
@@ -90,7 +90,7 @@ public final strictfp class GridGeometry
         /*
          * Verify other computed properties.
          */
-        assertArrayEquals("resolution", new double[] {1, 1, 1, 1}, grid.resolution(false),
STRICT);
+        assertArrayEquals("resolution", new double[] {1, 1, 1, 1}, grid.getResolution(false),
STRICT);
         assertTrue("isConversionLinear", grid.isConversionLinear(0, 1, 2, 3));
     }
 
@@ -135,7 +135,7 @@ public final strictfp class GridGeometry
         /*
          * Verify other computed properties.
          */
-        assertArrayEquals("resolution", new double[] {1, 1, 1}, grid.resolution(false), STRICT);
+        assertArrayEquals("resolution", new double[] {1, 1, 1}, grid.getResolution(false),
STRICT);
         assertTrue("isConversionLinear", grid.isConversionLinear(0, 1, 2));
     }
 
@@ -157,8 +157,8 @@ public final strictfp class GridGeometry
         final MathTransform temporal  = MathTransforms.linear(3600, 60);
         final MathTransform gridToCRS = MathTransforms.compound(horizontal, vertical, temporal);
         final GridGeometry  grid      = new GridGeometry(extent, PixelInCell.CELL_CENTER,
gridToCRS, null);
-        assertArrayEquals("resolution", new double[] {0.5, 0.25,        6.0, 3600}, grid.resolution(true),
 STRICT);
-        assertArrayEquals("resolution", new double[] {0.5, 0.25, Double.NaN, 3600}, grid.resolution(false),
STRICT);
+        assertArrayEquals("resolution", new double[] {0.5, 0.25,        6.0, 3600}, grid.getResolution(true),
 STRICT);
+        assertArrayEquals("resolution", new double[] {0.5, 0.25, Double.NaN, 3600}, grid.getResolution(false),
STRICT);
         assertFalse("isConversionLinear", grid.isConversionLinear(0, 1, 2, 3));
         assertTrue ("isConversionLinear", grid.isConversionLinear(0, 1,    3));
     }



Mime
View raw message