Skip to content

A Python implementation of the Thumbhash image placeholder generation algorithm.

License

Notifications You must be signed in to change notification settings

Astropilot/thumbhash-python

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


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.