Support more options for copying images in Tkinter

[serhiy-storchaka]

Feature or enhancement

Tk's photo image has the copy subcommand which supports a number of options,

https://www.tcl.tk/man/tcl8.4/TkCmd/photo.htm#M17

       imageName copy sourceImage ?option value(s) ...?
              Copies a region from the image called sourceImage (which must be
              a photo image) to the  image  called  imageName,  possibly  with
              pixel  zooming and/or subsampling.  If no options are specified,
              this command copies the whole  of  sourceImage  into  imageName,
              starting  at  coordinates (0,0) in imageName.  The following op‐
              tions may be specified:

              -from x1 y1 x2 y2
                     Specifies a rectangular sub-region of the source image to
                     be  copied.  (x1,y1) and (x2,y2) specify diagonally oppo‐
                     site corners of the rectangle.  If  x2  and  y2  are  not
                     specified,  the  default value is the bottom-right corner
                     of the source image.  The pixels copied will include  the
                     left and top edges of the specified rectangle but not the
                     bottom or right edges.  If the -from option is not given,
                     the default is the whole source image.

              -to x1 y1 x2 y2
                     Specifies a rectangular sub-region of the destination im‐
                     age to be affected.  (x1,y1) and (x2,y2)  specify  diago‐
                     nally  opposite  corners  of the rectangle.  If x2 and y2
                     are not specified, the default value is (x1,y1) plus  the
                     size of the source region (after subsampling and zooming,
                     if specified).  If x2 and y2 are  specified,  the  source
                     region will be replicated if necessary to fill the desti‐
                     nation region in a tiled fashion.

              -shrink
                     Specifies that the size of the destination  image  should
                     be reduced, if necessary, so that the region being copied
                     into is at the bottom-right corner of  the  image.   This
                     option  will  not affect the width or height of the image
                     if the user has specified a non-zero value for the -width
                     or -height configuration option, respectively.

              -zoom x y
                     Specifies that the source region should be magnified by a
                     factor of x in the X direction and y in the Y  direction.
                     If  y  is  not given, the default value is the same as x.
                     With this option, each pixel in the source image will  be
                     expanded  into a block of x x y pixels in the destination
                     image, all the same color.  x and y must be greater  than
                     0.

              -subsample x y
                     Specifies that the source image should be reduced in size
                     by using only every xth pixel in the X direction and  yth
                     pixel in the Y direction.  Negative values will cause the
                     image to be flipped about the Y or X axes,  respectively.
                     If y is not given, the default value is the same as x.

              -compositingrule rule
                     Specifies  how transparent pixels in the source image are
                     combined with the destination image.  When a  compositing
                     rule  of overlay is set, the old contents of the destina‐
                     tion image are visible,  as  if  the  source  image  were
                     printed  on  a  piece of transparent film and placed over
                     the top of the destination.  When a compositing  rule  of
                     set is set, the old contents of the destination image are
                     discarded and the source image is used  as-is.   The  de‐
                     fault compositing rule is overlay.

The Tkinter wrapper provides three PhotoImage methods copy(), zoom() and subsample() which implement only -zoom and -subsample options (but not their combination) and the call without options. They also have a different semantic, because always return a new image, without possibility to change the part of the existing image.

I propose to add a new method which supports all options and has closer to the origin semantic. Since the name copy() is already used, the preliminary name of the new method is copy_replace(). It replaces a part of this image with a part of the specified image, possible with zooming and/or subsampling.

It is possible also to add new options to existing methods if they make sense: from_ to all three of them, and zoom and subsample to copy.

Recent discussion: https://discuss.python.org/t/add-additional-options-for-the-tkinters-photoimage-copy-method/51598. IIRC there was also a discussion on the bug tracker a long time ago, but I cannot find it.

Better suggestions for the method name are welcome.

We could implement the copying in the opposite direction: src.copy_into(dst, ...) instead of dst.copy_replace(src, ...), it could be simpler with choosing the right name, but this is less future proof. What if tomorrow Tk allows to copy from bitmap images (currently it is forbidden) or from other sources? We could not use it in Python until implement a new method of BitmapImage.

Linked PRs

• gh-118225: Support more options for copying images in Tkinter #118228