Uttori ImagePNG

A PNG Decoder and meta data reading utility.

Install

npm install --save @uttori/image-png

Config

{
}

Example

const image_data = await FileUtility.readFile('./test/assets/PngSuite', 'oi1n0g16', 'png', null);
const image = ImagePNG.fromFile(image_data);
image.decodePixels();
const length = image.pixels.length;
➜ 6144
const pixel = image.getPixel(0, 0);
➜ [255, 255, 255, 255]

API Reference

Classes

ImagePNG ⇐ DataBuffer: PNG Decoder

Functions

debug() : function

ImagePNG ⇐ `DataBuffer`

PNG Decoder

Kind: global class
Extends: DataBuffer
See

Chunk Specifications
The Art of PNG Glitch
PngSuite, test-suite for PNG
Chunk Specifications (LibPNG)
Chunk Specifications (W3C)
PNGs containing a chunk with length 0xffffffff
PNG files can be animated via network latency
TweakPNG

Properties

Name	Type	Description
width	`number`	Pixel Width
height	`number`	Pixel Height
bitDepth	`number`	Image Bit Depth, one of: 1, 2, 4, 8, 16
colorType	`number`	= Defines pixel structure, one of: 0, 2, 3, 4, 6
compressionMethod	`number`	Type of compression, always 0
filterMethod	`number`	Type of filtering, always 0
interlaceMethod	`number`	Type of interlacing, one of: 0, 1
colors	`number`	Number of bytes for each pixel
alpha	`boolean`	True when the image has an alpha transparency layer
palette	`Array.<number>` \| `Uint8Array`	Raw Color data
pixels	`Uint8Array`	Raw Image Pixel data
transparency	`Uint8Array`	Raw Transparency data
physical	`object`	Object containing physical dimension information
physical.width	`number`	Physical Dimension Width
physical.height	`number`	Physical Dimension Height
physical.unit	`number`	Physical Dimension Units, with 0 being unknown and 1 being Meters
dataChunks	`Array.<Uint8Array>`	Image Data pieces
header	`Uint8Array`	PNG Signature from the data

ImagePNG ⇐ DataBuffer
- new ImagePNG(input)
- instance
  - .width : number
  - .height : number
  - .bitDepth : number
  - .colorType : number
  - .compressionMethod : number
  - .filterMethod : number
  - .interlaceMethod : number
  - .colors : number
  - .alpha : boolean
  - .palette : Array.<number> | Uint8Array
  - .pixels : Uint8Array
  - .transparency : Uint8Array
  - .physical : object
    - .width : number
    - .height : number
    - .unit : number
  - .dataChunks : Array.<Uint8Array>
  - .header : Array | Uint8Array
  - .setBitDepth(bitDepth)
  - .setColorType(colorType)
  - .setCompressionMethod(compressionMethod)
  - .setFilterMethod(filterMethod)
  - .setInterlaceMethod(interlaceMethod)
  - .setPalette(palette)
  - .getPixel(x, y) ⇒ Array
  - .parse()
  - .decodeHeader()
  - .decodeChunk() ⇒ string
  - .decodeIHDR(chunk)
  - .decodePLTE(chunk)
  - .decodeIDAT(chunk)
  - .decodeTRNS(chunk)
  - .decodePHYS(chunk)
  - .decodeIEND(_chunk)
  - .decodePixels()
  - .interlaceNone(data)
  - .unFilterNone(scanline, bpp, offset, length)
  - .unFilterSub(scanline, bpp, offset, length)
- static
  - .fromFile(data) ⇒ ImagePNG
  - .fromBuffer(buffer) ⇒ ImagePNG

new ImagePNG(input)

Creates a new ImagePNG.

Param	Type	Description
input	`Array` \| `ArrayBuffer` \| `Buffer` \| `DataBuffer` \| `Int8Array` \| `Int16Array` \| `Int32Array` \| `number` \| `string` \| `Uint8Array` \| `Uint16Array` \| `Uint32Array`	The data to process.

Example (new ImagePNG(list, options))

const image_data = await FileUtility.readFile('./test/assets/PngSuite', 'oi1n0g16', 'png', null);
const image = ImagePNG.fromFile(image_data);
image.decodePixels();
const length = image.pixels.length;
 ➜ 6144
const pixel = image.getPixel(0, 0);
 ➜ [255, 255, 255, 255]

imagePNG.width : `number`

Pixel Width

Kind: instance property of ImagePNG

imagePNG.height : `number`

Pixel Height

Kind: instance property of ImagePNG

imagePNG.bitDepth : `number`

