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 2026/02/13 17:07:56 UTC
(sis) 01/03: Move `TiledGridResource` and `TiledGridCoverage` to public API.
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 ca6eba4f648ec92a0f0513deb19e4141cf1706e9
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Thu Feb 12 12:46:57 2026 +0100
Move `TiledGridResource` and `TiledGridCoverage` to public API.
---
.../org/apache/sis/coverage/grid/GridCoverage.java | 10 +-
.../sis/storage/geotiff/CompressedSubset.java | 2 +-
.../org/apache/sis/storage/geotiff/DataCube.java | 2 +-
.../org/apache/sis/storage/geotiff/DataSubset.java | 4 +-
.../{base => tiling}/TiledDeferredImage.java | 9 +-
.../{base => tiling}/TiledGridCoverage.java | 123 +++++++++++----------
.../{base => tiling}/TiledGridResource.java | 31 ++++--
.../apache/sis/storage/tiling/package-info.java | 10 +-
.../apache/sis/storage/geoheif/ImageResource.java | 4 +-
.../org/apache/sis/storage/gdal/TiledCoverage.java | 4 +-
.../org/apache/sis/storage/gdal/TiledResource.java | 2 +-
11 files changed, 114 insertions(+), 87 deletions(-)
diff --git a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/GridCoverage.java b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/GridCoverage.java
index e036c2de7f..5f0489bd42 100644
--- a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/GridCoverage.java
+++ b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/coverage/grid/GridCoverage.java
@@ -58,15 +58,19 @@ import org.opengis.coverage.CannotEvaluateException;
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Johann Sorel (Geomatys)
- * @version 1.6
+ * @version 1.7
* @since 1.0
*/
public abstract class GridCoverage extends BandedCoverage {
/**
* A constant for making easier to identify codes working on two dimensional data.
- * This is the minimal number of dimension required for {@link GridCoverage2D}.
+ * This constant can be used for making easier to identify codes where a two-dimensional slice is assumed.
+ *
+ * @see #render(GridExtent)
+ *
+ * @since 1.7
*/
- static final int BIDIMENSIONAL = 2;
+ protected static final int BIDIMENSIONAL = 2;
/**
* The processor to use in calls to {@link #convert(RenderedImage, DataType, MathTransform1D[], ImageProcessor)}.
diff --git a/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/CompressedSubset.java b/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/CompressedSubset.java
index b8efc5f907..72c93d2e25 100644
--- a/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/CompressedSubset.java
+++ b/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/CompressedSubset.java
@@ -23,7 +23,7 @@ import java.awt.Point;
import java.awt.image.Raster;
import static java.lang.Math.toIntExact;
import org.apache.sis.storage.DataStoreException;
-import org.apache.sis.storage.base.TiledGridResource;
+import org.apache.sis.storage.tiling.TiledGridResource;
import org.apache.sis.storage.geotiff.inflater.Inflater;
import org.apache.sis.image.DataType;
import org.apache.sis.image.internal.shared.RasterFactory;
diff --git a/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataCube.java b/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataCube.java
index 0b8ea082e4..c5ec2f001e 100644
--- a/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataCube.java
+++ b/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataCube.java
@@ -32,7 +32,7 @@ import org.apache.sis.storage.geotiff.base.Tags;
import org.apache.sis.storage.geotiff.base.Resources;
import org.apache.sis.storage.geotiff.base.Predictor;
import org.apache.sis.storage.geotiff.base.Compression;
-import org.apache.sis.storage.base.TiledGridResource;
+import org.apache.sis.storage.tiling.TiledGridResource;
import org.apache.sis.storage.base.StoreResource;
import org.apache.sis.math.Vector;
diff --git a/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataSubset.java b/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataSubset.java
index bd70e5380c..943f67d9dd 100644
--- a/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataSubset.java
+++ b/endorsed/src/org.apache.sis.storage.geotiff/main/org/apache/sis/storage/geotiff/DataSubset.java
@@ -43,8 +43,8 @@ import org.apache.sis.image.internal.shared.ImageUtilities;
import org.apache.sis.image.internal.shared.RasterFactory;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.DataStoreContentException;
-import org.apache.sis.storage.base.TiledGridCoverage;
-import org.apache.sis.storage.base.TiledGridResource;
+import org.apache.sis.storage.tiling.TiledGridCoverage;
+import org.apache.sis.storage.tiling.TiledGridResource;
import org.apache.sis.storage.geotiff.base.Resources;
import org.apache.sis.storage.geotiff.reader.ReversedBitsChannel;
import org.apache.sis.io.stream.Region;
diff --git a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledDeferredImage.java b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledDeferredImage.java
similarity index 92%
rename from endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledDeferredImage.java
rename to endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledDeferredImage.java
index d5f803d077..50812101ee 100644
--- a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledDeferredImage.java
+++ b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledDeferredImage.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-package org.apache.sis.storage.base;
+package org.apache.sis.storage.tiling;
import java.util.Map;
import java.awt.Rectangle;
@@ -53,9 +53,12 @@ final class TiledDeferredImage extends BatchComputedImage {
* @param imageSize full image size, after subsampling.
* @param tileLower indices of first tile to read, inclusive.
* @param properties image properties, or {@code null} if none.
+ * @param iterator iterator over the coordinates of the tiles.
*/
- TiledDeferredImage(final int[] imageSize, final int[] tileLower,
- final Map<String,Object> properties, final TiledGridCoverage.TileIterator iterator)
+ TiledDeferredImage(final int[] imageSize,
+ final int[] tileLower,
+ final Map<String,Object> properties,
+ final TiledGridCoverage.TileIterator iterator)
{
super(iterator.getCoverage().model, properties);
this.width = imageSize[TiledGridCoverage.X_DIMENSION];
diff --git a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledGridCoverage.java b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledGridCoverage.java
similarity index 93%
rename from endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledGridCoverage.java
rename to endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledGridCoverage.java
index b921826c94..06498ac4d7 100644
--- a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledGridCoverage.java
+++ b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledGridCoverage.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-package org.apache.sis.storage.base;
+package org.apache.sis.storage.tiling;
import java.util.Map;
import java.util.Locale;
@@ -25,6 +25,7 @@ import java.awt.image.DataBuffer;
import java.awt.image.ColorModel;
import java.awt.image.SampleModel;
import java.awt.image.MultiPixelPackedSampleModel;
+import java.awt.image.SinglePixelPackedSampleModel;
import java.awt.image.RenderedImage;
import java.awt.image.Raster;
import java.awt.image.WritableRaster;
@@ -41,7 +42,6 @@ import org.apache.sis.coverage.grid.GridExtent;
import org.apache.sis.coverage.grid.DisjointExtentException;
import org.apache.sis.image.internal.shared.DeferredProperty;
import org.apache.sis.image.internal.shared.TiledImage;
-import org.apache.sis.storage.tiling.TileMatrixSet;
import org.apache.sis.storage.internal.Resources;
import org.apache.sis.util.collection.WeakValueHashMap;
import org.apache.sis.util.resources.Errors;
@@ -56,18 +56,20 @@ import org.opengis.coordinate.MismatchedDimensionException;
/**
- * Base class of grid coverage read from a resource where data are stored in tiles.
+ * Base class of grid coverages that are read from resources with data stored in tiles.
* This grid coverage may represent only a subset of the coverage resource.
- * Tiles are read from the storage only when first needed.
+ * Tiles are read from the storage when first needed, then cached using weak references.
+ * The reading of tiles is done by the {@link #readTiles(TileIterator)} method,
+ * which must be defined by subclasses.
*
* <h2>Cell coordinates</h2>
* When there is no subsampling, this coverage uses the same cell coordinates as the originating resource.
* When there is a subsampling, cell coordinates in this coverage are divided by the subsampling factors.
- * Conversions are done by {@link #coverageToResourceCoordinate(long, int)}.
+ * Conversions can be done by {@link #coverageToResourceCoordinate(long, int)}.
*
* <p><b>Design note:</b> {@code TiledGridCoverage} uses the same cell coordinates as the originating
* {@link TiledGridResource} (when no subsampling) because those two classes use {@code long} integers.
- * There is no integer overflow to avoid.</p>
+ * There is no integer overflow to avoid, contrarily to tile indices described below.</p>
*
* <h2>Tile matrix coordinate (<abbr>TMC</abbr>)</h2>
* In each {@code TiledGridCoverage}, indices of tiles starts at (0, 0, …).
@@ -75,14 +77,10 @@ import org.opengis.coordinate.MismatchedDimensionException;
* Each {@code TiledGridCoverage} instance uses its own, independent, Tile Matrix Coordinates (<abbr>TMC</abbr>).
*
* @author Martin Desruisseaux (Geomatys)
+ * @version 1.7
+ * @since 1.7
*/
public abstract class TiledGridCoverage extends GridCoverage {
- /**
- * Number of dimensions in a rendered image.
- * Used for identifying codes where a two-dimensional slice is assumed.
- */
- protected static final int BIDIMENSIONAL = 2;
-
/**
* The dimensions of <var>x</var> and <var>y</var> axes.
* Static constants for now, may become configurable fields in the future.
@@ -101,7 +99,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
* The read extent is not cropped when reading a tiled image on the assumption that
* tiles are reasonable small, because reading tiles fully makes easier to cache them.</p>
*/
- protected final GridExtent readExtent;
+ private final GridExtent readExtent;
/**
* Whether to enforce {@link #virtualTileSize} even if the intersection with {@link #readExtent} is smaller.
@@ -201,13 +199,13 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Indices of {@link TiledGridResource} bands which have been retained for
* inclusion in this {@code TiledGridCoverage}, in strictly increasing order.
- * An "included" band is stored in memory but not necessarily visible to the user,
- * because the {@link SampleModel} can be configured for ignoring some bands.
+ * An included band is stored in memory but not necessarily visible to users,
+ * depending on how the {@link SampleModel} uses each band.
* This array is {@code null} if all bands shall be included.
*
- * <p>If the user specified bands out of order, the change of band order is taken in account
- * by the sample {@link #model}. This {@code includedBands} array does not apply any change
- * of order for making sequential readings easier.</p>
+ * <p>If the user specified bands out of order, the band reordering is applied by the sample {@link #model}.
+ * Changes of band order are not encoded in this {@code includedBands} array
+ * (i.e., values are always in strictly increasing order) for making sequential reads easier.</p>
*/
protected final int[] includedBands;
@@ -223,9 +221,10 @@ public abstract class TiledGridCoverage extends GridCoverage {
private final WeakValueHashMap<TiledGridResource.CacheKey, Raster> rasters;
/**
- * The sample model for all rasters. The width and height of this sample model are the two first elements
- * of {@link #virtualTileSize} divided by subsampling and clipped to the domain.
- * If user requested to read only a subset of the bands, then this sample model is already the subset.
+ * The sample model for all rasters. The width and height of this sample model are computed
+ * from the size of tiles in the resource divided by subsampling and clipped to the domain.
+ * The components may be a subset of the bands in the resource if the user requested to read
+ * only a subset of those bands.
*
* @see TiledGridResource#getSampleModel(int[])
*/
@@ -372,36 +371,38 @@ public abstract class TiledGridCoverage extends GridCoverage {
}
/**
- * Converts a cell coordinate from this coverage to the {@code TiledGridResource} coordinate space.
- * This method removes the subsampling effect, i.e. returns the coordinate that we would have if this
- * coverage was at full resolution. When there is no subsampling, {@code TiledGridCoverage} uses the
- * same coordinates as the originating {@link TiledGridResource}.
+ * Converts a cell coordinate of this coverage to the {@code TiledGridResource} coordinate space.
+ * This method removes the subsampling effect,
+ * i.e. returns the coordinate that we would have if this coverage was at full resolution.
+ * The result is the given {@code coordinate} value unchanged when there is no subsampling.
*
* @param coordinate coordinate in this {@code TiledGridCoverage} domain.
* @param dimension the dimension of the coordinate to convert.
- * @return coordinate in this {@code TiledGridResource} with no subsampling applied.
- * @throws ArithmeticException if the coordinate cannot be represented as a long integer.
+ * @return coordinate in the {@code TiledGridResource} domain with no subsampling applied.
+ * @throws ArithmeticException if the coordinate cannot be represented as a 64 bits integer.
*/
protected final long coverageToResourceCoordinate(final long coordinate, final int dimension) {
return addExact(multiplyExact(coordinate, subsampling[dimension]), subsamplingOffsets[dimension]);
}
/**
- * Converts a cell coordinate from {@link TiledGridResource} space to {@code TiledGridCoverage} coordinate.
+ * Converts a cell coordinate from the {@code TiledGridResource} to this coverage coordinate space.
* This method is the converse of {@link #coverageToResourceCoordinate(long, int)}.
- * Note that there is a possible accuracy lost.
+ * The result is the given {@code coordinate} value unchanged when there is no subsampling.
+ * If there is a subsampling, the returned value is rounded toward negative infinity.
*
* @param coordinate coordinate in the {@code TiledGridResource} domain.
* @param dimension the dimension of the coordinate to convert.
* @return coordinates in this subsampled {@code TiledGridCoverage} domain.
- * @throws ArithmeticException if the coordinate cannot be represented as a long integer.
+ * @throws ArithmeticException if the coordinate cannot be represented as a 64 bits integer.
*/
- private long resourceToCoverageCoordinate(final long coordinate, final int dimension) {
+ protected final long resourceToCoverageCoordinate(final long coordinate, final int dimension) {
return floorDiv(subtractExact(coordinate, subsamplingOffsets[dimension]), subsampling[dimension]);
}
/**
- * Converts a tile index from the <abbr>TMC</abbr> of this coverage to a cell coordinate in the originating resource.
+ * Converts a tile index from the <abbr>TMC</abbr> of this coverage to the
+ * coordinate of the upper-left cell of the tile in the originating resource.
* Note that the computation (like all methods in this class) uses the <em>virtual</em> tile size.
* This is usually the same as the real tile size, but not always.
*
@@ -409,7 +410,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
* @param dimension the dimension of the coordinate to convert.
* @return cell coordinate of the tile lower coordinate in the originating resource.
*/
- final long coverageTileToResourceCell(final long tileIndex, final int dimension) {
+ private long coverageTileToResourceCell(final long tileIndex, final int dimension) {
return multiplyExact(addExact(tileIndex, tmcOfFirstTile[dimension]), virtualTileSize[dimension]);
}
@@ -434,13 +435,11 @@ public abstract class TiledGridCoverage extends GridCoverage {
* This value is a power of 2 according {@code MultiPixelPackedSampleModel} specification.
*
* <h4>Design note</h4>
- * This is "pixels per element", not "samples per element". It makes a difference in the
- * {@link java.awt.image.SinglePixelPackedSampleModel} case, for which this method returns 1
- * (by contrast a "samples per element" would give a value greater than 1).
- * But this value can nevertheless be understood as a "samples per element" value
- * where only one band is considered at a time.
+ * This is value is the number of <em>pixels per element</em>, not <em>samples per element</em>.
+ * This distinction is important in the case of {@link SinglePixelPackedSampleModel}, for which
+ * this method returns 1 (contrarily to the number of samples per element which would be greater than 1).
*
- * @return number of pixels in a single bank element. Usually 1.
+ * @return number of pixels in a single bank element. This is often 1.
*
* @see SampleModel#getSampleSize(int)
* @see MultiPixelPackedSampleModel#getPixelBitStride()
@@ -493,6 +492,8 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Returns a two-dimensional slice of grid data as a rendered image.
+ * The default implementation creates a {@link TileIterator} over the region specified in argument,
+ * then {@linkplain #readTiles(TileIterator) reads the tiles} and stores the result in a rendered image.
*
* @param sliceExtent a subspace of this grid coverage, or {@code null} for the whole image.
* @return the grid slice as a rendered image. Image location is relative to {@code sliceExtent}.
@@ -686,6 +687,9 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Returns the cached tile for current <abbr>AOI</abbr> position.
+ * This method returns the value given in a call to the {@link #cache(Raster)}
+ * during a previous iteration when the iterator was at the same position,
+ * if that raster has not yet been garbage collected.
*
* @return cached tile at current <abbr>AOI</abbr> position, or {@code null} if none.
*
@@ -734,13 +738,13 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Stores the given raster in the cache for the current <abbr>AOI</abbr> position.
- * If another raster existed previously in the cache, the old raster will be reused if
- * it has the same size and model, or discarded otherwise. The latter case may happen if
- * {@link #getCachedTile()} determined that a cached raster exists but cannot be reused.
+ * If a raster is already in the cache and has the same size and equal sample model,
+ * then the given raster is ignored and the existing raster is returned
+ * on the assumption that it has the same content.
*
* @param tile the raster to cache.
* @return the cached raster. Should be the given {@code raster} instance,
- * but this method check for concurrent caching as a paranoiac check.
+ * unless this method is invoked during two concurrent reads of the same tile.
*
* @see #getCachedTile()
*/
@@ -751,7 +755,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Creates an initially empty raster for the tile at the current <abbr>AOI</abbr> position.
* The sample model is {@link #model} and the minimum <var>x</var> and <var>y</var> position
- * are set the the pixel coordinates in the two first dimensions of the <abbr>AOI</abbr>.
+ * are set to the pixel coordinates in two dimensions of the <abbr>AOI</abbr>.
*
* <p>The raster is <em>not</em> filled with {@link #fillValues}.
* Filling, if needed, should be done by the caller.</p>
@@ -767,7 +771,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Returns the given raster relocated at the current <abbr>AOI</abbr> position.
* This method does not need to be invoked for tiles created by {@link #createRaster()},
- * but may need to be invoked for tiles created in a different way.
+ * but may need to be invoked for tiles created by a method external to this class.
* If the given raster is already at the current <abbr>AOI</abbr> position,
* then this method returns that raster directly.
*
@@ -787,9 +791,14 @@ public abstract class TiledGridCoverage extends GridCoverage {
/**
* Returns the location (relative to the cropped tile) of the upper-left corner of the uncropped tile.
- * This value should be present only when reading an image made of a single potentially huge tile,
- * and the {@link #readExtent} has been cropped for avoiding to read that huge tile in whole.
- * This value should always be empty for tiled images, because this class usually reads tiles
+ * This value is present under the following conditions:
+ *
+ * <ul>
+ * <li>Reading an image made of a single potentially huge tile, and</li>
+ * <li>the huge tile is cropped for avoiding to read that tile in whole.</li>
+ * </ul>
+ *
+ * This value is empty for tiled images, because this class usually reads tiles
* fully (without cropping) on the assumption that they are reasonably small.
*
* <p>This value can be <em>added</em> to the coordinates of a point
@@ -881,8 +890,10 @@ public abstract class TiledGridCoverage extends GridCoverage {
* @param subsampled whether to return coordinates with subsampling applied.
* @return {@code true} on success, or {@code false} if the tile is empty.
*/
- public boolean getRegionInsideTile(final long[] lower, final long[] upper,
- final long[] subsampling, final boolean subsampled)
+ public boolean getRegionInsideTile(final long[] lower,
+ final long[] upper,
+ final long[] subsampling,
+ final boolean subsampled)
{
int dimension = Math.min(lower.length, upper.length);
final TiledGridCoverage coverage = getCoverage();
@@ -1032,7 +1043,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
* @param endTile indices (relative to enclosing {@code TiledGridCoverage}) after the bottom-right tile to read.
* @return a new {@code TileIterator} instance for the specified sub-region.
*/
- public TileIterator subset(final int[] firstTile, final int[] endTile) {
+ final TileIterator subset(final int[] firstTile, final int[] endTile) {
final int[] offset = offsetAOI.clone();
final int[] lower = tileLower.clone();
for (int i = Math.min(firstTile.length, lower.length); --i >= 0;) {
@@ -1068,8 +1079,8 @@ public abstract class TiledGridCoverage extends GridCoverage {
*
* <p>The returned region is based on the user's request in her/his call to {@link #render(GridExtent)},
* but is not necessarily identical. The render method may have expanded or clipped the user's request.
- * The returned extent may be larger than the actual resource extent because {@link #readExtent} size
- * is rounded to an integer number of chunks.</p>
+ * The returned extent may be larger than the actual resource extent because it may be rounded to an
+ * integer number of chunks.</p>
*
* @return extent of all tiles to be traversed by this iterator, in units of the originating resource.
*/
@@ -1078,6 +1089,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
final long[] lower = new long[dimension];
final long[] upper = new long[dimension];
for (int i=0; i<dimension; i++) {
+ // Note: `readExtent` is rounded to an integer number of chunks.
lower[i] = Math.max(coverageTileToResourceCell(tileLower[i], i), readExtent.getLow(i));
upper[i] = Math.min(coverageTileToResourceCell(tileUpper[i], i)-1, readExtent.getHigh(i));
}
@@ -1094,7 +1106,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
* @param ceil {@code true} for rounding up, or {@code false} for rounding down.
* @return cell coordinate in the {@link TiledGridResource} coordinate system.
*/
- public long resourceToImage(long coordinate, final int dimension, final boolean ceil) {
+ private long resourceToImage(long coordinate, final int dimension, final boolean ceil) {
coordinate = subtractExact(coordinate, coverageTileToResourceCell(tileLower[dimension], dimension));
long s = getSubsampling(dimension);
coordinate = ceil ? ceilDiv(coordinate, s) : floorDiv(coordinate, s);
@@ -1111,7 +1123,7 @@ public abstract class TiledGridCoverage extends GridCoverage {
* @param dimension the dimension of the coordinate to convert.
* @return cell coordinate in the {@link TiledGridResource} coordinate system.
*/
- public long imageToResource(long coordinate, final int dimension) {
+ private long imageToResource(long coordinate, final int dimension) {
coordinate = subtractExact(coordinate, offsetAOI[dimension]); // (0,0) at image origin instead of AOI.
coordinate = multiplyExact(coordinate, getSubsampling(dimension)); // Full resolution, like in the resource.
coordinate = addExact(coordinate, coverageTileToResourceCell(tileLower[dimension], dimension));
@@ -1359,7 +1371,6 @@ public abstract class TiledGridCoverage extends GridCoverage {
* subtypes for Java2D errors.
*
* @see TileIterator#createRaster()
- * @see TileIterator#getTileOrigin(int)
* @see TileIterator#getTileIndexInResultArray()
*/
protected abstract Raster[] readTiles(TileIterator iterator) throws Exception;
diff --git a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledGridResource.java b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledGridResource.java
similarity index 97%
rename from endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledGridResource.java
rename to endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledGridResource.java
index d2442b62cc..12f595eb6c 100644
--- a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/base/TiledGridResource.java
+++ b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/TiledGridResource.java
@@ -14,7 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-package org.apache.sis.storage.base;
+package org.apache.sis.storage.tiling;
import java.util.List;
import java.util.Arrays;
@@ -49,15 +49,15 @@ import org.apache.sis.measure.NumberRange;
import org.apache.sis.util.ArraysExt;
import org.apache.sis.util.internal.shared.Numerics;
import org.apache.sis.util.collection.WeakValueHashMap;
-import static org.apache.sis.storage.base.TiledGridCoverage.X_DIMENSION;
-import static org.apache.sis.storage.base.TiledGridCoverage.Y_DIMENSION;
+import static org.apache.sis.storage.tiling.TiledGridCoverage.X_DIMENSION;
+import static org.apache.sis.storage.tiling.TiledGridCoverage.Y_DIMENSION;
// Specific to the geoapi-3.1 and geoapi-4.0 branches:
import org.opengis.coverage.CannotEvaluateException;
/**
- * Base class of grid coverage resource storing data in tiles.
+ * Base class of grid coverage resources that store data in tiles.
* The word "tile" is used for simplicity but can be understood
* as "chunk" in a <var>n</var>-dimensional generalization.
* Subclasses need to implement the following methods:
@@ -85,8 +85,16 @@ import org.opengis.coverage.CannotEvaluateException;
* }
*
* @author Martin Desruisseaux (Geomatys)
+ * @version 1.7
+ * @since 1.7
*/
public abstract class TiledGridResource extends AbstractGridCoverageResource {
+ /**
+ * Number of dimensions in a rendered image.
+ * Used for identifying codes where a two-dimensional slice is assumed.
+ */
+ private static final int BIDIMENSIONAL = 2;
+
/**
* A key in the {@link #rasters} cache of tiles.
* Each key shall be unique within its enclosing {@link TiledGridResource} instance.
@@ -160,7 +168,7 @@ public abstract class TiledGridResource extends AbstractGridCoverageResource {
/**
* Returns the size of tiles in this resource.
* The length of the returned array is the number of dimensions,
- * which must be {@value TiledGridCoverage#BIDIMENSIONAL} or more.
+ * which must be {@value #BIDIMENSIONAL} or more.
*
* @return the size of tiles (in pixels) in this resource.
* @throws DataStoreException if an error occurred while fetching the tile size.
@@ -689,13 +697,14 @@ check: if (dataType.isInteger()) {
/**
* If the loading strategy is to load all tiles at {@code read(…)} time, replaces the given coverage
* by a coverage will all data in memory. This method should be invoked by subclasses at the end of
- * their {@link #read(GridGeometry, int...)} method implementation.
+ * their {@link #read(GridGeometry, int...)} method implementation if the tile loading strategy is not
+ * {@link RasterLoadingStrategy#AT_GET_TILE_TIME}.
*
* @param coverage the {@link TiledGridCoverage} to potentially replace by a coverage with preloaded data.
* @return a coverage with preloaded data, or the given coverage if preloading is not enabled.
* @throws DataStoreException if an error occurred while preloading data.
*/
- protected final GridCoverage preload(final GridCoverage coverage) throws DataStoreException {
+ protected GridCoverage preload(final GridCoverage coverage) throws DataStoreException {
assert Thread.holdsLock(getSynchronizationLock());
// Note: `loadingStrategy` may still be null if unitialized.
if (loadingStrategy == null || loadingStrategy == RasterLoadingStrategy.AT_READ_TIME) {
@@ -704,7 +713,7 @@ check: if (dataType.isInteger()) {
* We apply it anyway in case the coverage geometry is not what was announced.
* This condition is also necessary if `loadingStrategy` has not been initialized.
*/
- if (coverage.getGridGeometry().getDimension() == TiledGridCoverage.BIDIMENSIONAL) try {
+ if (coverage.getGridGeometry().getDimension() == BIDIMENSIONAL) try {
final RenderedImage image = coverage.render(null);
return new GridCoverage2D(coverage.getGridGeometry(), coverage.getSampleDimensions(), image);
} catch (RuntimeException e) {
@@ -737,7 +746,7 @@ check: if (dataType.isInteger()) {
* Non-immediate loading allows users to specify two-dimensional slices.
*/
private boolean supportImmediateLoading() throws DataStoreException {
- return getTileSize().length == TiledGridCoverage.BIDIMENSIONAL;
+ return getTileSize().length == BIDIMENSIONAL;
}
/**
@@ -747,7 +756,7 @@ check: if (dataType.isInteger()) {
* @throws DataStoreException if an error occurred while fetching data store configuration.
*/
@Override
- public final RasterLoadingStrategy getLoadingStrategy() throws DataStoreException {
+ public RasterLoadingStrategy getLoadingStrategy() throws DataStoreException {
synchronized (getSynchronizationLock()) {
if (loadingStrategy == null) {
setLoadingStrategy(supportImmediateLoading());
@@ -765,7 +774,7 @@ check: if (dataType.isInteger()) {
* @throws DataStoreException if an error occurred while setting data store configuration.
*/
@Override
- public final boolean setLoadingStrategy(final RasterLoadingStrategy strategy) throws DataStoreException {
+ public boolean setLoadingStrategy(final RasterLoadingStrategy strategy) throws DataStoreException {
synchronized (getSynchronizationLock()) {
if (strategy == RasterLoadingStrategy.AT_GET_TILE_TIME) {
loadingStrategy = strategy;
diff --git a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/package-info.java b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/package-info.java
index 8d286d322f..d9015c8187 100644
--- a/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/package-info.java
+++ b/endorsed/src/org.apache.sis.storage/main/org/apache/sis/storage/tiling/package-info.java
@@ -19,7 +19,7 @@
/**
* Base types for retrieving and saving tiles in resources.
* A {@link TiledResource} if a resource capable to describe its tiling schemes as {@link TileMatrixSet} instances.
- * A {@link TileMatrixSet} is a collection of {@link TileMatrix} instances in the same CRS but at different scale levels.
+ * A {@link TileMatrixSet} is a collection of {@link TileMatrix} instances in the same <abbr>CRS</abbr> but at different scale levels.
* A {@link TileMatrix} is a collection of {@link Tile} instances with the same size and properties placed on a regular grid with no overlapping.
* The "tile" word is used because of its wide usage with two-dimensional data, but actually this package has no restriction
* on the number of dimensions and can work with multi-dimensional "tiles" as well.
@@ -27,7 +27,7 @@
* <h2>References</h2>
* <ul>
* <li><a href="https://www.ogc.org/standards/tms">OGC Two Dimensional Tile Matrix Set</a> — the core standard used in this package.</li>
- * <li><a href="https://www.ogc.org/standards/wmts">OGC Web Map Tile Service (WMTS)</a> — a common use of above standard.</li>
+ * <li><a href="https://www.ogc.org/standards/wmts">OGC Web Map Tile Service (<abbr>WMTS</abbr>)</a> — a common use of above standard.</li>
* <li><a href="https://docs.opengeospatial.org/is/17-066r1/17-066r1.html">OGC Geopackage: Extension for Tiled Gridded Coverage Data</a> — another common use.</li>
* <li><a href="https://docs.ogc.org/per/18-074.html">OGC Geopackage: Extension for vector tiles</a> — experimental work for tiled geometries.</li>
* </ul>
@@ -40,12 +40,12 @@
* <a href="https://docs.mapbox.com/mapbox-tiling-service/guides/">MapBox Tiling service</a>.
*
*
- * <h2>Relationship with OGC specifications</h2>
+ * <h2>Relationship with <abbr>OGC</abbr> specifications</h2>
* The {@code TileMatrix} and {@code TileMatrixSet} class names are reused as defined by OGC.
* The "2D" suffix in class names is omitted because this package is fully multi-dimensional.
* The concept of "tiling scheme" is encapsulated in a {@link org.apache.sis.coverage.grid.GridGeometry}.
*
- * <h3>Departures with OGC specifications</h3>
+ * <h3>Departures with <abbr>OGC</abbr> specifications</h3>
* The OGC {@code TileMatrixLimits} class is replaced by {@link org.apache.sis.coverage.grid.GridExtent}.
* The OGC restriction against negative numbers is removed (Apache SIS accepts negative tile indices).
* The <var>tile span</var> and <var>tile matrix min/max</var> coefficients are replaced by a more generic
@@ -68,7 +68,7 @@
* @author Johann Sorel (Geomatys)
* @author Alexis Manin (Geomatys)
* @author Martin Desruisseaux (Geomatys)
- * @version 1.2
+ * @version 1.7
* @since 1.2
*/
package org.apache.sis.storage.tiling;
diff --git a/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/geoheif/ImageResource.java b/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/geoheif/ImageResource.java
index 32439c4d07..8864b943c1 100644
--- a/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/geoheif/ImageResource.java
+++ b/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/geoheif/ImageResource.java
@@ -41,8 +41,8 @@ import org.apache.sis.metadata.iso.DefaultMetadata;
import org.apache.sis.storage.DataStore;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.base.StoreResource;
-import org.apache.sis.storage.base.TiledGridCoverage;
-import org.apache.sis.storage.base.TiledGridResource;
+import org.apache.sis.storage.tiling.TiledGridCoverage;
+import org.apache.sis.storage.tiling.TiledGridResource;
import org.apache.sis.storage.isobmff.ByteRanges;
import org.apache.sis.io.stream.ChannelDataInput;
diff --git a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledCoverage.java b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledCoverage.java
index fa311b9365..59c990133b 100644
--- a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledCoverage.java
+++ b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledCoverage.java
@@ -25,8 +25,8 @@ import java.lang.foreign.MemorySegment;
import org.opengis.util.GenericName;
import org.apache.sis.util.logging.Logging;
import org.apache.sis.storage.DataStoreException;
-import org.apache.sis.storage.base.TiledGridCoverage;
-import org.apache.sis.storage.base.TiledGridResource;
+import org.apache.sis.storage.tiling.TiledGridCoverage;
+import org.apache.sis.storage.tiling.TiledGridResource;
// Test dependencies
import org.apache.sis.image.internal.shared.AssertionMessages;
diff --git a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledResource.java b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledResource.java
index b243fe1a55..2fd8453c29 100644
--- a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledResource.java
+++ b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/TiledResource.java
@@ -49,7 +49,7 @@ import org.apache.sis.image.internal.shared.ColorModelFactory;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.DataStoreReferencingException;
import org.apache.sis.storage.base.MetadataBuilder;
-import org.apache.sis.storage.base.TiledGridResource;
+import org.apache.sis.storage.tiling.TiledGridResource;
import org.apache.sis.system.Configuration;
import org.apache.sis.util.ArraysExt;
import org.apache.sis.util.resources.Vocabulary;