How to add a 256-color alpha palette to an image?

[pekkavaa]

    from PIL import Image
    import numpy as np
    palette = np.random.random_integers(0, 255, size=(256,4)).astype(np.uint8)
    indices = np.random.random_integers(0, 255, size=(20, 10)).astype(np.uint16)
    img = Image.fromarray(indices, mode='PA')
    img.putpalette(palette)

Running it with PIL 11.3.0 gives ValueError: invalid palette size but no exception is given if I change the palette shape to (256,3). Using indices of type np.uint32 has the same behavior.

In unpack.c https://github.com/python-pillow/Pillow/blob/9fd4af55f773110edaaca75905568bf8d805eea0/src/libImaging/Unpack.c#L1604C1-L1607C32 I see

    /* palette w. alpha */
    {"PA", "PA", 16, unpackLA},
    {"PA", "PA;L", 16, unpackLAL},
    {"PA", "LA", 16, unpackLA},

which are used in _imaging.c

Pillow/src/_imaging.c

Line 1764 in 9fd4af5

if (palettesize * 8 / bits > 256) {

    unpack = ImagingFindUnpacker(palette_mode, rawmode, &bits);
   if (!unpack) {
       PyErr_SetString(PyExc_ValueError, wrong_raw_mode);
       return NULL;
   }

   if (palettesize * 8 / bits > 256) {
       PyErr_SetString(PyExc_ValueError, wrong_palette_size);
       return NULL;
   }

If I read that right, palettes are expected to be 16 bits per color? How does that work with RGBA?

[radarhere]

I will attempt to explain, let me know if there is any confusion left aftewards.

PA images do not necessarily have a palette that includes alpha values. They have two separate values for each pixel, the palette index (P) and the alpha value (A). For each 16 bit pixel, 8 bits describe the palette index (0-255) and 8 bits describe an independent alpha value. So you can combine any palette index with any alpha value.

In Pillow, palettes can be in RGBA mode, containing 256 RGBA colours. I suggest using img.putpalette(palette, 'RGBA'). See https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.putpalette. So you probably want

img = Image.fromarray(indices, mode='P')
img.putpalette(palette, 'RGBA')

[radarhere]

While I understand this was the answer in your case, I don't imagine it will be the solution in every case - there are a lot of numbers that are divisible by both 4 and 3.

[pekkavaa]

I mean that if the given palette NumPy array is of shape (N,4), it's likely the user intended the palette to have per-color alphas. If I understood correctly, this kind of input doesn't make sense without an 'RGBA' argument.

[radarhere]

Oh, sorry, I clearly misunderstood.

If you look at https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.putpalette, you will see that we are expecting either an ImagePalette, bytes, or a 1 dimensional list of integers. The fact that your 2-dimensional list works is actually unintended, and only a consequence of the fact that we convert what we think is a 1 dimensional list of integers to bytes.

Pillow/src/PIL/Image.py

Lines 2034 to 2042 in c60b36d

	if isinstance(data, ImagePalette.ImagePalette):
	if data.rawmode is not None:
	palette = ImagePalette.raw(data.rawmode, data.palette)
	else:
	palette = ImagePalette.ImagePalette(palette=data.palette)
	palette.dirty = 1
	else:
	if not isinstance(data, bytes):
	data = bytes(data)

So to do what you're suggesting, we'd first need to add explicit support for 2 dimensional data, and then yes, we could add a warning (or I think an error) if the data was of the wrong shape.

It seems a bit convoluted, but is that what you're requesting?

[pekkavaa]

Yes that's exactly my point. Apparently I'm using the API in an unintended way :)

[radarhere]

Ok. Given that we're sort of recently gone through the process of adding type hints to Pillow to clarify what the input data should be, I'm not keen to add support for incorrect data types. You received ValueError: invalid palette size and I think we agree that is true. Checking if it's a 2d array and what shape it has feels like going out of our way.

If you'd still like to pursue that further though, feel to create an issue and see if others disagree with me.