PhotoImage - Full-color images

SYNOPSIS

imageName = tkinter.PhotoImage([**options])

DESCRIPTION

A photo is an image whose pixels can display any color or be transparent. A photo image is stored internally in full color (32 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file or a string. At present, only PNG, GIF and PPM/PGM formats are supported.

SPECEFIC OPTIONS

Photos support the following options:

data="string"

Specifies the contents of the image as a string. The string should contain data in the default list-of-lists form, binary data or, for some formats, base64-encoded data (this is currently guaranteed to be supported for PNG and GIF images). The format of the string must be one of those for which there is an image file format handler that will accept string data. If both the data and file options are specified, the file option takes precedence.

format="format-name [-option value ...]"

Specifies the name of the file format for the data specified with the data or file option and optional arguments passed to the format handler. Note: the value of this option must be a Tcl list, and must be in string format.

file=name

name gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data.

gamma=value

Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most CRT displays is a power function of the input value, to a good approximation; gamma is the exponent and is typically around 2). The value specified must be greater than zero. The default value is one (no correction). In general, values greater than one will make the image lighter, and values less than one will make it darker.

height=number

Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it.

width=number

Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it.

METHODS

The following methods are possible for photo images:

imageName.blank()

Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through.

imageName.cget("option")

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the PhotoImage class.

imageName.configure([**options])

If one or more >option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string.

Option may have any of the values accepted by the PhotoImage class.

imageName.get(x ,y)

Returns the color of the pixel at coordinates (x,y) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively.

imageName.write(filename ,format ,from_coords)

Writes image data from imageName to a file named filename. The following options may be specified:

format="format-name [-option value ...]"

Specifies the name of the image file format handler to be used to write the data to the file and, optionally, options to pass to the format handler. Specifically, this option searches for the first handler whose name matches the format-name and which has the capability to write an image file. If this option is not given, the format is guessed from the file extension. If that cannot be determined, this option uses the first handler that has the capability to write an image file. Note: the value of this option must be a Tcl list, and is in string format

from_coords=(x1 ,y1 ,x2 ,y2)

Specifies a rectangular region of imageName to be written to the image file. If only x1 and y1 are specified, the region extends from (x1,y1) to the bottom-right corner of imageName. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image.

FORMAT SUBOPTIONS

the -format option supports sub-options. At the time of writing, the following are supported:

"gif -index indexValue"

When parsing a multi-part GIF image, Tkinter normally only accesses the first image. By giving the -index sub-option, the indexValue'th value may be used instead. The indexValue must be an integer from 0 up to the number of image parts in the GIF data.

"png -alpha alphaValue"

An additional alpha filtering for the overall image, which allows the background on which the image is displayed to show through. This usually also has the effect of desaturating the image. The alphaValue must be between 0.0 and 1.0.

COLOR ALLOCATION

When a photo image is displayed in a window, the photo image code allocates colors to use to display the image and dithers the image, if necessary, to display a reasonable approximation to the image using the colors that are available. The colors are allocated as a color cube, that is, the number of colors allocated is the product of the number of shades of red, green and blue.

Normally, the number of colors allocated is chosen based on the depth of the window. For example, in an 8-bit PseudoColor window, the photo image code will attempt to allocate seven shades of red, seven shades of green and four shades of blue, for a total of 198 colors. In a 1-bit StaticGray (monochrome) window, it will allocate two colors, black and white. In a 24-bit DirectColor or TrueColor window, it will allocate 256 shades each of red, green and blue. Fortunately, because of the way that pixel values can be combined in DirectColor and TrueColor windows, this only requires 256 colors to be allocated. If not all of the colors can be allocated, the photo image code reduces the number of shades of each primary color and tries again.

The user can exercise some control over the number of colors that a photo image uses with the palette configuration option. If this option is used, it specifies the maximum number of shades of each primary color to try to allocate. It can also be used to force the image to be displayed in shades of gray, even on a color display, by giving a single number rather than three numbers separated by slashes.