Image Bit Depth, one of: 1, 2, 4, 8, 16

Kind: instance property of ImagePNG

imagePNG.colorType : `number`

Defines pixel structure, one of: 0, 2, 3, 4, 6

Kind: instance property of ImagePNG

imagePNG.compressionMethod : `number`

Type of compression, always 0

Kind: instance property of ImagePNG

imagePNG.filterMethod : `number`

Type of filtering, always 0

Kind: instance property of ImagePNG

imagePNG.interlaceMethod : `number`

Type of interlacing, one of: 0, 1

Kind: instance property of ImagePNG

imagePNG.colors : `number`

Number of bytes for each pixel

Kind: instance property of ImagePNG

imagePNG.alpha : `boolean`

True when the image has an alpha transparency layer

Kind: instance property of ImagePNG

imagePNG.palette : `Array.<number>` | `Uint8Array`

Raw Color data

Kind: instance property of ImagePNG

imagePNG.pixels : `Uint8Array`

Raw Image Pixel data

Kind: instance property of ImagePNG

imagePNG.transparency : `Uint8Array`

Raw Transparency data

Kind: instance property of ImagePNG

imagePNG.physical : `object`

physical - Object containing physical dimension information

Kind: instance property of ImagePNG

.physical : object
- .width : number
- .height : number
- .unit : number

physical.width : `number`

Physical Dimension Width

Kind: static property of physical

physical.height : `number`

Physical Dimension Height

Kind: static property of physical

physical.unit : `number`

Physical Dimension Units, with 0 being unknown and 1 being Meters

Kind: static property of physical

imagePNG.dataChunks : `Array.<Uint8Array>`

Image Data pieces

Kind: instance property of ImagePNG

imagePNG.header : `Array` | `Uint8Array`

PNG Signature from the data

Kind: instance property of ImagePNG

imagePNG.setBitDepth(bitDepth)

Sets the bitDepth on the ImagePNG instance.

Kind: instance method of ImagePNG

Param	Type	Description
bitDepth	`number`	The bitDepth to set, one of: 1, 2, 4, 8, 16

imagePNG.setColorType(colorType)

Sets the colorType on the ImagePNG instance. Both color and alpha properties are inferred from the colorType.

Color Type	Allowed Bit Depths	Interpretation
0	1, 2, 4, 8, 16	Each pixel is a grayscale sample.
2	8, 16	Each pixel is an R, G, B triple.
3	1, 2, 4, 8	Each pixel is a palette index; a `PLTE` chunk must appear.
4	8, 16	Each pixel is a grayscale sample, followed by an alpha sample.
6	8, 16	Each pixel is an R, G, B triple, followed by an alpha sample.

Kind: instance method of ImagePNG
Throws:

Error Invalid Color Type, anything other than 0, 2, 3, 4, 6

Param	Type	Description
colorType	`number`	The colorType to set, one of: 0, 2, 3, 4, 6

imagePNG.setCompressionMethod(compressionMethod)

Sets the compressionMethod on the ImagePNG instance. The compressionMethod should always be 0.

Kind: instance method of ImagePNG
Throws:

Error Unsupported Compression Method, anything other than 0

Param	Type	Description
compressionMethod	`number`	The compressionMethod to set, always 0

imagePNG.setFilterMethod(filterMethod)

Sets the filterMethod on the ImagePNG instance. The filterMethod should always be 0.

Kind: instance method of ImagePNG
Throws:

Error Unsupported Filter Method, anything other than 0

Param	Type	Description
filterMethod	`number`	The filterMethod to set, always 0

imagePNG.setInterlaceMethod(interlaceMethod)

Sets the interlaceMethod on the ImagePNG instance. The interlaceMethod should always be 0 or 1.

Kind: instance method of ImagePNG
Throws:

Error Unsupported Interlace Method, anything other than 0 or 1

Param	Type	Description
interlaceMethod	`number`	The filterMethod to set, always 0 or 1

imagePNG.setPalette(palette)

Sets the palette on the ImagePNG instance.

Kind: instance method of ImagePNG
Throws:

Error No colors in the palette
Error Too many colors for the current bit depth

Param	Type	Description
palette	`Array.<number>` \| `Uint8Array`	The palette to set

imagePNG.getPixel(x, y) ⇒ `Array`

Get the pixel color at a specified x, y location.

Kind: instance method of ImagePNG
Returns: Array - the color as [red, green, blue, alpha]
Throws:

Error x is out of bound for the image
Error y is out of bound for the image
Error Unknown color types

Param	Type	Description
x	`number`	The hoizontal offset to read.
y	`number`	The vertical offset to read.

