How to merge a transparent png image with another image using PIL

Question

I have a transparent png image foo.png and I've opened another image with:

im = Image.open("foo2.png")

Now what I need is to merge foo.png with foo2.png.

(foo.png contains some text and I want to print that text on foo2.png)

Don't use `;` at the end of your commands in python: It's ugly... — nosklo, Mar 16 '11 at 11:48
Related question [here](https://stackoverflow.com/q/2563822/13762264) — pjpscriv, Oct 08 '22 at 04:09

score 483 · Accepted Answer · edited Feb 18 '21 at 09:43

483

from PIL import Image

background = Image.open("test1.png")
foreground = Image.open("test2.png")

background.paste(foreground, (0, 0), foreground)
background.show()

First parameter to .paste() is the image to paste. Second are coordinates, and the secret sauce is the third parameter. It indicates a mask that will be used to paste the image. If you pass a image with transparency, then the alpha channel is used as mask.

Check the docs.

edited Feb 18 '21 at 09:43

cheng10

714
7
10

answered Mar 16 '11 at 11:48

nosklo

217,122
57
293
297

15

To make sure the foreground contains transparency in all cases, use `foreground.convert('RGBA')` for the mask parameter. – Mark Ransom Oct 04 '12 at 02:28
Wow! This solution did the trick instantly two weeks ago, but now I totally forgot it already, and now I see it again, it again does the trick! – physicalattraction Jun 30 '15 at 20:13
23

I'm getting ```ValueError: bad transparency mask``` – Deniz Ozger Mar 03 '16 at 15:48
1

Depending on your version, you may have to install the Python Image Library, and:' from PIL import Image` – William H. Hooper Jul 23 '16 at 17:57
1

Amazing, you can use image as mask. But can I use vectorial images like svg? – Beatriz Fonseca Sep 14 '16 at 01:57
1

`TypeError: paste() got an unexpected keyword argument 'alpha'` – Schütze Aug 08 '18 at 06:11
12

@DenizOzger To fix `ValueError: bad transparency mask` use `bg.paste(fg, (0, 0), fg.convert('RGBA'))` – Mingwei Samuel Jan 01 '19 at 03:01
1

Thank you for indicating the information about the mask and the link to the documentation appreciate it. – user3613932 May 25 '19 at 22:05
1

this does not work as expected, it is not a proper overlay for a transparent image. fading transparency gives ugly results. It transparency is ON/OFF you should get what you expect though – yota May 01 '20 at 09:57
1

Thank you for sharing. In my case "import Image" doesn't work. I had to use "from PIL import Image" instead. – Luis Jose May 24 '20 at 14:03
This doesn't work. paste() blits each channel (including alpha) using the mask as a weight, which means pasting a transparent image on top of an opaque one can cause opaque pixels to become transparent. It just happens to work in limited cases, but it's not alpha blending. At least 450 people have been confused by this so far, so it'd be nice to add a warning to the answer. – Glenn Maynard Mar 07 '23 at 23:17

olt · Answer 2 · 2017-01-19T12:43:32.593

98

Image.paste does not work as expected when the background image also contains transparency. You need to use real Alpha Compositing.

Pillow 2.0 contains an alpha_composite function that does this.

background = Image.open("test1.png")
foreground = Image.open("test2.png")

Image.alpha_composite(background, foreground).save("test3.png")

EDIT: Both images need to be of the type RGBA. So you need to call convert('RGBA') if they are paletted, etc.. If the background does not have an alpha channel, then you can use the regular paste method (which should be faster).

edited Jan 19 '17 at 12:43

answered Apr 10 '13 at 07:45

olt

2,267
1
19
13

I just used paste() to overlay one semi-transparent image on another, with PIL, and it worked as I expected. In what way doesn't it work as you expected? – Peter Hansen Jul 25 '13 at 17:27
3

@PeterHansen, paste() doesn't work as expected "when the background image also contains transparency". – homm Nov 05 '14 at 17:19
1

@PeterHansen There is example: https://github.com/python-pillow/Pillow/issues/924#issuecomment-61848826 – homm Nov 05 '14 at 17:53
@homm thanks. That was so long ago I have no memory of what I tried. It seems likely I did miss the part you quoted about the background image also having transparency. – Peter Hansen Nov 05 '14 at 19:58
4

I get `ValueError: image has wrong made` as well @DenizOzger – digitaldavenyc Oct 11 '16 at 20:55
This worked for me whereas paste was punching a "transparent hole" through my background. – Lian May 30 '17 at 12:01
2

`ValueError: images do not match` . Because this method works only when the image sizes are same – Trect Nov 28 '19 at 15:30
yup, you're right. both my bg and fg had transparency. the portion of my fg that contained color is supposed to be pasted on a transparent region of the bg. when `.paste` is used the fg becomes very grainy and off. alpha_composite worked perfectly – SpectraXCD Sep 12 '22 at 18:07

score 87 · Answer 3 · answered Apr 20 '17 at 08:50

87

As olt already pointed out, Image.paste doesn't work properly, when source and destination both contain alpha.

Consider the following scenario:

Two test images, both contain alpha:

layer1 = Image.open("layer1.png")
layer2 = Image.open("layer2.png")

Compositing image using Image.paste like so:

final1 = Image.new("RGBA", layer1.size)
final1.paste(layer1, (0,0), layer1)
final1.paste(layer2, (0,0), layer2)

produces the following image (the alpha part of the overlayed red pixels is completely taken from the 2nd layer. The pixels are not blended correctly):

Compositing image using Image.alpha_composite like so:

final2 = Image.new("RGBA", layer1.size)
final2 = Image.alpha_composite(final2, layer1)
final2 = Image.alpha_composite(final2, layer2)

produces the following (correct) image:

answered Apr 20 '17 at 08:50

P.Melch

8,066
43
40

3

Thanks for the screenshots! Really helps! – Viet May 01 '17 at 08:44
1

But `alpha_composite` can not set the offset, would you mind to give an example to completely replace `paste` function? – Mithril Jul 10 '17 at 08:03
3

I guess you would have to create a new empty image with the same size as the garget image, paste the layer at the proper position and use alpha_compositing to blend the new image over the target image. – P.Melch Jul 11 '17 at 15:24
1

I get: ValueError: images do not match – Student Jun 13 '21 at 10:00
2

Images need to have the same size – P.Melch Jun 17 '21 at 06:58
Thanks so much! It fixed transparency issue I was tackling for long – Ali Naderi Dec 16 '22 at 16:02

nvd · Answer 4 · 2017-09-11T12:32:42.700

18

One can also use blending:

im1 = Image.open("im1.png")
im2 = Image.open("im2.png")
blended = Image.blend(im1, im2, alpha=0.5)
blended.save("blended.png")

edited Sep 11 '17 at 12:32

answered Sep 08 '17 at 11:19

nvd

2,995
28
16

1

This one ascetically worked for me. The images must have exactly the same size, but it is ok. The paste function did not quite cut it for me ... – Liviu Sosu Oct 04 '17 at 11:42
3

'ValueError: images do not match' – Schütze Aug 08 '18 at 05:50
2

Possibly, they are of different dimensions. You may need to scale or crop one of those. – nvd Aug 20 '18 at 04:12
2

@Schütze see nvd's comment because he/she didn't ping (using @blahblah) you – MilkyWay90 Mar 03 '19 at 03:10
@Schütze I had to add these lines to avoid "images do not match": ` cloud_as_img.convert("RGBA") cloud_as_img.putalpha(255) cloud_as_img.save(temp_file_name) ` – Jordan The Genius Mar 25 '22 at 20:01

score 3 · Answer 5 · answered Dec 07 '18 at 04:25

Had a similar question and had difficulty finding an answer. The following function allows you to paste an image with a transparency parameter over another image at a specific offset.

import Image

def trans_paste(fg_img,bg_img,alpha=1.0,box=(0,0)):
    fg_img_trans = Image.new("RGBA",fg_img.size)
    fg_img_trans = Image.blend(fg_img_trans,fg_img,alpha)
    bg_img.paste(fg_img_trans,box,fg_img_trans)
    return bg_img

bg_img = Image.open("bg.png")
fg_img = Image.open("fg.png")
p = trans_paste(fg_img,bg_img,.7,(250,100))
p.show()

`ValueError: images do not match` – lllllllllllll May 15 '19 at 14:33 — lllllllllllll, May 15 '19 at 14:33

score 3 · Answer 6 · answered Sep 24 '21 at 13:23

Here is my code to merge 2 images of different sizes, each with transparency and with offset:

from PIL import Image

background = Image.open('image1.png')
foreground = Image.open("image2.png")

x = background.size[0]//2
y = background.size[1]//2

background = Image.alpha_composite(
    Image.new("RGBA", background.size),
    background.convert('RGBA')
)

background.paste(
    foreground,
    (x, y),
    foreground
)

background.show()

This snippet is a mix of the previous answers, blending elements with offset while handling images with different sizes, each with transparency.

This answer doesn't appear to be quite correct. I've submitted an edit I think fixes it :) — pjpscriv, Oct 08 '22 at 03:47

