image-to-pixelart

Converts images to pixel art using a fixed 16-colour palette (derived from a 4×4 colour grid source image).

Usage

# Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
python3 extract_palette_colours.py
python3 render_palette_grid.py   # Optional
python3 convert_to_pixel_art.py

Inputs:

• input/original.jpeg
• input/colour-palette.png (a 4×4 grid of colours)

Outputs:

• output/interim/palette_hex_4x4.json
• output/palette_grid.png
• output/pixel-art-128x128.png
• output/pixel-art-1536x1536.png

How it Works

1. Extracts the colour palette from input/colour-palette.png
2. Downsamples the input image to 128×128
3. Quantizes each pixel to the nearest colour in the extracted palette using Euclidean distance in RGB space
4. Upscales the 128×128 version to 1536×1536 using nearest-neighbor resampling

Requirements

• Python 3.7+
• Pillow 12.0+