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 2023/04/18 14:44:51 UTC
[sis-site] branch asf-staging updated: Regenerate the "how to" pages with new examples.
This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch asf-staging
in repository https://gitbox.apache.org/repos/asf/sis-site.git
The following commit(s) were added to refs/heads/asf-staging by this push:
new 305efa36 Regenerate the "how to" pages with new examples.
305efa36 is described below
commit 305efa36253765a1ce886532dd0511fcbc78897e
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Tue Apr 18 16:44:31 2023 +0200
Regenerate the "how to" pages with new examples.
---
howto.html | 4 +
...read_geotiff.html => datalake_to_datacube.html} | 165 +++++++++++----------
.../{resample_raster.html => geodetic_paths.html} | 119 +++++----------
howto/index.xml | 39 +++++
...ample_raster.html => parallel_computation.html} | 112 +++++---------
...aster.html => parse_and_format_mgrs_codes.html} | 126 ++++++----------
howto/raster_values_at_pixel_coordinates.html | 8 +-
howto/rasters_bigger_than_memory.html | 7 +
howto/read_geotiff.html | 19 ++-
howto/read_netcdf.html | 24 ++-
howto/resample_raster.html | 4 +-
11 files changed, 294 insertions(+), 333 deletions(-)
diff --git a/howto.html b/howto.html
index eb9274f4..19d3cd7e 100644
--- a/howto.html
+++ b/howto.html
@@ -122,6 +122,8 @@ The examples are grouped in the following sections:</p>
<li><a href="howto/raster_values_at_geographic_coordinates.html">Get raster values at geographic coordinates</a></li>
<li><a href="howto/rasters_bigger_than_memory.html">Handle rasters bigger than memory</a></li>
<li><a href="howto/resample_raster.html">Resample a raster</a></li>
+<li><a href="howto/parallel_computation.html">Parallel computation</a></li>
+<li><a href="howto/datalake_to_datacube.html">From data lake to data cube</a></li>
<li><a href="howto/write_raster.html">Write a raster to a file</a></li>
</ul>
<h1 id="referencing">Referencing by coordinates </h1>
@@ -131,8 +133,10 @@ The examples are grouped in the following sections:</p>
<li><a href="howto/lookup_crs_urn.html">Get the EPSG code or URN of an existing reference system</a></li>
<li><a href="howto/transform_coordinates.html">Transform points between two reference systems</a></li>
<li><a href="howto/transform_envelopes.html">Transform envelopes between two reference systems</a></li>
+<li><a href="howto/parse_and_format_mgrs_codes.html">Parse and format MGRS codes</a></li>
<li><a href="howto/envelopes_in_different_crs.html">Union or intersection of envelopes in different reference systems</a></li>
<li><a href="howto/crs_equality.html">Determine if two reference systems are functionally equal</a></li>
+<li><a href="howto/geodetic_paths.html">Compute geodetic distances and paths</a></li>
</ul>
<h1 id="metadata">Metadata </h1>
<ul>
diff --git a/howto/read_geotiff.html b/howto/datalake_to_datacube.html
similarity index 54%
copy from howto/read_geotiff.html
copy to howto/datalake_to_datacube.html
index dcaead8d..7007e0a9 100644
--- a/howto/read_geotiff.html
+++ b/howto/datalake_to_datacube.html
@@ -3,7 +3,7 @@
<head>
- <title>Apache SIS - Read raster from a GeoTIFF file</title>
+ <title>Apache SIS - From data lake to data cube</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css"
@@ -103,16 +103,33 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Read raster from a GeoTIFF file</p>
+ <p class="page-title">From data lake to data cube</p>
- <p>This example reads data in GeoTIFF format.
-Contrarily to other formats such as PNG or JPEG,
-a GeoTIFF file can contain an arbitrary number of images.
-For this reason, <code>GeoTiffStore</code> does not implement directly <code>GridCoverageResource</code>.
-Instead, <code>GeoTiffStore</code> implements the <code>Aggregate</code> interface.</p>
-<p>This example assumes that the raster, optionally clipped to a subregion, can fit in memory.
-For potentially much bigger rasters,
-see <a href="rasters_bigger_than_memory.html">rasters bigger than memory</a> code example.</p>
+ <p>This example opens a few files where each file represent a slice in a data cube.
+Then the slices are aggregated together in a single multi-dimensional data cube.
+For example each file may be a raster representing Sea Surface Temperature (SST) at a specific day,
+and those files can be a aggregated in a single three-dimensional raster with a temporal dimension.</p>
+<p>A current limitation is that each slice must have the same number of dimensions than the data cube.
+For the example of SST raster for a specific day, the raster CRS must still have a temporal axis
+even if the grid contains only one cell in the temporal dimension.
+A future Apache SIS version will provide methods for adding dimensions.</p>
+<p>This example assumes that all slice have the same size, resolution and coordinate reference system.
+If this is not the case, the aggregation will still work but instead of producing a data cube,
+it may produce an <code>Aggregate</code> resource containing a tree like below:</p>
+<pre tabindex="0"><code>Root aggregate
+├─ All coverages with same sample dimensions #1
+│ └─ ...
+└─ All coverages with same sample dimensions #2
+ ├─ Coverages with equivalent reference systems #1
+ │ └─ ...
+ └─ Coverages with equivalent reference systems #2
+ ├─ Slices with compatible "grid to CRS" #1
+ ├─ Slices with compatible "grid to CRS" #2
+ └─ ...</pre>
+</code></pre><p>A future Apache SIS version will provide methods for controlling the way to aggregate
+such heterogeneous data set.</p>
+<p>This example works with <code>Resource</code> instances, which are not necessarily data loaded in memory.
+Consequently the <code>DataStore</code> instances must be kept open for all the duration of data cube usage.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -124,109 +141,93 @@ see <a href="rasters_bigger_than_memory.html">rasters bigger than memory</a> cod
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-geotiff</code></td>
-<td><code>org.apache.sis.storage.geotiff</code></td>
+<td><code>org.apache.sis.code:sis-feature</code></td>
+<td><code>org.apache.sis.feature</code></td>
<td></td>
</tr>
<tr>
-<td><code>org.apache.sis.non-free:sis-embedded-data</code></td>
-<td><code>org.apache.sis.referencing.database</code></td>
-<td>Optional. Non-Apache license.</td>
+<td><code>org.apache.sis.storage:sis-netcdf</code></td>
+<td><code>org.apache.sis.storage.netcdf</code></td>
+<td></td>
+</tr>
+<tr>
+<td><code>edu.ucar:cdm-core</code></td>
+<td></td>
+<td>For netCDF-4 or HDF5</td>
</tr>
</tbody>
</table>
-<p>The <a href="../epsg.html">EPSG dependency</a> may or may not be needed,
-depending how the Coordinate Reference System (CRS) is encoded in the GeoTIFF file.</p>
+<p>The <code>cdm-core</code> dependency can be omitted for netCDF-3 (a.k.a. “classic”),</p>
<h1 id="code-example">Code example</h1>
<p>The file name and geospatial coordinates in following code need to be updated for yours data.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.io.File</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.util.Collection</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.image.ImagingOpException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.Resource</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.Aggregate</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.DataStore</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.DataStores</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.DataStoreException</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.GridCoverageResource</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverage</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridGeometry</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridOrientation</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.geometry.GeneralEnvelope</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CommonCRS</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.storage.aggregate.CoverageAggregator</span><span class="o">;</span>
</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ReadGeoTIFF</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">DataLakeToDataCube</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Demo entry point.
</span></span></span><span class="line"><span class="cl"><span class="cm"> *
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @param args ignored.
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws DataStoreException if an error occurred while reading the raster.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while loading a tile.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">DataStoreException</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="k">try</span> <span class="o">(</span><span class="n">DataStore</span> <span class="n">store</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"Aéroport.tiff"</span><span class="o">)))</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This data store is an aggregate because a GeoTIFF file may contain many images.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Not all data stores are aggregate, so the following casts do not apply to all.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * For this example, we know that the file is GeoTIFF and we take the first image.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">Collection</span><span class="o"><?</span> <span class="kd">extends</span> <span class="n">Resource</span><span class="o">></span> <span class="n">allImages</span> <span class="o">=</span> <span class="o">((</span><span class="n">Aggregate</span><span class="o">)</span> <span class="n">store</span><span class="o">).</span><span class="na">components</span><span class="o">();</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverageResource</span> <span class="n">firstImage</span> <span class="o">=</span> <span class="o">(</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">allImages</span><span class="o">.</span><span class="na">iterator</span><span class="o">().</span><span class="na">next</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="k">try</span> <span class="o">(</span><span class="n">DataStore</span> <span class="n">s1</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"CMEMS_20220301.nc"</span><span class="o">));</span>
+</span></span><span class="line"><span class="cl"> <span class="n">DataStore</span> <span class="n">s2</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"CMEMS_20220302.nc"</span><span class="o">));</span>
+</span></span><span class="line"><span class="cl"> <span class="n">DataStore</span> <span class="n">s3</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"CMEMS_20220303.nc"</span><span class="o">)))</span>
+</span></span><span class="line"><span class="cl"> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Read the resource immediately and fully.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Following casts are okay if we know that the resources are raster data,
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * all of them having the same grid geometry. Otherwise the code can still
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * work but would require more `if (x instanceof Y)` checks.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="n">firstImage</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the selected image:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">r1</span> <span class="o">=</span> <span class="o">(</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">s1</span><span class="o">.</span><span class="na">findResource</span><span class="o">(</span><span class="s">"sea_surface_height_above_geoid"</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">r2</span> <span class="o">=</span> <span class="o">(</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">s2</span><span class="o">.</span><span class="na">findResource</span><span class="o">(</span><span class="s">"sea_surface_height_above_geoid"</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">r3</span> <span class="o">=</span> <span class="o">(</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">s3</span><span class="o">.</span><span class="na">findResource</span><span class="o">(</span><span class="s">"sea_surface_height_above_geoid"</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Extent of first set of slices:%n%s%n"</span><span class="o">,</span> <span class="n">r1</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Extent of second set of slices:%n%s%n"</span><span class="o">,</span> <span class="n">r2</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Extent of third set of slices:%n%s%n"</span><span class="o">,</span> <span class="n">r3</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">aggregator</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CoverageAggregator</span><span class="o">(</span><span class="kc">null</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">aggregator</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">r1</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">aggregator</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">r2</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">aggregator</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">r3</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">dataCube</span> <span class="o">=</span> <span class="o">(</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">aggregator</span><span class="o">.</span><span class="na">build</span><span class="o">();</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Read only a subset of the resource. The Area Of Interest can be specified
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * in any Coordinate Reference System (CRS). The envelope will be transformed
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * automatically to the CRS of the data (the data are not transformed).
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This example uses Universal Transverse Mercator (UTM) zone 31 North.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * From this point, the data cube can be used as a three-dimension grid coverage.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * See "Get raster values at geographic (or pixel) coordinates" for usage examples.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * However all usages must be done inside this `try` block.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">areaOfInterest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">GeneralEnvelope</span><span class="o">(</span><span class="n">CommonCRS</span><span class="o">.</span><span class="na">WGS84</span><span class="o">.</span><span class="na">universal</span><span class="o">(</span><span class="n">49</span><span class="o">,</span> <span class="n">2</span><span class [...]
-</span></span><span class="line"><span class="cl"> <span class="n">areaOfInterest</span><span class="o">.</span><span class="na">setRange</span><span class="o">(</span><span class="n">0</span><span class="o">,</span> <span class="n">46600</span><span class="o">,</span> <span class="n">467000</span><span class="o">);</span> <span class="c1">// Minimal and maximal easting values (metres)
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">areaOfInterest</span><span class="o">.</span><span class="na">setRange</span><span class="o">(</span><span class="n">1</span><span class="o">,</span> <span class="n">5427000</span><span class="o">,</span> <span class="n">5428000</span><span class="o">);</span> <span class="c1">// Minimal and maximal northing values (metres).
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">data</span> <span class="o">=</span> <span class="n">firstImage</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="k">new</span> <span class="n">GridGeometry</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="n">areaOfInterest</span><span class="o">,</span> <span class="n">GridOrientation</spa [...]
-</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the resource subset:%n%s%n"</span><span class="o">,</span>
-</span></span><span class="line"><span class="cl"> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Extent of the data cube:%n%s%n"</span><span class="o">,</span> <span class="n">dataCube</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div>
<h1 id="output">Output</h1>
-<p>If logging at fine level is enabled, the logs should contain some entries like below.
-The “Slowness” level is an Apache SIS custom level for operations taking more than an arbitrary time limit.</p>
-<pre tabindex="0"><code>Slowness [GridCoverageResource] Loaded grid coverage between 48°59′N – 49°02′N and 2°31′E – 2°35′E from file “Aéroport.tiff” in 1.249 seconds.
-FINE [GridCoverageResource] Loaded grid coverage between 48°59.6′N – 49°00.3′N and 2°31′E – 2°33′E from file “Aéroport.tiff” in 0.033 seconds.
-</code></pre><p>The output depends on the raster data and the locale.
+<p>The output depends on the raster data and the locale.
Below is an example:</p>
-<pre tabindex="0"><code>Information about the selected image:
-GridCoverage2D
- ├─Coverage domain
- │ ├─Grid extent
- │ │ ├─Column: [0 … 8191] (8192 cells)
- │ │ └─Row: [0 … 8191] (8192 cells)
- │ ├─Geographic extent
- │ │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ │ └─Upper bound: 49°01′08″N 02°34′16″E
- │ ├─Envelope
- │ │ ├─Easting: 465,341.6 … 468,618.39999999997 ∆E = 0.4 m
- │ │ └─Northing: 5,426,352.8 … 5,429,629.6 ∆N = 0.4 m
- │ ├─Coordinate reference system
- │ │ └─EPSG:32631 — WGS 84 / UTM zone 31N
- │ └─Conversion (origin in a cell center)
- │ └─┌ ┐
- │ │ 0.4 0 465341.8 │
- │ │ 0 -0.4 5429629.4 │
- │ │ 0 0 1 │
- │ └ ┘
- └─Image layout
- ├─Origin: 0, 0
- ├─Tile size: 8,192 × 128
- ├─Data type: byte
- └─Image is opaque.
+<pre tabindex="0"><code>Extent of first set of slices:
+Column: [0 … 864] (865 cells)
+Row: [0 … 1080] (1081 cells)
+Time: [0 … 95] (96 cells)
+
+Extent of second set of slices:
+Column: [0 … 864] (865 cells)
+Row: [0 … 1080] (1081 cells)
+Time: [0 … 95] (96 cells)
+
+Extent of third set of slices:
+Column: [0 … 864] (865 cells)
+Row: [0 … 1080] (1081 cells)
+Time: [0 … 95] (96 cells)
-Information about the resource subset:
-Column: [ 0 … 4145] (4146 cells)
-Row: [3968 … 6655] (2688 cells)
+Extent of the data cube:
+Column: [0 … 864] (865 cells)
+Row: [0 … 1080] (1081 cells)
+Time: [0 … 287] (288 cells)
</code></pre>
</article>
diff --git a/howto/resample_raster.html b/howto/geodetic_paths.html
similarity index 56%
copy from howto/resample_raster.html
copy to howto/geodetic_paths.html
index 9af7c301..ead96bfb 100644
--- a/howto/resample_raster.html
+++ b/howto/geodetic_paths.html
@@ -3,7 +3,7 @@
<head>
- <title>Apache SIS - Resample a raster</title>
+ <title>Apache SIS - Compute geodetic distances and paths</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css"
@@ -103,14 +103,12 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Resample a raster</p>
+ <p class="page-title">Compute geodetic distances and paths</p>
- <p>This example reprojects a raster to a different Coordinate Reference System (CRS).
-This example assumes a preloaded two-dimensional raster.
-For the loading part,
-see <a href="read_netcdf.html">read from a netCDF file</a>
-or <a href="read_geotiff.html">read from a GeoTIFF file</a>
-code examples.</p>
+ <p>The following example computes the geodetic distance between given positions.
+The geodetic distance is the shortest distance on Earth ellipsoid.
+Apache SIS can also compute the path as a Béziers curve,
+with the property that the azimuths at the two curve extremities are preserved.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -122,96 +120,53 @@ code examples.</p>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.code:sis-feature</code></td>
-<td><code>org.apache.sis.feature</code></td>
+<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.referencing</code></td>
<td></td>
</tr>
-<tr>
-<td><code>org.apache.sis.non-free:sis-embedded-data</code></td>
-<td><code>org.apache.sis.referencing.database</code></td>
-<td>Non-Apache license.</td>
-</tr>
</tbody>
</table>
-<p>The <a href="../epsg.html">EPSG dependency</a> is necessary for this example
-because a Coordinate Reference System (CRS) is instantiated from its EPSG code.
-But it would also be possible to specify a CRS without EPSG code,
-for example using Well Known Text (WKT) format.</p>
<h1 id="code-example">Code example</h1>
-<p>The file name in following code need to be updated for yours data.</p>
-<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.image.ImagingOpException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverage</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverageProcessor</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.image.Interpolation</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CRS</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.referencing.operation.TransformException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.util.FactoryException</span><span class="o">;</span>
+<p>Note that all geographic coordinates below express latitude <em>before</em> longitude.</p>
+<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.Shape</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CommonCRS</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.GeodeticCalculator</span><span class="o">;</span>
</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ResampleRaster</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">GeodeticPaths</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Demo entry point.
</span></span></span><span class="line"><span class="cl"><span class="cm"> *
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @param args ignored.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws FactoryException if an error occurred while creating the Coordinate Reference System (CRS).
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws TransformException if an error occurred while transforming coordinates to the target CRS.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while resampling a tile.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">FactoryException</span><span class="o">,</span> <span class="n">TransformException</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// See "Read netCDF" or "Read GeoTIFF" code examples.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the selected image:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">());</span>
-</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Reproject to "WGS 84 / World Mercator" (EPSG::3395) using bilinear interpolation.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This example lets Apache SIS choose the output grid size and resolution.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * But it is possible to specify those aspects if desired.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">processor</span> <span class="o">=</span> <span class="k">new</span> <span class="n">GridCoverageProcessor</span><span class="o">();</span>
-</span></span><span class="line"><span class="cl"> <span class="n">processor</span><span class="o">.</span><span class="na">setInterpolation</span><span class="o">(</span><span class="n">Interpolation</span><span class="o">.</span><span class="na">BILINEAR</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">processor</span><span class="o">.</span><span class="na">resample</span><span class="o">(</span><span class="n">data</span><span class="o">,</span> <span class="n">CRS</span><span class="o">.</span><span class="na">forCode</span><span class="o">(</span><span class="s">"EPSG::3395"</span><span class="o">));</span>
-</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the image after reprojection:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">calculator</span> <span class="o">=</span> <span class="n">GeodeticCalculator</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">CommonCRS</span><span class="o">.</span><span class="na">WGS84</span><span class="o">.</span><span class="na">geographic</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="n">calculator</span><span class="o">.</span><span class="na">setStartGeographicPoint</span><span class="o">(</span><span class="n">40</span><span class="o">,</span> <span class="n">5</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">calculator</span><span class="o">.</span><span class="na">setEndGeographicPoint</span><span class="o">(</span><span class="n">42</span><span class="o">,</span> <span class="n">3</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Result of geodetic calculation: %s%n"</span><span class="o">,</span> <span class="n">calculator</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="kt">double</span> <span class="n">d</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"> <span class="n">d</span> <span class="o">=</span> <span class="n">calculator</span><span class="o">.</span><span class="na">getRhumblineLength</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="n">d</span> <span class="o">-=</span> <span class="n">calculator</span><span class="o">.</span><span class="na">getGeodesicDistance</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"The rhumbline is %1.2f %s longer%n"</span><span class="o">,</span> <span class="n">d</span><span class="o">,</span> <span class="n">calculator</span><span class="o">.</span><span class="na">getDistanceUnit</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="n">Shape</span> <span class="n">path</span> <span class="o">=</span> <span class="n">calculator</span><span class="o">.</span><span class="na">createGeodesicPath2D</span><span class="o">(</span><span class="n">100</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Java2D shape class for approximating this path: %s%n"</span><span class="o">,</span> <span class="n">path</span><span class="o">.</span><span class="na">getClass</span><span class="o">());</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div>
<h1 id="output">Output</h1>
-<p>The output depends on the raster data and the locale.
+<p>The output depends on the locale.
Below is an example:</p>
-<pre tabindex="0"><code>Information about the image after reprojection:
-GridGeometry
- ├─Grid extent
- │ ├─Column: [0 … 8191] (8192 cells)
- │ └─Row: [0 … 8191] (8192 cells)
- ├─Geographic extent
- │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ └─Upper bound: 49°01′08″N 02°34′16″E
- ├─Envelope
- │ ├─Easting: 465,341.6 … 468,618.39999999997 ∆E = 0.4 m
- │ └─Northing: 5,426,352.8 … 5,429,629.6 ∆N = 0.4 m
- ├─Coordinate reference system
- │ └─EPSG:32631 — WGS 84 / UTM zone 31N
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.4 0 465341.8 │
- │ 0 -0.4 5429629.4 │
- │ 0 0 1 │
- └ ┘
+<pre tabindex="0"><code>Result of geodetic calculation:
+Coordinate reference system: WGS 84
+┌─────────────┬─────────────────┬────────────────┬────────────┐
+│ │ Latitude │ Longitude │ Azimuth │
+│ Start point │ 40°00′00.0000″N │ 5°00′00.0000″E │ -36°29′45″ │
+│ End point │ 42°00′00.0000″N │ 3°00′00.0000″E │ -37°48′29″ │
+└─────────────┴─────────────────┴────────────────┴────────────┘
+Geodesic distance: 278,632.68 m
-Information about the image after reprojection:
-GridGeometry
- ├─Grid extent
- │ ├─Dimension 0: [0 … 8239] (8240 cells)
- │ └─Dimension 1: [0 … 8240] (8241 cells)
- ├─Geographic extent
- │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ └─Upper bound: 49°01′08″N 02°34′16″E
- ├─Envelope
- │ ├─Easting: 281,190.4273301751 … 286,207.11249780044 ∆E = 0.60882102 m
- │ └─Northing: 6,240,752.860382801 … 6,245,770.154371441 ∆N = 0.60882102 m
- ├─Coordinate reference system
- │ └─EPSG:3395 — WGS 84 / World Mercator
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.6088210154885099 0 281190.73174068285 │
- │ 0 -0.60882101548851 6245769.8499609330 │
- │ 0 0 1 │
- └ ┘
+The rhumbline is 6.09 m longer
+Java2D shape class for approximating this path: class java.awt.geom.QuadCurve2D$Double
</code></pre>
</article>
diff --git a/howto/index.xml b/howto/index.xml
index 564dd827..f15c8c36 100644
--- a/howto/index.xml
+++ b/howto/index.xml
@@ -6,6 +6,16 @@
<description>Recent content in How to on Apache SIS</description>
<generator>Hugo -- gohugo.io</generator>
<language>en</language><atom:link href="https://sis.apache.org/howto/index.xml" rel="self" type="application/rss+xml" />
+ <item>
+ <title>Compute geodetic distances and paths</title>
+ <link>https://sis.apache.org/howto/geodetic_paths.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/geodetic_paths.html</guid>
+ <description>The following example computes the geodetic distance between given positions. The geodetic distance is the shortest distance on Earth ellipsoid. Apache SIS can also compute the path as a Béziers curve, with the property that the azimuths at the two curve extremities are preserved.
+Direct dependencies Maven coordinates Module info Remarks org.apache.sis.storage:sis-referencing org.apache.sis.referencing Code example Note that all geographic coordinates below express latitude before longitude.</description>
+ </item>
+
<item>
<title>Determine if two CRS are functionally equal</title>
<link>https://sis.apache.org/howto/crs_equality.html</link>
@@ -16,6 +26,16 @@
In some cases, equalsIgnoreMetadata(…) may fail to see that two reference systems are equal. It may happen for example when two map projections are defined with different parameters, but are mathematically equivalent.</description>
</item>
+ <item>
+ <title>From data lake to data cube</title>
+ <link>https://sis.apache.org/howto/datalake_to_datacube.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/datalake_to_datacube.html</guid>
+ <description>This example opens a few files where each file represent a slice in a data cube. Then the slices are aggregated together in a single multi-dimensional data cube. For example each file may be a raster representing Sea Surface Temperature (SST) at a specific day, and those files can be a aggregated in a single three-dimensional raster with a temporal dimension.
+A current limitation is that each slice must have the same number of dimensions than the data cube.</description>
+ </item>
+
<item>
<title>Geographic bounding box of a data file</title>
<link>https://sis.apache.org/howto/export_metadata_to_xml.html</link>
@@ -84,6 +104,25 @@ Some file formats store values as integers for compactness reasons, but provide
An alternative, more standard, way using geographic coordinates is to format an &ldquo;AUTO&rdquo; authority code.</description>
</item>
+ <item>
+ <title>Parallel computation</title>
+ <link>https://sis.apache.org/howto/parallel_computation.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/parallel_computation.html</guid>
+ <description>Some grid coverages will read or compute chunks of data only when first requested. For example when a coverage is the result of a reprojection, or when a big coverage uses deferred tile reading. However if tiles are always requested in the same thread, it will result in a sequential, mono-threaded computation. Furthermore it may cause a lot of seek or &ldquo;HTTP range&rdquo; operations if tiles are read in random order.</description>
+ </item>
+
+ <item>
+ <title>Parse and format MGRS codes</title>
+ <link>https://sis.apache.org/howto/parse_and_format_mgrs_codes.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/parse_and_format_mgrs_codes.html</guid>
+ <description>The following example converts geographic coordinates to Military Grid Reference System (MGRS) codes and conversely. MGRS codes can be seen as a kind of GeoHash but with better properties. Apache SIS supports also GeoHash if desired, in a way similar to this example.
+Direct dependencies Maven coordinates Module info Remarks org.apache.sis.storage:sis-referencing org.apache.sis.referencing Code example Note that all geographic coordinates below express latitude before longitude.</description>
+ </item>
+
<item>
<title>Read raster from a GeoTIFF file</title>
<link>https://sis.apache.org/howto/read_geotiff.html</link>
diff --git a/howto/resample_raster.html b/howto/parallel_computation.html
similarity index 61%
copy from howto/resample_raster.html
copy to howto/parallel_computation.html
index 9af7c301..a18aa5c5 100644
--- a/howto/resample_raster.html
+++ b/howto/parallel_computation.html
@@ -3,7 +3,7 @@
<head>
- <title>Apache SIS - Resample a raster</title>
+ <title>Apache SIS - Parallel computation</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css"
@@ -103,14 +103,17 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Resample a raster</p>
+ <p class="page-title">Parallel computation</p>
- <p>This example reprojects a raster to a different Coordinate Reference System (CRS).
-This example assumes a preloaded two-dimensional raster.
-For the loading part,
-see <a href="read_netcdf.html">read from a netCDF file</a>
-or <a href="read_geotiff.html">read from a GeoTIFF file</a>
-code examples.</p>
+ <p>Some grid coverages will read or compute chunks of data only when first requested.
+For example when a coverage is the <a href="resample_raster.html">result of a reprojection</a>,
+or when a big coverage <a href="rasters_bigger_than_memory.html">uses deferred tile reading</a>.
+However if tiles are always requested in the same thread,
+it will result in a sequential, mono-threaded computation.
+Furthermore it may cause a lot of seek or “HTTP range” operations if tiles are read in random order.
+For parallel computation using all available processors,
+or for more efficient read operations,
+we need to inform Apache SIS in advance about which pixels are about to be requested.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -126,93 +129,44 @@ code examples.</p>
<td><code>org.apache.sis.feature</code></td>
<td></td>
</tr>
-<tr>
-<td><code>org.apache.sis.non-free:sis-embedded-data</code></td>
-<td><code>org.apache.sis.referencing.database</code></td>
-<td>Non-Apache license.</td>
-</tr>
</tbody>
</table>
-<p>The <a href="../epsg.html">EPSG dependency</a> is necessary for this example
-because a Coordinate Reference System (CRS) is instantiated from its EPSG code.
-But it would also be possible to specify a CRS without EPSG code,
-for example using Well Known Text (WKT) format.</p>
<h1 id="code-example">Code example</h1>
-<p>The file name in following code need to be updated for yours data.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.image.ImagingOpException</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.image.RenderedImage</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverage</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverageProcessor</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.image.Interpolation</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CRS</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.referencing.operation.TransformException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.util.FactoryException</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.image.ImageProcessor</span><span class="o">;</span>
</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ResampleRaster</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ParallelTileComputation</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Demo entry point.
</span></span></span><span class="line"><span class="cl"><span class="cm"> *
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @param args ignored.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws FactoryException if an error occurred while creating the Coordinate Reference System (CRS).
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws TransformException if an error occurred while transforming coordinates to the target CRS.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while resampling a tile.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while computing a tile.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">FactoryException</span><span class="o">,</span> <span class="n">TransformException</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// See "Read netCDF" or "Read GeoTIFF" code examples.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the selected image:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">coverage</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// See "Resample a raster" code example.
+</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Get all data from the coverage, assuming that the grid is two-dimensional.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If there is three or more dimensions, the null value needs to be replaced
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * by a `GridExtent` specifying the two-dimensional slice to fetch.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">RenderedImage</span> <span class="n">data</span> <span class="o">=</span> <span class="n">coverage</span><span class="o">.</span><span class="na">render</span><span class="o">(</span><span class="kc">null</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * With above `RenderedImage`, tiles are computed when first requested and cached for future uses.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If all tiles will be requested in the same thread, it results in a sequential tile computation.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * For parallel computation using all available processors, we need to inform Apache SIS in advance
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * about which pixels will be requested. The `null` argument below means "all pixels in the image".
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Don't use that null argument if the image is very big!
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">processor</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ImageProcessor</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">processor</span><span class="o">.</span><span class="na">prefetch</span><span class="o">(</span><span class="n">data</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Reproject to "WGS 84 / World Mercator" (EPSG::3395) using bilinear interpolation.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This example lets Apache SIS choose the output grid size and resolution.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * But it is possible to specify those aspects if desired.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * See for example "Get raster values at pixel coordinates" for using this image.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">processor</span> <span class="o">=</span> <span class="k">new</span> <span class="n">GridCoverageProcessor</span><span class="o">();</span>
-</span></span><span class="line"><span class="cl"> <span class="n">processor</span><span class="o">.</span><span class="na">setInterpolation</span><span class="o">(</span><span class="n">Interpolation</span><span class="o">.</span><span class="na">BILINEAR</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">processor</span><span class="o">.</span><span class="na">resample</span><span class="o">(</span><span class="n">data</span><span class="o">,</span> <span class="n">CRS</span><span class="o">.</span><span class="na">forCode</span><span class="o">(</span><span class="s">"EPSG::3395"</span><span class="o">));</span>
-</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the image after reprojection:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">());</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div>
-<h1 id="output">Output</h1>
-<p>The output depends on the raster data and the locale.
-Below is an example:</p>
-<pre tabindex="0"><code>Information about the image after reprojection:
-GridGeometry
- ├─Grid extent
- │ ├─Column: [0 … 8191] (8192 cells)
- │ └─Row: [0 … 8191] (8192 cells)
- ├─Geographic extent
- │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ └─Upper bound: 49°01′08″N 02°34′16″E
- ├─Envelope
- │ ├─Easting: 465,341.6 … 468,618.39999999997 ∆E = 0.4 m
- │ └─Northing: 5,426,352.8 … 5,429,629.6 ∆N = 0.4 m
- ├─Coordinate reference system
- │ └─EPSG:32631 — WGS 84 / UTM zone 31N
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.4 0 465341.8 │
- │ 0 -0.4 5429629.4 │
- │ 0 0 1 │
- └ ┘
-Information about the image after reprojection:
-GridGeometry
- ├─Grid extent
- │ ├─Dimension 0: [0 … 8239] (8240 cells)
- │ └─Dimension 1: [0 … 8240] (8241 cells)
- ├─Geographic extent
- │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ └─Upper bound: 49°01′08″N 02°34′16″E
- ├─Envelope
- │ ├─Easting: 281,190.4273301751 … 286,207.11249780044 ∆E = 0.60882102 m
- │ └─Northing: 6,240,752.860382801 … 6,245,770.154371441 ∆N = 0.60882102 m
- ├─Coordinate reference system
- │ └─EPSG:3395 — WGS 84 / World Mercator
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.6088210154885099 0 281190.73174068285 │
- │ 0 -0.60882101548851 6245769.8499609330 │
- │ 0 0 1 │
- └ ┘
-</code></pre>
</article>
</main>
diff --git a/howto/resample_raster.html b/howto/parse_and_format_mgrs_codes.html
similarity index 58%
copy from howto/resample_raster.html
copy to howto/parse_and_format_mgrs_codes.html
index 9af7c301..18245077 100644
--- a/howto/resample_raster.html
+++ b/howto/parse_and_format_mgrs_codes.html
@@ -3,7 +3,7 @@
<head>
- <title>Apache SIS - Resample a raster</title>
+ <title>Apache SIS - Parse and format MGRS codes</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.1/dist/css/bootstrap.min.css"
@@ -103,14 +103,12 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Resample a raster</p>
+ <p class="page-title">Parse and format MGRS codes</p>
- <p>This example reprojects a raster to a different Coordinate Reference System (CRS).
-This example assumes a preloaded two-dimensional raster.
-For the loading part,
-see <a href="read_netcdf.html">read from a netCDF file</a>
-or <a href="read_geotiff.html">read from a GeoTIFF file</a>
-code examples.</p>
+ <p>The following example converts geographic coordinates to
+Military Grid Reference System (MGRS) codes and conversely.
+MGRS codes can be seen as a kind of GeoHash but with better properties.
+Apache SIS supports also GeoHash if desired, in a way similar to this example.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -122,96 +120,60 @@ code examples.</p>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.code:sis-feature</code></td>
-<td><code>org.apache.sis.feature</code></td>
+<td><code>org.apache.sis.storage:sis-referencing</code></td>
+<td><code>org.apache.sis.referencing</code></td>
<td></td>
</tr>
-<tr>
-<td><code>org.apache.sis.non-free:sis-embedded-data</code></td>
-<td><code>org.apache.sis.referencing.database</code></td>
-<td>Non-Apache license.</td>
-</tr>
</tbody>
</table>
-<p>The <a href="../epsg.html">EPSG dependency</a> is necessary for this example
-because a Coordinate Reference System (CRS) is instantiated from its EPSG code.
-But it would also be possible to specify a CRS without EPSG code,
-for example using Well Known Text (WKT) format.</p>
<h1 id="code-example">Code example</h1>
-<p>The file name in following code need to be updated for yours data.</p>
-<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.image.ImagingOpException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverage</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverageProcessor</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.image.Interpolation</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CRS</span><span class="o">;</span>
+<p>Note that all geographic coordinates below express latitude <em>before</em> longitude.</p>
+<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.geometry.DirectPosition2D</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CommonCRS</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.gazetteer.MilitaryGridReferenceSystem</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.referencing.gazetteer.Location</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.referencing.operation.TransformException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.util.FactoryException</span><span class="o">;</span>
</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ResampleRaster</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MGRS</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/**
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Demo entry point.
</span></span></span><span class="line"><span class="cl"><span class="cm"> *
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @param args ignored.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws FactoryException if an error occurred while creating the Coordinate Reference System (CRS).
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws TransformException if an error occurred while transforming coordinates to the target CRS.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while resampling a tile.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws TransformException if an error occurred when encoding or decoding a position.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">FactoryException</span><span class="o">,</span> <span class="n">TransformException</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// See "Read netCDF" or "Read GeoTIFF" code examples.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the selected image:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">());</span>
-</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Reproject to "WGS 84 / World Mercator" (EPSG::3395) using bilinear interpolation.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This example lets Apache SIS choose the output grid size and resolution.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * But it is possible to specify those aspects if desired.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">processor</span> <span class="o">=</span> <span class="k">new</span> <span class="n">GridCoverageProcessor</span><span class="o">();</span>
-</span></span><span class="line"><span class="cl"> <span class="n">processor</span><span class="o">.</span><span class="na">setInterpolation</span><span class="o">(</span><span class="n">Interpolation</span><span class="o">.</span><span class="na">BILINEAR</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">processor</span><span class="o">.</span><span class="na">resample</span><span class="o">(</span><span class="n">data</span><span class="o">,</span> <span class="n">CRS</span><span class="o">.</span><span class="na">forCode</span><span class="o">(</span><span class="s">"EPSG::3395"</span><span class="o">));</span>
-</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the image after reprojection:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">TransformException</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">rs</span> <span class="o">=</span> <span class="k">new</span> <span class="n">MilitaryGridReferenceSystem</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">point</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DirectPosition2D</span><span class="o">(</span><span class="n">CommonCRS</span><span class="o">.</span><span class="na">WGS84</span><span class="o">.</span><span class="na">geographic</span><span class="o">(),</span> <span class="n">40</span><span class="o">,</span> <span class="n">5</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">coder</span> <span class="o">=</span> <span class="n">rs</span><span class="o">.</span><span class="na">createCoder</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="n">var</span> <span class="n">code</span> <span class="o">=</span> <span class="n">coder</span><span class="o">.</span><span class="na">encode</span><span class="o">(</span><span class="n">point</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"MGRS code of %s is %s%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">code</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="n">coder</span><span class="o">.</span><span class="na">setPrecision</span><span class="o">(</span><span class="n">1000</span><span class="o">);</span> <span class="c1">// Limit to a precision of 1 km.
+</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">code</span> <span class="o">=</span> <span class="n">coder</span><span class="o">.</span><span class="na">encode</span><span class="o">(</span><span class="n">point</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Same code reduced to 1 km precision: %s%n"</span><span class="o">,</span> <span class="n">code</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="n">Location</span> <span class="n">reverse</span> <span class="o">=</span> <span class="n">coder</span><span class="o">.</span><span class="na">decode</span><span class="o">(</span><span class="n">code</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Back to geographic coordinates: %s%n"</span><span class="o">,</span> <span class="n">reverse</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div>
<h1 id="output">Output</h1>
-<p>The output depends on the raster data and the locale.
+<p>The output depends on the locale.
Below is an example:</p>
-<pre tabindex="0"><code>Information about the image after reprojection:
-GridGeometry
- ├─Grid extent
- │ ├─Column: [0 … 8191] (8192 cells)
- │ └─Row: [0 … 8191] (8192 cells)
- ├─Geographic extent
- │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ └─Upper bound: 49°01′08″N 02°34′16″E
- ├─Envelope
- │ ├─Easting: 465,341.6 … 468,618.39999999997 ∆E = 0.4 m
- │ └─Northing: 5,426,352.8 … 5,429,629.6 ∆N = 0.4 m
- ├─Coordinate reference system
- │ └─EPSG:32631 — WGS 84 / UTM zone 31N
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.4 0 465341.8 │
- │ 0 -0.4 5429629.4 │
- │ 0 0 1 │
- └ ┘
-
-Information about the image after reprojection:
-GridGeometry
- ├─Grid extent
- │ ├─Dimension 0: [0 … 8239] (8240 cells)
- │ └─Dimension 1: [0 … 8240] (8241 cells)
- ├─Geographic extent
- │ ├─Lower bound: 48°59′20″N 02°31′33″E
- │ └─Upper bound: 49°01′08″N 02°34′16″E
- ├─Envelope
- │ ├─Easting: 281,190.4273301751 … 286,207.11249780044 ∆E = 0.60882102 m
- │ └─Northing: 6,240,752.860382801 … 6,245,770.154371441 ∆N = 0.60882102 m
- ├─Coordinate reference system
- │ └─EPSG:3395 — WGS 84 / World Mercator
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.6088210154885099 0 281190.73174068285 │
- │ 0 -0.60882101548851 6245769.8499609330 │
- │ 0 0 1 │
- └ ┘
+<pre tabindex="0"><code>MGRS code of POINT(40 5) is 31TFE7072529672
+Same code reduced to 1 km precision: 31TFE7029
+Back to geographic coordinates:
+┌─────────────────────────────────────────────────────────────────┐
+│ Location type: Grid coordinate │
+│ Geographic identifier: 31TFE7029 │
+│ West bound: 670,000 m — 4°59′28″E │
+│ Representative value: 670,500 m — 4°59′51″E │
+│ East bound: 671,000 m — 5°00′12″E │
+│ South bound: 4,429,656 m — 40°00′00″N │
+│ Representative value: 4,429,828 m — 40°00′05″N │
+│ North bound: 4,430,000 m — 40°00′12″N │
+│ Coordinate reference system: WGS 84 / UTM zone 31N │
+│ Administrator: North Atlantic Treaty Organization │
+└─────────────────────────────────────────────────────────────────┘
</code></pre>
</article>
diff --git a/howto/raster_values_at_pixel_coordinates.html b/howto/raster_values_at_pixel_coordinates.html
index eb60448d..9e775ace 100644
--- a/howto/raster_values_at_pixel_coordinates.html
+++ b/howto/raster_values_at_pixel_coordinates.html
@@ -115,6 +115,10 @@ code examples.</p>
but provide a <em>transfer function</em> for converting those integers to “real world” values.
Apache SIS can provide either the original integers or the converted values, at user’s choice.
This choice is specified by the boolean argument in the <code>data.forConvertedValues(…)</code> call.</p>
+<p>Note that pixel coordinates are relative to the request made in the call to <code>render(…)</code>.
+They are not directly the grid coordinates of the coverage.
+The use of relative coordinates makes possible to avoid 32 bits integer overflow,
+and is also convenient for working on an area of interest regardless the grid coverage origin.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -181,8 +185,8 @@ This choice is specified by the boolean argument in the <code>data.forConvert
</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Value at (%d,%d) is %g %s.%n"</span><span class="o">,</span> <span class="n">pos</span><span class="o">.</span><span class="na">x</span><span class="o">,</span> <span class="n">pos</span><span class="o">.</span><span class="na">y</span><span class [...]
</span></span><span class="line"><span class="cl"> <span class="k">if</span> <span class="o">(--</span><span class="n">n</span> <span class="o">==</span> <span class="n">0</span><span class="o">)</span> <span class="k">break</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
-</span></span><span class="line"><span class="cl"> <span class="n">pit</span><span class="o">.</span><span class="na">moveTo</span><span class="o">(</span><span class="n">100</span><span class="o">,</span> <span class="n">200</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="kt">float</span> <span class="n">value</span> <span class="o">=</span> <span class="n">pit</span><span class="o">.</span><span class="na">getSampleFloat</span><span class="o">(</span><span class="n">band</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">pit</span><span class="o">.</span><span class="na">moveTo</span><span class="o">(</span><span class="n">100</span><span class="o">,</span> <span class="n">200</span><span class="o">);</span> <span class="c1">// Relative to `extent` low coordinates.
+</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="kt">float</span> <span class="n">value</span> <span class="o">=</span> <span class="n">pit</span><span class="o">.</span><span class="na">getSampleFloat</span><span class="o">(</span><span class="n">band</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Value at (100,200) is %g %s.%n"</span><span class="o">,</span> <span class="n">value</span><span class="o">,</span> <span class="n">unit</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div>
diff --git a/howto/rasters_bigger_than_memory.html b/howto/rasters_bigger_than_memory.html
index eb032400..fe52ab6f 100644
--- a/howto/rasters_bigger_than_memory.html
+++ b/howto/rasters_bigger_than_memory.html
@@ -113,6 +113,9 @@ provided that the application does not request all tiles at once.
It integrates well with operations provided by Apache <abbr title="Spatial Information System">SIS</abbr> such as
<a href="resample_raster.html">raster resampling</a> and
<a href="raster_values_at_geographic_coordinates.html">getting values at geographic coordinates</a>.</p>
+<p>The approach demonstrated in this example has one drawback compared to the default behavior:
+the <code>DataStore</code> must be kept open during all the time that the <code>GridCoverage</code> is used.
+Consequently the <code>data</code> variable should not be used outside the <code>try</code> block in this example.</p>
<p>The example in this page works with pixel coordinates.
For working with geographic coordinates, see
<a href="raster_values_at_geographic_coordinates.html">values at geographic coordinates</a> code example.</p>
@@ -180,6 +183,10 @@ depending how the Coordinate Reference System (CRS) is encoded in the GeoTIFF fi
</span></span><span class="line"><span class="cl"> <span class="n">firstImage</span><span class="o">.</span><span class="na">setLoadingStrategy</span><span class="o">(</span><span class="n">RasterLoadingStrategy</span><span class="o">.</span><span class="na">AT_GET_TILE_TIME</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="n">firstImage</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="n">printPixelValue</span><span class="o">(</span><span class="n">data</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Contrarily to other examples, the `GridCoverage` fetched in deferred reading mode
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * can NOT be used outside this `try` block, because the `DataStore` must be open.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl">
diff --git a/howto/read_geotiff.html b/howto/read_geotiff.html
index dcaead8d..f1c013fe 100644
--- a/howto/read_geotiff.html
+++ b/howto/read_geotiff.html
@@ -163,6 +163,17 @@ depending how the Coordinate Reference System (CRS) is encoded in the GeoTIFF fi
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while loading a tile.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">DataStoreException</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">example</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="o">}</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="cm">/**
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Reads an example file and prints some information about it.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> *
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @return the raster data.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws DataStoreException if an error occurred while reading the raster.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="n">GridCoverage</span> <span class="nf">example</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">DataStoreException</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"> <span class="k">try</span> <span class="o">(</span><span class="n">DataStore</span> <span class="n">store</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"Aéroport.tiff"</span><span class="o">)))</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
</span></span></span><span class="line"><span class="cl"><span class="cm"> * This data store is an aggregate because a GeoTIFF file may contain many images.
@@ -174,7 +185,7 @@ depending how the Coordinate Reference System (CRS) is encoded in the GeoTIFF fi
</span></span><span class="line"><span class="cl"> <span class="cm">/*
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Read the resource immediately and fully.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="n">firstImage</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">firstImage</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the selected image:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Read only a subset of the resource. The Area Of Interest can be specified
@@ -189,6 +200,12 @@ depending how the Coordinate Reference System (CRS) is encoded in the GeoTIFF fi
</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the resource subset:%n%s%n"</span><span class="o">,</span>
</span></span><span class="line"><span class="cl"> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
+</span></span><span class="line"><span class="cl"> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * By default, it is possible to continue to use the `GridCoverage` (but not the `Resource`) after
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * the `DataStore` has been closed because data are in memory. Note that it would not be the case
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * if deferred data loading was enabled has shown in "Handle rasters bigger than memory" example.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="k">return</span> <span class="n">data</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span></span></span></code></pre></div>
<h1 id="output">Output</h1>
diff --git a/howto/read_netcdf.html b/howto/read_netcdf.html
index 78617a90..baeeddcb 100644
--- a/howto/read_netcdf.html
+++ b/howto/read_netcdf.html
@@ -161,7 +161,18 @@ in following code need to be updated for yours data.</p>
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws DataStoreException if an error occurred while reading the raster.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">DataStoreException</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="k">try</span> <span class="o">(</span><span class="n">DataStore</span> <span class="n">store</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"CMEMS_R20220516.nc"</span><span class="o">)))</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">example</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="o">}</span>
+</span></span><span class="line"><span class="cl">
+</span></span><span class="line"><span class="cl"> <span class="cm">/**
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Reads an example file and prints some information about it.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> *
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @return the raster data.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws DataStoreException if an error occurred while reading the raster.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="n">GridCoverage</span> <span class="nf">example</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">DataStoreException</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"> <span class="k">try</span> <span class="o">(</span><span class="n">DataStore</span> <span class="n">store</span> <span class="o">=</span> <span class="n">DataStores</span><span class="o">.</span><span class="na">open</span><span class="o">(</span><span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"CMEMS_20220516.nc"</span><span class="o">)))</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
</span></span></span><span class="line"><span class="cl"><span class="cm"> * See what is inside this file. One of the components listed
</span></span></span><span class="line"><span class="cl"><span class="cm"> * below can be given in argument to `findResource(String)`.
@@ -172,8 +183,9 @@ in following code need to be updated for yours data.</p>
</span></span><span class="line"><span class="cl"> <span class="k">if</span> <span class="o">(</span><span class="n">resource</span> <span class="k">instanceof</span> <span class="n">GridCoverageResource</span> <span class="n">gridded</span><span class="o">)</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Read the resource immediately and fully.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * `data` can be used outside the `try` block.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="n">gridded</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">gridded</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the selected resource:%n%s%n"</span><span class="o">,</span> <span class="n">data</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="cm">/*
</span></span></span><span class="line"><span class="cl"><span class="cm"> * Read only a subset of the resource. The Area Of Interest can be specified
@@ -186,8 +198,16 @@ in following code need to be updated for yours data.</p>
</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">data</span> <span class="o">=</span> <span class="n">gridded</span><span class="o">.</span><span class="na">read</span><span class="o">(</span><span class="k">new</span> <span class="n">GridGeometry</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="n">areaOfInterest</span><span class="o">,</span> <span class="n">GridOrientation</sp [...]
</span></span><span class="line"><span class="cl"> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">printf</span><span class="o">(</span><span class="s">"Information about the resource subset:%n%s%n"</span><span class="o">,</span>
</span></span><span class="line"><span class="cl"> <span class="n">data</span><span class="o">.</span><span class="na">getGridGeometry</span><span class="o">().</span><span class="na">getExtent</span><span class="o">());</span>
+</span></span><span class="line"><span class="cl"> <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="k">throw</span> <span class="k">new</span> <span class="n">DataStoreException</span><span class="o">(</span><span class="s">"Unexpected type of resource."</span><span class="o">);</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
+</span></span><span class="line"><span class="cl"> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * By default, it is possible to continue to use the `GridCoverage` (but not the `Resource`) after
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * the `DataStore` has been closed because data are in memory. Note that it would not be the case
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * if deferred data loading was enabled has shown in "Handle rasters bigger than memory" example.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="k">return</span> <span class="n">data</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"> <span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"> <span class="cm">/**
diff --git a/howto/resample_raster.html b/howto/resample_raster.html
index 9af7c301..a0f043b4 100644
--- a/howto/resample_raster.html
+++ b/howto/resample_raster.html
@@ -139,8 +139,7 @@ But it would also be possible to specify a CRS without EPSG code,
for example using Well Known Text (WKT) format.</p>
<h1 id="code-example">Code example</h1>
<p>The file name in following code need to be updated for yours data.</p>
-<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.awt.image.ImagingOpException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverage</span><span class="o">;</span>
+<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-java" data-lang="java"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverage</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.coverage.grid.GridCoverageProcessor</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.image.Interpolation</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.referencing.CRS</span><span class="o">;</span>
@@ -154,7 +153,6 @@ for example using Well Known Text (WKT) format.</p>
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @param args ignored.
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws FactoryException if an error occurred while creating the Coordinate Reference System (CRS).
</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws TransformException if an error occurred while transforming coordinates to the target CRS.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws ImagingOpException unchecked exception thrown if an error occurred while resampling a tile.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">FactoryException</span><span class="o">,</span> <span class="n">TransformException</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl"> <span class="n">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// See "Read netCDF" or "Read GeoTIFF" code examples.