score 2 · Answer 7 · answered Apr 28 '19 at 07:16

2

def trans_paste(bg_img,fg_img,box=(0,0)):
    fg_img_trans = Image.new("RGBA",bg_img.size)
    fg_img_trans.paste(fg_img,box,mask=fg_img)
    new_img = Image.alpha_composite(bg_img,fg_img_trans)
    return new_img

answered Apr 28 '19 at 07:16

陈旭周记

21
2

3

Hi, can you possibly add a little more context to your answer? Otherwise the requestor is not likely to learn the "why" behind it. – jimf Apr 28 '19 at 07:22

score 1 · Answer 8 · answered Aug 26 '21 at 03:10

the key code is:

_, _, _, alpha = image_element_copy.split()
image_bg_copy.paste(image_element_copy, box=(x0, y0, x1, y1), mask=alpha)

the full function is:

def paste_image(image_bg, image_element, cx, cy, w, h, rotate=0, h_flip=False):
    image_bg_copy = image_bg.copy()
    image_element_copy = image_element.copy()

    image_element_copy = image_element_copy.resize(size=(w, h))
    if h_flip:
        image_element_copy = image_element_copy.transpose(Image.FLIP_LEFT_RIGHT)
    image_element_copy = image_element_copy.rotate(rotate, expand=True)
    _, _, _, alpha = image_element_copy.split()
    # image_element_copy's width and height will change after rotation
    w = image_element_copy.width
    h = image_element_copy.height
    x0 = cx - w // 2
    y0 = cy - h // 2
    x1 = x0 + w
    y1 = y0 + h
    image_bg_copy.paste(image_element_copy, box=(x0, y0, x1, y1), mask=alpha)
    return image_bg_copy

the above function supports:

position(cx, cy)
auto resize image_element to (w, h)
rotate image_element without cropping it
horizontal flip

How to merge a transparent png image with another image using PIL

8 Answers8

Linked

Related