png-es6

png-es6

installation

• png.min.js 15kb, (6kb gzipped)
• png-with-worker.min.js 20kb, (7kb gzipped)
• png.es6.min.js 15kb, (5kb gzipped)
• png-es6-master.zip

npm install png-es6

see the dist folder for more versions.

what is it?

a png decoder in javascript for the browser. this module is mainly focussed on a small file size and web worker support.

for node, you can use png-js instead. there exist plenty of other, more feature rich png decoders.

examples

you can find more examples for using this library in the browser as well as in web workers in the examples folder of this repository.

how to use it

this library can be used in web browsers directly as well as in web workers (with limited functionality).

it supports loading as an AMD module, as a CommonJS module or a global variable.

a simple example

<script src="png-browser-with.js"></script>
<script>
var canvas = document.getElementsByTagName('canvas')[0];
	
png.fromURL( 'images/djay.png' )
	.then( pngData => {
		png.renderToCanvas( pngData, canvas, true );
	} );

as you can see, there are two calls happening:

1. first, an image is loaded and parsed
2. the the image is rendered to the canvas element

for an explanation of all available methods and parameters, check out the reference section below.

all input methods are asynchronous and are using promises for flow control.

promises are not yet supported by all browsers. however, this library does not include a polyfill for promises or web workers, so you may have to include them separately.

reference

pngData

the parser returns the data in the following format:

{
	animation: { // for non-animated pngs, this is null
		currentFrameIndex: 17,
		currentPlayCount: 2,
		frames: [
			{
				blendOp: 0,
				data: Array [120, 156, 237, 189, …],
				decoded: Uint8Array [0, 0, 0, …],
				delay: 40,
				disposeOp: 1,
				height: 120,
				image: HTMLImageElement
				width: 166,
				xOffset: 0
				yOffset: 0
			}
		],
		numFrames: 21,
		numPlays: Infinity,
	},
	bits: 8,
	colorSpace: "DeviceRGB",
	colorType: 6,
	colors: 3,
	compressionMethod: 0,
	data: Uint8Array [137, 80, 78, …],
	decodedPalette: Uint8Array [ ],
	filterMethod: 0,
	hasAlphaChannel: true,
	height: 120,
	imgData: Uint8Array [ ],
	interlaceMethod: 0,
	palette: Array [ ],
	pixelBitlength: 32,
	pixels: Uint8Array [ ],
	pos: 288309,
	text: {
		Software: "Adobe ImageReady"
	},
	transparency: { },
	width: 166
}

fromURL

fromURL can take the URL of a PNG image as parameter. it returns a promise that resolves a pngData object

example:

import { fromURL } from 'png-es6';

fromURL( 'my-png.png' )
	.then( pngData => {
		console.log( 'PNG loaded and parsed', pngData );
	} );

fromData

fromData can take an Uint8Array

example:

import { fromData } from 'png-es6';

// load a png and convert it into an ArrayBuffer
fetch( 'my-png.png' )
	.then( res => res.arrayBuffer() )
	.then( arrayBuffer => new Uint8Array( arrayBuffer ) )
	.then( data => fromData )
	.then( pngData => {
		console.log( 'PNG parsed', pngData );
	} );

toImageData

toImageData takes a pngData object and converts it into an ImageData object.

ImageData is not available in web workers, so in web workers the method returns an object instead: { width: 100, height: 100, data: UInt8Array [ ] }

example:

renderToCanvas

renderToCanvas takes pngData object and a canvas element and draws the png data on the canvas.

optional arguments:

• resizeCanvas boolean: resize canvas to fit pngData (default: false)
• preventAnimation boolean: prevent animation on canvas for APNGs (default: false)

by default, if the image is an animated png, it starts playing the animation.

example:

var canvas = document.getElementsByTagName('canvas')[0];
	
png.fromURL( 'images/djay.png' )
	.then( pngData => {
		png.renderToCanvas( pngData, canvas, true );
	} );

this method is not available in web workers.

renderToContext

renderToContext takes a pngData object and a CanvasContext2D Object and draws the image on the context.

example:

var canvas = document.getElementsByTagName('canvas')[0];
var ctx = canvas.getContext( '2d' );
	
png.fromURL( 'images/djay.png' )
	.then( pngData => {
		png.renderToContext( pngData, ctx, true );
	} );

this method is not available in web workers.

animateOnContext

animateOnContext takes a CanvasContext2D Object and a pngData object and draws the image on the context.

if the image is an animated png, it plays the animation by default.

example:

var canvas = document.getElementsByTagName('canvas')[0];
var ctx = canvas.getContext( '2d' );
	
png.fromURL( 'images/djay.png' )
	.then( pngData => {
		png.renderToContext( pngData, ctx, true );
	} );

this method is not available in web workers.

missing something?

found a bug? missing a feature? are you using this library in an interesting project? take a look at the issues, open a pull request and let me know.

most importantly

thank you for taking a look at this repo. have a great day :)