imagePNG.parse()

Parse the PNG file, decoding the supported chunks.

Kind: instance method of ImagePNG

imagePNG.decodeHeader()

Decodes and validates PNG Header. Signature (Decimal): [137, 80, 78, 71, 13, 10, 26, 10] Signature (Hexadecimal): [89, 50, 4E, 47, 0D, 0A, 1A, 0A] Signature (ASCII): [\211, P, N, G, \r, \n, \032, \n]

Kind: instance method of ImagePNG
Throws:

Error Missing or invalid PNG header

See: PNG Signature

imagePNG.decodeChunk() ⇒ `string`

Decodes the chunk type, and attempts to parse that chunk if supported. Supported Chunk Types: IHDR, PLTE, IDAT, IEND, tRNS, pHYs

Chunk Structure: Length: 4 bytes Type: 4 bytes (IHDR, PLTE, IDAT, IEND, etc.) Chunk: {length} bytes CRC: 4 bytes

Kind: instance method of ImagePNG
Returns: string - Chunk Type
Throws:

Error Invalid Chunk Length when less than 0

See: Chunk Layout

imagePNG.decodeIHDR(chunk)

Decode the IHDR (Image header) chunk. Should be the first chunk in the data stream.

Width: 4 bytes Height: 4 bytes Bit Depth: 1 byte Colour Type: 1 byte Compression Method: 1 byte Filter Method: 1 byte Interlace Method: 1 byte

Kind: instance method of ImagePNG
See

Image Header
Image Header

Param	Type	Description
chunk	`Uint8Array`	Data Blob

imagePNG.decodePLTE(chunk)

Decode the PLTE (Palette) chunk. The PLTE chunk contains from 1 to 256 palette entries, each a three-byte series of the form. The number of entries is determined from the chunk length. A chunk length not divisible by 3 is an error.

Kind: instance method of ImagePNG
See: Palette

Param	Type	Description
chunk	`Uint8Array`	Data Blob

imagePNG.decodeIDAT(chunk)

Decode the IDAT (Image Data) chunk. The IDAT chunk contains the actual image data which is the output stream of the compression algorithm.

Kind: instance method of ImagePNG
See: Image Data

Param	Type	Description
chunk	`Uint8Array`	Data Blob

imagePNG.decodeTRNS(chunk)

Decode the tRNS (Transparency) chunk. The tRNS chunk specifies that the image uses simple transparency: either alpha values associated with palette entries (for indexed-color images) or a single transparent color (for grayscale and truecolor images). Although simple transparency is not as elegant as the full alpha channel, it requires less storage space and is sufficient for many common cases.

Kind: instance method of ImagePNG
See: Transparency

Param	Type	Description
chunk	`Uint8Array`	Data Blob

imagePNG.decodePHYS(chunk)

Decode the pHYs (Pixel Dimensions) chunk. The pHYs chunk specifies the intended pixel size or aspect ratio for display of the image. When the unit specifier is 0, the pHYs chunk defines pixel aspect ratio only; the actual size of the pixels remains unspecified. If the pHYs chunk is not present, pixels are assumed to be square, and the physical size of each pixel is unspecified.

Structure: Pixels per unit, X axis: 4 bytes (unsigned integer) Pixels per unit, Y axis: 4 bytes (unsigned integer) Unit specifier: 1 byte 0: unit is unknown 1: unit is the meter

Kind: instance method of ImagePNG
See: Pixel Dimensions

Param	Type	Description
chunk	`Uint8Array`	Data Blob

imagePNG.decodeIEND(_chunk)

Decode the IEND (Image trailer) chunk. The IEND chunk marks the end of the PNG DataBuffer. The chunk's data field is empty.

Kind: instance method of ImagePNG
See: Image Trailer

Param	Type	Description
_chunk	`Uint8Array`	Unused.

imagePNG.decodePixels()

Uncompress IDAT chunks.

Kind: instance method of ImagePNG
Throws:

Error No IDAT chunks to decode
Error Deinterlacing Error
Error Inflating Error
Error Adam7 interlaced format is unsupported

imagePNG.interlaceNone(data)

Deinterlace with no interlacing.

Kind: instance method of ImagePNG
See: PNG Filters

Param	Type	Description
data	`Buffer`	Data to deinterlace.

imagePNG.unFilterNone(scanline, bpp, offset, length)

No filtering, direct copy.

Kind: instance method of ImagePNG

Param	Type	Description
scanline	`Array` \| `Uint8Array`	Scanline to search for pixels in.
bpp	`number`	Bytes Per Pixel
offset	`number`	Offset
length	`number`	Length

