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/17 15:33:12 UTC
[sis-site] branch asf-staging updated: Regenerate the "howto" pages with better separation of raster use cases.
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 a96505cf Regenerate the "howto" pages with better separation of raster use cases.
a96505cf is described below
commit a96505cf6f6a0ac9861b7a8ebd01b31fbf8c8d9a
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Mon Apr 17 17:32:48 2023 +0200
Regenerate the "howto" pages with better separation of raster use cases.
---
howto.html | 22 ++-
howto/crs_equality.html | 22 +--
howto/envelopes_in_different_crs.html | 4 +-
howto/export_metadata_to_xml.html | 4 +-
howto/geographic_bounding_box.html | 4 +-
howto/index.xml | 99 +++++++---
howto/instantiate_utm_projection.html | 4 +-
howto/lookup_crs_urn.html | 44 ++---
howto/raster_values_at_geographic_coordinates.html | 202 ++++++---------------
...tml => raster_values_at_pixel_coordinates.html} | 128 ++++++-------
howto/rasters_bigger_than_memory.html | 84 ++++-----
...mple_and_save_raster.html => read_geotiff.html} | 115 +++++-------
...eographic_coordinates.html => read_netcdf.html} | 121 +++++-------
...sform_coordinates.html => resample_raster.html} | 123 ++++++++-----
howto/transform_coordinates.html | 4 +-
howto/transform_envelopes.html | 4 +-
...graphic_bounding_box.html => write_raster.html} | 81 +++------
17 files changed, 480 insertions(+), 585 deletions(-)
diff --git a/howto.html b/howto.html
index 0e23f7f3..eb9274f4 100644
--- a/howto.html
+++ b/howto.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - How to</title>
<meta charset="utf-8">
@@ -104,16 +104,26 @@
<article>
<img src="./images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">How to</p>
-
+
<p>Java code examples for performing some tasks with Apache <abbr title="Spatial Information System">SIS</abbr>.
The examples are grouped in the following sections:</p>
<nav id="TableOfContents">
<ul>
+ <li><a href="#raster">Grid coverages (rasters) </a></li>
<li><a href="#referencing">Referencing by coordinates </a></li>
<li><a href="#metadata">Metadata </a></li>
- <li><a href="#raster">Grid coverages (rasters) </a></li>
</ul>
</nav>
+<h1 id="raster">Grid coverages (rasters) </h1>
+<ul>
+<li><a href="howto/read_netcdf.html">Read raster from a netCDF file</a></li>
+<li><a href="howto/read_geotiff.html">Read raster from a GeoTIFF file</a></li>
+<li><a href="howto/raster_values_at_pixel_coordinates.html">Get raster values at pixel coordinates</a></li>
+<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/write_raster.html">Write a raster to a file</a></li>
+</ul>
<h1 id="referencing">Referencing by coordinates </h1>
<ul>
<li><a href="howto/instantiate_utm_projection.html">Instantiate a Universal Transverse Mercator (UTM) projection</a></li>
@@ -128,12 +138,6 @@ The examples are grouped in the following sections:</p>
<ul>
<li><a href="howto/geographic_bounding_box.html">Get the geographic bounding box of a data file</a></li>
<li><a href="howto/export_metadata_to_xml.html">Export metadata of a data file to standard XML</a></li>
-</ul>
-<h1 id="raster">Grid coverages (rasters) </h1>
-<ul>
-<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_and_save_raster.html">Resample a raster and write to a file</a></li>
</ul>
diff --git a/howto/crs_equality.html b/howto/crs_equality.html
index 297302d0..a1c37686 100644
--- a/howto/crs_equality.html
+++ b/howto/crs_equality.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Determine if two CRS are functionally equal</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Determine if two CRS are functionally equal</p>
-
+
<p>Two Coordinate Reference Systems may not be considered equal if they are associated to different metadata
(name, identifiers, scope, domain of validity, remarks), even though they represent the same logical <abbr title="Coordinate Reference System">CRS</abbr>.
In order to test if two <abbr title="Coordinate Reference System">CRS</abbr> are functionally equivalent,
@@ -147,15 +147,15 @@ is to request the coordinate operation between them, and check if that operation
</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></span><span class="line"><span class="cl"> <span class="n">CoordinateReferenceSystem</span> <span class="n">crs1</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">CoordinateReferenceSystem</span> <span class="n">crs2</span> <span class="o">=</span> <span class="n">CRS</span><span class="o">.</span><span class="na">fromWKT</span><span class="o">(</span>
-</span></span><span class="line"><span class="cl"> <span class="s">"""
-</span></span></span><span class="line"><span class="cl"><span class="s"> GeodeticCRS["</span><span class="n">WGS84</span> <span class="n">with</span> <span class="n">a</span> <span class="n">different</span> <span class="n">name</span><span class="s">",
-</span></span></span><span class="line"><span class="cl"><span class="s"> Datum["</span><span class="n">World</span> <span class="n">Geodetic</span> <span class="n">System</span> <span class="n">1984</span><span class="s">",
-</span></span></span><span class="line"><span class="cl"><span class="s"> Ellipsoid["</span><span class="n">A</span> <span class="n">different</span> <span class="n">name</span><span class="s">", 6378137.0, 298.257223563]],
-</span></span></span><span class="line"><span class="cl"><span class="s"> CS[ellipsoidal, 2],
-</span></span></span><span class="line"><span class="cl"><span class="s"> Axis["</span><span class="n">Latitude</span> <span class="o">(</span><span class="n">B</span><span class="o">)</span><span class="s">", north],
-</span></span></span><span class="line"><span class="cl"><span class="s"> Axis["</span><span class="n">Longitude</span> <span class="o">(</span><span class="n">L</span><span class="o">)</span><span class="s">", east],
-</span></span></span><span class="line"><span class="cl"><span class="s"> Unit["</span><span class="n">degree</span><span class="s">", 0.017453292519943295]]
-</span></span></span><span class="line"><span class="cl"><span class="s"> """</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="s">"""
+</span></span></span><span class="line"><span class="cl"><span class="s"> GeodeticCRS["</span><span class="n">WGS84</span> <span class="n">with</span> <span class="n">a</span> <span class="n">different</span> <span class="n">name</span><span class="s">",
+</span></span></span><span class="line"><span class="cl"><span class="s"> Datum["</span><span class="n">World</span> <span class="n">Geodetic</span> <span class="n">System</span> <span class="n">1984</span><span class="s">",
+</span></span></span><span class="line"><span class="cl"><span class="s"> Ellipsoid["</span><span class="n">A</span> <span class="n">different</span> <span class="n">name</span><span class="s">", 6378137.0, 298.257223563]],
+</span></span></span><span class="line"><span class="cl"><span class="s"> CS[ellipsoidal, 2],
+</span></span></span><span class="line"><span class="cl"><span class="s"> Axis["</span><span class="n">Latitude</span> <span class="o">(</span><span class="n">B</span><span class="o">)</span><span class="s">", north],
+</span></span></span><span class="line"><span class="cl"><span class="s"> Axis["</span><span class="n">Longitude</span> <span class="o">(</span><span class="n">L</span><span class="o">)</span><span class="s">", east],
+</span></span></span><span class="line"><span class="cl"><span class="s"> Unit["</span><span class="n">degree</span><span class="s">", 0.017453292519943295]]
+</span></span></span><span class="line"><span class="cl"><span class="s"> """</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">println</span><span class="o">(</span><span class="s">"equals: "</span>
</span></span><span class="line"><span class="cl"> <span class="o">+</span> <span class="n">crs1</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">crs2</span><span class="o">));</span>
diff --git a/howto/envelopes_in_different_crs.html b/howto/envelopes_in_different_crs.html
index 89e78020..c1f5cd91 100644
--- a/howto/envelopes_in_different_crs.html
+++ b/howto/envelopes_in_different_crs.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Union or intersection of envelopes in different CRS</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Union or intersection of envelopes in different CRS</p>
-
+
<p>Before to compute the union or intersection of two or more envelopes (bounding boxes),
all envelopes must be <a href="transform_envelopes.html">transformed</a> to the same Coordinate Reference System (CRS).
But the choice of a common <abbr title="Coordinate Reference System">CRS</abbr> is not easy.
diff --git a/howto/export_metadata_to_xml.html b/howto/export_metadata_to_xml.html
index 8fa2b717..591b39c5 100644
--- a/howto/export_metadata_to_xml.html
+++ b/howto/export_metadata_to_xml.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Geographic bounding box of a data file</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Geographic bounding box of a data file</p>
-
+
<p>This example prints the metadata of a netCDF file in the XML format
defined by the ISO 19115-3 international standard.
The coverage values are not read, only the netCDF file header is read.</p>
diff --git a/howto/geographic_bounding_box.html b/howto/geographic_bounding_box.html
index 278b84bd..b9f4ac4b 100644
--- a/howto/geographic_bounding_box.html
+++ b/howto/geographic_bounding_box.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Geographic bounding box of a data file</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Geographic bounding box of a data file</p>
-
+
<p>This example prints the bounding box of a GeoTIFF image.
The pixel values are not read, only the GeoTIFF file header is read.
If the file contains many images, the bounding box of each image is printed.</p>
diff --git a/howto/index.xml b/howto/index.xml
index edcad466..564dd827 100644
--- a/howto/index.xml
+++ b/howto/index.xml
@@ -10,107 +10,148 @@
<title>Determine if two CRS are functionally equal</title>
<link>https://sis.apache.org/howto/crs_equality.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/crs_equality.html</guid>
<description>Two Coordinate Reference Systems may not be considered equal if they are associated to different metadata (name, identifiers, scope, domain of validity, remarks), even though they represent the same logical CRS. In order to test if two CRS are functionally equivalent, Utilities.equalsIgnoreMetadata(myFirstCRS, mySecondCRS) can be used.
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>Geographic bounding box of a data file</title>
<link>https://sis.apache.org/howto/export_metadata_to_xml.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/export_metadata_to_xml.html</guid>
<description>This example prints the metadata of a netCDF file in the XML format defined by the ISO 19115-3 international standard. The coverage values are not read, only the netCDF file header is read.
Direct dependencies Maven coordinates Module info Remarks org.apache.sis.storage:sis-netcdf org.apache.sis.storage.netcdf edu.ucar:cdm-core For netCDF-4 or HDF5 The cdm-core dependency can be omitted for netCDF-3 (a.k.a. &ldquo;classic&rdquo;), GeoTIFF or any other formats supported by Apache SIS.</description>
</item>
-
+
<item>
<title>Geographic bounding box of a data file</title>
<link>https://sis.apache.org/howto/geographic_bounding_box.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/geographic_bounding_box.html</guid>
<description>This example prints the bounding box of a GeoTIFF image. The pixel values are not read, only the GeoTIFF file header is read. If the file contains many images, the bounding box of each image is printed.
Direct dependencies Maven coordinates Module info Remarks org.apache.sis.storage:sis-geotiff org.apache.sis.storage.geotiff org.apache.sis.non-free:sis-embedded-data org.apache.sis.referencing.database Optional. Non-Apache license. The EPSG dependency may or may not be needed, depending how the Coordinate Reference System (CRS) is encoded in the GeoTIFF file.</description>
</item>
-
+
<item>
<title>Get raster values at geographic coordinates</title>
<link>https://sis.apache.org/howto/raster_values_at_geographic_coordinates.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/raster_values_at_geographic_coordinates.html</guid>
- <description>This example reads a netCDF file and fetches values at given coordinates. The coordinates can be expressed in different Coordinate Reference System (CRS). Conversions from geographic coordinates to pixel coordinates, followed by conversions from raster data to units of measurement, are done automatically. Raster rata and spatiotemporal coordinates can have more than two dimensions.
-This example uses data in netCDF format. A netCDF file can contain an arbitrary amount of variables.</description>
+ <description>This example fetches values at given geospatial coordinates in a raster. The coordinates can be expressed in different Coordinate Reference System (CRS). Conversions from geographic or projected coordinates to pixel coordinates, optionally followed by conversions from raster data to units of measurement, are done automatically. Raster data and spatiotemporal coordinates can have more than two dimensions.
+This example assumes a preloaded three-dimensional raster. For the loading part, see read from a netCDF file or read from a GeoTIFF file code examples.</description>
</item>
-
+
+ <item>
+ <title>Get raster values at pixel coordinates</title>
+ <link>https://sis.apache.org/howto/raster_values_at_pixel_coordinates.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/raster_values_at_pixel_coordinates.html</guid>
+ <description>This example fetches values at given pixel coordinates in a raster. This example assumes a preloaded three-dimensional raster. For the loading part, see read from a netCDF file or read from a GeoTIFF file code examples.
+Some file formats store values as integers for compactness reasons, but provide a transfer function for converting those integers to &ldquo;real world&rdquo; values. Apache SIS can provide either the original integers or the converted values, at user&rsquo;s choice.</description>
+ </item>
+
<item>
<title>Get the EPSG code or URN of an existing CRS</title>
<link>https://sis.apache.org/howto/lookup_crs_urn.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/lookup_crs_urn.html</guid>
<description>The identifier of a Coordinate Reference System (CRS) object can be obtained by the getIdentifiers() method, which usually return a collection of zero or one element. If the CRS has been created from a Well Known Text (WKT) parsing and the WKT ends with an AUTHORITY[&quot;EPSG&quot;, &quot;xxxx&quot;] (WKT version 1) or ID[&quot;EPSG&quot;, xxxx] (WKT version 2) element, then the identifier (an EPSG numerical code in this example) is the xxxx va [...]
</item>
-
+
<item>
<title>Handle rasters bigger than memory</title>
<link>https://sis.apache.org/howto/rasters_bigger_than_memory.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/rasters_bigger_than_memory.html</guid>
<description>This example opens a big GeoTIFF file without reading the tiles immediately. Instead, tiles will be read only when requested by a call to the Java2D RenderedImage.getTile(int, int) method. Loaded tiles are cached by soft references, i.e. they may be discarted and reloaded when needed again. This approach allows processing of raster data larger than memory, provided that the application does not request all tiles at once. It integrates well with operations provided by A [...]
</item>
-
+
<item>
<title>Instantiate a UTM projection</title>
<link>https://sis.apache.org/howto/instantiate_utm_projection.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/instantiate_utm_projection.html</guid>
<description>The Universal Transverse Mercator (UTM) projection divides the world in 60 zones. If the UTM zone is unknown, an easy way to instantiate the projection is to invoke the universal(…) method on one of the CommonCRS predefined constants. That method receives in argument a geographic coordinate in (latitude, longitude) order and computes the UTM zone from it. It takes in account the special cases of Norway and Svalbard.
An alternative, more standard, way using geographic coordinates is to format an &ldquo;AUTO&rdquo; authority code.</description>
</item>
-
+
+ <item>
+ <title>Read raster from a GeoTIFF file</title>
+ <link>https://sis.apache.org/howto/read_geotiff.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/read_geotiff.html</guid>
+ <description>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, GeoTiffStore does not implement directly GridCoverageResource. Instead, GeoTiffStore implements the Aggregate interface.
+This example assumes that the raster, optionally clipped to a subregion, can fit in memory. For potentially much bigger rasters, see rasters bigger than memory code example.
+Direct dependencies Maven coordinates Module info Remarks org.</description>
+ </item>
+
<item>
- <title>Resample a raster and write to a file</title>
- <link>https://sis.apache.org/howto/resample_and_save_raster.html</link>
+ <title>Read raster from a netCDF file</title>
+ <link>https://sis.apache.org/howto/read_netcdf.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>https://sis.apache.org/howto/resample_and_save_raster.html</guid>
- <description>This example reads a raster in a GeoTIFF file and reprojects it to a different Coordinate Reference System (CRS). The result is saved as a World File in PNG format.
-Direct dependencies Maven coordinates Module info Remarks org.apache.sis.storage:sis-geotiff org.apache.sis.storage.geotiff org.apache.sis.non-free:sis-embedded-data org.apache.sis.referencing.database Non-Apache license. The EPSG dependency is necessary for this example because a Coordinate Reference System (CRS) is instantiated from its EPSG code.</description>
+
+ <guid>https://sis.apache.org/howto/read_netcdf.html</guid>
+ <description>This example reads data in netCDF format. Contrarily to other formats such as PNG or JPEG, a netCDF file can contain an arbitrary number of variables with none of them identified as the main data. Furthermore those data are not necessarily rasters. For this reason, NetcdfStore does not implement directly GridCoverageResource. Instead, NetcdfStore implements the Aggregate interface and the desired variable must be specified. The variables may be instances of GridCoverag [...]
</item>
-
+
+ <item>
+ <title>Resample a raster</title>
+ <link>https://sis.apache.org/howto/resample_raster.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/resample_raster.html</guid>
+ <description>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 read from a netCDF file or read from a GeoTIFF file code examples.
+Direct dependencies Maven coordinates Module info Remarks org.apache.sis.code:sis-feature org.apache.sis.feature org.apache.sis.non-free:sis-embedded-data org.apache.sis.referencing.database Non-Apache license. The EPSG dependency is necessary for this example because a Coordinate Reference System (CRS) is instantiated from its EPSG code.</description>
+ </item>
+
<item>
<title>Transform coordinates</title>
<link>https://sis.apache.org/howto/transform_coordinates.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/transform_coordinates.html</guid>
<description>The following Java code projects geographic coordinates from the World Geodetic System 1984 (WGS84) to WGS 84 / UTM zone 33N. In order to make the example a little bit simpler, this code uses predefined constants given by the CommonCRS convenience class. But more advanced applications may use EPSG codes or definitions in Well-Known Text (WKT) instead.
Note: if the result of a coordinate transformation seems wrong, see the FAQ page.</description>
</item>
-
+
<item>
<title>Transform envelopes (bounding boxes)</title>
<link>https://sis.apache.org/howto/transform_envelopes.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/transform_envelopes.html</guid>
<description>The transformation of envelopes (or bounding boxes) is a much more difficult task than transforming the four corners of a rectangle. The rectangle straight lines in source CRS may become curves in the target CRS with minimum and maximum values that are not located in any corner. The calculation is also more complicated if the envelope contains a pole or crosses the anti-meridian. Apache SIS handles those complexities in convenience static methods.</description>
</item>
-
+
<item>
<title>Union or intersection of envelopes in different CRS</title>
<link>https://sis.apache.org/howto/envelopes_in_different_crs.html</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
+
<guid>https://sis.apache.org/howto/envelopes_in_different_crs.html</guid>
<description>Before to compute the union or intersection of two or more envelopes (bounding boxes), all envelopes must be transformed to the same Coordinate Reference System (CRS). But the choice of a common CRS is not easy. We must verify that all envelopes are inside the domain of validity of the common CRS, which may require to choose a common CRS different than the CRS of all envelopes. Apache SIS can handle this task automatically.</description>
</item>
-
+
+ <item>
+ <title>Write a raster to a file</title>
+ <link>https://sis.apache.org/howto/write_raster.html</link>
+ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+
+ <guid>https://sis.apache.org/howto/write_raster.html</guid>
+ <description>This example saves a raster in PNG format. This example assumes a preloaded raster. For the loading part, see read from a netCDF file or read from a GeoTIFF file code examples.
+Note: this example is incomplete. A more complete example will be provided with next Apache SIS release.
+Direct dependencies Maven coordinates Module info Remarks org.apache.sis.storage:sis-storage org.apache.sis.storage Code example The file name in following code need to be updated for yours data.</description>
+ </item>
+
</channel>
</rss>
diff --git a/howto/instantiate_utm_projection.html b/howto/instantiate_utm_projection.html
index 3cf1e732..3eaa0c5b 100644
--- a/howto/instantiate_utm_projection.html
+++ b/howto/instantiate_utm_projection.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Instantiate a UTM projection</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Instantiate a UTM projection</p>
-
+
<p>The Universal Transverse Mercator (UTM) projection divides the world in 60 zones.
If the UTM zone is unknown, an easy way to instantiate the projection
is to invoke the <code>universal(…)</code> method on one of the <code>CommonCRS</code> predefined constants.
diff --git a/howto/lookup_crs_urn.html b/howto/lookup_crs_urn.html
index 43060363..173d9e03 100644
--- a/howto/lookup_crs_urn.html
+++ b/howto/lookup_crs_urn.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Get the EPSG code or URN of an existing CRS</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Get the EPSG code or URN of an existing CRS</p>
-
+
<p>The <em>identifier</em> of a Coordinate Reference System (CRS) object can be obtained by the <code>getIdentifiers()</code> method,
which usually return a collection of zero or one element.
If the <abbr title="Coordinate Reference System">CRS</abbr> has been created from a Well Known Text (WKT) parsing
@@ -162,26 +162,26 @@ for finding its value.</p>
</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></span><span class="line"><span class="cl"> <span class="n">CoordinateReferenceSystem</span> <span class="n">crs</span> <span class="o">=</span> <span class="n">CRS</span><span class="o">.</span><span class="na">fromWKT</span><span class="o">(</span>
-</span></span><span class="line"><span class="cl"> <span class="s">"""
-</span></span></span><span class="line"><span class="cl"><span class="s"> PROJCRS["</span><span class="n">NTF</span> <span class="o">(</span><span class="n">Paris</span><span class="o">)</span> <span class="o">/</span> <span class="n">zone</span> <span class="n">to</span> <span class="n">be</span> <span class="n">discovered</span> <span class="n">by</span> <span class="n">the</span> <span class="n">demo</span><span class="s">",
-</span></span></span><span class="line"><span class="cl"><span class="s"> BASEGEODCRS["</span><span class="n">NTF</span> <span class="o">(</span><span class="n">Paris</span><span class="o">)</span><span class="s">",
-</span></span></span><span class="line"><span class="cl"><span class="s"> DATUM["</span><span class="n">Nouvelle</span> <span class="n">Triangulation</span> <span class="n">Francaise</span><span class="s">",
-</span></span></span><span class="line"><span class="cl"><span class="s"> ELLIPSOID["</span><span class="n">Clarke</span> <span class="nf">1880</span> <span class="o">(</span><span class="n">IGN</span><span class="o">)</span><span class="s">", 6378249.2, 293.4660212936269]],
-</span></span></span><span class="line"><span class="cl"><span class="s"> PRIMEM["</span><span class="n">Paris</span><span class="s">", 2.5969213],
-</span></span></span><span class="line"><span class="cl"><span class="s"> UNIT["</span><span class="n">grade</span><span class="s">", 0.015707963267948967]],
-</span></span></span><span class="line"><span class="cl"><span class="s"> CONVERSION["</span><span class="n">Lambert</span> <span class="n">zone</span> <span class="n">II</span><span class="s">",
-</span></span></span><span class="line"><span class="cl"><span class="s"> METHOD["</span><span class="n">Lambert</span> <span class="n">Conic</span> <span class="nf">Conformal</span> <span class="o">(</span><span class="n">1SP</span><span class="o">)</span><span class="s">"],
-</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">Latitude</span> <span class="n">of</span> <span class="n">natural</span> <span class="n">origin</span><span class="s">", 52.0],
-</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">Longitude</span> <span class="n">of</span> <span class="n">natural</span> <span class="n">origin</span><span class="s">", 0.0],
-</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">Scale</span> <span class="n">factor</span> <span class="n">at</span> <span class="n">natural</span> <span class="n">origin</span><span class="s">", 0.99987742],
-</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">False</span> <span class="n">easting</span><span class="s">", 600000.0],
-</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">False</span> <span class="n">northing</span><span class="s">", 2200000.0]],
-</span></span></span><span class="line"><span class="cl"><span class="s"> CS[Cartesian, 2],
-</span></span></span><span class="line"><span class="cl"><span class="s"> AXIS["</span><span class="n">Easting</span> <span class="o">(</span><span class="n">E</span><span class="o">)</span><span class="s">", east],
-</span></span></span><span class="line"><span class="cl"><span class="s"> AXIS["</span><span class="n">Northing</span> <span class="o">(</span><span class="n">N</span><span class="o">)</span><span class="s">", north],
-</span></span></span><span class="line"><span class="cl"><span class="s"> LENGTHUNIT["</span><span class="n">metre</span><span class="s">", 1],
-</span></span></span><span class="line"><span class="cl"><span class="s"> REMARK["</span><span class="n">EPSG</span><span class="o">:</span><span class="n">27572</span> <span class="n">identifier</span> <span class="n">intentionally</span> <span class="n">omitted</span><span class="o">.</span><span class="s">"]]
-</span></span></span><span class="line"><span class="cl"><span class="s"> """</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="s">"""
+</span></span></span><span class="line"><span class="cl"><span class="s"> PROJCRS["</span><span class="n">NTF</span> <span class="o">(</span><span class="n">Paris</span><span class="o">)</span> <span class="o">/</span> <span class="n">zone</span> <span class="n">to</span> <span class="n">be</span> <span class="n">discovered</span> <span class="n">by</span> <span class="n">the</span> <span class="n">demo</span><span class="s">",
+</span></span></span><span class="line"><span class="cl"><span class="s"> BASEGEODCRS["</span><span class="n">NTF</span> <span class="o">(</span><span class="n">Paris</span><span class="o">)</span><span class="s">",
+</span></span></span><span class="line"><span class="cl"><span class="s"> DATUM["</span><span class="n">Nouvelle</span> <span class="n">Triangulation</span> <span class="n">Francaise</span><span class="s">",
+</span></span></span><span class="line"><span class="cl"><span class="s"> ELLIPSOID["</span><span class="n">Clarke</span> <span class="nf">1880</span> <span class="o">(</span><span class="n">IGN</span><span class="o">)</span><span class="s">", 6378249.2, 293.4660212936269]],
+</span></span></span><span class="line"><span class="cl"><span class="s"> PRIMEM["</span><span class="n">Paris</span><span class="s">", 2.5969213],
+</span></span></span><span class="line"><span class="cl"><span class="s"> UNIT["</span><span class="n">grade</span><span class="s">", 0.015707963267948967]],
+</span></span></span><span class="line"><span class="cl"><span class="s"> CONVERSION["</span><span class="n">Lambert</span> <span class="n">zone</span> <span class="n">II</span><span class="s">",
+</span></span></span><span class="line"><span class="cl"><span class="s"> METHOD["</span><span class="n">Lambert</span> <span class="n">Conic</span> <span class="nf">Conformal</span> <span class="o">(</span><span class="n">1SP</span><span class="o">)</span><span class="s">"],
+</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">Latitude</span> <span class="n">of</span> <span class="n">natural</span> <span class="n">origin</span><span class="s">", 52.0],
+</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">Longitude</span> <span class="n">of</span> <span class="n">natural</span> <span class="n">origin</span><span class="s">", 0.0],
+</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">Scale</span> <span class="n">factor</span> <span class="n">at</span> <span class="n">natural</span> <span class="n">origin</span><span class="s">", 0.99987742],
+</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">False</span> <span class="n">easting</span><span class="s">", 600000.0],
+</span></span></span><span class="line"><span class="cl"><span class="s"> PARAMETER["</span><span class="n">False</span> <span class="n">northing</span><span class="s">", 2200000.0]],
+</span></span></span><span class="line"><span class="cl"><span class="s"> CS[Cartesian, 2],
+</span></span></span><span class="line"><span class="cl"><span class="s"> AXIS["</span><span class="n">Easting</span> <span class="o">(</span><span class="n">E</span><span class="o">)</span><span class="s">", east],
+</span></span></span><span class="line"><span class="cl"><span class="s"> AXIS["</span><span class="n">Northing</span> <span class="o">(</span><span class="n">N</span><span class="o">)</span><span class="s">", north],
+</span></span></span><span class="line"><span class="cl"><span class="s"> LENGTHUNIT["</span><span class="n">metre</span><span class="s">", 1],
+</span></span></span><span class="line"><span class="cl"><span class="s"> REMARK["</span><span class="n">EPSG</span><span class="o">:</span><span class="n">27572</span> <span class="n">identifier</span> <span class="n">intentionally</span> <span class="n">omitted</span><span class="o">.</span><span class="s">"]]
+</span></span></span><span class="line"><span class="cl"><span class="s"> """</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">println</span><span class="o">(</span><span class="s">"Identifier declared in the CRS: "</span>
</span></span><span class="line"><span class="cl"> <span class="o">+</span> <span class="n">IdentifiedObjects</span><span class="o">.</span><span class="na">getIdentifier</span><span class="o">(</span><span class="n">crs</span><span class="o">,</span> <span class="kc">null</span><span class="o">));</span>
diff --git a/howto/raster_values_at_geographic_coordinates.html b/howto/raster_values_at_geographic_coordinates.html
index e280b3d7..4be22063 100644
--- a/howto/raster_values_at_geographic_coordinates.html
+++ b/howto/raster_values_at_geographic_coordinates.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Get raster values at geographic coordinates</title>
<meta charset="utf-8">
@@ -104,22 +104,22 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Get raster values at geographic coordinates</p>
-
- <p>This example reads a netCDF file and fetches values at given coordinates.
+
+ <p>This example fetches values at given geospatial coordinates in a raster.
The coordinates can be expressed in different Coordinate Reference System (CRS).
-Conversions from geographic coordinates to pixel coordinates,
-followed by conversions from raster data to units of measurement,
+Conversions from geographic or projected coordinates to pixel coordinates,
+optionally followed by conversions from raster data to units of measurement,
are done automatically.
-Raster rata and spatiotemporal coordinates can have more than two dimensions.</p>
-<p>This example uses data in netCDF format.
-A netCDF file can contain an arbitrary amount of variables.
-For this reason, the data store implements the <code>Aggregate</code> interface
-and the desired variable must be specified.
-A similar code can be used for reading data in other
-formats supported by Apache <abbr title="Spatial Information System">SIS</abbr> such as GeoTIFF,
-but not all formats are aggregates.
-For some file formats, the data store implements directly
-the <code>GridCoverageResource</code> interface instead of <code>Aggregate</code>.</p>
+Raster data and spatiotemporal coordinates can have more than two dimensions.</p>
+<p>This example assumes a preloaded three-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 file formats store values as integers for compactness reasons,
+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>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -131,33 +131,16 @@ the <code>GridCoverageResource</code> interface instead of <code>Aggregate</code
</thead>
<tbody>
<tr>
-<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><code>org.apache.sis.code:sis-feature</code></td>
+<td><code>org.apache.sis.feature</code></td>
<td></td>
-<td>For netCDF-4 or HDF5</td>
</tr>
</tbody>
</table>
-<p>The <code>cdm-core</code> dependency can be omitted for netCDF-3 (a.k.a. “classic”),
-GeoTIFF or any other <a href="../formats.html">formats supported by Apache SIS</a>.
-For the dependencies required for reading GeoTIFF instead of netCDF files,
-see the <a href="rasters_bigger_than_memory.html">rasters bigger than memory</a> code example.</p>
<h1 id="code-example">Code example</h1>
-<p>The file name, resource name and geographic 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.Map</span><span class="o">;</span>
+<p>The geographic 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.util.Map</span><span class="o">;</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">javax.measure.Unit</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.geometry.GeneralDirectPosition</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>
@@ -168,122 +151,51 @@ in following code need to be updated for yours data.</p>
</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"> */</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.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)`.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">printComponents</span><span class="o">(</span><span class="n">store</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"> * The following code read fully the specified resource.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * For reading only a subset, or for handling data bigger
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * than memory, see "How to..." in Apache SIS web site.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">Resource</span> <span class="n">resource</span> <span class="o">=</span> <span class="n">store</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">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="o">((</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">resource</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"> * Switch to a view of the data in the units of measurement.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Then get the unit of measurement of the first band (0).
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * If no unit is specified, fallback on dimensionless unit.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">forConvertedValues</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="kt">int</span> <span class="n">band</span> <span class="o">=</span> <span class="n">0</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"> <span class="n">Unit</span><span class="o"><?></span> <span class="n">unit</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">getSampleDimensions</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="n">band</span><span class="o">).</span><span class="na">getUnits</span><span class="o">().</span><span class="na">orElse</span><span [...]
-</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Get raster values at geographic coordinates expressed in WGS84.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Coordinate values in this example are in (latitude, longitude) order.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Any compatible coordinate reference system (CRS) can be used below,
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Apache SIS will automatically transform to the CRS used by the raster.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * If the raster data are three-dimensional, a 3D CRS should be specified.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</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">println</span><span class="o">(</span><span class="s">"Evaluation at some (latitude, longitude) coordinates:"</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">GeneralDirectPosition</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">GridCoverage</span><span class="o">.</span><span class="na">Evaluator</span> <span class="n">eval</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">evaluator</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"> * If the data are three-dimensional but we still want to use two-dimensional
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * coordinates, we need to specify a default value for the temporal dimension.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This code set the default to slice 0 (the first slice) in dimension 2.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Omit this line if the data are two-dimensional or if `point` has a 3D CRS.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">eval</span><span class="o">.</span><span class="na">setDefaultSlice</span><span class="o">(</span><span class="n">Map</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">2</span><span class="o">,</span> <span class="n">0L</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"> * The same `Evaluator` can be reused as often as needed for evaluating
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * at many points.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">point</span><span class="o">.</span><span class="na">setCoordinate</span><span class="o">(</span><span class="n">40</span><span class="o">,</span> <span class="o">-</span><span class="n">10</span><span class="o">);</span> <span class="c1">// 40°N 10°W
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="kt">double</span><span class="o">[]</span> <span class="n">values</span> <span class="o">=</span> <span class="n">eval</span><span class="o">.</span><span class="na">apply</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">"- Value at %s is %g %s.%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">values</span><span class="o">[</span><span class="n">band</span><span class="o">],</span> <span class="n">unit</span><sp [...]
-</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"> <span class="n">point</span><span class="o">.</span><span class="na">setCoordinate</span><span class="o">(</span><span class="n">30</span><span class="o">,</span> <span class="o">-</span><span class="n">15</span><span class="o">);</span> <span class="c1">// 30°N 15°W
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">values</span> <span class="o">=</span> <span class="n">eval</span><span class="o">.</span><span class="na">apply</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">"- Value at %s is %g %s.%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">values</span><span class="o">[</span><span class="n">band</span><span class="o">],</span> <span class="n">unit</span><sp [...]
-</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="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">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="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Switch to a view of the data in the units of measurement.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Then get the unit of measurement of the first band (0).
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If no unit is specified, fallback on dimensionless unit.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">forConvertedValues</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="kt">int</span> <span class="n">band</span> <span class="o">=</span> <span class="n">0</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"> <span class="n">Unit</span><span class="o"><?></span> <span class="n">unit</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">getSampleDimensions</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="n">band</span><span class="o">).</span><span class="na">getUnits</span><span class="o">().</span><span class="na">orElse</span><span clas [...]
+</span></span><span class="line"><span class="cl"> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Get raster values at geographic coordinates expressed in WGS84.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Coordinate values in this example are in (latitude, longitude) order.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Any compatible coordinate reference system (CRS) can be used below,
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Apache SIS will automatically transform to the CRS used by the raster.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If the raster data are three-dimensional, a 3D CRS should be specified.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</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">println</span><span class="o">(</span><span class="s">"Evaluation at some (latitude, longitude) coordinates:"</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">GeneralDirectPosition</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">GridCoverage</span><span class="o">.</span><span class="na">Evaluator</span> <span class="n">eval</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">evaluator</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"> * If the data are three-dimensional but we still want to use two-dimensional
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * coordinates, we need to specify a default value for the temporal dimension.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * This code set the default to slice 0 (the first slice) in dimension 2.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Omit this line if the data are two-dimensional or if `point` has a 3D CRS.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">eval</span><span class="o">.</span><span class="na">setDefaultSlice</span><span class="o">(</span><span class="n">Map</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">2</span><span class="o">,</span> <span class="n">0L</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"> * The same `Evaluator` can be reused as often as needed for evaluating
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * at many points.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">point</span><span class="o">.</span><span class="na">setCoordinate</span><span class="o">(</span><span class="n">40</span><span class="o">,</span> <span class="o">-</span><span class="n">10</span><span class="o">);</span> <span class="c1">// 40°N 10°W
+</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="kt">double</span><span class="o">[]</span> <span class="n">values</span> <span class="o">=</span> <span class="n">eval</span><span class="o">.</span><span class="na">apply</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">"- Value at %s is %g %s.%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">values</span><span class="o">[</span><span class="n">band</span><span class="o">],</span> <span class="n">unit</span><span c [...]
</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"> * Lists the components found in the given data store.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * They are the values that can be given to {@link DataStore#findResource(String).
-</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 store the data store from which to get the components.
-</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">private</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">printComponents</span><span class="o">(</span><span class="n">DataStore</span> <span class="n">store</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">if</span> <span class="o">(</span><span class="n">store</span> <span class="k">instanceof</span> <span class="n">Aggregate</span> <span class="n">agg</span><span class="o">)</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">println</span><span class="o">(</span><span class="s">"Components found in the data store:"</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="k">for</span> <span class="o">(</span><span class="n">Resource</span> <span class="n">component</span> <span class="o">:</span> <span class="n">agg</span><span class="o">.</span><span class="na">components</span><span class="o">())</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="n">component</span><span class="o">.</span><span class="na">getIdentifier</span><span class="o">().</span><span class="na">ifPresent</span><span class="o">((</span><span class="n">id</span><span class="o">)</span> <span class="o">-></span> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class [...]
-</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 class="k">else</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">println</span><span class="o">(</span><span class="s">"The data store is not an aggregate."</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">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">();</span>
+</span></span><span class="line"><span class="cl"> <span class="n">point</span><span class="o">.</span><span class="na">setCoordinate</span><span class="o">(</span><span class="n">30</span><span class="o">,</span> <span class="o">-</span><span class="n">15</span><span class="o">);</span> <span class="c1">// 30°N 15°W
+</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">values</span> <span class="o">=</span> <span class="n">eval</span><span class="o">.</span><span class="na">apply</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">"- Value at %s is %g %s.%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">values</span><span class="o">[</span><span class="n">band</span><span class="o">],</span> <span class="n">unit</span><span c [...]
</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>Components found in the data store:
-- sea_surface_height_above_geoid
-- sea_water_velocity
-
-Information about the selected resource:
-Raster
- ├─Coverage domain
- │ ├─Grid extent
- │ │ ├─Column: [0 … 864] (865 cells)
- │ │ ├─Row: [0 … 1080] (1081 cells)
- │ │ └─Time: [0 … 95] (96 cells)
- │ ├─Geographic extent
- │ │ ├─Lower bound: 25°59′09″N 19°00′50″W 2022-05-16T00:00:00Z
- │ │ └─Upper bound: 56°00′50″N 05°00′50″E 2022-05-17T00:00:00Z
- │ ├─Envelope
- │ │ ├─Geodetic longitude: -19.01388888888889 … 5.013888888888888 ∆Lon = 0.02777778°
- │ │ ├─Geodetic latitude: 25.98611111111111 … 56.013888888888886 ∆Lat = 0.02777778°
- │ │ └─time: 634,392.0 … 634,416.0 ∆t = 0.25 h
- │ ├─Coordinate reference system
- │ │ └─time latitude longitude
- │ └─Conversion (origin in a cell center)
- │ └─┌ ┐
- │ │ 0.027777777777777776 0 0 -19.000 │
- │ │ 0 0.027777777777777776 0 26.000 │
- │ │ 0 0 0.25 634392.125 │
- │ │ 0 0 0 1 │
- │ └ ┘
- └─Sample dimensions
- └─┌────────────────────┬────────────────────────┬────────────────────┐
- │ Values │ Measures │ Name │
- ╞════════════════════╧════════════════════════╧════════════════════╡
- │ zos │
- ├────────────────────┬────────────────────────┬────────────────────┤
- │ -32,767 │ NaN #0 │ Fill value │
- │ [-10,000 … 10,000] │ [-10.0000 … 10.0000] m │ Sea surface height │
- └────────────────────┴────────────────────────┴────────────────────┘
-
-Evaluation at some (latitude, longitude) coordinates:
+<pre tabindex="0"><code>Evaluation at some (latitude, longitude) coordinates:
- Value at POINT(40 -10) is 0.188000 m.
- Value at POINT(30 -15) is 0.619000 m.
</code></pre>
diff --git a/howto/instantiate_utm_projection.html b/howto/raster_values_at_pixel_coordinates.html
similarity index 52%
copy from howto/instantiate_utm_projection.html
copy to howto/raster_values_at_pixel_coordinates.html
index 3cf1e732..eb60448d 100644
--- a/howto/instantiate_utm_projection.html
+++ b/howto/raster_values_at_pixel_coordinates.html
@@ -1,9 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<head>
+
-
- <title>Apache SIS - Instantiate a UTM projection</title>
+ <title>Apache SIS - Get raster values at pixel coordinates</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,29 +103,18 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Instantiate a UTM projection</p>
-
- <p>The Universal Transverse Mercator (UTM) projection divides the world in 60 zones.
-If the UTM zone is unknown, an easy way to instantiate the projection
-is to invoke the <code>universal(…)</code> method on one of the <code>CommonCRS</code> predefined constants.
-That method receives in argument a geographic coordinate in (<em>latitude</em>, <em>longitude</em>) order and computes the UTM zone from it.
-It takes in account the special cases of Norway and Svalbard.</p>
-<p>An alternative, more standard, way using geographic coordinates is to format an “AUTO” authority code.
-The syntax is <code>"AUTO2:42001,1,<longitude>,<latitude>"</code>.
-However this approach works only for the WGS84 datum.</p>
-<p>If the UTM zone is known, another way is to use the “EPSG” authority factory.
-The EPSG code of some UTM projections can be determined as below, where <em>zone</em> is a number from 1 to 60 inclusive (unless otherwise specified):</p>
-<ul>
-<li>WGS 84 (northern hemisphere): 32600 + <em>zone</em></li>
-<li>WGS 84 (southern hemisphere): 32700 + <em>zone</em></li>
-<li>WGS 72 (northern hemisphere): 32200 + <em>zone</em></li>
-<li>WGS 72 (southern hemisphere): 32300 + <em>zone</em></li>
-<li>NAD 83 (northern hemisphere): 26900 + <em>zone</em> (zone 1 to 23 only)</li>
-<li>NAD 27 (northern hemisphere): 26700 + <em>zone</em> (zone 1 to 22 only)</li>
-<li>See the EPSG dataset for additional UTM definitions
-(WGS 72BE, SIRGAS 2000, SIRGAS 1995, SAD 69, ETRS 89, <em>etc.</em>).</li>
-</ul>
-<p>The code example below instantiates the same <abbr title="Coordinate Reference System">CRS</abbr> using the three approaches.</p>
+ <p class="page-title">Get raster values at pixel coordinates</p>
+
+ <p>This example fetches values at given pixel coordinates in a raster.
+This example assumes a preloaded three-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 file formats store values as integers for compactness reasons,
+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>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -137,61 +126,78 @@ The EPSG code of some UTM projections can be determined as below, where <em>zone
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
-<td><code>org.apache.sis.referencing</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>
-</tr>
</tbody>
</table>
-<p>The <a href="../epsg.html">EPSG dependency</a> is optional for examples using the <code>CommonCRS</code> enumeration
-or the “AUTO” authority, but is required for examples using the “EPSG” authority.</p>
<h1 id="code-example">Code example</h1>
-<p>Note that all geographic coordinates below express latitude <em>before</em> longitude,
-except in “AUTO2” authority code.</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.opengis.referencing.crs.CoordinateReferenceSystem</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.referencing.CRS</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.util.Utilities</span><span class="o">;</span>
+<p>The pixel 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.awt.Point</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">javax.measure.Unit</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.GridExtent</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.PixelIterator</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.apache.sis.measure.Units</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">InstantiateUTM</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">RasterValuesAtPixelCoordinates</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"> */</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></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Get UTM projection for whatever zone is valid for 40°N 14°E.
+</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">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="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Switch to a view of the data in the units of measurement.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Then get the unit of measurement of the first band (0).
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If no unit is specified, fallback on dimensionless unit.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="kt">double</span> <span class="n">latitude</span> <span class="o">=</span> <span class="n">40</span><span class="o">;</span> <span class="c1">// Will determine the hemisphere.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="kt">double</span> <span class="n">longitude</span> <span class="o">=</span> <span class="n">14</span><span class="o">;</span> <span class="c1">// Will determine the UTM zone.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">CoordinateReferenceSystem</span> <span class="n">crsFromPoint</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">latitude</span><span class="o">,</span> <span class="n">longitude</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="n">CoordinateReferenceSystem</span> <span class="n">crsFromAUTO2</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">"AUTO2:42001,1,"</span> <span class="o">+</span> <span class="n">longitude</span> <span class="o">+</span> <span class="s">","</span> <span class="o">+</span> <span class="n">latitude</sp [...]
+</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">forConvertedValues</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="kt">int</span> <span class="n">band</span> <span class="o">=</span> <span class="n">0</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"> <span class="n">Unit</span><span class="o"><?></span> <span class="n">unit</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">getSampleDimensions</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="n">band</span><span class="o">).</span><span class="na">getUnits</span><span class="o">().</span><span class="na">orElse</span><span clas [...]
</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Get the UTM projection for a specific zone.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If the data are three-dimensional, we need to specify a two-dimensional slice
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * for the `RenderedImage`. Following code arbitrarily takes the first slice.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="kt">int</span> <span class="n">zone</span> <span class="o">=</span> <span class="n">33</span><span class="o">;</span> <span class="c1">// UTM zone 33.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="kt">int</span> <span class="n">code</span> <span class="o">=</span> <span class="n">32600</span> <span class="o">+</span> <span class="n">zone</span><span class="o">;</span> <span class="c1">// For WGS84 northern hemisphere
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">CoordinateReferenceSystem</span> <span class="n">crsFromCode</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:"</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">GridExtent</span> <span class="n">extent</span> <span class="o">=</span> <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">format</span><span class="o">(</span><span class="s">"Grid extent:%n%s%n"</span><span class="o">,</span> <span class="n">extent</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="k">if</span> <span class="o">(</span><span class="n">extent</span><span class="o">.</span><span class="na">getDimension</span><span class="o">()</span> <span class="o">></span> <span class="n">2</span><span class="o">)</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="kt">long</span> <span class="n">first</span> <span class="o">=</span> <span class="n">extent</span><span class="o">.</span><span class="na">getLow</span><span class="o">(</span><span class="n">2</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="n">extent</span> <span class="o">=</span> <span class="n">extent</span><span class="o">.</span><span class="na">withRange</span><span class="o">(</span><span class="n">2</span><span class="o">,</span> <span class="n">first</span><span class="o">,</span> <span class="n">first</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">RenderedImage</span> <span class="n">image</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">render</span><span class="o">(</span><span class="n">extent</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"> * Compare the results.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Prints the value at a few positions. For avoiding to flood the output stream,
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * this example prints a value only for the 3 first pixel, then an arbitrary pixel.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</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">println</span><span class="o">(</span><span class="s">"Are the CRS equivalent?"</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">println</span><span class="o">(</span><span class="s">"AUTO2: "</span> <span class="o">+</span> <span class="n">Utilities</span><span class="o">.</span><span class="na">equalsIgnoreMetadata</span><span class="o">(</span><span class="n">crsFromPoint</span><span class="o">,</span> <span class="n">crsFromAU [...]
-</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">println</span><span class="o">(</span><span class="s">"EPSG: "</span> <span class="o">+</span> <span class="n">Utilities</span><span class="o">.</span><span class="na">equalsIgnoreMetadata</span><span class="o">(</span><span class="n">crsFromPoint</span><span class="o">,</span> <span class="n">crsFromCo [...]
+</span></span><span class="line"><span class="cl"> <span class="kt">int</span> <span class="n">n</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">PixelIterator</span> <span class="n">pit</span> <span class="o">=</span> <span class="n">PixelIterator</span><span class="o">.</span><span class="na">create</span><span class="o">(</span><span class="n">image</span><span class="o">);</span>
+</span></span><span class="line"><span class="cl"> <span class="k">while</span> <span class="o">(</span><span class="n">pit</span><span class="o">.</span><span class="na">next</span><span class="o">())</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">Point</span> <span class="n">pos</span> <span class="o">=</span> <span class="n">pit</span><span class="o">.</span><span class="na">getPosition</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">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">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>
<h1 id="output">Output</h1>
-<pre tabindex="0"><code>Are the CRS equivalent?
-AUTO2: true
-EPSG: true
+<p>The output depends on the raster data and the locale.
+Below is an example:</p>
+<pre tabindex="0"><code>Grid extent:
+Column: [0 … 864] (865 cells)
+Row: [0 … 1080] (1081 cells)
+Time: [0 … 95] (96 cells)
+
+Value at (0,0) is NaN m.
+Value at (1,0) is NaN m.
+Value at (2,0) is NaN m.
+Value at (100,200) is 0.586000 m.
</code></pre>
</article>
diff --git a/howto/rasters_bigger_than_memory.html b/howto/rasters_bigger_than_memory.html
index 4aeeea55..eb032400 100644
--- a/howto/rasters_bigger_than_memory.html
+++ b/howto/rasters_bigger_than_memory.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Handle rasters bigger than memory</title>
<meta charset="utf-8">
@@ -104,14 +104,14 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Handle rasters bigger than memory</p>
-
+
<p>This example opens a big GeoTIFF file without reading the tiles immediately.
Instead, tiles will be read only when requested by a call to the Java2D <code>RenderedImage.getTile(int, int)</code> method.
Loaded tiles are cached by soft references, i.e. they may be discarted and reloaded when needed again.
This approach allows processing of raster data larger than memory,
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_and_save_raster.html">raster resampling</a> and
+<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 example in this page works with pixel coordinates.
For working with geographic coordinates, see
@@ -168,11 +168,6 @@ 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"> */</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">"TM250m.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="cm">/*
@@ -184,56 +179,49 @@ 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"> */</span>
</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">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"> * Get an arbitrary tile, then get an arbitrary sample value in an arbitrary band
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * (the blue channel) of that tile.
-</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">image</span> <span class="o">=</span> <span class="n">data</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="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 image has %d × %d tiles.%n"</span><span class="o">,</span> <span class="n">image</span><span class="o">.</span><span class="na">getNumXTiles</span><span class="o">(),</span> <span class="n">image</span><span class="o">.</span><span class="na"> [...]
+</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="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="n">Raster</span> <span class="n">tile</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="na">getTile</span><span class="o">(</span><span class="n">130</span><span class="o">,</span> <span class="n">80</span><span class="o">);</span> <span class="c1">// This is where tile loading actually happen.
-</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">"Got a tile starting at coordinates %d, %d.%n"</span><span class="o">,</span> <span class="n">tile</span><span class="o">.</span><span class="na">getMinX</span><span class="o">(),</span> <span class="n">tile</span><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">"A sample value in a tile: %d%n"</span><span class="o">,</span> <span class="n">tile</span><span class="o">.</span><span class="na">getSample</span><span class="o">(</span><span class="n">93710</span><span class="o">,</span> <span class="n">57680</ [...]
-</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * If we know in advance which tiles will be requested, specifying them in advance allows
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * the GeoTIFF reader to use a better strategy than loading the tiles in random order.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="cm">/**
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Prints the value of an arbitrary pixel.
+</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 data the data from which to get sample values.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @param prefetch whether to load some pixels in advance.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="kd">private</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">printPixelValue</span><span class="o">(</span><span class="n">GridCoverage</span> <span class="n">data</span><span class="o">,</span> <span class="kt">boolean</span> <span class="n">prefetch</span><span class="o">)</span> <span class="o">{</span>
+</span></span><span class="line"><span class="cl"> <span class="n">RenderedImage</span> <span class="n">image</span> <span class="o">=</span> <span class="n">data</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="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 image has %d × %d tiles.%n"</span><span class="o">,</span> <span class="n">image</span><span class="o">.</span><span class="na">getNumXTiles</span><span class="o">(),</span> <span class="n">image</span><span class="o">.</span><span class="na">getN [...]
+</span></span><span class="line"><span class="cl"> <span class="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * If we know in advance which tiles will be requested, specifying them in advance allows
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * the GeoTIFF reader to use a better strategy than loading the tiles in random order.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * This step is optional.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="k">if</span> <span class="o">(</span><span class="n">prefetch</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">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">image</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">image</span><span class="o">,</span> <span class="k">new</span> <span class="n">Rectangle</span><span class="o">(</span><span class="n">90000</span><span class="o">,</span> <span class="n">50000</span><span class="o">,</span> <span class="n">1000</ [...]
-</span></span><span class="line"><span class="cl"> <span class="n">tile</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="na">getTile</span><span class="o">(</span><span class="n">130</span><span class="o">,</span> <span class="n">80</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, but from prefetched image: %d%n%n"</span><span class="o">,</span> <span class="n">tile</span><span class="o">.</span><span class="na">getSample</span><span class="o">(</span><span class="n">93710</span><span class="o">,</span> <span class="n [...]
</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"> * Get an arbitrary tile, then get an arbitrary sample value in an arbitrary band (the blue channel).
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * This example handles the tiles directly for demonstration purposes, but it could be simplified
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * by using `PixelIterator` instead.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">Raster</span> <span class="n">tile</span> <span class="o">=</span> <span class="n">image</span><span class="o">.</span><span class="na">getTile</span><span class="o">(</span><span class="n">130</span><span class="o">,</span> <span class="n">80</span><span class="o">);</span> <span class="c1">// This is where tile loading actually happen.
+</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">"Got a tile starting at coordinates %d, %d.%n"</span><span class="o">,</span> <span class="n">tile</span><span class="o">.</span><span class="na">getMinX</span><span class="o">(),</span> <span class="n">tile</span><span c [...]
+</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">"A sample value in the arbitrary tile: %d%n"</span><span class="o">,</span> <span class="n">tile</span><span class="o">.</span><span class="na">getSample</span><span class="o">(</span><span class="n">93710</span><span class="o">,</span> <span class="n" [...]
</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 selected image:
-CompressedSubset
- └─Coverage domain
- ├─Grid extent
- │ ├─Column: [0 … 172799] (172800 cells)
- │ └─Row: [0 … 86399] (86400 cells)
- ├─Geographic extent
- │ ├─Lower bound: 90°00′00″S 180°00′00″W
- │ └─Upper bound: 90°00′00″N 180°00′00″E
- ├─Envelope
- │ ├─Geodetic longitude: -180.000 … 180.000 ∆Lon = 0.00208333°
- │ └─Geodetic latitude: -90.000 … 90.000 ∆Lat = 0.00208333°
- ├─Coordinate reference system
- │ └─CRS:84 — WGS 84
- └─Conversion (origin in a cell center)
- └─┌ ┐
- │ 0.0020833333333333333 0 -179.99895833333332 │
- │ 0 -0.0020833333333333333 89.99895833333333 │
- │ 0 0 1 │
- └ ┘
-
-The image has 240 × 120 tiles.
+<pre tabindex="0"><code>The image has 240 × 120 tiles.
Got a tile starting at coordinates 93600, 57600.
-A sample value in a tile: 20
-Same, but from prefetched image: 20
+A sample value in the arbitrary tile: 20
+</code></pre><p>If logging at fine level is enabled, the logs should contain an entry likes below.
+The interesting point is that the “loading” of the TIFF file was quick even if the file was very big.
+This is because the loading did not really happens at that time,
+but instead was deferred at <code>image.getTile(…)</code> or <code>processor.prefetch(…)</code> time.</p>
+<pre tabindex="0"><code>FINE [GridCoverageResource] Loaded grid coverage between 90°S – 90°N and 180°W – 180°E from file “TM250m.tiff” in 0.779 seconds.
</code></pre>
</article>
diff --git a/howto/resample_and_save_raster.html b/howto/read_geotiff.html
similarity index 69%
rename from howto/resample_and_save_raster.html
rename to howto/read_geotiff.html
index b3cd378f..dcaead8d 100644
--- a/howto/resample_and_save_raster.html
+++ b/howto/read_geotiff.html
@@ -1,9 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<head>
+
-
- <title>Apache SIS - Resample a raster and write to a file</title>
+ <title>Apache SIS - Read raster from a GeoTIFF file</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,11 +103,16 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Resample a raster and write to a file</p>
-
- <p>This example reads a raster in a GeoTIFF file
-and reprojects it to a different Coordinate Reference System (CRS).
-The result is saved as a World File in PNG format.</p>
+ <p class="page-title">Read raster from a GeoTIFF file</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>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -126,21 +131,16 @@ The result is saved as a World File in PNG format.</p>
<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>
+<td>Optional. 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>
+<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>
<h1 id="code-example">Code example</h1>
-<p>The file name in following code need to be updated for yours data.</p>
+<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.io.IOException</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">java.nio.file.Paths</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">javax.imageio.ImageIO</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>
@@ -149,24 +149,21 @@ for example using Well Known Text (WKT) format.</p>
</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.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.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></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ResampleAndSaveRaster</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">ReadGeoTIFF</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 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 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 class="n">FactoryException</span><span class="o">,</span> <span class="n">TransformEx [...]
-</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="n">Paths</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"Airport.tiff"</span><span class="o">)))</span> <span class= [...]
+</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.
@@ -175,35 +172,33 @@ for example using Well Known Text (WKT) format.</p>
</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="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * The following code read fully the specified resource.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * For reading only a subset, or for handling data bigger
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * than memory, see "How to..." in Apache SIS web site.
+</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">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"> * 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"> * 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"> */</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></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * TODO: Apache SIS is missing a `DataStores.write(…)` convenience method.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Writing a TIFF World File is possible but requires use of internal API.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * A public convenience method will be added in next version.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * For now we use Java I/O API.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">ImageIO</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="n">data</span><span class="o">.</span><span class="na">render</span><span class="o">(</span><span class="kc">null</span><span class="o">),</span> <span class="s">"png"</span><span class="o">,</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"test [...]
+</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="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>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.
Below is an example:</p>
-<pre tabindex="0"><code>Information about the image after reprojection:
+<pre tabindex="0"><code>Information about the selected image:
GridCoverage2D
├─Coverage domain
│ ├─Grid extent
@@ -229,31 +224,9 @@ GridCoverage2D
├─Data type: byte
└─Image is opaque.
-Information about the image after reprojection:
-GridCoverage2D
- ├─Coverage domain
- │ ├─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 │
- │ └ ┘
- └─Image layout
- ├─Origin: 0, 0
- ├─Tile size: 1,648 × 201
- ├─Data type: byte
- └─Image is opaque.
+Information about the resource subset:
+Column: [ 0 … 4145] (4146 cells)
+Row: [3968 … 6655] (2688 cells)
</code></pre>
</article>
diff --git a/howto/raster_values_at_geographic_coordinates.html b/howto/read_netcdf.html
similarity index 65%
copy from howto/raster_values_at_geographic_coordinates.html
copy to howto/read_netcdf.html
index e280b3d7..78617a90 100644
--- a/howto/raster_values_at_geographic_coordinates.html
+++ b/howto/read_netcdf.html
@@ -1,9 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<head>
+
-
- <title>Apache SIS - Get raster values at geographic coordinates</title>
+ <title>Apache SIS - Read raster from a netCDF file</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,23 +103,17 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Get raster values at geographic coordinates</p>
-
- <p>This example reads a netCDF file and fetches values at given coordinates.
-The coordinates can be expressed in different Coordinate Reference System (CRS).
-Conversions from geographic coordinates to pixel coordinates,
-followed by conversions from raster data to units of measurement,
-are done automatically.
-Raster rata and spatiotemporal coordinates can have more than two dimensions.</p>
-<p>This example uses data in netCDF format.
-A netCDF file can contain an arbitrary amount of variables.
-For this reason, the data store implements the <code>Aggregate</code> interface
+ <p class="page-title">Read raster from a netCDF file</p>
+
+ <p>This example reads data in netCDF format.
+Contrarily to other formats such as PNG or JPEG,
+a netCDF file can contain an arbitrary number of variables
+with none of them identified as the main data.
+Furthermore those data are not necessarily rasters.
+For this reason, <code>NetcdfStore</code> does not implement directly <code>GridCoverageResource</code>.
+Instead, <code>NetcdfStore</code> implements the <code>Aggregate</code> interface
and the desired variable must be specified.
-A similar code can be used for reading data in other
-formats supported by Apache <abbr title="Spatial Information System">SIS</abbr> such as GeoTIFF,
-but not all formats are aggregates.
-For some file formats, the data store implements directly
-the <code>GridCoverageResource</code> interface instead of <code>Aggregate</code>.</p>
+The variables may be instances of <code>GridCoverageResource</code>, but not necessarily.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -142,16 +136,11 @@ the <code>GridCoverageResource</code> interface instead of <code>Aggregate</code
</tr>
</tbody>
</table>
-<p>The <code>cdm-core</code> dependency can be omitted for netCDF-3 (a.k.a. “classic”),
-GeoTIFF or any other <a href="../formats.html">formats supported by Apache SIS</a>.
-For the dependencies required for reading GeoTIFF instead of netCDF files,
-see the <a href="rasters_bigger_than_memory.html">rasters bigger than memory</a> code example.</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, resource name and geographic 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.Map</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">javax.measure.Unit</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>
@@ -159,11 +148,12 @@ in following code need to be updated for yours data.</p>
</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.geometry.GeneralDirectPosition</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.measure.Units</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">RasterValuesAtGeographicCoordinates</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">ReadNetCDF</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"> *
@@ -171,56 +161,32 @@ 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.nc"</span><span class="o">)))</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="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)`.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * For this example we use a hard-coded variable name.
</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="n">printComponents</span><span class="o">(</span><span class="n">store</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"> * The following code read fully the specified resource.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * For reading only a subset, or for handling data bigger
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * than memory, see "How to..." in Apache SIS web site.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
</span></span><span class="line"><span class="cl"> <span class="n">Resource</span> <span class="n">resource</span> <span class="o">=</span> <span class="n">store</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">GridCoverage</span> <span class="n">data</span> <span class="o">=</span> <span class="o">((</span><span class="n">GridCoverageResource</span><span class="o">)</span> <span class="n">resource</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"> * Switch to a view of the data in the units of measurement.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Then get the unit of measurement of the first band (0).
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * If no unit is specified, fallback on dimensionless unit.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">data</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">forConvertedValues</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
-</span></span><span class="line"><span class="cl"> <span class="kt">int</span> <span class="n">band</span> <span class="o">=</span> <span class="n">0</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"> <span class="n">Unit</span><span class="o"><?></span> <span class="n">unit</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">getSampleDimensions</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="n">band</span><span class="o">).</span><span class="na">getUnits</span><span class="o">().</span><span class="na">orElse</span><span [...]
-</span></span><span class="line"><span class="cl"> <span class="cm">/*
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Get raster values at geographic coordinates expressed in WGS84.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Coordinate values in this example are in (latitude, longitude) order.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Any compatible coordinate reference system (CRS) can be used below,
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Apache SIS will automatically transform to the CRS used by the raster.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * If the raster data are three-dimensional, a 3D CRS should be specified.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</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">println</span><span class="o">(</span><span class="s">"Evaluation at some (latitude, longitude) coordinates:"</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">GeneralDirectPosition</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">GridCoverage</span><span class="o">.</span><span class="na">Evaluator</span> <span class="n">eval</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="na">evaluator</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"> * If the data are three-dimensional but we still want to use two-dimensional
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * coordinates, we need to specify a default value for the temporal dimension.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * This code set the default to slice 0 (the first slice) in dimension 2.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * Omit this line if the data are two-dimensional or if `point` has a 3D CRS.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">eval</span><span class="o">.</span><span class="na">setDefaultSlice</span><span class="o">(</span><span class="n">Map</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">2</span><span class="o">,</span> <span class="n">0L</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"> * The same `Evaluator` can be reused as often as needed for evaluating
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * at many points.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
-</span></span><span class="line"><span class="cl"> <span class="n">point</span><span class="o">.</span><span class="na">setCoordinate</span><span class="o">(</span><span class="n">40</span><span class="o">,</span> <span class="o">-</span><span class="n">10</span><span class="o">);</span> <span class="c1">// 40°N 10°W
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="kt">double</span><span class="o">[]</span> <span class="n">values</span> <span class="o">=</span> <span class="n">eval</span><span class="o">.</span><span class="na">apply</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">"- Value at %s is %g %s.%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">values</span><span class="o">[</span><span class="n">band</span><span class="o">],</span> <span class="n">unit</span><sp [...]
-</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"> <span class="n">point</span><span class="o">.</span><span class="na">setCoordinate</span><span class="o">(</span><span class="n">30</span><span class="o">,</span> <span class="o">-</span><span class="n">15</span><span class="o">);</span> <span class="c1">// 30°N 15°W
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">values</span> <span class="o">=</span> <span class="n">eval</span><span class="o">.</span><span class="na">apply</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">"- Value at %s is %g %s.%n"</span><span class="o">,</span> <span class="n">point</span><span class="o">,</span> <span class="n">values</span><span class="o">[</span><span class="n">band</span><span class="o">],</span> <span class="n">unit</span><sp [...]
+</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"> */</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">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
+</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"> */</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">geographic</span><span class="o">());</span>
+</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">30</span><span class="o">,</span> <span class="n">40</span><span class="o">);</span> <span class="c1">// Minimal and maximal latitude values.
+</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="o">-</span><span class="n">5</span><span class="o">,</span> <span class="n">4</span><span class="o">);</span> <span class="c1">// Minimal and maximal longitude values.
+</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></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">
@@ -244,7 +210,11 @@ in following code need to be updated for yours data.</p>
</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>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 25°N – 57°N and 19°W – 6°E from file “CMEMS.nc” in 1.03 seconds.
+FINE [GridCoverageResource] Loaded grid coverage between 29°N – 41°N and 5°W – 5°E from file “CMEMS.nc” in 0.246 seconds.
+</code></pre><p>The output depends on the raster data and the locale.
Below is an example:</p>
<pre tabindex="0"><code>Components found in the data store:
- sea_surface_height_above_geoid
@@ -283,9 +253,10 @@ Raster
│ [-10,000 … 10,000] │ [-10.0000 … 10.0000] m │ Sea surface height │
└────────────────────┴────────────────────────┴────────────────────┘
-Evaluation at some (latitude, longitude) coordinates:
-- Value at POINT(40 -10) is 0.188000 m.
-- Value at POINT(30 -15) is 0.619000 m.
+Information about the resource subset:
+Column: [504 … 828] (325 cellules)
+Row: [144 … 504] (361 cellules)
+Time: [ 0 … 95] (96 cellules)
</code></pre>
</article>
diff --git a/howto/transform_coordinates.html b/howto/resample_raster.html
similarity index 64%
copy from howto/transform_coordinates.html
copy to howto/resample_raster.html
index 442ef1e3..9af7c301 100644
--- a/howto/transform_coordinates.html
+++ b/howto/resample_raster.html
@@ -1,9 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<head>
+
-
- <title>Apache SIS - Transform coordinates</title>
+ <title>Apache SIS - Resample a raster</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,13 +103,14 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Transform coordinates</p>
-
- <p>The following Java code projects geographic coordinates from the <em>World Geodetic System 1984</em> (WGS84) to <em>WGS 84 / UTM zone 33N</em>.
-In order to make the example a little bit simpler, this code uses predefined constants given by the <code>CommonCRS</code> convenience class.
-But more advanced applications may use <a href="../epsg.html">EPSG codes</a> or definitions in Well-Known Text (WKT) instead.</p>
-<p><strong>Note:</strong> if the result of a coordinate transformation seems wrong, see the <a href="../faq.html">FAQ</a> page.
-Unexpected results are often caused by wrong axis order.</p>
+ <p class="page-title">Resample a raster</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>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -121,72 +122,96 @@ Unexpected results are often caused by wrong axis order.</p>
</thead>
<tbody>
<tr>
-<td><code>org.apache.sis.storage:sis-referencing</code></td>
-<td><code>org.apache.sis.referencing</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>Non-Apache license.</td>
</tr>
</tbody>
</table>
-<p>The <a href="../epsg.html">EPSG dependency</a> is optional for this example.
-But if present, the Coordinate Reference Systems will have more metadata.
-Consequently, coordinate transformation results between some pairs of reference systems
-may be different depending on whether the EPSG dataset is present or not.
-In general, results are more accurate and/or more reliable in presence of EPSG dataset.</p>
+<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>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.opengis.geometry.DirectPosition</span><span class="o">;</span>
-</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">org.opengis.referencing.crs.CoordinateReferenceSystem</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.CoordinateOperation</span><span class="o">;</span>
+<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>
-</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.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.geometry.DirectPosition2D</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">TransformCoordinates</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">ResampleRaster</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">CoordinateReferenceSystem</span> <span class="n">sourceCRS</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">CoordinateReferenceSystem</span> <span class="n">targetCRS</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">40</span><span class="o">,</span> <span class="n">14</span><span class="o">);</span> <span class="c1">// UTM zone for 40°N 14°E.
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">CoordinateOperation</span> <span class="n">operation</span> <span class="o">=</span> <span class="n">CRS</span><span class="o">.</span><span class="na">findOperation</span><span class="o">(</span><span class="n">sourceCRS</span><span class="o">,</span> <span class="n">targetCRS</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">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"> * The above lines are costly and should be performed only once before to project many points.
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * In this example, the operation that we got is valid for coordinates in geographic area from
-</span></span></span><span class="line"><span class="cl"><span class="cm"> * 12°E to 18°E (UTM zone 33) and 0°N to 84°N.
+</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">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Domain of validity:"</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">println</span><span class="o">(</span><span class="n">CRS</span><span class="o">.</span><span class="na">getGeographicBoundingBox</span><span class="o">(</span><span class="n">operation</span><span class="o">));</span>
-</span></span><span class="line"><span class="cl">
-</span></span><span class="line"><span class="cl"> <span class="n">DirectPosition</span> <span class="n">ptSrc</span> <span class="o">=</span> <span class="k">new</span> <span class="n">DirectPosition2D</span><span class="o">(</span><span class="n">40</span><span class="o">,</span> <span class="n">14</span><span class="o">);</span> <span class="c1">// 40°N 14°E
-</span></span></span><span class="line"><span class="cl"><span class="c1"></span> <span class="n">DirectPosition</span> <span class="n">ptDst</span> <span class="o">=</span> <span class="n">operation</span><span class="o">.</span><span class="na">getMathTransform</span><span class="o">().</span><span class="na">transform</span><span class="o">(</span><span class="n">ptSrc</span><span class="o">,</span> <span class="kc">null</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">println</span><span class="o">(</span><span class="s">"Source: "</span> <span class="o">+</span> <span class="n">ptSrc</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">println</span><span class="o">(</span><span class="s">"Target: "</span> <span class="o">+</span> <span class="n">ptDst</span><span class="o">);</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>Note: for some pairs of Coordinate Reference Systems,
-the output may vary depending on whether the <a href="../epsg.html">EPSG geodetic dataset</a> is present or not.</p>
-<pre tabindex="0"><code>Domain of validity:
-Geographic bounding box
- ├─West bound longitude…… 12°E
- ├─East bound longitude…… 18°E
- ├─South bound latitude…… 0°N
- └─North bound latitude…… 84°N
+<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 │
+ └ ┘
-Source: POINT(40 14)
-Target: POINT(414639.5381572213 4428236.064633072)
+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>
diff --git a/howto/transform_coordinates.html b/howto/transform_coordinates.html
index 442ef1e3..2a8a053d 100644
--- a/howto/transform_coordinates.html
+++ b/howto/transform_coordinates.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Transform coordinates</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Transform coordinates</p>
-
+
<p>The following Java code projects geographic coordinates from the <em>World Geodetic System 1984</em> (WGS84) to <em>WGS 84 / UTM zone 33N</em>.
In order to make the example a little bit simpler, this code uses predefined constants given by the <code>CommonCRS</code> convenience class.
But more advanced applications may use <a href="../epsg.html">EPSG codes</a> or definitions in Well-Known Text (WKT) instead.</p>
diff --git a/howto/transform_envelopes.html b/howto/transform_envelopes.html
index 6e73a66f..d0d22b59 100644
--- a/howto/transform_envelopes.html
+++ b/howto/transform_envelopes.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html lang="en">
<head>
-
+
<title>Apache SIS - Transform envelopes (bounding boxes)</title>
<meta charset="utf-8">
@@ -104,7 +104,7 @@
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
<p class="page-title">Transform envelopes (bounding boxes)</p>
-
+
<p>The transformation of envelopes (or bounding boxes) is a much more difficult task
than transforming the four corners of a rectangle.
The rectangle straight lines in source <abbr title="Coordinate Reference System">CRS</abbr> may become curves in the target <abbr title="Coordinate Reference System">CRS</abbr>
diff --git a/howto/geographic_bounding_box.html b/howto/write_raster.html
similarity index 62%
copy from howto/geographic_bounding_box.html
copy to howto/write_raster.html
index 278b84bd..f483e307 100644
--- a/howto/geographic_bounding_box.html
+++ b/howto/write_raster.html
@@ -1,9 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<head>
+
-
- <title>Apache SIS - Geographic bounding box of a data file</title>
+ <title>Apache SIS - Write a raster to a file</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,11 +103,16 @@
<main class="container">
<article>
<img src="../images/logo.png" class="sis-logo" align="left"/>
- <p class="page-title">Geographic bounding box of a data file</p>
-
- <p>This example prints the bounding box of a GeoTIFF image.
-The pixel values are not read, only the GeoTIFF file header is read.
-If the file contains many images, the bounding box of each image is printed.</p>
+ <p class="page-title">Write a raster to a file</p>
+
+ <p>This example saves a raster in PNG format.
+This example assumes a preloaded 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>Note: this example is incomplete.
+A more complete example will be provided with next Apache SIS release.</p>
<h1 id="direct-dependencies">Direct dependencies</h1>
<table>
<thead>
@@ -119,68 +124,38 @@ If the file contains many images, the bounding box of each image is printed.</p>
</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.storage:sis-storage</code></td>
+<td><code>org.apache.sis.storage</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>
-</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>
<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.io.File</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.metadata.iso.extent.Extents</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">java.io.IOException</span><span class="o">;</span>
+</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">javax.imageio.ImageIO</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></span><span class="line"><span class="cl"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">GetBBOX</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">WriteRaster</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 data file.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * @throws IOException if an error occurred while writing 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">"Airport.tiff"</span><span class="o">)))</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">println</span><span class="o">(</span><span class="s">"For the whole file"</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">println</span><span class="o">(</span><span class="n">Extents</span><span class="o">.</span><span class="na">getGeographicBoundingBox</span><span class="o">(</span><span class="n">store</span><span class="o">.</span><span class="na">getMetadata</span><span class="o">()));</span>
-</span></span><span class="line"><span class="cl"> <span class="k">if</span> <span class="o">(</span><span class="n">store</span> <span class="k">instanceof</span> <span class="n">Aggregate</span> <span class="n">agg</span><span class="o">)</span> <span class="o">{</span>
-</span></span><span class="line"><span class="cl"> <span class="k">for</span> <span class="o">(</span><span class="n">Resource</span> <span class="n">component</span> <span class="o">:</span> <span class="n">agg</span><span class="o">.</span><span class="na">components</span><span class="o">())</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">println</span><span class="o">(</span><span class="s">"For component "</span> <span class="o">+</span> <span class="n">component</span><span class="o">.</span><span class="na">getIdentifier</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">println</span><span class="o">(</span><span class="n">Extents</span><span class="o">.</span><span class="na">getGeographicBoundingBox</span><span class="o">(</span><span class="n">component</span><span class="o">.</span><span class="na">getMetadata</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><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">IOException</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="cm">/*
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * TODO: Apache SIS is missing a `DataStores.write(…)` convenience method.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * Writing a TIFF World File is possible but requires use of internal API.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * A public convenience method will be added in next version.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> * For now we use Java I/O API.
+</span></span></span><span class="line"><span class="cl"><span class="cm"> */</span>
+</span></span><span class="line"><span class="cl"> <span class="n">ImageIO</span><span class="o">.</span><span class="na">write</span><span class="o">(</span><span class="n">data</span><span class="o">.</span><span class="na">render</span><span class="o">(</span><span class="kc">null</span><span class="o">),</span> <span class="s">"png"</span><span class="o">,</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"test.png [...]
</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 data and the locale.
-Below is an example:</p>
-<pre tabindex="0"><code>For the whole file
-Geographic bounding box
- ├─West bound longitude…… 2°31′33.51153867218″E
- ├─East bound longitude…… 2°34′15.75923342244″E
- ├─South bound latitude…… 48°59′20.7793385101″N
- ├─North bound latitude…… 49°01′07.5236778991″N
- └─Extent type code……………… True
-For component Optional[Airport:1]
-Geographic bounding box
- ├─West bound longitude…… 2°31′33.51153867218″E
- ├─East bound longitude…… 2°34′15.75923342244″E
- ├─South bound latitude…… 48°59′20.7793385101″N
- ├─North bound latitude…… 49°01′07.5236778991″N
- └─Extent type code……………… True
-</code></pre>
</article>
</main>