1
0
mirror of https://github.com/kettek/png-js synced 2025-03-14 06:24:30 -07:00
png-js/README.md

111 lines
3.3 KiB
Markdown
Raw Normal View History

2019-01-23 18:16:58 -08:00
# png-js
This is a modified version of [png.js](https://github.com/react-pdf/png.js) that is intended to be used for palette swapping within the browser.
2019-01-23 18:20:54 -08:00
**NOTE**: Only supports indexed PNGs for obvious reasons. All others will cause IndexedPNG to throw during construction.
2019-01-23 18:16:58 -08:00
## 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](https://nodejs.org/api/buffer.html#buffer_class_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](#palette).
async decode()
: Decodes the palette and the pixel data of the PNG data passed into the constructor. Calls `decodePixels()` and `decodePalette()`.
[ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData) async toImageData([ImageDataOptions](#imagedataoptions))
: Returns ImageData. Calls `toPNGData(options)`.
[PNGData](#pngdata) async toPNGData([ImageDataOptions](#imagedataoptions))
: Returns PNGData. Calls `decode()` automatically if PNG has not been decoded.
2019-01-23 18:16:58 -08:00
### ImageDataOptions
Object containing options to apply during `toImageData()`.
| Property | Type | Description
|----------|---------------------|---------------
| palette | [Palette](#palette) | Palette data to use for decoding.
| clip | [Clip](#clip) | Clipping options to use for decoding.
#### Palette
A [Buffer](https://nodejs.org/api/buffer.html#buffer_class_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,
}
2019-01-23 18:20:54 -08:00
```
### PNGData
Object containing the pixel data and row width.
| Property | Type
|----------|------------
| pixels | [Uint8ClampedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray) | RGBA pixel data.
| width | Number | Width of each row of pixel data.