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 2018/06/18 09:44:25 UTC
[sis] 14/31: Method renaming and javadoc.
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 31ae4af5dfc5f9e4d631a7e6a706f7ca89d4eb7f
Author: Martin Desruisseaux <de...@apache.org>
AuthorDate: Fri Jun 1 09:04:30 2018 +0000
Method renaming and javadoc.
git-svn-id: https://svn.apache.org/repos/asf/sis/branches/JDK8@1832670 13f79535-47bb-0310-9956-ffa450edef68
---
.../org/apache/sis/coverage/grid/GridExtent.java | 10 +++-
.../org/apache/sis/coverage/grid/GridGeometry.java | 69 ++++++++++++----------
.../apache/sis/coverage/grid/GridGeometryTest.java | 8 +--
3 files changed, 49 insertions(+), 38 deletions(-)
diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
index 8cef725..8a02c13 100644
--- a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridExtent.java
@@ -264,11 +264,14 @@ public class GridExtent implements GridEnvelope, Serializable {
}
/**
- * 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 GridEnvelope, Serializable {
*/
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) {
diff --git a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
index 6bf983d..bde543a 100644
--- a/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
+++ b/core/sis-raster/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java
@@ -53,7 +53,7 @@ import org.opengis.coverage.grid.GridEnvelope;
* <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 Serializable {
* 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 Serializable {
* 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 Serializable {
* 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 Serializable {
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 Serializable {
* 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 Serializable {
}
/**
- * 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 Serializable {
*
* <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 Serializable {
}
/**
+ * 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
diff --git a/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java b/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
index 35787c6..de9b0d3 100644
--- a/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
+++ b/core/sis-raster/src/test/java/org/apache/sis/coverage/grid/GridGeometryTest.java
@@ -90,7 +90,7 @@ public final strictfp class GridGeometryTest extends TestCase {
/*
* 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 GridGeometryTest extends TestCase {
/*
* 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 GridGeometryTest extends TestCase {
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));
}
--
To stop receiving notification emails like this one, please contact
desruisseaux@apache.org.