From f95373cebd919b1c9001529f1960aebe98aa3151 Mon Sep 17 00:00:00 2001 From: Ross Olson Date: Mon, 8 Sep 2025 18:38:07 -0700 Subject: [PATCH 1/2] Update ImageDraw.rst to avoid transparency issue Per the conversation https://github.com/python-pillow/Pillow/issues/2496#issuecomment-3268255530 I have added a FAR TOO LONG explanation of the situation and the resolution. Please for the love of Guido, help edit this down. --- docs/reference/ImageDraw.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 4a2223a40c5..6da0e386282 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -57,6 +57,31 @@ Color names See :ref:`color-names` for the color names supported by Pillow. +Transparency and Alpha Channel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When generating an image in memory and adding transparent elements (for +instance a red rectangle placed on a blue background) to be composited +against the background (creating a purple rectangle), you may mistakenly +assume that the base image (generated from `Image.new()`) must be use RGBA +color space. This is incorrect. For a semi-transparent element to be +composited against the base image, the base image object must be in the +RGB color-space. If the base image is kept in the RGBA color space then an +alpha channel mask is created and all added elements will have their +shapes completely added to the alpha channel of the base image, causing +the element to show as composited against 100% white. + +:: + + # generate a blank image with a blue background + custom_image = Image.new('RGB', (100, 100), color=(128, 128, 255)) + # generate a draw object with the RGBA colorspace + d = ImageDraw.Draw(custom_image, 'RGBA') + # generate a red rectangle with transparency + d.rectangle([25, 25, 50, 50], fill=(255, 128, 128, 128)) + + + Fonts ^^^^^ From 95739fef07e2569cda37150cbb8b1d7ea118ee25 Mon Sep 17 00:00:00 2001 From: Ross Olson Date: Mon, 8 Sep 2025 19:49:31 -0700 Subject: [PATCH 2/2] Update ImageDraw.rst Lint --- docs/reference/ImageDraw.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/ImageDraw.rst b/docs/reference/ImageDraw.rst index 6da0e386282..ac0ab3a99ec 100644 --- a/docs/reference/ImageDraw.rst +++ b/docs/reference/ImageDraw.rst @@ -63,7 +63,7 @@ Transparency and Alpha Channel When generating an image in memory and adding transparent elements (for instance a red rectangle placed on a blue background) to be composited against the background (creating a purple rectangle), you may mistakenly -assume that the base image (generated from `Image.new()`) must be use RGBA +assume that the base image (generated from ``Image.new()``) must be use RGBA color space. This is incorrect. For a semi-transparent element to be composited against the base image, the base image object must be in the RGB color-space. If the base image is kept in the RGBA color space then an