Metadata-Version: 2.4
Name: thumbhash-rs
Version: 0.1.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Dist: pillow ; extra == 'pillow'
Provides-Extra: pillow
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES.md
Summary: Fast ThumbHash bindings for Python using Rust (PyO3)
Home-Page: https://github.com/fdemmer/thumbhash-rs
Author: Sita Berete
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# thumbhash-rs

[![Test](https://github.com/fdemmer/thumbhash-rs/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/fdemmer/thumbhash-rs/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/thumbhash-rs.svg)](https://pypi.org/project/thumbhash-rs/)

A fast Python package for [ThumbHash](https://evanw.github.io/thumbhash/) image encoding/decoding using Rust bindings (PyO3, maturin) to the official `thumbhash` crate.

> [!NOTE]
> This is a fork of [sitatec/fast_python_thumbhash](https://github.com/sitatec/fast_python_thumbhash) (originally named `fast_thumbhash`), renamed to `thumbhash-rs` and imported as `thumbhash`.

## Usage Example

`image_to_thumb_hash` needs the `[pillow]` extra (see Installation).

```python
from PIL import Image
from thumbhash import image_to_thumb_hash, thumb_hash_to_rgba

thash = image_to_thumb_hash("example.jpg")
width, height, rgba = thumb_hash_to_rgba(thash)
restored = Image.frombytes("RGBA", (width, height), rgba)
restored.save("restored.png")
```

## Installation

```sh
pip install thumbhash-rs
```

With Pillow support (for `image_to_thumb_hash`):

```sh
pip install "thumbhash-rs[pillow]"
```

## API

Each function has a docstring (`help(thumbhash.rgba_to_thumb_hash)`), also available as editor hints through the bundled type stubs.

- `rgba_to_thumb_hash(width, height, rgba)`: encode raw RGBA pixels (at most 100x100) to a ThumbHash (`bytes`).
- `thumb_hash_to_rgba(hash)`: decode a ThumbHash to `(width, height, rgba)`.
- `thumb_hash_to_average_rgba(hash)`: the average color as `(r, g, b, a)`, each from 0 to 1.
- `thumb_hash_to_approximate_aspect_ratio(hash)`: the approximate width / height of the original image.
- `image_to_thumb_hash(fp)`: open an image file with Pillow and encode it (requires the `[pillow]` extra).

## Benchmark

Compared with the pure-Python packages [`thumbhash`](https://github.com/justinforlenza/thumbhash-py) (encoding only) and [`thumbhash-python`](https://github.com/Astropilot/thumbhash-python). Run it yourself with `just bench` (see `benchmarks/`). Output on an AMD Ryzen 7 5700X, Python 3.14, release build:

```
rgba_to_thumb_hash, 100x100 RGBA image -> ThumbHash

implementation                    median ms    min ms    runs   speedup
thumbhash-rs (this package)           1.124     1.120     887
thumbhash                            29.452    28.929      34     26.2x
thumbhash-python                     29.764    29.182      33     26.5x
all implementations produced the same output

thumb_hash_to_rgba, ThumbHash -> 32x32 RGBA image

implementation                    median ms    min ms    runs   speedup
thumbhash-rs (this package)           0.049     0.048   20328
thumbhash-python                      5.543     5.519     179    113.8x
all implementations produced the same output (within +-1 per channel)

speedup = how much faster thumbhash-rs is than that implementation (median)
```

## Other Python packages

Pure-Python implementations of ThumbHash:
- [`thumbhash`](https://github.com/justinforlenza/thumbhash-py) ([PyPI](https://pypi.org/project/thumbhash/))
- [`thumbhash-python`](https://github.com/Astropilot/thumbhash-python) ([PyPI](https://pypi.org/project/thumbhash-python/))

## License

MIT

