sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 03/03: Move PlanarImage in public API. I think it has reasonable chances to be stable now.
Date Sun, 29 Dec 2019 22:40:39 GMT
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

commit eb9ad2543b6a7f4bba85057b029653c971e70819
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Sun Dec 29 23:40:05 2019 +0100

    Move PlanarImage in public API. I think it has reasonable chances to be stable now.
---
 .../apache/sis/coverage/grid/ReshapedImage.java    |  2 +-
 .../coverage/j2d => image}/PlanarImage.java        | 52 ++++++++++++++++------
 .../internal/coverage/j2d/ScaledColorSpace.java    | 14 ++++--
 .../sis/coverage/grid/ReshapedImageTest.java       |  2 +-
 .../coverage/j2d => image}/PlanarImageTest.java    |  4 +-
 .../java/org/apache/sis/image/TiledImageMock.java  |  1 -
 .../apache/sis/test/suite/FeatureTestSuite.java    |  2 +-
 7 files changed, 54 insertions(+), 23 deletions(-)

diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/ReshapedImage.java
b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/ReshapedImage.java
index bb4fe6c..ca98c7f 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/ReshapedImage.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/ReshapedImage.java
@@ -23,7 +23,7 @@ import java.awt.image.RenderedImage;
 import java.awt.image.SampleModel;
 import java.awt.image.ColorModel;
 import java.awt.image.WritableRaster;
-import org.apache.sis.internal.coverage.j2d.PlanarImage;
+import org.apache.sis.image.PlanarImage;
 import org.apache.sis.util.ArgumentChecks;
 
 import static java.lang.Math.min;
diff --git a/core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/PlanarImage.java
b/core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java
similarity index 89%
rename from core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/PlanarImage.java
rename to core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java
index 76a350f..0b329d0 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/PlanarImage.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java
@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.sis.internal.coverage.j2d;
+package org.apache.sis.image;
 
 import java.awt.Image;
 import java.awt.Rectangle;
@@ -32,23 +32,27 @@ import org.apache.sis.internal.util.Numerics;
 import org.apache.sis.util.resources.Errors;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.Classes;
