This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-imaging.git
commit 645e63189be982313426b271b722d25133e287f8 Author: Gary Gregory <[email protected]> AuthorDate: Sun Jan 4 08:16:59 2026 -0500 Javadoc --- .../imaging/formats/png/PngImageParser.java | 15 ++++++++ .../commons/imaging/formats/png/PngWriter.java | 31 ++++++++++------ .../imaging/formats/pnm/PnmImageParser.java | 3 ++ .../imaging/formats/pnm/PnmImagingParameters.java | 30 ++++++++++++++++ .../commons/imaging/icc/IccTagDataTypes.java | 12 +++++++ .../commons/imaging/mylzw/MyBitInputStream.java | 25 +++++++++++++ .../commons/imaging/mylzw/MyLzwDecompressor.java | 42 ++++++++++++++++++++++ 7 files changed, 147 insertions(+), 11 deletions(-) diff --git a/src/main/java/org/apache/commons/imaging/formats/png/PngImageParser.java b/src/main/java/org/apache/commons/imaging/formats/png/PngImageParser.java index 1488658e..77c8c38c 100644 --- a/src/main/java/org/apache/commons/imaging/formats/png/PngImageParser.java +++ b/src/main/java/org/apache/commons/imaging/formats/png/PngImageParser.java @@ -78,6 +78,12 @@ public class PngImageParser extends AbstractImageParser<PngImagingParameters> im private static final String DEFAULT_EXTENSION = ImageFormats.PNG.getDefaultExtension(); private static final String[] ACCEPTED_EXTENSIONS = ImageFormats.PNG.getExtensions(); + /** + * Gets the chunk type name from chunk type integer. + * + * @param chunkType the chunk type. + * @return the chunk type name as a string. + */ public static String getChunkTypeName(final int chunkType) { final StringBuilder result = new StringBuilder(); result.append((char) (0xff & chunkType >> 24)); @@ -647,6 +653,15 @@ public class PngImageParser extends AbstractImageParser<PngImagingParameters> im // BinaryFileParser // I may not have always preserved byte order correctly. + /** + * Checks if the PNG image has the specified chunk type. + * + * @param byteSource the byte source. + * @param chunkType the chunk type to check. + * @return true if chunk type exists, false otherwise. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public boolean hasChunkType(final ByteSource byteSource, final ChunkType chunkType) throws ImagingException, IOException { try (InputStream is = byteSource.getInputStream()) { readSignature(is); diff --git a/src/main/java/org/apache/commons/imaging/formats/png/PngWriter.java b/src/main/java/org/apache/commons/imaging/formats/png/PngWriter.java index adb49861..c0f1e057 100644 --- a/src/main/java/org/apache/commons/imaging/formats/png/PngWriter.java +++ b/src/main/java/org/apache/commons/imaging/formats/png/PngWriter.java @@ -32,9 +32,12 @@ import org.apache.commons.imaging.internal.Debug; import org.apache.commons.imaging.palette.Palette; import org.apache.commons.imaging.palette.PaletteFactory; +/** + * PNG image writer. + */ public class PngWriter { - /* + /** * 1. IHDR: image header, which is the first chunk in a PNG data stream. 2. PLTE: palette table associated with indexed PNG images. 3. IDAT: image data * chunks. 4. IEND: image trailer, which is the last chunk in a PNG data stream. * @@ -44,7 +47,6 @@ public class PngWriter { * space information). 3. Textual information: iTXt, tEXt, zTXt (see 11.3.4: Textual information). 4. Miscellaneous information: bKGD, hIST, pHYs, sPLT (see * 11.3.5: Miscellaneous information). 5. Time information: tIME (see 11.3.6: Time stamp information). */ - private static final class ImageHeader { public final int width; public final int height; @@ -67,6 +69,13 @@ public class PngWriter { } + /** + * Constructs a new PNG writer. + */ + public PngWriter() { + // Default constructor + } + private byte[] deflate(final byte[] bytes) throws IOException { try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) { try (DeflaterOutputStream dos = new DeflaterOutputStream(baos)) { @@ -254,6 +263,15 @@ public class PngWriter { writeChunk(os, ChunkType.iTXt, baos.toByteArray()); } + /* + * between two chunk types indicates alternatives. Table 5.3 - Chunk ordering rules Critical chunks (shall appear in this order, except PLTE is optional) + * Chunk name Multiple allowed Ordering constraints IHDR No Shall be first PLTE No Before first IDAT IDAT Yes Multiple IDAT chunks shall be consecutive IEND + * No Shall be last Ancillary chunks (need not appear in this order) Chunk name Multiple allowed Ordering constraints cHRM No Before PLTE and IDAT gAMA No + * Before PLTE and IDAT iCCP No Before PLTE and IDAT. If the iCCP chunk is present, the sRGB chunk should not be present. sBIT No Before PLTE and IDAT sRGB + * No Before PLTE and IDAT. If the sRGB chunk is present, the iCCP chunk should not be present. bKGD No After PLTE; before IDAT hIST No After PLTE; before + * IDAT tRNS No After PLTE; before IDAT pHYs No Before IDAT sCAL No Before IDAT sPLT Yes Before IDAT tIME No None iTXt Yes None tEXt Yes None zTXt Yes None + */ + private void writeChunkzTXt(final OutputStream os, final AbstractPngText.Ztxt text) throws IOException, ImagingException { if (!isValidISO_8859_1(text.keyword)) { throw new ImagingException("PNG zTXt chunk keyword is not ISO-8859-1: " + text.keyword); @@ -277,15 +295,6 @@ public class PngWriter { writeChunk(os, ChunkType.zTXt, baos.toByteArray()); } - /* - * between two chunk types indicates alternatives. Table 5.3 - Chunk ordering rules Critical chunks (shall appear in this order, except PLTE is optional) - * Chunk name Multiple allowed Ordering constraints IHDR No Shall be first PLTE No Before first IDAT IDAT Yes Multiple IDAT chunks shall be consecutive IEND - * No Shall be last Ancillary chunks (need not appear in this order) Chunk name Multiple allowed Ordering constraints cHRM No Before PLTE and IDAT gAMA No - * Before PLTE and IDAT iCCP No Before PLTE and IDAT. If the iCCP chunk is present, the sRGB chunk should not be present. sBIT No Before PLTE and IDAT sRGB - * No Before PLTE and IDAT. If the sRGB chunk is present, the iCCP chunk should not be present. bKGD No After PLTE; before IDAT hIST No After PLTE; before - * IDAT tRNS No After PLTE; before IDAT pHYs No Before IDAT sCAL No Before IDAT sPLT Yes Before IDAT tIME No None iTXt Yes None tEXt Yes None zTXt Yes None - */ - /** * Writes an image to an output stream. * diff --git a/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImageParser.java b/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImageParser.java index 8cac6533..f23cc12d 100644 --- a/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImageParser.java +++ b/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImageParser.java @@ -40,6 +40,9 @@ import org.apache.commons.imaging.common.ImageBuilder; import org.apache.commons.imaging.common.ImageMetadata; import org.apache.commons.imaging.palette.PaletteFactory; +/** + * Parser for PNM (Portable aNyMap) image format. + */ public class PnmImageParser extends AbstractImageParser<PnmImagingParameters> { private static final String TOKEN_ENDHDR = "ENDHDR"; diff --git a/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImagingParameters.java b/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImagingParameters.java index ab00990a..b1fc4653 100644 --- a/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImagingParameters.java +++ b/src/main/java/org/apache/commons/imaging/formats/pnm/PnmImagingParameters.java @@ -27,24 +27,54 @@ import org.apache.commons.imaging.ImagingParameters; public class PnmImagingParameters extends ImagingParameters<PnmImagingParameters> { private boolean rawBits = true; + /** * Pnm format subtype (e.g. pam, pbm, etc). */ private ImageFormats subtype; + /** + * Constructs a new instance. + */ + public PnmImagingParameters() { + // Default constructor + } + + /** + * Gets the subtype. + * + * @return the subtype. + */ public ImageFormats getSubtype() { return subtype; } + /** + * Checks if using raw bits. + * + * @return true if using raw bits, false otherwise. + */ public boolean isRawBits() { return rawBits; } + /** + * Sets whether to use raw bits. + * + * @param rawBits whether to use raw bits. + * @return this instance. + */ public PnmImagingParameters setRawBits(final boolean rawBits) { this.rawBits = rawBits; return asThis(); } + /** + * Sets the subtype. + * + * @param subtype the subtype. + * @return this instance. + */ public PnmImagingParameters setSubtype(final ImageFormats subtype) { this.subtype = subtype; return asThis(); diff --git a/src/main/java/org/apache/commons/imaging/icc/IccTagDataTypes.java b/src/main/java/org/apache/commons/imaging/icc/IccTagDataTypes.java index f337c948..c2b1948a 100644 --- a/src/main/java/org/apache/commons/imaging/icc/IccTagDataTypes.java +++ b/src/main/java/org/apache/commons/imaging/icc/IccTagDataTypes.java @@ -27,7 +27,12 @@ import java.util.logging.Logger; import org.apache.commons.imaging.ImagingException; +/** + * ICC tag data types enumeration. + */ public enum IccTagDataTypes implements IccTagDataType { + + /** Description type. */ DESC_TYPE("descType", 0x64657363) { @Override public void dump(final String prefix, final byte[] bytes) throws ImagingException, IOException { @@ -46,6 +51,7 @@ public enum IccTagDataTypes implements IccTagDataType { }, + /** Data type. */ DATA_TYPE("dataType", 0x64617461) { @Override public void dump(final String prefix, final byte[] bytes) throws ImagingException, IOException { @@ -56,6 +62,7 @@ public enum IccTagDataTypes implements IccTagDataType { }, + /** Multi-localized Unicode type. */ MULTI_LOCALIZED_UNICODE_TYPE("multiLocalizedUnicodeType", 0x6D6C7563) { @Override public void dump(final String prefix, final byte[] bytes) throws ImagingException, IOException { @@ -66,6 +73,7 @@ public enum IccTagDataTypes implements IccTagDataType { }, + /** Signature type. */ SIGNATURE_TYPE("signatureType", 0x73696720) { @Override public void dump(final String prefix, final byte[] bytes) throws ImagingException, IOException { @@ -82,6 +90,7 @@ public enum IccTagDataTypes implements IccTagDataType { }, + /** Text type. */ TEXT_TYPE("textType", 0x74657874) { @Override public void dump(final String prefix, final byte[] bytes) throws ImagingException, IOException { @@ -97,7 +106,10 @@ public enum IccTagDataTypes implements IccTagDataType { private static final Logger LOGGER = Logger.getLogger(IccTagDataTypes.class.getName()); + /** Name of the tag data type. */ public final String name; + + /** Signature of the tag data type. */ public final int signature; IccTagDataTypes(final String name, final int signature) { diff --git a/src/main/java/org/apache/commons/imaging/mylzw/MyBitInputStream.java b/src/main/java/org/apache/commons/imaging/mylzw/MyBitInputStream.java index c67168ae..43783d05 100644 --- a/src/main/java/org/apache/commons/imaging/mylzw/MyBitInputStream.java +++ b/src/main/java/org/apache/commons/imaging/mylzw/MyBitInputStream.java @@ -21,6 +21,9 @@ import java.io.IOException; import java.io.InputStream; import java.nio.ByteOrder; +/** + * Bit-oriented input stream for LZW decompression. + */ public class MyBitInputStream extends FilterInputStream { private final ByteOrder byteOrder; private final boolean tiffLZWMode; @@ -28,17 +31,32 @@ public class MyBitInputStream extends FilterInputStream { private int bitsInCache; private int bitCache; + /** + * Constructs a bit input stream. + * + * @param is input stream. + * @param byteOrder byte order. + * @param tiffLZWMode whether TIFF LZW mode. + */ public MyBitInputStream(final InputStream is, final ByteOrder byteOrder, final boolean tiffLZWMode) { super(is); this.byteOrder = byteOrder; this.tiffLZWMode = tiffLZWMode; } + /** + * Flushes the bit cache. + */ public void flushCache() { bitsInCache = 0; bitCache = 0; } + /** + * Gets the number of bytes read. + * + * @return bytes read. + */ public long getBytesRead() { return bytesRead; } @@ -48,6 +66,13 @@ public class MyBitInputStream extends FilterInputStream { return readBits(8); } + /** + * Reads specified number of bits. + * + * @param sampleBits number of bits to read. + * @return the bits as an integer. + * @throws IOException if I/O error occurs. + */ public int readBits(final int sampleBits) throws IOException { while (bitsInCache < sampleBits) { final int next = in.read(); diff --git a/src/main/java/org/apache/commons/imaging/mylzw/MyLzwDecompressor.java b/src/main/java/org/apache/commons/imaging/mylzw/MyLzwDecompressor.java index bb7b3c28..835b6ce5 100644 --- a/src/main/java/org/apache/commons/imaging/mylzw/MyLzwDecompressor.java +++ b/src/main/java/org/apache/commons/imaging/mylzw/MyLzwDecompressor.java @@ -26,12 +26,29 @@ import java.util.Arrays; import org.apache.commons.imaging.ImagingException; import org.apache.commons.imaging.common.Allocator; +/** + * LZW decompressor. + */ public final class MyLzwDecompressor { + /** + * Listener for decompression events. + */ public interface Listener { + /** + * Called for each code. + * + * @param code the code. + */ void code(int code); + /** + * Called on initialization. + * + * @param clearCode the clear code. + * @param eoiCode the end-of-information code. + */ void init(int clearCode, int eoiCode); } @@ -47,10 +64,27 @@ public final class MyLzwDecompressor { private int written; private final boolean tiffLZWMode; + /** + * Constructs a decompressor. + * + * @param initialCodeSize initial code size. + * @param byteOrder byte order. + * @param tiffLZWMode whether TIFF LZW mode. + * @throws ImagingException if error occurs. + */ public MyLzwDecompressor(final int initialCodeSize, final ByteOrder byteOrder, final boolean tiffLZWMode) throws ImagingException { this(initialCodeSize, byteOrder, tiffLZWMode, null); } + /** + * Constructs a decompressor with listener. + * + * @param initialCodeSize initial code size. + * @param byteOrder byte order. + * @param tiffLZWMode whether TIFF LZW mode. + * @param listener listener for events. + * @throws ImagingException if error occurs. + */ public MyLzwDecompressor(final int initialCodeSize, final ByteOrder byteOrder, final boolean tiffLZWMode, final Listener listener) throws ImagingException { this.listener = listener; this.byteOrder = byteOrder; @@ -102,6 +136,14 @@ public final class MyLzwDecompressor { incrementCodeSize(); } + /** + * Decompresses data. + * + * @param is input stream. + * @param expectedLength expected length. + * @return decompressed bytes. + * @throws IOException if I/O error occurs. + */ public byte[] decompress(final InputStream is, final int expectedLength) throws IOException { int code; int oldCode = -1;
