[IMAGING-340] Support Extensions to the PNG 1.2 Specification, Version 1.5.0

src/changes/changes.xml

@@ -59,6 +59,7 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Arnout Engelen">Add an Imaging-specific security page #439.</action>
       <action dev="ggregory" type="add" due-to="Gary Gregory">Add Maven property commons.taglist.version for debugging.</action>
       <action dev="ggregory" type="add" due-to="Stefal, Gary Gregory">Add support of GPSHPositioningError in GpsTagConstants #451.</action> 
+      <action dev="kinow"    type="add" due-to="Glavo">Support Extensions from PNG 1.2 Specification, Version 1.5.0 #269.</action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Dependabot, Gary Gregory">Bump org.apache.commons:commons-parent from 69 to 78 #400, #406, #428, #430, #436, #442, #445, #545.</action>
       <action dev="ggregory" type="update" due-to="Dependabot">Bump org.apache.commons:commons-lang3 from 3.14.0 to 3.17.0 #416, #423, #431.</action>

src/conf/spotbugs-exclude-filter.xml

@@ -173,6 +173,16 @@
     <Method name="&lt;init&gt;" />
     <Bug pattern="EI_EXPOSE_REP2" />
   </Match>
+  <Match>
+    <Class name="org.apache.commons.imaging.formats.png.PngImageMetadata" />
+    <Method name="getExif" />
+    <Bug pattern="EI_EXPOSE_REP" />
+  </Match>
+  <Match>
+    <Class name="org.apache.commons.imaging.formats.png.PngImageMetadata" />
+    <Method name="&lt;init&gt;" />
+    <Bug pattern="EI_EXPOSE_REP2" />
+  </Match>
   <!-- Reason: We don't want to implement Serializable at all.  -->
   <Match>
     <Bug pattern="SE_COMPARATOR_SHOULD_BE_SERIALIZABLE" />

src/main/java/org/apache/commons/imaging/formats/png/ChunkType.java

@@ -16,80 +16,217 @@
  */
 package org.apache.commons.imaging.formats.png;
 
+import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 
 import org.apache.commons.imaging.common.BinaryFunctions;
