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 8f36385c7d7532e33f38fbfe3f6be86348fa0d08 Author: Martin Desruisseaux <martin.desruisse...@geomatys.com> AuthorDate: Fri Mar 24 11:19:12 2023 +0100 Rename some arguments for consistency and update documentation. There is no significant code change in this commit, only renaming. --- .../org/apache/sis/coverage/grid/GridExtent.java | 143 +++++++++++---------- .../org/apache/sis/coverage/grid/GridGeometry.java | 10 +- 2 files changed, 78 insertions(+), 75 deletions(-) diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java index 176adfe28a..fd8b7daadd 100644 --- a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java +++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridExtent.java @@ -820,7 +820,7 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * This is equal to {@code getHigh(dimension) - getLow(dimension) + 1}. * * @param index the dimension for which to obtain the size. - * @return the number of integer grid coordinates along the given dimension. + * @return the number of cells along the given dimension. * @throws IndexOutOfBoundsException if the given index is negative or is equal or greater * than the {@linkplain #getDimension() grid dimension}. * @throws ArithmeticException if the size is too large for the {@code long} primitive type. @@ -844,7 +844,7 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * * @param index the dimension for which to obtain the size. * @param minusOne {@code true} for returning <var>size</var>−1 instead of <var>size</var>. - * @return the number of integer grid coordinates along the given dimension. + * @return the number of cells along the given dimension, optionally minus one. */ public double getSize(final int index, final boolean minusOne) { final int dimension = getDimension(); @@ -928,11 +928,12 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable /** * Returns indices of all dimensions where this grid extent has a size greater than 1. - * This method can be used for getting the grid extent of a <var>s</var>-dimensional slice - * in a <var>n</var>-dimensional cube where <var>s</var> ≤ <var>n</var>. + * This method can be used for getting the grid extent of a slice with {@code numDim} + * dimensions from a <var>n</var>-dimensional cube where {@code numDim} ≤ <var>n</var>. * * <h4>Example</h4> - * suppose that we want to get a two-dimensional slice <var>(y,z)</var> in a four-dimensional data cube <var>(x,y,z,t)</var>. + * suppose that we want to get a two-dimensional slice (<var>y</var>,<var>z</var>) in + * a four-dimensional data cube (<var>x</var>,<var>y</var>,<var>z</var>,<var>t</var>). * The first step is to specify the <var>x</var> and <var>t</var> coordinates of the slice. * In this example we set <var>x</var> to 5 and <var>t</var> to 8. * @@ -956,46 +957,46 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * which has been created elsewhere, or when we do not really want the {@code slice2D} but only its dimension indices. * * <h4>Number of dimensions</h4> - * This method returns exactly <var>s</var> indices. If there is more than <var>s</var> dimensions having a - * {@linkplain #getSize(int) size} greater than 1, then a {@link SubspaceNotSpecifiedException} is thrown. - * If there is less than <var>s</var> dimensions having a size greater than 1, then the returned list of + * This method returns exactly {@code numDim} indices. If there is more than {@code numDim} dimensions having + * a {@linkplain #getSize(int) size} greater than 1, then a {@link SubspaceNotSpecifiedException} is thrown. + * If there is less than {@code numDim} dimensions having a size greater than 1, then the returned list of * dimensions is completed with some dimensions of size 1, starting with the first dimensions in this grid - * extent, until there is exactly <var>s</var> dimensions. If this grid extent does not have at least - * <var>s</var> dimensions, then a {@link CannotEvaluateException} is thrown. + * extent, until there is exactly {@code numDim} dimensions. If this grid extent does not have at least + * {@code numDim} dimensions, then a {@link CannotEvaluateException} is thrown. * - * @param s number of dimensions of the sub-space. - * @return indices of sub-space dimensions, in increasing order in an array of length <var>s</var>. - * @throws SubspaceNotSpecifiedException if there is more than <var>s</var> dimensions having a size greater than 1. - * @throws CannotEvaluateException if this grid extent does not have at least <var>s</var> dimensions. + * @param numDim number of dimensions of the sub-space. + * @return indices of sub-space dimensions, in increasing order in an array of length {@code numDim}. + * @throws SubspaceNotSpecifiedException if there is more than {@code numDim} dimensions having a size greater than 1. + * @throws CannotEvaluateException if this grid extent does not have at least {@code numDim} dimensions. */ - public int[] getSubspaceDimensions(final int s) { - ArgumentChecks.ensurePositive("s", s); + public int[] getSubspaceDimensions(final int numDim) { + ArgumentChecks.ensurePositive("numDim", numDim); final int m = getDimension(); - if (s > m) { - throw new CannotEvaluateException(Resources.format(Resources.Keys.GridEnvelopeMustBeNDimensional_1, s)); + if (numDim > m) { + throw new CannotEvaluateException(Resources.format(Resources.Keys.GridEnvelopeMustBeNDimensional_1, numDim)); } - final int[] selected = new int[s]; + final int[] selected = new int[numDim]; int count = 0; for (int i=0; i<m; i++) { final long low = coordinates[i]; final long high = coordinates[i+m]; if (low != high) { - if (count < s) { + if (count < numDim) { selected[count++] = i; } else { long size = high - low; if (size != -1) size++; // When interpreted as unsigned long, -1 is the maximal value. throw new SubspaceNotSpecifiedException(Resources.format(Resources.Keys.NoNDimensionalSlice_3, - s, getAxisIdentification(i,i), Numerics.toUnsignedDouble(size))); + numDim, getAxisIdentification(i,i), Numerics.toUnsignedDouble(size))); } } } - if (s != count) { + if (numDim != count) { for (int i=0; ; i++) { // An IndexOutOfBoundsException would be a bug in our algorithm. if (coordinates[i] == coordinates[i+m]) { selected[count++] = i; - if (count == s) break; + if (count == numDim) break; } } Arrays.sort(selected); @@ -1264,9 +1265,9 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable /** * Returns a new grid extent with the specified dimension inserted at the given index in this grid extent. - * To append a new dimension after all existing dimensions, set {@code offset} to {@link #getDimension()}. + * To append a new dimension after all existing dimensions, set {@code index} to {@link #getDimension()}. * - * @param offset where to insert the new dimension, from 0 to {@link #getDimension()} inclusive. + * @param index where to insert the new dimension, from 0 to {@link #getDimension()} inclusive. * @param axisType the type of the grid axis to add, or {@code null} if unspecified. * @param low the valid minimum grid coordinate (always inclusive). * @param high the valid maximum grid coordinate, inclusive or exclusive depending on the next argument. @@ -1274,15 +1275,16 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * or {@code false} if it is exclusive (as in Java2D usage). * This argument does not apply to {@code low} value, which is always inclusive. * @return a new grid extent with the specified dimension added. + * @throws IndexOutOfBoundsException if the given index is negative or greater than the {@linkplain #getDimension() grid dimension}. * @throws IllegalArgumentException if the low coordinate value is greater than the high coordinate value. * * @see #selectDimensions(int...) * * @since 1.1 */ - public GridExtent insertDimension(final int offset, final DimensionNameType axisType, final long low, long high, final boolean isHighIncluded) { + public GridExtent insertDimension(final int index, final DimensionNameType axisType, final long low, long high, final boolean isHighIncluded) { final int dimension = getDimension(); - ArgumentChecks.ensureBetween("offset", 0, dimension, offset); + ArgumentChecks.ensureValidIndex(dimension+1, index); if (!isHighIncluded) { high = Math.decrementExact(high); } @@ -1290,19 +1292,19 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable DimensionNameType[] axisTypes = null; if (types != null || axisType != null) { if (types != null) { - axisTypes = ArraysExt.insert(types, offset, 1); + axisTypes = ArraysExt.insert(types, index, 1); } else { axisTypes = new DimensionNameType[newDim]; } - axisTypes[offset] = axisType; + axisTypes[index] = axisType; } final GridExtent ex = new GridExtent(newDim, axisTypes); - System.arraycopy(coordinates, 0, ex.coordinates, 0, offset); - System.arraycopy(coordinates, offset, ex.coordinates, offset + 1, dimension - offset); - System.arraycopy(coordinates, dimension, ex.coordinates, newDim, offset); - System.arraycopy(coordinates, dimension + offset, ex.coordinates, newDim + offset + 1, dimension - offset); - ex.coordinates[offset] = low; - ex.coordinates[offset + newDim] = high; + System.arraycopy(coordinates, 0, ex.coordinates, 0, index); + System.arraycopy(coordinates, index, ex.coordinates, index + 1, dimension - index); + System.arraycopy(coordinates, dimension, ex.coordinates, newDim, index); + System.arraycopy(coordinates, dimension + index, ex.coordinates, newDim + index + 1, dimension - index); + ex.coordinates[index] = low; + ex.coordinates[index + newDim] = high; ex.validateCoordinates(); return ex; } @@ -1311,13 +1313,13 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * Returns a grid extent that encompass only some dimensions of this grid extent. * This method copies the specified dimensions of this grid extent into a new grid extent. * The given dimensions must be in strictly ascending order without duplicated values. - * The number of dimensions of the sub grid extent will be {@code dimensions.length}. + * The number of dimensions of the sub grid extent will be {@code indices.length}. * - * <p>This method performs a <cite>dimensionality reduction</cite> and can be used as the - * converse of {@link #insertDimension(int, DimensionNameType, long, long, boolean)}. + * <p>This method performs a <cite>dimensionality reduction</cite> and can be used as the converse + * of {@link #insertDimension(int, DimensionNameType, long, long, boolean) insertDimension(…)}. * This method cannot be used for changing dimension order.</p> * - * @param dimensions the dimensions to select, in strictly increasing order. + * @param indices the dimensions to select, in strictly increasing order. * @return the sub-envelope, or {@code this} if the given array contains all dimensions of this grid extent. * @throws IndexOutOfBoundsException if an index is out of bounds. * @@ -1327,31 +1329,31 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * * @since 1.3 */ - public GridExtent selectDimensions(int... dimensions) { - dimensions = verifyDimensions(dimensions, getDimension()); - return (dimensions != null) ? reorder(dimensions) : this; + public GridExtent selectDimensions(int... indices) { + indices = verifyDimensions(indices, getDimension()); + return (indices != null) ? reorder(indices) : this; } /** * Verifies the validity of a given {@code dimensions} argument. * - * @param dimensions the user supplied argument to validate. - * @param limit maximal number of dimensions, exclusive. + * @param indices the user supplied argument to validate. + * @param limit maximal number of dimensions, exclusive. * @return a clone of the given array, or {@code null} if the caller can return {@code this}. */ - static int[] verifyDimensions(int[] dimensions, final int limit) { - ArgumentChecks.ensureNonNull("dimensions", dimensions); - final int n = dimensions.length; - ArgumentChecks.ensureSizeBetween("dimensions", 1, limit, n); - dimensions = dimensions.clone(); - if (!ArraysExt.isSorted(dimensions, true)) { + static int[] verifyDimensions(int[] indices, final int limit) { + ArgumentChecks.ensureNonNull("indices", indices); + final int n = indices.length; + ArgumentChecks.ensureSizeBetween("indices", 1, limit, n); + indices = indices.clone(); + if (!ArraysExt.isSorted(indices, true)) { throw new IllegalArgumentException(Resources.format(Resources.Keys.NotStrictlyOrderedDimensions)); } - int d = dimensions[0]; + int d = indices[0]; if (d >= 0) { - d = dimensions[n - 1]; + d = indices[n - 1]; if (d < limit) { - return (n != limit) ? dimensions : null; + return (n != limit) ? indices : null; } } throw new IndexOutOfBoundsException(Errors.format(Errors.Keys.IndexOutOfBounds_1, d)); @@ -1361,19 +1363,19 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * Changes axis order or reduces the number of dimensions. * It is caller responsibility to ensure that the given dimensions are valid. */ - final GridExtent reorder(final int[] dimensions) { + final GridExtent reorder(final int[] indices) { final int sd = getDimension(); - final int td = dimensions.length; + final int td = indices.length; DimensionNameType[] tt = null; if (types != null) { tt = new DimensionNameType[td]; for (int i=0; i<td; i++) { - tt[i] = types[dimensions[i]]; + tt[i] = types[indices[i]]; } } final GridExtent sub = new GridExtent(td, tt); for (int i=0; i<td; i++) { - final int j = dimensions[i]; + final int j = indices[i]; sub.coordinates[i] = coordinates[j]; sub.coordinates[i+td] = coordinates[j+sd]; } @@ -1737,26 +1739,26 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable } /** - * Returns {@code true} if this extent contains the given cell indices. - * An index is considered inside the grid extent if its value is between + * Returns {@code true} if this extent contains the given coordinates of a grid cell. + * A grid coordinate is considered inside the grid extent if its value is between * {@link #getLow(int) low} and {@link #getHigh(int) high} bounds, inclusive. * * <h4>Number of arguments</h4> - * The {@code indices} array length should be equal to the {@linkplain #getDimension() number of dimensions}. - * If the array is shorter, missing index values are considered inside the extent. - * If the array is longer, extraneous values are ignored. + * The {@code cell} array length should be equal to the {@linkplain #getDimension() number of dimensions}. + * If the array is shorter, missing coordinate values are considered inside the extent. + * If the array is longer, extraneous coordinate values are ignored. * - * @param indices indices of the grid cell to check. - * @return whether the given indices are inside this extent. + * @param cell grid coordinates of a cell to check for inclusion. + * @return whether the given grid coordinates are inside this extent. * * @since 1.2 */ - public boolean contains(final long... indices) { - ArgumentChecks.ensureNonNull("indices", indices); + public boolean contains(final long... cell) { + ArgumentChecks.ensureNonNull("cell", cell); final int m = getDimension(); - final int length = Math.min(m, indices.length); + final int length = Math.min(m, cell.length); for (int i=0; i<length; i++) { - final long c = indices[i]; + final long c = cell[i]; if (c < coordinates[i] || c > coordinates[i + m]) { return false; } @@ -1866,8 +1868,9 @@ public class GridExtent implements GridEnvelope, LenientComparable, Serializable * If the given extent is {@code null} or has a different number of dimensions, * then this method returns {@code false}. * - * <p>This method is not public because we do not yet have a policy - * about whether we should verify if axis {@link #types} match.</p> + * <p>This method is not public because it does not verify if the axis {@link #types} match. + * Currently, the context in which this method is invoked is for checking if an optimization can be applied. + * Checking the axis types would disable the optimization for an end result which would be the same.</p> * * @param other the other extent to compare with this extent. Can be {@code null}. * @return whether the two extents has the same size. diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java index 7ea425dd19..d2c22a6718 100644 --- a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java +++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridGeometry.java @@ -1525,7 +1525,7 @@ public class GridGeometry implements LenientComparable, Serializable { * <p>This method performs a <cite>dimensionality reduction</cite>. * This method cannot be used for changing dimension order.</p> * - * @param dimensions the grid (not CRS) dimensions to select, in strictly increasing order. + * @param indices the grid (not CRS) dimensions to select, in strictly increasing order. * @return the sub-grid geometry, or {@code this} if the given array contains all dimensions of this grid geometry. * @throws IndexOutOfBoundsException if an index is out of bounds. * @@ -1535,10 +1535,10 @@ public class GridGeometry implements LenientComparable, Serializable { * * @since 1.3 */ - public GridGeometry selectDimensions(int... dimensions) { - dimensions = GridExtent.verifyDimensions(dimensions, getDimension()); - if (dimensions != null) try { - return new SliceGeometry(this, null, dimensions, null).reduce(null, -1); + public GridGeometry selectDimensions(int... indices) { + indices = GridExtent.verifyDimensions(indices, getDimension()); + if (indices != null) try { + return new SliceGeometry(this, null, indices, null).reduce(null, -1); } catch (FactoryException e) { throw new BackingStoreException(e); }