TIP 166: Reading and Writing the Photo Image Alpha Channel

Author:         Donal K. Fellows <[email protected]>
Author:         Simon Bachmann <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        19-Nov-2003
Keywords:       Tk,image get,image put
Tcl-Version:    8.7
Tk-Branch:      tip-166


This TIP describes how to update the image get and image put subcommands so as to allow script-level access to the full alpha channel information that has been present in the photo image data model since Tk 8.3.


Alpha channels. We've had them in Tk's photo image data model (which is currently 8-bits-per-channel RGBA) for quite some time now. We can copy the alpha data around inside the image. We now display them correctly on deep-enough displays (many thanks to the people who have worked on that!) But can we write alpha data into an image? No. Not unless you have an image format handler that produces alpha data installed (e.g. the PNG from tkimg.) I think we should fix this so that people can read and write the full alpha data from scripts.


I propose to update the photoImageInstance get subcommand so that it takes an extra option -withalpha (to be placed after the coordinates). If that option is specified, the subcommand will return four values instead of three, with the fourth being the contents of the alpha channel for the pixel. Without this new option, the subcommand will return three values as before.

I also propose to update the photoImageInstance put subcommand so that alpha channel information may be specified in the following ways when using the list-of-lists-of-pixel-data format (the image-format format will be up to the particular image format code, as always.)

It should also be possible to include alpha information in the data retrieved with the photoImageInstance data subcommand. For this, I propose to make the list-of-lists-of-pixel-data format a regular photo image format (like PNG, GIF, PPM, etc.) with the name default. This format will have no file read/write capabilities. As before, the list-of-lists format will be the default choice for photoImageInstance data, and the last one to be tried for photoImageInstance put. The main benefit of this change is that it will be possible to request the default format explicitly with the -format option and - most important - to pass suboptions to the format handler. The default image data format shall accept the suboption -colorformat type which specifies the format to be used to encode the color and alpha data for each pixel. Accepted values shall be rgb for the #RRGGBB format (the current format and default for the suboption), rgba for the #RRGGBBAA format, and list for the list format with four elements. This change will have two side effects:

Finally, the photoImageInstance transparency command's subcommands will be updated in the following way:


Create a small image with a black border and a partially-transparent red area in the center.

image create photo transExample
transExample put black -to 0 0 10 10
transExample put [email protected] -to 2 2 8 8

Retrieve the alpha value of a pixel near the middle of the image created previously.

set aVal [transExample transparency get 5 5 -alpha]

Create a green box with a simple shadow effect

image create photo foo
# Make a simple graduated fill varying in alpha for the shadow
for {set i 14} {$i>0} {incr i -1} {
   set i2 [expr {$i+30}]
   foo put [format black#%x [expr {15-$i}]] -to $i $i $i2 $i2
# Put a solid green rectangle on top
foo put #080 -to 0 0 30 30

Retrieve image data with alpha information in the list-of-lists form and create a new image with it.

image create photo bar -file imageWithTransparency.png
set imageData [bar data -format {default -colorformat rgba}

# Inspect / modify / save data

image create photo baz -data $imageData

Reference Implementation

Branch tip-166 on fossil.


This document is placed in the public domain.