(sis) branch geoapi-4.0 updated: Fix: calculation of contributions in `ImageOverlay` was too large. Edit documentation by saying that each image is fully opaque.

[de...@apache.org]

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

desruisseaux 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 8c9c31766b Fix: calculation of contributions in `ImageOverlay` was too large. Edit documentation by saying that each image is fully opaque.
8c9c31766b is described below

commit 8c9c31766bcde90d64a7372137b59c6e1a66c78d
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Sat Dec 21 21:54:54 2024 +0100

    Fix: calculation of contributions in `ImageOverlay` was too large.
    Edit documentation by saying that each image is fully opaque.
---
 .../main/org/apache/sis/image/ImageOverlay.java          | 16 ++++++++--------
 .../main/org/apache/sis/image/ImageProcessor.java        | 14 +++++++++-----
 2 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageOverlay.java b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageOverlay.java
index c7f13c83fe..4bb06de124 100644
--- a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageOverlay.java
+++ b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageOverlay.java
@@ -48,7 +48,9 @@ import org.apache.sis.coverage.privy.ImageUtilities;
  * An overlay of an arbitrary number of images. All images have the same pixel coordinate system,
  * but potentially different bounding boxes, tile sizes and tile indices. Source images are drawn
  * in reverse order: the last source image is drawn first, and the first source image is drawn last
- * on top of all other images. The requirements are:
+ * on top of all other images. All images are considered fully opaque, including the alpha channel
+ * which is handled as an ordinary band.
+ * The requirements are:
  *
  * <ul>
  *   <li>All source images shall have the same pixel coordinate systems (but not necessarily the same tile matrix).</li>
@@ -120,12 +122,11 @@ final class ImageOverlay extends MultiSourceImage {
             final Area area = new Area(ImageUtilities.getValidArea(source));
             if (aoi != null) area.intersect(aoi);
             if (area.isEmpty()) continue;         // Source does not intersect the specified bounds.
+            final Area contrib = new Area(area);
+            contrib.subtract(validArea);
+            if (contrib.isEmpty()) continue;      // The new source is fully masked by previous sources.
             validArea.add(area);
-            if (count != 0) {
-                area.subtract(contributions[count - 1]);
-                if (area.isEmpty()) continue;     // The new source is fully masked by previous sources.
-            }
-            contributions[count] = area;
+            contributions[count] = contrib;
             sources[count++] = source;
             /*
              * The default sample model is selected after filtering because the choice of a sample model
@@ -160,8 +161,7 @@ final class ImageOverlay extends MultiSourceImage {
         sources = ArraysExt.resize(sources, count);
         contributions = ArraysExt.resize(contributions, count);
         /*
-         * Last area is now the union of the Area Of iInterest (AOI) of all source images.
-         * The size of the destination image is this valid area, unless specified otherwise.
+         * The valid area defines the size of the combined image, unless specified otherwise.
          * If the tile size is not a divisor of the image size, try to find a better tile size.
          */
         if (bounds == null) {
diff --git a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
index db2faaefa2..59e1ea80dd 100644
--- a/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
+++ b/endorsed/src/org.apache.sis.feature/main/org/apache/sis/image/ImageProcessor.java
@@ -969,13 +969,17 @@ public class ImageProcessor implements Cloneable {
      * Creates a new image overlay or returns one of the given sources if equivalent.
      * All source images shall have the same pixel coordinate system, but they may have different bounding boxes,
      * tile sizes and tile indices. Images are drawn in reverse order: the last source image is drawn first, and
-     * the first source image is drawn last on top of all other images. The returned image may have less sources
-     * than the specified ones if this method determines that some sources will never be drawn.
-     * This method may return {@code sources[0]} directly.
+     * the first source image is drawn last on top of all other images. All images are considered fully opaque,
+     * including the alpha channel which is handled as an ordinary band.
      *
-     * <p>All source images shall have the same number of bands (but not necessarily the same sample model).
+     * <p>The returned image may have less sources than the ones given in argument if this method determines
+     * that some sources will never be drawn (i.e., are fully hidden behind the first images).
+     * If only one source appears to be effectively used, this method returns that image directly.</p>
+     *
+     * <h4>Preconditions</h4>
+     * All source images shall have the same number of bands (but not necessarily the same sample model).
      * All source images should have equivalent color model, otherwise color consistency is not guaranteed.
-     * At least one image shall intersect the given bounds.</p>
+     * At least one image shall intersect the given bounds.
      *
      * <h4>Properties used</h4>
      * This operation uses the following properties in addition to method parameters: