DOCSEARCHbyAlgolia
Submit Docs

upng.js Documentation

repository·master·Indexed 25 days ago

https://github.com/photopea/upng.js

A high-performance PNG and APNG encoder and decoder used by the Photopea image editor. Version 2.2.0 supports various bit depths, color types, and lossy compression via quantization. Key features include UPNG.encode() for image conversion, UPNG.decode() for parsing PNG files, UPNG.toRGBA8() for standardized 8-bit RGBA representation, and UPNG.quantize() for generating optimal color palettes.

Tokens
1.1K
Snippets
2
Records
7
Agent score
31%

What's inside upng.js

  1. Best practices for Quantization

    master

    When using UPNG.quantize() or preparing data for processing, follow these guidelines:

    • Multiple Images: To generate one common palette for multiple images (like animation frames), concatenate them into a single data array.
    • Fewer than 4 components: If working with less than four components (e.g., grayscale), set the remaining components to a constant value (e.g., zero).
    • Transparency: When working with transparency, premultiply color components by the transparency value. This prevents transparent pixels from being incorrectly mapped to colors like white (e.g., rgba(1,1,1,0) should be handled so it is closer to rgba(0,0,0,0) than rgba(1,1,1,1)).

  3. Decode PNG files with UPNG.decode()

    master

    Use UPNG.decode() to parse a PNG file into an image object. It supports all color types (Truecolor, Grayscale, Palette, etc.), all channel depths (1, 2, 4, 8, 16), and interlaced images.

    Parameters:

    • buffer: ArrayBuffer containing the PNG file.

    Returns: An image object with the following properties:

    • width: Image width.
    • height: Image height.
    • depth: Bits per channel.
    • ctype: Color type (e.g., Truecolor, Grayscale, Palette).
    • frames: Additional info about frames (e.g., delays).
    • tabs: Additional PNG chunks.
    • data: The raw pixel data (interpretation depends on ctype and depth).

  4. Convert decoded images to RGBA8 with UPNG.toRGBA8()

    master

    Since UPNG.decode() returns raw data that varies based on color type and depth, use UPNG.toRGBA8() to get a standardized 8-bit RGBA representation.

    Parameters:

    • img: The image object returned by UPNG.decode().

    Returns: An array of frames, where each frame is an ArrayBuffer in RGBA format (8 bits per channel).

  5. Generate color palettes with UPNG.quantize()

    master

    The UPNG.quantize() method performs quantization on 4-component 8-bit vectors (pixels) to find an optimal palette and remap colors.

    Parameters:

    • data: ArrayBuffer of samples (byte length must be a multiple of four).
    • psize: The desired palette size (number of colors).

    Returns: An object res containing:

    • abuf: ArrayBuffer of the data with colors remapped by the palette.
    • inds: Uint8Array of color indices for each sample (only if psize <= 256).
    • plte: An Array representing the palette. Each entry plte[i] contains est.q and est.rgba color values.
    var res = UPNG.quantize(data, psize);

  6. Low-level encoding with UPNG.encodeLL()

    master

    Use UPNG.encodeLL() for low-level encoding when you need to bypass optimizations or handle specific bit depths and channel configurations. This is useful for saving 16-bit colors or reducing memory usage for extremely large images by avoiding the expansion to 8-bit RGBA.

    Parameters:

    • imgs: Array of frames (ArrayBuffer).
    • w: Width.
    • h: Height.
    • cc: Number of color channels (1 or 3).
    • ac: Number of alpha channels (0 or 1).
    • depth: Bit depth of pixel data (1, 2, 4, 8, 16).
    • dels (optional): Array of millisecond delays for each frame.

    Returns: An ArrayBuffer containing the binary data of the PNG file.

  7. Encode images with UPNG.encode()

    master

    Use UPNG.encode() to convert pixel data into a PNG or APNG file. It supports lossy compression via quantization by specifying the number of allowed colors.

    Parameters:

    • imgs: An array of frames. Each frame is an ArrayBuffer containing RGBA pixel data (8 bits per channel).
    • w: Width of the image.
    • h: Height of the image.
    • cnum: Number of colors in the result. Use 0 for lossless compression, or a specific number (e.g., 256) for lossy compression.
    • dels (optional): An array of millisecond delays for each frame (required for animations with 2 or more frames).

    Returns: An ArrayBuffer containing the binary data of the PNG file.

    // Read RGBA from canvas and encode with UPNG
var dta = ctx.getImageData(0,0,200,300).data;  // ctx is Context2D of a Canvas
// dta = new Uint8Array(200 * 300 * 4);       // or generate pixels manually
var png = UPNG.encode([dta.buffer], 200, 300, 0);   console.log(new Uint8Array(png));