DOCSEARCHbyAlgolia
Submit Docs

ThumbHash Documentation

repository·main·Indexed 26 days ago

https://github.com/evanw/thumbhash

A compact image placeholder format that encodes visual details, aspect ratio, and alpha channel information into a small string or byte array. It provides native implementations in JavaScript, Rust, Swift, and Java, with community support for Go, Perl, PHP, and Ruby. Features include encoding RGBA images to ThumbHash, decoding ThumbHash to RGBA images or PNG data URLs, and extracting average colors and aspect ratios.

Tokens
792
Snippets
3
Records
9
Agent score
88%

What's inside ThumbHash

  1. Overview of ThumbHash

    main

    ThumbHash is a compact representation of an image placeholder designed to be stored inline with data. It is used to show a placeholder while a real image is loading to provide a smoother user experience.

    Key advantages over BlurHash include:

    • Higher detail encoding in the same space.
    • Encoding of the image aspect ratio.
    • More accurate color representation.
    • Support for images with alpha channels.

    Note: Unlike BlurHash, the algorithm parameters in ThumbHash are automatically configured and not user-configurable.

  2. Available ThumbHash Implementations

    main

    ThumbHash is implemented in several languages. This repository provides native implementations for:

    • JavaScript
    • Rust
    • Swift
    • Java

    Additional community implementations are available for:

    • Go
    • Perl
    • PHP
    • Ruby

  3. Extract the average RGBA color from a ThumbHash

    main

    Retrieve the average color represented by a ThumbHash as normalized floating-point values.

    Returns a Result containing a tuple of (r, g, b, a) where each value is in the range $[0.0, 1.0]$.

    • RGB values are not premultiplied by Alpha.
    • An error is returned if the input hash is shorter than 5 bytes.
    pub fn thumb_hash_to_average_rgba(hash: &[u8]) -> Result<(f32, f32, f32, f32), ()>

  5. Decode a ThumbHash to an RGBA image

    main

    Render a ThumbHash back into an RGBA image.

    Returns a Result containing a tuple of (width, height, pixels).

    • width: The width of the rendered placeholder image.
    • height: The height of the rendered placeholder image.
    • pixels: A Vec<u8> containing the RGBA pixel data (row-by-row).

    Note: RGB values are not premultiplied by Alpha. An error is returned if the input hash is too short.

    pub fn thumb_hash_to_rgba(mut hash: &[u8]) -> Result<(usize, usize, Vec<u8>), ()>

  7. Extract the approximate aspect ratio from a ThumbHash

    main

    Calculate the approximate aspect ratio of the original image used to create the ThumbHash.

    Returns a Result containing the aspect ratio as an f32. An error is returned if the input hash is shorter than 5 bytes.

    pub fn thumb_hash_to_approximate_aspect_ratio(hash: &[u8]) -> Result<f32, ()>

  8. Encode an RGBA image to a PNG data URL

    main

    Convert an RGBA pixel array directly into a PNG data URL string. This method is optimized for speed and simplicity and does not perform advanced compression.

    Constraints:

    • w and h must be ≤ 100px.
    • rgba must have w * h * 4 elements.
    • RGB values should not be premultiplied by Alpha.

  9. Encode an RGBA image to a ThumbHash

    main

    Convert an RGBA image into a ThumbHash Uint8Array.

    Constraints:

    • The input image width (w) and height (h) must be ≤ 100px.
    • The rgba array must contain w * h * 4 elements.
    • RGB values should not be premultiplied by Alpha.

    Parameters:

    • w: Image width.
    • h: Image height.
    • rgba: Pixel data in row-by-row RGBA format.