This is an automated email from the ASF dual-hosted git repository. desruisseaux pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit 38f76152abf38271575891a3680376a7c4748a1b Author: Martin Desruisseaux <[email protected]> AuthorDate: Sat May 7 15:47:29 2022 +0200 Remove warning about bug in URL for downloading EPSG data and add a list of supported formats. --- layouts/_default/baseof.html | 1 + layouts/partials/menu.html | 1 + layouts/shortcodes/CSV.html | 1 + layouts/shortcodes/GPX.html | 1 + source/code-patterns.md | 24 ++++++++--- source/command-line.md | 22 +--------- source/formats.md | 100 +++++++++++++++++++++++++++++++++++++++++++ source/javafx.md | 57 ++++++++++++------------ 8 files changed, 153 insertions(+), 54 deletions(-) diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html index 740cafe6..c9c1b1b1 100644 --- a/layouts/_default/baseof.html +++ b/layouts/_default/baseof.html @@ -36,6 +36,7 @@ <ul class="nav nav-pills flex-column mb-auto position-fixed"> <li><a class="nav-link {{ if eq .Page.RelPermalink "/" }} active {{ else }} text-white {{ end }}" href="/index.html">Home</a></li> <li><a class="nav-link {{ if eq .Page.RelPermalink "/standards.html" }} active {{ else }} text-white {{ end }}" href="standards.html">Standards</a></li> + <li><a class="nav-link {{ if eq .Page.RelPermalink "/formats.html" }} active {{ else }} text-white {{ end }}" href="formats.html">Formats</a></li> <li><a class="nav-link text-white" href="http://www.apache.org/licenses/";>License</a></li> <li><a class="nav-link {{ if eq .Page.RelPermalink "/javafx.html" }} active {{ else }} text-white {{ end }}" href="javafx.html">Application (demo)</a></li> <li><a class="nav-link {{ if eq .Page.RelPermalink "/downloads.html" }} active {{ else }} text-white {{ end }}" href="downloads.html">Downloads</a></li> diff --git a/layouts/partials/menu.html b/layouts/partials/menu.html index 7e844450..443b3bc7 100644 --- a/layouts/partials/menu.html +++ b/layouts/partials/menu.html @@ -24,6 +24,7 @@ <ul class="dropdown-menu" aria-labelledby="menuDocumentation"> <li><a class="dropdown-item" href="apidocs/index.html">Online Javadoc</a></li> <li><a class="dropdown-item" href="book/en/developer-guide.html">Developer Guide</a></li> + <li><a class="dropdown-item" href="formats.html">Supported formats</a></li> <li><a class="dropdown-item" href="tables/CoordinateReferenceSystems.html">Supported CRS</a></li> <li><a class="dropdown-item" href="tables/CoordinateOperationMethods.html">Map Projections</a></li> <li><a class="dropdown-item" href="code-patterns.html">Code Patterns</a></li> diff --git a/layouts/shortcodes/CSV.html b/layouts/shortcodes/CSV.html new file mode 100644 index 00000000..c633a1e6 --- /dev/null +++ b/layouts/shortcodes/CSV.html @@ -0,0 +1 @@ +<abbr title="Comma Separated Values">CSV</abbr> \ No newline at end of file diff --git a/layouts/shortcodes/GPX.html b/layouts/shortcodes/GPX.html new file mode 100644 index 00000000..1ec7a328 --- /dev/null +++ b/layouts/shortcodes/GPX.html @@ -0,0 +1 @@ +<abbr title="GPS Exchange Format">GPX</abbr> \ No newline at end of file diff --git a/source/code-patterns.md b/source/code-patterns.md index ebe649d5..266ac9b8 100644 --- a/source/code-patterns.md +++ b/source/code-patterns.md @@ -8,7 +8,7 @@ This page lists some recommended code pattern for developing or using Apache {{% # Referencing {#referencing} -Recommended code pattern when using the `sis-referencing` module. +This section lists recommended code pattern when using the `sis-referencing` module. ## Never explicitely swap coordinates for axis order {#axisOrder} @@ -21,9 +21,9 @@ Instead of patching the coordinate values, try to make sure that the _Source CRS and the _Target CRS_ (the coordinate space where to perform the work) are properly defined, and let the referencing engine performs the conversion from the source to the target {{% CRS %}}. -# Coverages {#coverage} +# Rasters and coverages {#coverage} -Recommended code pattern when using the `sis-coverage` module. +This section lists recommended code pattern when using the `sis-coverage` module. ## Georeference images with affine transforms, _not_ bounding boxes {#gridToCRS} @@ -34,9 +34,18 @@ All images in SIS shall be georeferenced by at least an affine transform (more c never by a rectangle or bounding box. In the two-dimensional case, the standard `java.awt.geom.AffineTransform` class can be used. +## Do not cast `Raster` to `WritableRaster` + +Some images are writable. But modifying pixel values should be done by invoking the +`getWritableTile(…)` and `releaseWritableTile(…)` methods of `WritableRenderedImage` interface. +Do not cast directly a `Raster` to `WritableRaster` even when the cast is safe, +because some raster data may be shared by many tiles having identical content. +Furthermore changes in pixel values may be lost if {@code releaseWritableTile(…)} is not invoked. + + # International {#international} -Recommended code pattern for internationalization. +This section lists recommended code pattern for internationalization. ## Specify timezone {#timezone} @@ -77,8 +86,11 @@ for (int i=0; i<string.length();) { # Logging {#logging} -Apache {{% SIS %}} uses the `java.util.logging` framework, but with a [mechanism allowing users to redirect -to another framework](http://sis.apache.org/apidocs/org/apache/sis/util/logging/LoggerFactory.html). +Apache {{% SIS %}} uses the `java.util.logging` framework. +It does not necessarily means that all SIS users are forced to use this framework, +as it is possible to use `java.util.logging` as an API and have logging redirected to another system. +For example the logging can be redirect to SLF4J by adding the `jul-to-slf4j` dependency to a project. + The logger names are usually the package name of the class emitting log messages, but not necessarily. In particular, we do not follow this convention if the class is located in an internal package (`org.apache.sis.internal.*`) since those packages are considered privates. diff --git a/source/command-line.md b/source/command-line.md index 3c35568f..33b5203c 100644 --- a/source/command-line.md +++ b/source/command-line.md @@ -144,30 +144,10 @@ sis crs EPSG:6676 <br/> The first time that a command requires the EPSG dataset, Apache {{% SIS %}} will propose to download and install a local copy. -This automatic download happen only when using the command-line tools described in this page or the [JavaFX](javafx.html) application. +This automatic download happens only when using the command-line tools described in this page or the [JavaFX](javafx.html) application. Developers who wish to use the EPSG dataset in their applications can use the Maven artifact documented in [download](downloads.html#epsg) page. -<div class="warning"> -<h3>Known bug</h3> -<p>Automatic download of EPSG data described in above paragraph does not work, -because Maven central does not accept anymore <code>"http:"</code> URLs -(they have to be changed to <code>"https:"</code>). -This problem will be fixed in Apache {{% SIS %}} 1.2. -In the meantime, the following commands can be executed in a Unix shell as a workaround -if you accept the <a href="https://epsg.org/terms-of-use.html";>EPSG terms of use</a>.</p> - -{{< highlight bash >}} -cd apache-sis-1.1/data -rm -rf Databases -wget https://repo1.maven.org/maven2/org/apache/sis/non-free/sis-embedded-data/1.1/sis-embedded-data-1.1.jar -unzip sis-embedded-data-1.1.jar SIS_DATA/Databases/* -mv SIS_DATA/Databases . -rmdir SIS_DATA -cd .. -{{< / highlight >}} -</div> - The above output is compatible with version 2 of _Well Known Text_ (WKT) format. The output format can be controlled as below: diff --git a/source/formats.md b/source/formats.md new file mode 100644 index 00000000..dbd2020e --- /dev/null +++ b/source/formats.md @@ -0,0 +1,100 @@ +--- +title: Formats supported by Apache SIS +--- + +Apache {{% SIS %}} can read data from the formats listed below. +Some formats are supported in read-only mode, others in read/write modes. +Data may be structured as vectors or rasters, +which in Apache {{% SIS %}} are mapped to the `FeatureSet` and `GridCoverageResource` interfaces respectively. +Some formats can contain an arbitrary amount of feature types or rasters, +in which case the root resource will be `Aggregate`. + +<table> + <tr> + <th>Format</th> + <th>Capability</th> + <th>Type of resource</th> + </tr><tr> + <td>{{% CSV %}}</td> + <td>Read</td> + <td><code>FeatureSet</code></td> + </tr><tr> + <td>ESRI ASCII Grid</td> + <td>Read/write</td> + <td><code>GridCoverageResource</code></td> + </tr><tr> + <td>ESRI BIL/BIQ/BSQ</td> + <td>Read</td> + <td><code>GridCoverageResource</code></td> + </tr><tr> + <td>Folder</td> + <td>Read/write</td> + <td><code>Aggregate</code>, <code>FeatureSet</code>, <code>GridCoverageResource</code></td> + </tr><tr> + <td>GeoTIFF</td> + <td>Read</td> + <td><code>Aggregate</code>, <code>GridCoverageResource</code></td> + </tr><tr> + <td>{{% GML %}} ({{% CRS %}} only)</td> + <td>Read/write⁽¹⁾</td> + <td><code>Resource</code></td> + </tr><tr> + <td>{{% GPX %}}</td> + <td>Read</td> + <td><code>FeatureSet</code></td> + </tr><tr> + <td>{{% ISO %}} 19115 {{% XML %}}</td> + <td>Read/write⁽¹⁾</td> + <td><code>Resource</code></td> + </tr><tr> + <td>Landsat</td> + <td>Read</td> + <td><code>Aggregate</code>, <code>GridCoverageResource</code></td> + </tr><tr> + <td>NetCDF</td> + <td>Read</td> + <td><code>Aggregate</code>, <code>FeatureSet</code>, <code>GridCoverageResource</code></td> + </tr><tr> + <td>{{% SQL %}}⁽²⁾</td> + <td>Read</td> + <td><code>Aggregate</code>, <code>FeatureSet</code></td> + </tr><tr> + <td>{{% WKT %}} ({{% CRS %}} only)</td> + <td>Read/write⁽¹⁾</td> + <td><code>Resource</code></td> + </tr><tr> + <td>World File</td> + <td>Read/write</td> + <td><code>GridCoverageResource</code>, sometime <code>Aggregate<code></td> + </tr> +</table> + +**Notes:** +1. {{% GML %}}, {{% WKT %}} and {{% ISO %}} 19115 can not yet be written +throught the `DataStore` API. They require the use of specific API. +2. {{% SQL %}} is not a file format but rather a connection to a database throught {{% JDBC %}} driver. + + +# How to read + +The easiest way to open a file in read-only mode is as below. +The `input` argument can be a `File`, `Path`, `URI`, `URL`, `InputStream`, `ReadableByteChannel` +or a {{% JDBC %}} `DataSource` (non-exhaustive list). + +{{< highlight java >}} +try (DataStore store = DataStores.open(input)) { + // Assuming that we know that the data is a single raster: + GridCoverageResource r = (GridCoverageResource) store; + + // Subset of data could be specified here (no subset in this example): + GridCoverage coverage = r.read(null, null); + + // Assuming that we know that the data is two-dimensional: + RenderedImage image = coverage.render(null); +} +{{< / highlight >}} + +Most of Apache {{% SIS %}} API is designed for multi-dimensional data. +When requesting a `RenderedImage`, a two-dimensional slice must be specified, +unless the data are already two-dimensional. +The two-dimensional slice can be along any dimensions. diff --git a/source/javafx.md b/source/javafx.md index a972a975..6fbae502 100644 --- a/source/javafx.md +++ b/source/javafx.md @@ -9,39 +9,23 @@ The graphical application is in early development stage and very far from provid all services that we can expect from a Geographic Information System (GIS). Furthermore this application covers a very small subset of Apache {{% SIS %}} capabilities. But it can give an idea of what is available there. -For launching the application, [download](downloads.html) binaries, unzip then execute (on Unix system): + +{{< toc >}} + +# Installation {#install} + +Select "Apache {{% SIS %}} {{% version %}} binary" from the [downloads page](downloads.html) an unzip in any directory. +See the [command line](command-line.html) page for a description of the directory structure. +For launching the application, execute (on Unix system): {{< highlight bash >}} -bash apache-sis-{{% version %}}/bin/sisfx +./apache-sis-{{% version %}}/bin/sisfx {{< / highlight >}} On first execution, the application will ask user to download the [JavaFX framework][JavaFX] (if not already done). That framework is not included in the Apache {{% SIS %}} binaries for licensing reasons (it is under GPL license). Later on, the application will offer to download the [EPSG geodetic dataset](epsg.html) when first needed. That dataset is not included neither again for licensing reasons. - - -<div class="warning"> -<h3>Known bug</h3> -<p>Automatic download of EPSG data described in above paragraph does not work, -because Maven central does not accept anymore <code>"http:"</code> URLs -(they have to be changed to <code>"https:"</code>). -This problem will be fixed in Apache {{% SIS %}} 1.2. -In the meantime, the following commands can be executed in a Unix shell as a workaround -if you accept the <a href="https://epsg.org/terms-of-use.html";>EPSG terms of use</a>.</p> - -{{< highlight bash >}} -cd apache-sis-1.1/data -rm -rf Databases -wget https://repo1.maven.org/maven2/org/apache/sis/non-free/sis-embedded-data/1.1/sis-embedded-data-1.1.jar -unzip sis-embedded-data-1.1.jar SIS_DATA/Databases/* -mv SIS_DATA/Databases . -rmdir SIS_DATA -cd .. -{{< / highlight >}} -</div> - - After those two steps are completed, user can see an application like below: <div id="carousel" class="carousel slide" data-bs-ride="carousel"> @@ -90,9 +74,10 @@ After those two steps are completed, user can see an application like below: # Open files -Drag and drop some netCDF or GeoTIFF files in the explorer (the white area on the left side of main window). +Drag and drop some netCDF, GeoTIFF, ASCII Grid or World Files in the explorer +(the white area on the left side of main window). Multiple files or entire directories can be dragged. -Opened files are listed and netCDF variables are shown below each file as a tree. +Opened files are listed and variables are shown below each file as a tree. Files can be closed with the contextual menu (click on a file with the right mouse button). The panel on the right side gives a summary of the selected file or variable; more information can be read in the “Metadata” tab. @@ -101,6 +86,24 @@ If the geographic area crosses the anti-meridian (the meridian at ±180° of lon the bounding box will be shown with two parts on each side of the map. Many (but not all) classes of the Apache {{% SIS %}} library are capable to handle such situation. +## Data on cloud + +Apache {{% SIS %}} can open data on Amazon S3. +This is not enabled by default in the JavaFX application because of the large amount of dependencies required. +An option for downloading the dependencies may be provided in a future release. +In the meantime, SIS has to be built from the source for enabling this functionality. + +## File size limit + +There is usually no size limit when viewing only the metadata, because only the file headers are read at that time. +When viewing the data, there is no size limit if the data are pyramided and tiled with tiles of reasonable size, +because the application loads only the tiles needed for the area being displayed. +An example of file format supporting tiling is GeoTIFF. +If a format does not support tiling (e.g. netCDF-3) or if data does not use the tiling capability of the format, +then the data are fully loaded as one big tile. +A future version of the JavaFX application may allow to load only a subset of the data +(the Apache {{% SIS %}} API already allows that). + # Explore metadata