+import org.apache.sis.internal.coverage.j2d.ImageUtilities;
+import org.apache.sis.internal.coverage.j2d.ScaledColorSpace;
 
 
 /**
  * Base class of {@link RenderedImage} implementations in Apache SIS.
  * The "Planar" part in the class name emphases that this image is a representation
- * of two-dimensional data and should not represent three-dimensional effects.
+ * of two-dimensional data and should not contain an image with three-dimensional effects.
  * Planar images can be used as data storage for {@link org.apache.sis.coverage.grid.GridCoverage2D}.
  *
  * <div class="note"><b>Note: inspirational source</b>
  * <p>This class takes some inspiration from the {@code javax.media.jai.PlanarImage}
  * class defined in the <cite>Java Advanced Imaging</cite> (<abbr>JAI</abbr>)
library.
- * That excellent library was maybe 20 years in advance over common imaging frameworks,
- * but unfortunately does not seems to be maintained anymore.
+ * That excellent library was 20 years in advance on thematic like defining a chain of image
operations,
+ * multi-threaded execution, distribution over a computer network, <i>etc.</i>
+ * But unfortunately the <abbr>JAI</abbr> library does not seems to be maintained
anymore.
  * We do not try to reproduce the full set of JAI functionalities here, but we progressively
  * reproduce some little bits of functionalities as they are needed by Apache SIS.</p></div>
  *
- * <p>Subclasses need to implement the following methods:</p>
+ * <p>This base class does not store any state and does not assume any tile layout.
+ * Subclasses need to implement at least the following methods:</p>
  * <ul>
  *   <li>{@link #getMinX()}        — the minimum <var>x</var> coordinate
(inclusive) of the image.</li>
  *   <li>{@link #getMinY()}        — the minimum <var>y</var> coordinate
(inclusive) of the image.</li>
@@ -61,6 +65,11 @@ import org.apache.sis.util.Classes;
  *   <li>{@link #getTile(int,int)} — the tile at given tile indices.</li>
  * </ul>
  *
+ * Default implementations are provided for {@link #getNumXTiles()}, {@link #getNumYTiles()},
+ * {@link #getTileGridXOffset()}, {@link #getTileGridYOffset()}, {@link #getData()},
+ * {@link #getData(Rectangle)} and {@link #copyData(WritableRaster)}
+ * in terms of above methods.
+ *
  * @author  Johann Sorel (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)
  * @version 1.1
@@ -322,29 +331,44 @@ public abstract class PlanarImage implements RenderedImage {
      * upper-left corner, and that image size is equal to the sum of the sizes of all tiles.
Compatibility
      * of sample model and color model is also verified.
      *
-     * @return {@code null} if image layout information are consistent, or name of inconsistent
property
-     *         if a problem is found.
+     * <p>The default implementation may return the following identifiers, in that
order
+     * (i.e. this method returns the identifier of the first test that fail):</p>
+     * <ul>
+     *   <li>{@code "SampleModel"} — Sample model is incompatible with color model.</li>
+     *   <li>{@code "tileWidth"}   — tile width is greater than sample model width.</li>
+     *   <li>{@code "tileHeight"}  — tile height is greater than sample model height.</li>
+     *   <li>{@code "numXTiles"}   — number of tiles on the X axis is inconsistent
with image width.</li>
+     *   <li>{@code "numYTiles"}   — number of tiles on the Y axis is inconsistent
with image height.</li>
+     *   <li>{@code "tileX"}       — {@ode minTileX} and/or {@code tileGridXOffset}
is inconsistent.</li>
+     *   <li>{@code "tileY"}       — {@ode minTileY} and/or {@code tileGridYOffset}
is inconsistent.</li>
+     * </ul>
+     *
+     * Subclasses may perform additional checks. For example some subclasses also check specifically
+     * for {@code "minX"}, {@code "minY"}, {@code "tileGridXOffset"} and {@code "tileGridYOffset"}.
+     *
+     * @return {@code null} if image layout information are consistent,
+     *         or the name of inconsistent attribute if a problem is found.
      */
     public String verify() {
         final int tileWidth  = getTileWidth();
         final int tileHeight = getTileHeight();
         final SampleModel sm = getSampleModel();
         if (sm != null) {
+            final ColorModel cm = getColorModel();
+            if (cm != null) {
+                if (!cm.isCompatibleSampleModel(sm)) return "SampleModel";
+            }
             /*
              * The SampleModel size represents the physical layout of pixels in the data
buffer,
              * while the Raster may be a virtual view over a sub-region of a parent raster.
              */
             if (sm.getWidth()  < tileWidth)  return "tileWidth";
             if (sm.getHeight() < tileHeight) return "tileHeight";
-            final ColorModel cm = getColorModel();
-            if (cm != null) {
-                if (!cm.isCompatibleSampleModel(sm)) return "SampleModel";
-            }
         }
-        if (((long) getMinTileX())  * tileWidth  + getTileGridXOffset() != getMinX()) return
"tileX";
-        if (((long) getMinTileY())  * tileHeight + getTileGridYOffset() != getMinY()) return
"tileY";
         if (((long) getNumXTiles()) * tileWidth  != getWidth())  return "numXTiles";
         if (((long) getNumYTiles()) * tileHeight != getHeight()) return "numYTiles";
+        if (((long) getMinTileX())  * tileWidth  + getTileGridXOffset() != getMinX()) return
"tileX";
+        if (((long) getMinTileY())  * tileHeight + getTileGridYOffset() != getMinY()) return
"tileY";
         return null;
     }
 
@@ -382,7 +406,7 @@ colors: if (cm != null) {
                     if (cs instanceof ScaledColorSpace) {
                         ((ScaledColorSpace) cs).formatRange(buffer.append("showing "));
                     } else if (cs.getType() == ColorSpace.TYPE_GRAY) {
-                        buffer.append("; grayscale");
+                        buffer.append("grayscale");
                     }
                 }
             }
diff --git a/core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/ScaledColorSpace.java
b/core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/ScaledColorSpace.java
index 56d4049..0ee9e58 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/ScaledColorSpace.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/internal/coverage/j2d/ScaledColorSpace.java
@@ -17,6 +17,7 @@
 package org.apache.sis.internal.coverage.j2d;
 
 import java.awt.color.ColorSpace;
+import org.apache.sis.util.Debug;
 
 
 /**
@@ -29,10 +30,13 @@ import java.awt.color.ColorSpace;
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @version 1.1
- * @since   1.0
+ *
+ * @see ColorModelFactory#createColorSpace(int, int, double, double)
+ *
+ * @since 1.0
  * @module
  */
