PngReader (PNGJ 2.1.1-SNAPSHOT API)

java.lang.Object
- ar.com.hjg.pngj.PngReader

Direct Known Subclasses:

PngReaderByte, PngReaderInt
```
public class PngReader
extends Object
```
Reads a PNG image (pixels and/or metadata) from a file or stream.
Each row is read as an ImageLineInt object (one int per sample), but this can be changed by setting a different ImageLineFactory
Internally, this wraps a ChunkSeqReaderPng with a BufferedStreamFeeder
The reading sequence is as follows:
1. At construction time, the header and IHDR chunk are read (basic image info)
2. Afterwards you can set some additional global options. Eg. setCrcCheckDisabled().
3. Optional: If you call getMetadata() or getChunksLisk() before start reading the rows, all the chunks before IDAT are then loaded and available
4a. The rows are read in order by calling readRow(). You can also call readRow(int) to skip rows -but you can't go backwards, at least not with this implementation. This method returns a IImageLine object which can be casted to the concrete class. This class returns by default a ImageLineInt, but this can be changed.
4b. Alternatively, you can read all rows, or a subset, in a single call: readRows(), readRows(int, int, int) ,etc. In general this consumes more memory, but for interlaced images this is equally efficient, and more so if reading a small subset of rows.
5. Reading of the last row automatically loads the trailing chunks, and ends the reader.
6. end() also loads the trailing chunks, if not done, and finishes cleanly the reading and closes the stream.
See also PngReaderInt (esentially the same as this, and slightly preferred) and PngReaderByte (uses byte instead of int to store the samples).

Field Summary

Fields
Modifier and Type	Field and Description
`protected ChunkSeqReaderPng`	`chunkseq` This object has most of the intelligence to parse the chunks and decompress the IDAT stream
`ImageInfo`	`imgInfo` Basic image info - final and inmutable.
`protected IImageLineSet<? extends IImageLine>`	`imlinesSet` Represents the set of lines (rows) being read.
`boolean`	`interlaced` flag: image was in interlaced format
`static long`	`MAX_BYTES_METADATA_DEFAULT` Defensive limit: refuse to load more than 5MB of ancillary metadata, see `setMaxBytesMetadata(long)` and also `addChunkToSkip(String)`
`static long`	`MAX_CHUNK_SIZE_SKIP` Skip ancillary chunks greater than 2MB, see `setSkipChunkMaxSize(long)`
`static long`	`MAX_TOTAL_BYTES_READ_DEFAULT` Defensive limit: refuse to read more than 900MB, can be changed with `setMaxTotalBytesRead(long)`
`protected PngMetadata`	`metadata`
`protected int`	`rowNum` Current row number (reading or read), numbered from 0
`protected BufferedStreamFeeder`	`streamFeeder` Takes bytes from the InputStream and passes it to the ChunkSeqReaderPng.

Constructor Summary