+import org.apache.commons.imaging.formats.png.chunks.PngChunk;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkGama;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkIccp;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkIdat;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkIhdr;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkItxt;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkPhys;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkPlte;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkScal;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkText;
+import org.apache.commons.imaging.formats.png.chunks.PngChunkZtxt;
 
 /**
- * Type of a PNG chunk.
+ * Type of PNG chunk.
  *
  * @see <a href="https://www.w3.org/TR/png/#11Chunks">Portable Network Graphics Specification - Chunk specifications</a>
  */
 public enum ChunkType {
 
-    /** Image header */
-    IHDR,
+    /**
+     * Image header
+     */
+    IHDR(PngChunkIhdr::new),
 
-    /** Palette */
-    PLTE,
+    /**
+     * Palette
+     */
+    PLTE(PngChunkPlte::new),
 
-    /** Image data */
-    IDAT,
+    /**
+     * Image data
+     */
+    IDAT(PngChunkIdat::new),
 
-    /** Image trailer */
+    /**
+     * Image trailer
+     */
     IEND,
 
-    /** Transparency */
+    /**
+     * Transparency
+     */
     tRNS,
 
-    /** Primary chromaticities and white point */
+    /**
+     * Primary chromaticities and white point
+     */
     cHRM,
 
-    /** Image gamma */
-    gAMA,
+    /**
+     * Image gamma
+     */
+    gAMA(PngChunkGama::new),
 
-    /** Embedded ICC profile */
-    iCCP,
+    /**
+     * Embedded ICC profile
+     */
+    iCCP(PngChunkIccp::new),
 
-    /** Significant bits */
+    /**
+     * Significant bits
+     */
     sBIT,
 
-    /** Standard RGB color space */
+    /**
+     * Standard RGB color space
+     */
     sRGB,
 
-    /** Textual data */
-    tEXt,
+    /**
+     * Textual data
+     */
+    tEXt(PngChunkText::new),
 
-    /** Compressed textual data */
-    zTXt,
+    /**
+     * Compressed textual data
+     */
+    zTXt(PngChunkZtxt::new),
 
-    /** International textual data */
-    iTXt,
+    /**
+     * International textual data
+     */
+    iTXt(PngChunkItxt::new),
 
-    /** Background color */
+    /**
+     * Background colour
+     */
     bKGD,
 
-    /** Image histogram */
+    /**
+     * Image histogram
+     */
     hIST,
 
-    /** Physical pixel dimensions */
-    pHYs,
+    /**
+     * Physical pixel dimensions
+     */
+    pHYs(PngChunkPhys::new),
 
-    /** Physical scale */
-    sCAL,
-
-    /** Suggested palette */
+    /**
+     * Suggested palette
+     */
     sPLT,
 
-    /** Image last-modification time */
-    tIME;
+    /**
+     * Image last-modification time
+     */
+    tIME,
+
+    /*
+     * PNGEXT
+     */
+
+    /**
+     * Image offset
+     *
+     * @since 1.0-alpha6
+     */
+    oFFs(Extension.PNGEXT),
+
+    /**
+     * Calibration of pixel values
+     *
+     * @since 1.0-alpha6
+     */
+    pCAL(Extension.PNGEXT),
+
+    /**
+     * Physical scale
+     */
+    sCAL(Extension.PNGEXT, PngChunkScal::new),
+
+    /**
+     * GIF Graphic Control Extension
+     *
+     * @since 1.0-alpha6
+     */
+    gIFg(Extension.PNGEXT),
+
+    /**
+     * GIF Application Extension
+     *
+     * @since 1.0-alpha6
+     */
+    gIFx(Extension.PNGEXT),
+
+    /**
+     * Indicator of Stereo Image
+     *
+     * @since 1.0-alpha6
+     */
+    sTER(Extension.PNGEXT),
+
+    /**
+     * Exchangeable Image File (Exif) Profile
+     *
+     * @since 1.0-alpha6
+     */
+    eXIf(Extension.PNGEXT),
+
+    ;
+
+    @FunctionalInterface
+    private interface ChunkConstructor {
+        PngChunk make(int length, int chunkType, int crc, byte[] bytes) throws IOException;
+    }
+
+    private static final ChunkType[] types = ChunkType.values();
+
+    static ChunkType findType(int chunkType) {
+        for (ChunkType type : types) {
+            if (type.value == chunkType) {
+                return type;
+            }
+        }
+        return null;
+    }
+
+    static PngChunk makeChunk(int length, int chunkType, int crc, byte[] bytes) throws IOException {
+        ChunkType type = findType(chunkType);
+        return type != null && type.constructor != null
+                ? type.constructor.make(length, chunkType, crc, bytes)
+                : new PngChunk(length, chunkType, crc, bytes);
+    }
 
     final byte[] array;
     final int value;
+    final Extension extension;
+    final ChunkConstructor constructor;
 
     ChunkType() {
+        this(null, null);
+    }
+
+    ChunkType(Extension extension) {
+        this(extension, null);
+    }
+
+    ChunkType(ChunkConstructor constructor) {
+        this(null, constructor);
+    }
+
+    ChunkType(Extension extension, ChunkConstructor constructor) {
         final char[] chars = name().toCharArray();
-        array = name().getBytes(StandardCharsets.UTF_8);
-        value = BinaryFunctions.charsToQuad(chars[0], chars[1], chars[2], chars[3]);
+        this.array = name().getBytes(StandardCharsets.UTF_8);
+        this.value = BinaryFunctions.charsToQuad(chars[0], chars[1], chars[2], chars[3]);
+        this.extension = extension;
+        this.constructor = constructor;
     }
 }

src/main/java/org/apache/commons/imaging/formats/png/Extension.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.imaging.formats.png;
+
+/**
+ * PNG extension types.
+ *
+ * @since 1.0-alpha6
+ */
+enum Extension {
+    /**
+     * @see <a href="http://ftp-osl.osuosl.org/pub/libpng/documents/pngext-1.5.0.html">Extensions to the PNG 1.2 Specification, Version 1.5.0</a>
+     */
+    PNGEXT,
+
+    /**
+     * @see <a href="https://wiki.mozilla.org/APNG_Specification">APNG Specification</a>
+     */
+    APNG,
+}