png-js

This is a modified version of png.js that is intended to be used for palette swapping within the browser.

NOTE: Only supports indexed PNGs for obvious reasons. All others will cause IndexedPNG to throw during construction.

Usage

The following shows the process of loading a PNG file and rendering it to a canvas with its palette data reversed.

import { IndexedPNG }   from '@kettek/png-js/src'
import { readFile   }   from 'fs'

readFile("my_png.png", (err, data) => {
    if (err) throw err
    
    // Create an IndexedPNG object from our data.
    let png = new IndexedPNG(data)
    
    // Preemptively decode PNG data (optional).
    png.decode()
    
    // Convert our PNG data into an ImageData, usable by a Canvas. Passed options provide a reversed palette and a clipping.
    png.toImageData({
      palette: png.decodePalette().reverse(),
      clip: {
        x: 16,
        y: 16,
        w: 32,
        h: 32
      }
    })
    .then(imageData => {
      // This presumes at least one canvas element exists on the page.
      document.getElementsByTagName('canvas')[0]
      .getContext('2d')
      .putImageData(imageData, 0, 0)
    })
    .catch(err => {
        throw err
    })
})

Types

IndexedPNG

IndexedPNG(Buffer) : processes PNG data but does not decode it.

async decodePixels() : Decodes the PNG pixel data and returns it.

decodePalette() : Decodes the PNG palette and returns it as a Palette.

async decode() : Decodes the palette and the pixel data of the PNG data passed into the constructor. Calls decodePixels() and decodePalette().

ImageData async toImageData(ImageDataOptions) : Returns ImageData. Calls toPNGData(options).

PNGData async toPNGData(ImageDataOptions) : Returns PNGData. Calls decode() automatically if PNG has not been decoded.

ImageDataOptions

Object containing options to apply during toImageData().

| Property | Type | Description |----------|---------------------|--------------- | palette | Palette | Palette data to use for decoding. | clip | Clip | Clipping options to use for decoding.

Palette

A Buffer or Array containing the palette RGBA palette data.

let palette = [
    255, 0  ,  0  , 255, // Index 0
    0  , 255,  0  , 255, // Index 1
    0  , 0  ,  255, 255, // Index 2
    ...
]

Clip

Options to clip pixel data.

| Property | Type | Defaults | Description |----------|--------|--------------|------------- | x | Number | 0 | Starting X coordinate. | y | Number | 0 | Starting Y coordinate. | w | Number | width - x | Width of clip. | h | Number | height - y | Height of clip.

let clip = {
    x: 16,
    y: 16,
    w: 32,
    h: 32,
}

PNGData

Object containing the pixel data and row width.

| Property | Type
|----------|------------ | pixels | Uint8ClampedArray | RGBA pixel data. | width | Number | Width of each row of pixel data.