Constructors
Constructor and Description
`PngReader(File file)` Constructs a PngReader opening a file.
`PngReader(InputStream inputStream)` Constructs a PngReader object from a stream, with default options.
`PngReader(InputStream inputStream, boolean shouldCloseStream)` Same as `PngReader(InputStream)` but allows to specify early if the stream must be closed

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addChunkToSkip(String chunkToSkip)`
`void`	`close()` Releases resources, and closes stream if corresponds.
`protected ChunkSeqReaderPng`	`createChunkSeqReader()` called on construction time.
`protected IImageLineSet<? extends IImageLine>`	`createLineSet(boolean singleCursor, int nlines, int noffset, int step)` By default this uses the factory (which, by default creates ImageLineInt).
`void`	`dontSkipChunk(String chunkToSkip)`
`void`	`end()` Reads till end of PNG stream and call `close()` This should normally be called after reading the pixel data, to read the trailing chunks and close the stream.
`ChunkSeqReaderPng`	`getChunkseq()` Gets wrapped `ChunkSeqReaderPng` object
`ChunksList`	`getChunksList()` All loaded chunks (metada).
`ChunksList`	`getChunksList(boolean forceLoadingOfFirstChunks)`
`ImageInfo`	`getCurImgInfo()`
`ImageInfo`	`getImgInfo()`
`PngMetadata`	`getMetadata()` High level wrapper over chunksList
`String`	`getSimpleDigestHex()` Pseudo 64-bits digest computed over the basic image properties and the raw pixels data: it should coincide for equivalent images encoded with different filters and compressors; but will not coincide for interlaced/non-interlaced; also, this does not take into account the palette info.
`boolean`	`hasMoreRows()` True if last row has not yet been read
`boolean`	`isInterlaced()` Interlaced PNG is accepted -though not welcomed- now...
`protected void`	`loadAllInterlaced(int nRows, int rowOffset, int rowStep)`
`void`	`prepareSimpleDigestComputation()` Enables and prepare the simple digest computation.
`protected void`	`readFirstChunks()` Reads chunks before first IDAT.
`IImageLine`	`readRow()` Reads next row.
`IImageLine`	`readRow(int nrow)` The row number is mostly meant as a check, the rows must be called in ascending order (not necessarily consecutive)
`IImageLineSet<? extends IImageLine>`	`readRows()` Reads all rows in a ImageLineSet This is handy, but less memory-efficient (except for interlaced)
`IImageLineSet<? extends IImageLine>`	`readRows(int nRows, int rowOffset, int rowStep)` Reads a subset of rows.
`void`	`readSkippingAllRows()` Reads all the (remaining) file, skipping the pixels data.
`void`	`setChunkLoadBehaviour(ChunkLoadBehaviour chunkLoadBehaviour)` Determines which ancillary chunks (metadata) are to be loaded and which skipped.
`void`	`setChunksToSkip(String... chunksToSkip)` Chunks ids to be skipped.
`void`	`setCrcCheckDisabled()` Disables the CRC integrity check in IDAT chunks and ancillary chunks, this gives a slight increase in reading speed for big files
`void`	`setLineSetFactory(IImageLineSetFactory<? extends IImageLine> factory)` Sets the factory that creates the ImageLine.
`void`	`setMaxBytesMetadata(long maxBytesMetadata)` Set total maximum bytes to load from ancillary chunks (0: unlimited; default: 5Mb). If exceeded, some chunks will be skipped
`void`	`setMaxTotalBytesRead(long maxTotalBytesToRead)` Set total maximum bytes to read (0: unlimited; default: 200MB).
`void`	`setShouldCloseStream(boolean shouldCloseStream)` if true, input stream will be closed after ending read
`void`	`setSkipChunkMaxSize(long skipChunkMaxSize)` Set maximum size in bytes for individual ancillary chunks (0: unlimited; default: 2MB).
`String`	`toString()` Basic info, for debugging.
`String`	`toStringCompact()` Basic info, in a compact format, apt for scripting COLSxROWS[dBITDEPTH][a][p][g][i] ( the default dBITDEPTH='d8' is ommited)

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - MAX_TOTAL_BYTES_READ_DEFAULT
```
public static final long MAX_TOTAL_BYTES_READ_DEFAULT
```
    Defensive limit: refuse to read more than 900MB, can be changed with setMaxTotalBytesRead(long)
    
    See Also:
    Constant Field Values
  - MAX_BYTES_METADATA_DEFAULT
```
public static final long MAX_BYTES_METADATA_DEFAULT
```
    Defensive limit: refuse to load more than 5MB of ancillary metadata, see setMaxBytesMetadata(long) and also addChunkToSkip(String)
    
    See Also:
    Constant Field Values
  - MAX_CHUNK_SIZE_SKIP
```
public static final long MAX_CHUNK_SIZE_SKIP
```
    Skip ancillary chunks greater than 2MB, see setSkipChunkMaxSize(long)
    
    See Also:
    Constant Field Values
  - imgInfo
```
public final ImageInfo imgInfo
```
    Basic image info - final and inmutable.
  - interlaced
```
public final boolean interlaced
```
    flag: image was in interlaced format
  - chunkseq
```
protected final ChunkSeqReaderPng chunkseq
```
    This object has most of the intelligence to parse the chunks and decompress the IDAT stream
  - streamFeeder
```
protected final BufferedStreamFeeder streamFeeder
```
    Takes bytes from the InputStream and passes it to the ChunkSeqReaderPng. Never null.
  - metadata
```
protected final PngMetadata metadata
```
    See Also:
    getMetadata()
  - rowNum
```
protected int rowNum
```
    Current row number (reading or read), numbered from 0
  - imlinesSet
```
protected IImageLineSet<? extends IImageLine> imlinesSet
```
    Represents the set of lines (rows) being read. Normally this works as a cursor, storing only one (the current) row. This stores several (perhaps all) rows only if calling readRows() or for interlaced images (this later is transparent to the user)
- Constructor Detail
  - PngReader
```
public PngReader(InputStream inputStream)
```
    Constructs a PngReader object from a stream, with default options. This reads the signature and the first IHDR chunk only.
    Warning: In case of exception the stream is NOT closed.
    Warning: By default the stream will be closed when this object is close()d. See PngReader(InputStream,boolean) or setShouldCloseStream(boolean)
    
    Parameters:
    inputStream - PNG stream
  - PngReader
```
public PngReader(InputStream inputStream,
         boolean shouldCloseStream)
