ThumbHash for Python

Introduction

The thumbhash library implements the Thumbhash image placeholder generation algorithm invented by Evan Wallace in Python.

A full explanation and interactive example of the algorithm can be found at https://github.com/evanw/thumbhash

Installation

You need Python 3.7+.

$ pip install thumbhash-python

Usage

Create thumbhash from image file:

from thumbhash import image_to_thumbhash

with open('image.jpg', 'rb') as image_file:
    hash = image_to_thumbhash(image_file)

You can also pass file name as parameter to the function:

from thumbhash import image_to_thumbhash

hash = image_to_thumbhash('image.jpg')

These functions use the Pillow library to read the image.

If you want to directly convert a rgba array to a thumbhash, you can use the low-level function:

from thumbhash.encode import rgba_to_thumbhash

rgba_to_thumbhash(w: int, h: int, rgba: Sequence[int]) -> bytes

To decode a thumbhash into an image:

from thumbhash import thumbhash_to_image

image = thumbhash_to_image("[THUMBHASH]", base_size=128)

image.show()

image.save('path/to/file.png')

Alternatively you can use the following function to deal directly with the pixels array (without relying on Pillow):

from thumbhash.decode import thumbhash_to_rgba

def thumbhash_to_rgba(
    hash: bytes, base_size: int = 32, saturation_boost: float = 1.25
) -> Tuple[int, int, List[int]]

CLI

You can also use the CLI mode to encode or decode directly via your shell.

Usage:

$ thumbhash [OPTIONS] COMMAND [ARGS]...

Options:

• --install-completion: Install completion for the current shell.
• --show-completion: Show completion for the current shell, to copy it or customize the installation.
• --help: Show this message and exit.

Commands:

• decode: Save thumbnail image from thumbhash
• encode: Get thumbhash from image

thumbhash decode

Save thumbnail image from thumbhash

Usage:

$ thumbhash decode [OPTIONS] IMAGE_PATH HASH

Arguments:

• IMAGE_PATH: The path where the image created from the hash will be saved [required]
• HASH: The base64-encoded thumbhash [required]

Options:

• -s, --size INTEGER RANGE: The base size of the output image [default: 32; x>=1]
• --saturation FLOAT: The saturation boost factor to use [default: 1.25]
• --help: Show this message and exit.

thumbhash encode

Get thumbhash from image

Usage:

$ thumbhash encode [OPTIONS] IMAGE_PATH

Arguments:

• IMAGE_PATH: The path of the image to convert [required]

Options:

• --help: Show this message and exit.

Contributing

See Contributing documentation

License

thumbhash-python is distributed under the terms of the MIT license.