Convert image to specific palette using PIL without dithering

Question

I am trying to convert an RGB image in PNG format to use a specific indexed palette using the Pillow library (Python Image Library, PIL). But I want to convert using the "round to closest color" method, not dithering, because the image is pixel art and dithering would distort the outlines of areas and add noise to areas that are intended to be flat.

I tried Image.Image.paste(), and it used the four specified colors, but it produced a dithered image:

from PIL import Image
oldimage = Image.open("oldimage.png")
palettedata = [0, 0, 0, 102, 102, 102, 176, 176, 176, 255, 255, 255]
newimage = Image.new('P', oldimage.size)
newimage.putpalette(palettedata * 64)
newimage.paste(oldimage, (0, 0) + oldimage.size)
newimage.show()    

I tried Image.Image.quantize() as mentioned in pictu's answer to a similar question, but it also produced dithering:

from PIL import Image
palettedata = [0, 0, 0, 102, 102, 102, 176, 176, 176, 255, 255, 255]
palimage = Image.new('P', (16, 16))
palimage.putpalette(palettedata * 64)
oldimage = Image.open("School_scrollable1.png")
newimage = oldimage.quantize(palette=palimage)
newimage.show()

I tried Image.Image.convert(), and it converted the image without dithering, but it included colors other than those specified, presumably because it used either a web palette or an adaptive palette

from PIL import Image
oldimage = Image.open("oldimage.png")
palettedata = [0, 0, 0, 102, 102, 102, 176, 176, 176, 255, 255, 255]
expanded_palettedata = palettedata * 64
newimage = oldimage.convert('P', dither=Image.NONE, palette=palettedata)
newimage.show()

How do I automatically convert an image to a specific palette without dithering? I would like to avoid a solution that processes each individual pixel in Python, as suggested in John La Rooy's answer and comments thereto, because my previous solution involving an inner loop written in Python has proven to be noticeably slow for large images.

Answer 1

Pillow 6 incorporates pull request 3699, merged on 2019-03-11, which adds the dither argument to the ordinary quantize() method. Prior to Pillow 6, the following was needed:

The parts of PIL implemented in C are in the PIL._imaging module, also available as Image.core after you from PIL import Image. Current versions of Pillow give every PIL.Image.Image instance a member named im which is an instance of ImagingCore, a class defined within PIL._imaging. You can list its methods with help(oldimage.im), but the methods themselves are undocumented from within Python.

The convert method of ImagingCore objects is implemented in _imaging.c. It takes one to three arguments and creates a new ImagingCore object (called Imaging_Type within _imaging.c).

• mode (required): mode string (e.g. "P")
• dither (optional, default 0): PIL passes 0 or 1
• paletteimage (optional): An ImagingCore with a palette

The problem I was facing is that quantize() in dist-packages/PIL/Image.py forces the dither argument to 1. So I pulled a copy of the quantize() method out and changed that. Because it relies on an ostensibly private method, it may not work in future versions of Pillow. By then, however, we can expect Pillow pre-6 to have passed out of use, as both Debian "bullseye" (stable in mid-2021) and Ubuntu "focal" (LTS in mid-2020) package Pillow 7 or newer.

#!/usr/bin/env python3
from PIL import Image

def quantizetopalette(silf, palette, dither=False):
    """Convert an RGB or L mode image to use a given P image's palette."""

    silf.load()

    # use palette from reference image
    palette.load()
    if palette.mode != "P":
        raise ValueError("bad mode for palette image")
    if silf.mode != "RGB" and silf.mode != "L":
        raise ValueError(
            "only RGB or L mode images can be quantized to a palette"
            )
    im = silf.im.convert("P", 1 if dither else 0, palette.im)
    # the 0 above means turn OFF dithering

    # Really old versions of Pillow (before 4.x) have _new
    # under a different name
    try:
        return silf._new(im)
    except AttributeError:
        return silf._makeself(im)

# putpalette() input is a sequence of [r, g, b, r, g, b, ...]
# The data chosen for this particular answer represent
# the four gray values in a game console's palette
palettedata = [0, 0, 0, 102, 102, 102, 176, 176, 176, 255, 255, 255]
# Fill the entire palette so that no entries in Pillow's
# default palette for P images can interfere with conversion
NUM_ENTRIES_IN_PILLOW_PALETTE = 256
num_bands = len("RGB")
num_entries_in_palettedata = len(palettedata) // num_bands
palettedata.extend(palettedata[:num_bands]
                   * (NUM_ENTRIES_IN_PILLOW_PALETTE
                      - num_entries_in_palettedata))
# Create a palette image whose size does not matter
arbitrary_size = 16, 16
palimage = Image.new('P', arbitrary_size)
palimage.putpalette(palettedata)

# Perform the conversion
oldimage = Image.open("School_scrollable1.png")
newimage = quantizetopalette(oldimage, palimage, dither=False)
newimage.show()