```
    Same as PngReader(InputStream) but allows to specify early if the stream must be closed
    
    Parameters:
    inputStream -
    shouldCloseStream - The stream will be closed in case of exception (constructor included) or normal termination.
  - PngReader
```
public PngReader(File file)
```
    Constructs a PngReader opening a file. Sets shouldCloseStream=true, so that the stream will be closed with this object.
    
    Parameters:
    file - PNG image file
- Method Detail
  - readFirstChunks
```
protected void readFirstChunks()
```
    Reads chunks before first IDAT. Normally this is called automatically
    Position before: after IDHR (crc included) Position after: just after the first IDAT chunk id
    This can be called several times (tentatively), it does nothing if already run
    (Note: when should this be called? in the constructor? hardly, because we loose the opportunity to call setChunkLoadBehaviour() and perhaps other settings before reading the first row? but sometimes we want to access some metadata (plte, phys) before. Because of this, this method can be called explicitly but is also called implicititly in some methods (getMetatada(), getChunksList())
  - setChunkLoadBehaviour
```
public void setChunkLoadBehaviour(ChunkLoadBehaviour chunkLoadBehaviour)
```
    Determines which ancillary chunks (metadata) are to be loaded and which skipped.
    Additional restrictions may apply. See also setChunksToSkip(String...), addChunkToSkip(String), setMaxBytesMetadata(long), setSkipChunkMaxSize(long)
    
    Parameters:
    chunkLoadBehaviour - ChunkLoadBehaviour
  - getChunksList
```
public ChunksList getChunksList()
```
    All loaded chunks (metada). If we have not yet end reading the image, this will include only the chunks before the pixels data (IDAT)
    Critical chunks are included, except that all IDAT chunks appearance are replaced by a single dummy-marker IDAT chunk. These might be copied to the PngWriter
    
    See Also:
    getMetadata()
  - getChunksList
```
public ChunksList getChunksList(boolean forceLoadingOfFirstChunks)
```
  - getMetadata
```
public PngMetadata getMetadata()
```
    High level wrapper over chunksList
    
    See Also:
    getChunksList()
  - readRow
```
public IImageLine readRow()
```
    Reads next row. The caller must know that there are more rows to read.
    
    Returns:
    Never null. Throws PngInputException if no more
  - hasMoreRows
```
public boolean hasMoreRows()
```
    True if last row has not yet been read
  - readRow
```
public IImageLine readRow(int nrow)
```
    The row number is mostly meant as a check, the rows must be called in ascending order (not necessarily consecutive)
  - readRows
```
public IImageLineSet<? extends IImageLine> readRows()
```
    Reads all rows in a ImageLineSet This is handy, but less memory-efficient (except for interlaced)
  - readRows
```
public IImageLineSet<? extends IImageLine> readRows(int nRows,
                                           int rowOffset,
                                           int rowStep)
```
    Reads a subset of rows.
    This method should called once, and not be mixed with readRow()
    
    Parameters:
    nRows - how many rows to read (default: imageInfo.rows; negative: autocompute)
    rowOffset - rows to skip (default:0)
    rowStep - step between rows to load( default:1)
  - setLineSetFactory
```
public void setLineSetFactory(IImageLineSetFactory<? extends IImageLine> factory)
```
    Sets the factory that creates the ImageLine. By default, this implementation uses ImageLineInt but this can be changed (at construction time or later) by calling this method.
    See also createLineSet(boolean, int, int, int)
    
    Parameters:
    factory -
  - createLineSet
```
protected IImageLineSet<? extends IImageLine> createLineSet(boolean singleCursor,
                                                int nlines,
                                                int noffset,
                                                int step)
```
    By default this uses the factory (which, by default creates ImageLineInt). You should rarely override this.
    See doc in IImageLineSetFactory.create(ImageInfo, boolean, int, int, int)
  - loadAllInterlaced
```
protected void loadAllInterlaced(int nRows,
                     int rowOffset,
                     int rowStep)
