This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit eb53c5465565ad388339adf1e8a5adbcdb0f2a71
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Tue Apr 18 12:19:12 2023 +0200
Clarify in which conditions the `GridCoverage` can be used outside the
`try` block.
---
content/howto/rasters_bigger_than_memory.md | 8 ++++++++
content/howto/read_geotiff.md | 19 ++++++++++++++++++-
content/howto/read_netcdf.md | 22 +++++++++++++++++++++-
3 files changed, 47 insertions(+), 2 deletions(-)
diff --git a/content/howto/rasters_bigger_than_memory.md
b/content/howto/rasters_bigger_than_memory.md
index 09f46d29..e4a2451f 100644
--- a/content/howto/rasters_bigger_than_memory.md
+++ b/content/howto/rasters_bigger_than_memory.md
@@ -11,6 +11,10 @@ It integrates well with operations provided by Apache {{%
SIS %}} such as
[raster resampling](resample_raster.html) and
[getting values at geographic
coordinates](raster_values_at_geographic_coordinates.html).
+The approach demonstrated in this example has one drawback compared to the
default behavior:
+the `DataStore` must be kept open during all the time that the `GridCoverage`
is used.
+Consequently the `data` variable should not be used outside the `try` block in
this example.
+
The example in this page works with pixel coordinates.
For working with geographic coordinates, see
[values at geographic
coordinates](raster_values_at_geographic_coordinates.html) code example.
@@ -70,6 +74,10 @@ public class RasterBiggerThanMemory {
firstImage.setLoadingStrategy(RasterLoadingStrategy.AT_GET_TILE_TIME);
GridCoverage data = firstImage.read(null, null);
printPixelValue(data, false);
+ /*
+ * Contrarily to other examples, the `GridCoverage` fetched in
deferred reading mode
+ * can NOT be used outside this `try` block, because the
`DataStore` must be open.
+ */
}
}
diff --git a/content/howto/read_geotiff.md b/content/howto/read_geotiff.md
index 1f37c984..6bfe43aa 100644
--- a/content/howto/read_geotiff.md
+++ b/content/howto/read_geotiff.md
@@ -53,6 +53,17 @@ public class ReadGeoTIFF {
* @throws ImagingOpException unchecked exception thrown if an error
occurred while loading a tile.
*/
public static void main(String[] args) throws DataStoreException {
+ example();
+ }
+
+ /**
+ * Reads an example file and prints some information about it.
+ *
+ * @return the raster data.
+ * @throws DataStoreException if an error occurred while reading the
raster.
+ */
+ public static GridCoverage example() throws DataStoreException {
+ GridCoverage data;
try (DataStore store = DataStores.open(new File("Aéroport.tiff"))) {
/*
* This data store is an aggregate because a GeoTIFF file may
contain many images.
@@ -64,7 +75,7 @@ public class ReadGeoTIFF {
/*
* Read the resource immediately and fully.
*/
- GridCoverage data = firstImage.read(null, null);
+ data = firstImage.read(null, null);
System.out.printf("Information about the selected image:%n%s%n",
data);
/*
* Read only a subset of the resource. The Area Of Interest can be
specified
@@ -79,6 +90,12 @@ public class ReadGeoTIFF {
System.out.printf("Information about the resource subset:%n%s%n",
data.getGridGeometry().getExtent());
}
+ /*
+ * By default, it is possible to continue to use the `GridCoverage`
(but not the `Resource`) after
+ * the `DataStore` has been closed because data are in memory. Note
that it would not be the case
+ * if deferred data loading was enabled has shown in "Handle rasters
bigger than memory" example.
+ */
+ return data;
}
}
{{< / highlight >}}
diff --git a/content/howto/read_netcdf.md b/content/howto/read_netcdf.md
index f10ae258..691b51db 100644
--- a/content/howto/read_netcdf.md
+++ b/content/howto/read_netcdf.md
@@ -50,6 +50,17 @@ public class ReadNetCDF {
* @throws DataStoreException if an error occurred while reading the
raster.
*/
public static void main(String[] args) throws DataStoreException {
+ example();
+ }
+
+ /**
+ * Reads an example file and prints some information about it.
+ *
+ * @return the raster data.
+ * @throws DataStoreException if an error occurred while reading the
raster.
+ */
+ public static GridCoverage example() throws DataStoreException {
+ GridCoverage data;
try (DataStore store = DataStores.open(new
File("CMEMS_R20220516.nc"))) {
/*
* See what is inside this file. One of the components listed
@@ -61,8 +72,9 @@ public class ReadNetCDF {
if (resource instanceof GridCoverageResource gridded) {
/*
* Read the resource immediately and fully.
+ * `data` can be used outside the `try` block.
*/
- GridCoverage data = gridded.read(null, null);
+ data = gridded.read(null, null);
System.out.printf("Information about the selected
resource:%n%s%n", data);
/*
* Read only a subset of the resource. The Area Of Interest
can be specified
@@ -75,8 +87,16 @@ public class ReadNetCDF {
data = gridded.read(new GridGeometry(null, areaOfInterest,
GridOrientation.HOMOTHETY), null);
System.out.printf("Information about the resource
subset:%n%s%n",
data.getGridGeometry().getExtent());
+ } else {
+ throw new DataStoreException("Unexpected type of resource.");
}
}
+ /*
+ * By default, it is possible to continue to use the `GridCoverage`
(but not the `Resource`) after
+ * the `DataStore` has been closed because data are in memory. Note
that it would not be the case
+ * if deferred data loading was enabled has shown in "Handle rasters
bigger than memory" example.
+ */
+ return data;
}
/**