imagePNG.unFilterSub(scanline, bpp, offset, length)

The Sub() filter transmits the difference between each byte and the value of the corresponding byte of the prior pixel. Sub(x) = Raw(x) + Raw(x - bpp)

Kind: instance method of ImagePNG

Param	Type	Description
scanline	`Array` \| `Uint8Array`	Scanline to search for pixels in.
bpp	`number`	Bytes Per Pixel
offset	`number`	Offset
length	`number`	Length

ImagePNG.fromFile(data) ⇒ `ImagePNG`

Creates a new ImagePNG from file data.

Kind: static method of ImagePNG
Returns: ImagePNG - the new ImagePNG instance for the provided file data

Param	Type	Description
data	`Array` \| `ArrayBuffer` \| `Buffer` \| `DataBuffer` \| `Int8Array` \| `Int16Array` \| `Int32Array` \| `number` \| `string` \| `Uint8Array` \| `Uint16Array` \| `Uint32Array`	The data of the image to process.

ImagePNG.fromBuffer(buffer) ⇒ `ImagePNG`

Creates a new ImagePNG from a DataBuffer.

Kind: static method of ImagePNG
Returns: ImagePNG - the new ImagePNG instance for the provided DataBuffer

Param	Type	Description
buffer	`DataBuffer`	The DataBuffer of the image to process.

debug() : `function`

Kind: global function

Tests

To run the test suite, first install the dependencies, then run npm test:

npm install
npm test
DEBUG=Uttori* npm test

Contributors

Matthew Callis

License

MIT

Files

README.md

Latest commit

History

README.md

File metadata and controls

Uttori ImagePNG

Install

Config

Example

API Reference

Classes

Functions

ImagePNG ⇐ DataBuffer

new ImagePNG(input)

imagePNG.width : number

imagePNG.height : number

imagePNG.bitDepth : number

imagePNG.colorType : number

imagePNG.compressionMethod : number

imagePNG.filterMethod : number

imagePNG.interlaceMethod : number

imagePNG.colors : number

imagePNG.alpha : boolean

imagePNG.palette : Array.<number> | Uint8Array

imagePNG.pixels : Uint8Array

imagePNG.transparency : Uint8Array

imagePNG.physical : object

physical.width : number

physical.height : number

physical.unit : number

imagePNG.dataChunks : Array.<Uint8Array>

imagePNG.header : Array | Uint8Array

imagePNG.setBitDepth(bitDepth)

imagePNG.setColorType(colorType)

imagePNG.setCompressionMethod(compressionMethod)

imagePNG.setFilterMethod(filterMethod)

imagePNG.setInterlaceMethod(interlaceMethod)

imagePNG.setPalette(palette)

imagePNG.getPixel(x, y) ⇒ Array

imagePNG.parse()

imagePNG.decodeHeader()

imagePNG.decodeChunk() ⇒ string

imagePNG.decodeIHDR(chunk)

imagePNG.decodePLTE(chunk)

imagePNG.decodeIDAT(chunk)

imagePNG.decodeTRNS(chunk)

imagePNG.decodePHYS(chunk)

imagePNG.decodeIEND(_chunk)

imagePNG.decodePixels()

imagePNG.interlaceNone(data)

imagePNG.unFilterNone(scanline, bpp, offset, length)

imagePNG.unFilterSub(scanline, bpp, offset, length)

ImagePNG.fromFile(data) ⇒ ImagePNG

ImagePNG.fromBuffer(buffer) ⇒ ImagePNG

debug() : function

Tests

Contributors

License

ImagePNG ⇐ `DataBuffer`

imagePNG.width : `number`

imagePNG.height : `number`

imagePNG.bitDepth : `number`

imagePNG.colorType : `number`

imagePNG.compressionMethod : `number`

imagePNG.filterMethod : `number`

imagePNG.interlaceMethod : `number`

imagePNG.colors : `number`

imagePNG.alpha : `boolean`

imagePNG.palette : `Array.<number>` | `Uint8Array`

imagePNG.pixels : `Uint8Array`

imagePNG.transparency : `Uint8Array`

imagePNG.physical : `object`

physical.width : `number`

physical.height : `number`

physical.unit : `number`

imagePNG.dataChunks : `Array.<Uint8Array>`

imagePNG.header : `Array` | `Uint8Array`

imagePNG.getPixel(x, y) ⇒ `Array`

imagePNG.decodeChunk() ⇒ `string`

ImagePNG.fromFile(data) ⇒ `ImagePNG`

ImagePNG.fromBuffer(buffer) ⇒ `ImagePNG`

debug() : `function`