thumbhash-python

A Python implementation of the Thumbhash image placeholder generation algorithm.


Keywords
image-hash, image-processing, python, python-types, python3, thumbhash
License
MIT
Install
pip install thumbhash-python==1.0.1

Documentation


ThumbHash for Python

Test Coverage Package version Supported Python versions MIT License

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.