Super Pyxelate converts images to 8-bit pixel art. It is an improved, faster implementation of the original Pyxelate algorithm with palette transfer support and enhanced dithering.

Usage

Once installed, Pyxelate can be used either from the command line or from Python.

$ pyxelate examples/blazkowicz.jpg output.png --factor 14 --palette 7

Pyxelating examples/blazkowicz.jpg...
Wrote output.png

Use pyxelate --help for a full list of command-line options, which map onto the Python arguments described below.

Invoking from Python:

from skimage import io
from pyxelate import Pyx, Pal

# load image with 'skimage.io.imread()'
image = io.imread("examples/blazkowicz.jpg")  

downsample_by = 14  # new image will be 1/14th of the original in size
palette = 7  # find 7 colors

# 1) Instantiate Pyx transformer
pyx = Pyx(factor=downsample_by, palette=palette)

# 2) fit an image, allow Pyxelate to learn the color palette
pyx.fit(image)

# 3) transform image to pixel art using the learned color palette
new_image = pyx.transform(image)

# save new image with 'skimage.io.imsave()'
io.imsave("pixel.png", new_image)

Pyxelate extends scikit-learn transformers, allowing the same learned palette to be reused on other, aesthetically similar images (so it's somewhat like an 8-bit style transfer):

car = io.imread("examples/f1.jpg")
robocop = io.imread("examples/robocop.jpg")

# fit a model on each
pyx_car = Pyx(factor=5, palette=8, dither="none").fit(car)
pyx_robocop = Pyx(factor=6, palette=7, dither="naive").fit(robocop)

"""
pyx_car.transform(car)
pyx_car.transform(robocop)
pyx_robocop.transform(car)
pyx_robocop.transform(robocop)
"""

For a single image, it is possible to call both fit() and transform() at the same time:

# fit() and transform() on image with alpha channel
trex = io.imread("examples/trex.png")
trex_p = Pyx(factor=9, palette=4, dither="naive", alpha=.6).fit_transform(trex)

Hyperparameters for Pyx()

Showcase of available dithering methods:

See more examples in the example Jupyter Notebook.

Assigning existing palette

Common retro palettes for different hardware (and others like the PICO-8 fantasy console) are available in Pal:

from pyxelate import Pyx, Pal

vangogh = io.imread("examples/vangogh.jpg")

vangogh_apple = Pyx(factor=12, palette=Pal.APPLE_II_HI, dither="atkinson").fit_transform(vangogh)
vangogh_mspaint = Pyx(factor=8, palette=Pal.MICROSOFT_WINDOWS_PAINT, dither="none").fit_transform(vangogh)

Assign your own palette:

my_pal = Pal.from_hex(["#FFFFFF", "#000000"])

# same but defined with RGB values
my_pal = Pal.from_rgb([[255, 255, 255], [0, 0, 0]])

Fitting existing palettes on different images will also have different results for transform().

Installation

pip install git+https://github.com/sedthh/pyxelate.git --upgrade

Pyxelate relies on the following libraries to run (included in requirements.txt):

• sklearn 0.24.1
• skimage 0.18.1
• numba 0.53.1

FAQ

The source code is available under the MIT license but I would appreciate the credit if your work uses Pyxelate (for instance you may add me in the Special Thanks section in the credits of your videogame)!

How does it work?

Pyxelate downsamples images by (iteratively) dividing it to 3x3 tiles and calculating the orientation of edges inside them. Each tile is downsampled to a single pixel value based on the angle the magnitude of these gradients, resulting in the approximation of a pixel art. This method was inspired by the Histogram of Oriented Gradients computer vision technique.

Then an unsupervised machine learning method, a Bayesian Gaussian Mixture model is fitted (instead of conventional K-means) to find a reduced palette. The tied gaussians give a better estimate (than Euclidean distance) and allow smaller centroids to appear and then lose importance to larger ones further away. The probability mass function returned by the uncalibrated model is then used as a basis for different dithering techniques.

Preprocessing and color space conversion tricks are also applied for better results. Singular Value Decomposition can optionally be enabled for noise reduction.

PROTIPs

• There is no one setting fits all, try experimenting with different parameters for better results! A setting that generates visually pleasing result on one image might not work well for another.
• The bigger the resulting image, the longer the process will take. Note that most parts of the algorithm are O(H*W) so an image that is twice the size will take 4 times longer to compute.
• Assigning existing palettes will take longer for larger palettes, because LAB color distance has to be calculated between each color separately.
• Dithering takes time (especially atkinson) as they are mostly implemented in plain python with loops.

Creating animations

It is possible to use Pyxelate on a sequence of images to create animations. To reduce flicker nd artifacts, it is recommended to first recreate the images as a sequence of keyframes and deviations from previous keyframes, and run the algorithm on these extracted differences only. Then as a second step these altered sequences can be merged on top of each other resulting in a series of pixel graphics.

Pyxelate offers 2 methods to separate keyframes: images_to_parts, parts_to_images

import os
from skimage import io
from pyxelate import Pyx, Pal, Vid

# get all images
images = []
for file in os.listdir("where_my_images_are/"):
    image = io.imread(file)
    images.append(image)
    
# generate a new image sequence based on differences between them
new_images, new_keys = [], []
# in case of unwanted artifacts remain on the final animation, try reducing sensitivity
for i, (image, is_keyframe) in enumerate(Vid(images, sensitivity=0.1)):
    if i == 0:  # update palette at keyframes, this can be 'if is_keyframe:' instead for each keyframe
        # if you must use dither, use dither="naive" for animations only
        pyx = Pyx(factor=9, upscale=5, palette=10, svd=False)
        pyx.fit(image)
    # run the algorithm on the difference only
    image = pyx.transform(image)
    # save the pyxelated image part for later
    io.imsave(f"converted_images_with_reduced_flicker/img_{i}.png", image)

Or use the CLI tool with --sequence and %d in both input and output file names:

$ pyxelate temp/img_%d.png output/img_%d.png --factor 9 --upscale 5  --palette 10 --sequence --nosvd

Pyxelating temp/img_%d.png...
Found 781 '.png' images in 'temp'
...

You can turn a video into a sequence of images using ffmpeg.