Image Quantization Library

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for flozz from gravatar.com flozz Avatar for wanadev from gravatar.com wanadev

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: BSD-3-Clause
  • Author: Wanadev
  • Maintainer: Fabien LOISON
  • Tags image, libimagequant, pngquant, cffi
  • Provides-Extra: dev, pil
Report project as malware

Project description

Github Discord PYPI Version Build Status Black License

Imagequant Python are bindings to allow using libimagequant from Python.

Libimagequant is a small, portable C library for high-quality conversion of RGBA images to 8-bit indexed-color (palette) images.

Install

From PyPI:

pip3 install imagequant

NOTE: you may require compilation tools to build the library if you system is not suitable for the precompiled wheels. On Debian / Ubuntu you can install the build dependencies with the following command:

sudo apt install build-essential python3-dev

Usage

With PIL / Pillow

from PIL import Image
import imagequant

input_image = Image.open("./example.png")
output_image = imagequant.quantize_pil_image(
    input_image,
    dithering_level=1.0,  # from 0.0 to 1.0
    max_colors=256,       # from 1 to 256
    min_quality=0,        # from 0 to 100
    max_quality=100,      # from 0 to 100
)
output_image.save("./out.png", format="PNG")

input_image → output_image

With Raw Data

import imagequant

# 2×2px image
IMAGE_DATA = (
    # | R | G | B | A |
    b"\xFF\x00\x00\xFF"  # red
    b"\x00\xFF\x00\xFF"  # lime
    b"\x00\x00\xFF\xFF"  # blue
    b"\xFF\xFF\xFF\xFF"  # white
)

output_image_data, output_palette = imagequant.quantize_raw_rgba_bytes(
    IMAGE_DATA,           # RGBA image data
    2, 2,                 # width, height
    dithering_level=1.0,  # from 0.0 to 1.0
    max_colors=256,       # from 1 to 256
    min_quality=0,        # from 0 to 100
    max_quality=100,      # from 0 to 100
)

# you can now encode image data and the palette in any image format...

Example output_image_data:

b'\x02\x03\x00\x01'

Example output_palette:

[0, 0, 255, 255, 255, 255, 255, 255, 255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 0, 0, ...]
# color 0      | color 1           | color 2       | color 3       | color 4   | ...

Development of the Bindings

Clone the repository and get the submodules:

git clone https://github.com/wanadev/imagequant-python.git
cd imagequant-python
git submodule init
git submodule update

Install some dependencies (preferably in a virtualenv):

pip3 install nox cffi pillow

Build the binary part of the lib:

python imagequant/libimagequant_build.py

A .so file (or a .pyd file on Windows, or a .dylib file on MacOS) shoud now be present in the imagequant/ folder. You will not need to run this command again until you change something in imagequant/libimagequant.h or in libimagequant/*.{c,h}.

To check the coding style, you can run the lint with the following command:

nox -s lint

To run the tests, use the following command:

nox -s test

License

Imagequant Python is licensed under the BSD 3 Clause. See the LICENSE file for more information.

Libimagequant is dual-licensed:

  • For Free/Libre Open Source Software it’s available under GPL v3 or later with additional copyright notices for older parts of the code.

  • For use in closed-source software, AppStore distribution, and other non-GPL uses, you can obtain a commercial license.

Read its license terms for more information.

Changelog

  • [NEXT] (changes on master that have not been released yet):

    • Nothing yet ;)

  • v1.1.4:

    • fix: Cleanup before throwing RuntimeError to avoid memory leak (@laggykiller, #26)

  • v1.1.3:

    • misc(deps): Fixed PyPy builds on Windows platform (@flozz)

  • v1.1.2:

    • misc: Removed PyPy wheels for Windows AMD64 as they won’t build (@flozz)

    • misc: Fixed libimagequant build on newer GCC versions (@flozz)

    • misc: Added Python 3.13 support (@flozz)

    • misc!: Removed Python 3.8 support (@flozz)

  • v1.1.1:

    • dist: Build and publish arm64 wheels for Linux and Windows (@laggykiller, #9, #10)

  • v1.1.0:

    • Added options to set minimal and target (maximal) quality (@injet-zhou, #4)

  • v1.0.5:

    • Added Python 3.12 support (@flozz)

    • Removed Python 3.7 support (@flozz)

  • v1.0.4:

    • Added Python 3.11 support

  • v1.0.3:

    • arm64 and universal2 wheels for macOS M1

    • x86 and x68_64 wheels for musl-based Linux distro (Alpine,…)

    • x86 wheels for Windows (x86_64 were already available)

  • v1.0.2: Python 3.10 support and wheels

  • v1.0.1: Fix encoding while reading the README in setup.py

  • v1.0.0: Initial release with a minimal API.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page