"box" parameter of PIL.ImageTk.PhotoImage.paste method appears to be dysfunctional

[daver1691]

The "box" 4-tuple parameter of the PIL.ImageTk.PhotoImage.paste method is intended to allow a PIL Image to be pasted onto a Tkinter compatible PhotoImage within the specified box coordinates, but "box" appears to be dysfunctional, and I can't see anything in the source code of the method to implement its function. Smaller images pasted to larger images appear top-left and ignore any "box" value.

The documentation detailing the "box" parameter is here:
https://pillow.readthedocs.io/en/stable/reference/ImageTk.html#PIL.ImageTk.PhotoImage.paste

The source code of the paste method includes "box" as a parameter and has a docstring for it:
https://github.com/python-pillow/Pillow/blob/main/src/PIL/ImageTk.py#L178

Test code. A smaller blue box pasted into a larger yellow box always appears top-left and ignores the paste coordinates:

import tkinter as tk
from PIL import Image, ImageTk
root = tk.Tk()
pil_img1 = Image.new("RGB",(400, 200), "yellow")
tk_img1 = ImageTk.PhotoImage(pil_img1)
tk.Label(root, image=tk_img1).pack()
pil_img2 = Image.new("RGB",(200, 100), "blue")
tk_img1.paste(pil_img2, box=(100, 50, 200, 150))
root.mainloop()

Tested with Windows 10, Python 3.10.4, Pillow 9.0.1
and with Ubuntu 21.10, Python 3.9.7, Pillow 8.1.2

[radarhere]

Investigating, the box parameter is unused, and this has been the case since the PIL fork.

[radarhere]

Experimenting with our call to Tk and your code, I don't think Tk actually provides a simple way to do this.

We could add this functionality at the Python level - by creating a larger RGBA image, pasting the incoming image into that, and then applying it onto the Tk image. But then again, so could you as the user.

Would you like us to implement this feature, or is it easier for us to deprecate and eventually remove the box parameter?

[daver1691]

Myself, I did find another way to do what I wanted. That code for creating a Tcl command looks complicated, so if that's non-trivial to adapt, then I'm OK with not adding to it. Remove the feature from the documentation and have the docstring say that it's unused?

[radarhere]

Thanks. I've created #6178. It suggests removing the description for box, and raises a warning when the parameter is used.