[sis] branch geoapi-4.0 updated: refactor(Core): Make Banded coverage envelope optional.

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amanin pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git


The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
     new 2225df5  refactor(Core): Make Banded coverage envelope optional.
2225df5 is described below

commit 2225df5fb6304622473cbdb6c7ca6cf69b53c2c0
Author: Alexis Manin <al...@geomatys.com>
AuthorDate: Thu Jan 27 14:31:04 2022 +0100

    refactor(Core): Make Banded coverage envelope optional.
    
    Take of corner-cases where an envelope is difficult to provide
    
    Moreover, keeping it this way allow implementation to extend both storage DataSet (or GridCoverageesource) and BandedCoverage(or GridCoverage).
---
 .../org/apache/sis/coverage/BandedCoverage.java    | 24 ++++++++++++++++++++--
 .../org/apache/sis/coverage/grid/GridCoverage.java |  6 +++---
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/BandedCoverage.java b/core/sis-feature/src/main/java/org/apache/sis/coverage/BandedCoverage.java
index 6f03f88..0c9d1e2 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/coverage/BandedCoverage.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/BandedCoverage.java
@@ -17,6 +17,7 @@
 package org.apache.sis.coverage;
 
 import java.util.List;
+import java.util.Optional;
 import java.util.function.Function;
 import org.opengis.geometry.Envelope;
 import org.opengis.geometry.DirectPosition;
@@ -73,11 +74,30 @@ public abstract class BandedCoverage {
      * The envelope encompasses all cell surfaces, from the left border of leftmost cell
      * to the right border of the rightmost cell and similarly along other axes.
      *
-     * @return the bounding box for the coverage domain in CRS coordinates.
+     * <p>For most common cases, the envelope should be present.
+     * However, the return value may be empty in cases like:</p>
+     * <ul>
+     *   <li>
+     *     Functional dataset: in case of a computed resource, the coverage could be potentially valid
+     *     in an infinite extent (repeating pattern, random numbers for tests, etc.).
+     *   </li>
+     *   <li>
+     *     Computational cost: if obtaining the overall envelope is too costly,
+     *     an implementation might decide to leave the result empty instead of returning a too approximate envelope.
+     *     For example, if a coverage aggregates a lot of data (by dynamically choosing data in a catalog upon evaluation),
+     *     it might rather not compute envelope union for the entire catalog.
+     *   </li>
+     *   <li>
+     *       hen the function does not have a clear boundary for its domain of validity,
+     *       for example because the sample values accuracy decreases progressively with distance.
+     *   </li>
+     * </ul>
+     *
+     * @return the bounding box for the coverage domain in CRS coordinates if available.
      *
      * @since 1.2
      */
-    public abstract Envelope getEnvelope();
+    public abstract Optional<Envelope> getEnvelope();
 
     /**
      * Returns information about the <cite>range</cite> of this coverage.
diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridCoverage.java b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridCoverage.java
index 3a848ea..f3095de 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridCoverage.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridCoverage.java
@@ -149,13 +149,13 @@ public abstract class GridCoverage extends BandedCoverage {
      * <p>The default implementation delegates to {@link GridGeometry#getEnvelope()}.</p>
      *
      * @return the bounding box for the coverage domain in CRS coordinates.
-     * @throws IncompleteGridGeometryException if the grid geometry has no envelope.
      *
      * @since 1.2
      */
     @Override
-    public Envelope getEnvelope() {
-        return gridGeometry.getEnvelope();
+    public Optional<Envelope> getEnvelope() {
+        if (gridGeometry.isDefined(GridGeometry.ENVELOPE)) return Optional.of(gridGeometry.getEnvelope());
+        else return Optional.empty();
     }
 
     /**