Decode and encode png files in browsers/Node.js
This is a PNG decoder and encoder library for JavaScript that runs in both the browser and in Node.js. It is used in Luna Paint (an image editor for VS Code) to work with PNG files.
You can try it out on vscode.dev
by installing the Luna Paint extension and opening a png file.
The supported way of installing the project is through npm:
npm install @lunapaint/png-codec
Alternatively, you could add the repo as a git submodule, or download the source from the GitHub releases page.
Basic usage:
import { decodePng, encodePng } from '@lunapaint/png-codec';
import * as fs from 'fs/promises';
async function decode(filepath) {
const data = await fs.readFile(filepath);
const decoded = await decodePng(data);
console.log('decoded image', decoded.image.data);
// [r, g, b, a, ...]
}
async function encode(data, width, height, filepath) {
const encoded = await encodePng({ data, width, height });
await fs.writeFile(filepath, encoded.data);
console.log('encoded image', encoded.data);
// [...binary data]
}
The full API is documented as a TypeScript .d.ts
declaration file. The view the API:
Go to Symbol in Editor
commandPNGs are made up of a fixed signature followed by a series of chunks. The following chunks can be decoded supported, with some notes provided where applicable:
Critical chunks:
Chunk | Name | Notes |
---|---|---|
IHDR | Image header | |
PLTE | Palette | |
IDAT | Image data | Full filtering and interlacing support for all bit depths (1, 2, 4, 8, 16) are supported. |
IEND | Image trailer |
Ancillary chunks:
Chunk | Name | Notes |
---|---|---|
bKGD | Background color | |
cHRM | Primary chromaticities and white point | |
eXIf | Exchangeable image file format | Approved 2017/7 |
gAMA | Image gamma | Gamma values are provided, but are not applied to the resulting image (see #11) |
hIST | Image histogram | |
iCCP | Embedded ICC profile | Exposes the profile as a byte array |
iTXt | International textual data | |
oFFs | Image offset | 🧪 Limited testing Extension to the PNG 1.2 Specification v1.2.0 |
pCAL | Calibration of pixel values | 🧪 Limited testing Extension to the PNG 1.2 Specification v1.2.0 |
pHYs | Physical pixel dimensions | |
sBIT | Significant bits | Since the decoded buffer uses a minimum of uint8, this is only when the significant bits are in the range of 9-15 |
sCAL | Physical scale of image subject | 🧪 Limited testing Extension to the PNG 1.2 Specification v1.2.0 |
sPLT | Suggested palette | |
sRGB | Standard RGB colour space | |
sTER | Indicator of stereo image | 🧪 Limited testing Extension to the PNG 1.2 Specification v1.3.0 |
tEXt | Textual data | |
tIME | Image last-modification time | |
tRNS | Transparency | Since this chunk modifies the resulting image, you cannot skip this chunk |
zTXt | Compressed textual data |
These are the main reasons:
The library has the single runtime dependency pako which provides the compression/decompression capabilities needed to read various png chunks.