-final class ScaledColorSpace extends ColorSpace {
+public final class ScaledColorSpace extends ColorSpace {
     /**
      * For cross-version compatibility.
      */
@@ -172,8 +176,12 @@ final class ScaledColorSpace extends ColorSpace {
 
     /**
      * Formats the range of values in the given buffer.
+     * This method is used for {@link #toString()} implementation and may change in any future
version.
+     *
+     * @param  buffer  where to append the range of values.
      */
-    final void formatRange(final StringBuilder buffer) {
+    @Debug
+    public final void formatRange(final StringBuilder buffer) {
         buffer.append('[').append(getMinValue(visibleBand))
             .append(" … ").append(getMaxValue(visibleBand))
             .append(" in band ").append(visibleBand).append(']');
diff --git a/core/sis-feature/src/test/java/org/apache/sis/coverage/grid/ReshapedImageTest.java
b/core/sis-feature/src/test/java/org/apache/sis/coverage/grid/ReshapedImageTest.java
index 6155bf9..316e855 100644
--- a/core/sis-feature/src/test/java/org/apache/sis/coverage/grid/ReshapedImageTest.java
+++ b/core/sis-feature/src/test/java/org/apache/sis/coverage/grid/ReshapedImageTest.java
@@ -38,7 +38,7 @@ import static org.apache.sis.test.FeatureAssert.assertValuesEqual;
  * @since   1.1
  * @module
  */
-@DependsOn(org.apache.sis.internal.coverage.j2d.PlanarImageTest.class)
+@DependsOn(org.apache.sis.image.PlanarImageTest.class)
 public final strictfp class ReshapedImageTest extends TestCase {
     /**
      * Size of tiles used in this test.
diff --git a/core/sis-feature/src/test/java/org/apache/sis/internal/coverage/j2d/PlanarImageTest.java
b/core/sis-feature/src/test/java/org/apache/sis/image/PlanarImageTest.java
similarity index 97%
rename from core/sis-feature/src/test/java/org/apache/sis/internal/coverage/j2d/PlanarImageTest.java
rename to core/sis-feature/src/test/java/org/apache/sis/image/PlanarImageTest.java
index c983c3e..0ac4572 100644
--- a/core/sis-feature/src/test/java/org/apache/sis/internal/coverage/j2d/PlanarImageTest.java
+++ b/core/sis-feature/src/test/java/org/apache/sis/image/PlanarImageTest.java
@@ -14,12 +14,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.sis.internal.coverage.j2d;
+package org.apache.sis.image;
 
 import java.util.Random;
 import java.awt.Rectangle;
 import java.awt.image.DataBuffer;
-import org.apache.sis.image.TiledImageMock;
+import org.apache.sis.internal.coverage.j2d.ImageUtilities;
 import org.apache.sis.test.TestCase;
 import org.apache.sis.test.TestUtilities;
 import org.junit.Test;
diff --git a/core/sis-feature/src/test/java/org/apache/sis/image/TiledImageMock.java b/core/sis-feature/src/test/java/org/apache/sis/image/TiledImageMock.java
index ac36645..9db5992 100644
--- a/core/sis-feature/src/test/java/org/apache/sis/image/TiledImageMock.java
+++ b/core/sis-feature/src/test/java/org/apache/sis/image/TiledImageMock.java
@@ -25,7 +25,6 @@ import java.awt.image.SampleModel;
 import java.awt.image.TileObserver;
 import java.awt.image.WritableRaster;
 import java.awt.image.WritableRenderedImage;
-import org.apache.sis.internal.coverage.j2d.PlanarImage;
 import org.apache.sis.internal.util.Numerics;
 import org.apache.sis.util.ArraysExt;
 
diff --git a/core/sis-feature/src/test/java/org/apache/sis/test/suite/FeatureTestSuite.java
b/core/sis-feature/src/test/java/org/apache/sis/test/suite/FeatureTestSuite.java
index 73940c8..d81d017 100644
--- a/core/sis-feature/src/test/java/org/apache/sis/test/suite/FeatureTestSuite.java
+++ b/core/sis-feature/src/test/java/org/apache/sis/test/suite/FeatureTestSuite.java
@@ -76,7 +76,7 @@ import org.junit.runners.Suite;
     // Rasters
     org.apache.sis.internal.coverage.j2d.ImageUtilitiesTest.class,
     org.apache.sis.internal.coverage.j2d.ScaledColorSpaceTest.class,
-    org.apache.sis.internal.coverage.j2d.PlanarImageTest.class,
+    org.apache.sis.image.PlanarImageTest.class,
     org.apache.sis.image.DefaultIteratorTest.class,
     org.apache.sis.image.LinearIteratorTest.class,
     org.apache.sis.coverage.CategoryTest.class,


Mime
View raw message