```
  - readSkippingAllRows
```
public void readSkippingAllRows()
```
    Reads all the (remaining) file, skipping the pixels data. This is much more efficient that calling readRow(), specially for big files (about 10 times faster!), because it doesn't even decompress the IDAT stream and disables CRC check Use this if you are not interested in reading pixels,only metadata.
  - setMaxTotalBytesRead
```
public void setMaxTotalBytesRead(long maxTotalBytesToRead)
```
    Set total maximum bytes to read (0: unlimited; default: 200MB).
    These are the bytes read (not loaded) in the input stream. If exceeded, an exception will be thrown.
  - setMaxBytesMetadata
```
public void setMaxBytesMetadata(long maxBytesMetadata)
```
    Set total maximum bytes to load from ancillary chunks (0: unlimited; default: 5Mb).
    If exceeded, some chunks will be skipped
  - setSkipChunkMaxSize
```
public void setSkipChunkMaxSize(long skipChunkMaxSize)
```
    Set maximum size in bytes for individual ancillary chunks (0: unlimited; default: 2MB).
    Chunks exceeding this length will be skipped (the CRC will not be checked) and the chunk will be saved as a PngChunkSkipped object. See also setSkipChunkIds
  - setChunksToSkip
```
public void setChunksToSkip(String... chunksToSkip)
```
    Chunks ids to be skipped.
    These chunks will be skipped (the CRC will not be checked) and the chunk will be saved as a PngChunkSkipped object. See also setSkipChunkMaxSize
  - addChunkToSkip
```
public void addChunkToSkip(String chunkToSkip)
```
  - dontSkipChunk
```
public void dontSkipChunk(String chunkToSkip)
```
  - setShouldCloseStream
```
public void setShouldCloseStream(boolean shouldCloseStream)
```
    if true, input stream will be closed after ending read
    default=true
  - end
```
public void end()
```
    Reads till end of PNG stream and call close() This should normally be called after reading the pixel data, to read the trailing chunks and close the stream. But it can be called at anytime. This will also read the first chunks if not still read, and skip pixels (IDAT) if still pending. If you want to read all metadata skipping pixels, readSkippingAllRows() is a little more efficient. If you want to abort immediately, call instead close()
  - close
```
public void close()
```
    Releases resources, and closes stream if corresponds. Idempotent, secure, no exceptions. This can be also called for abort. It is recommended to call this in case of exceptions
  - isInterlaced
```
public boolean isInterlaced()
```
    Interlaced PNG is accepted -though not welcomed- now...
  - setCrcCheckDisabled
```
public void setCrcCheckDisabled()
```
    Disables the CRC integrity check in IDAT chunks and ancillary chunks, this gives a slight increase in reading speed for big files
  - getChunkseq
```
public ChunkSeqReaderPng getChunkseq()
```
    Gets wrapped ChunkSeqReaderPng object
  - createChunkSeqReader
```
protected ChunkSeqReaderPng createChunkSeqReader()
```
    called on construction time. Override if you want an alternative class
  - prepareSimpleDigestComputation
```
public void prepareSimpleDigestComputation()
```
    Enables and prepare the simple digest computation. Must be called before reading the pixels. See getSimpleDigestHex()
  - getSimpleDigestHex
```
public String getSimpleDigestHex()
```
    Pseudo 64-bits digest computed over the basic image properties and the raw pixels data: it should coincide for equivalent images encoded with different filters and compressors; but will not coincide for interlaced/non-interlaced; also, this does not take into account the palette info. This will be valid only if prepareSimpleDigestComputation() has been called, and all rows have been read. Not fool-proof, not cryptografically secure, only for informal testing and duplicates detection.
    
    Returns:
    A 64-digest in hexadecimal
  - toString
```
public String toString()
```
    Basic info, for debugging.
    
    Overrides:
    
    toString in class Object
  - toStringCompact
```
public String toStringCompact()
```
    Basic info, in a compact format, apt for scripting COLSxROWS[dBITDEPTH][a][p][g][i] ( the default dBITDEPTH='d8' is ommited)
  - getImgInfo
```
public ImageInfo getImgInfo()
```
  - getCurImgInfo
```
public ImageInfo getCurImgInfo()
```

Class PngReader

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_TOTAL_BYTES_READ_DEFAULT

MAX_BYTES_METADATA_DEFAULT

MAX_CHUNK_SIZE_SKIP

imgInfo

interlaced

chunkseq

streamFeeder

metadata

rowNum

imlinesSet

Constructor Detail

PngReader

PngReader

PngReader

Method Detail

readFirstChunks

setChunkLoadBehaviour

getChunksList

getChunksList

getMetadata

readRow

hasMoreRows

readRow

readRows

readRows

setLineSetFactory

createLineSet

loadAllInterlaced

readSkippingAllRows

setMaxTotalBytesRead

setMaxBytesMetadata

setSkipChunkMaxSize

setChunksToSkip

addChunkToSkip

dontSkipChunk

setShouldCloseStream

end

close

isInterlaced

setCrcCheckDisabled

getChunkseq

createChunkSeqReader

prepareSimpleDigestComputation

getSimpleDigestHex

toString

toStringCompact

getImgInfo

getCurImgInfo