NAME
photo - Full-color images
SYNOPSIS
image create photo ?name? ?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, or it can be supplied
from C code through a procedural interface. At present,
only GIF and PPM/PGM formats are supported, but an inter
face exists to allow additional image file formats to be
added easily. A photo image is transparent in regions
where no image data has been supplied.
CREATING PHOTOS
Like all images, photos are created using the image create
command. Photos support the following options:
-data string
Specifies the contents of the image as a string.
The string can contain base64 encoded data or
binary data. 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
Specifies the name of the file format for the data
specified with the -data or -file option.
-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 expo
nent 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
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.
-palette palette-spec
Specifies the resolution of the color cube to be
allocated for displaying this image, and thus the
number of colors used from the colormaps of the
windows where it is displayed. The palette-spec
string may be either a single decimal number, spec
ifying the number of shades of gray to use, or
three decimal numbers separated by slashes (/),
specifying the number of shades of red, green and
blue to use, respectively. If the first form (a
single number) is used, the image will be displayed
in monochrome (i.e., grayscale).
-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 hori
zontally to fit the data stored in it.
IMAGE COMMAND
When a photo image is created, Tk also creates a new com
mand whose name is the same as the image. This command
may be used to invoke various operations on the image. It
has the following general form:
imageName option ?arg arg ...?
Option and the args determine the exact behavior of the
command.
Those options that write data to the image generally
expand the size of the image, if necessary, to accommodate
the data written to the image, unless the user has speci
fied non-zero values for the -width and/or -height config
uration options, in which case the width and/or height,
respectively, of the image will not be changed.
The following commands are possible for photo images:
Blank the image; that is, set the entire image to
have no data, so it will be displayed as transpar
ent, 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 image create photo command.
imageName configure ?option? ?value option value ...?
Query or modify the configuration options for the
image. If no option is specified, returns a list
describing all of the available options for image
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ
ing the one named option (this list will be identi
cal to the corresponding sublist of the value
returned if no option is specified). 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 image create photo command.
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 sub
sampling. If no options are specified, this com
mand copies the whole of sourceImage into image
Name, starting at coordinates (0,0) in imageName.
The following options 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 opposite corners
of the rectangle. If x2 and y2 are not
specified, the default value is the bottom-
right corner of the source image. The pix
els 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 image to be affected. (x1,y1)
and (x2,y2) specify diagonally opposite cor
ners of the rectangle. If x2 and y2 are not
the size of the source region (after subsam
pling and zooming, if specified). If x2 and
y2 are specified, the source region will be
replicated if necessary to fill the destina
tion 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 direc
tion 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.
imageName data ?option value(s) ...?
Returns image data in the form of a string. The
following options may be specified:
-background color
If the color is specified, the data will not
contain any transparency information. In all
transparent pixels the color will be
replaced by the specified color.
-format format-name
Specifies the name of the image file format
handler to be used. Specifically, this sub
command searches for the first handler whose
name matches a initial substring of format-
name and which has the capability to read
this image data. If this option is not
given, this subcommand uses the first
image data.
-from x1 y1 x2 y2
Specifies a rectangular region of imageName
to be returned. If only x1 and y1 are spec
ified, 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 rectangu
lar region, including x1,y1 and excluding
x2,y2. The default, if this option is not
given, is the whole image.
-grayscale
If this options is specified, the data will
not contain color information. All pixel
data will be transformed into grayscale.
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 com
ponents respectively.
imageName put data ?option value(s) ...?
Sets pixels in imageName to the data specified in
data. This command first searches the list of image
file format handlers for a handler that can inter
pret the data in data, and then reads the image in
filename into imageName (the destination image).
The following options may be specified:
-format format-name
Specifies the format of the image data in
data. Specifically, only image file format
handlers whose names begin with format-name
will be used while searching for an image
data format handler to read the data.
-from x1 y1 x2 y2
Specifies a rectangular sub-region of the
image file data to be returned. If only x1
and y1 are specified, the region extends
from (x1,y1) to the bottom-right corner of
the image in the image file. If all four
coordinates are specified, they specify
diagonally opposite corners or the region.
The default, if this option is not speci
fied, is the whole of the image.
-shrink
If this option, the size of imageName will
be reduced, if necessary, so that the region
at the bottom-right corner of the imageName.
This option will not affect the width or
height of the image if the user has speci
fied a non-zero value for the -width or
-height configuration option, respectively.
-to x y
Specifies the coordinates of the top-left
corner of the region of imageName into which
data from filename are to be read. The
default is (0,0).
imageName read filename ?option value(s) ...?
Reads image data from the file named filename into
the image. This command first searches the list of
image file format handlers for a handler that can
interpret the data in filename, and then reads the
image in filename into imageName (the destination
image). The following options may be specified:
-format format-name
Specifies the format of the image data in
filename. Specifically, only image file
format handlers whose names begin with for
mat-name will be used while searching for an
image data format handler to read the data.
-from x1 y1 x2 y2
Specifies a rectangular sub-region of the
image file data to be copied to the destina
tion image. If only x1 and y1 are speci
fied, the region extends from (x1,y1) to the
bottom-right corner of the image in the
image file. If all four coordinates are
specified, they specify diagonally opposite
corners or the region. The default, if this
option is not specified, is the whole of the
image in the image file.
-shrink
If this option, the size of imageName will
be reduced, if necessary, so that the region
into which the image file data are read is
at the bottom-right corner of the imageName.
This option will not affect the width or
height of the image if the user has speci
fied a non-zero value for the -width or
-height configuration option, respectively.
-to x y
Specifies the coordinates of the top-left
corner of the region of imageName into which
data from filename are to be read. The
imageName redither
The dithering algorithm used in displaying photo
images propagates quantization errors from one
pixel to its neighbors. If the image data for ima
geName is supplied in pieces, the dithered image
may not be exactly correct. Normally the differ
ence is not noticeable, but if it is a problem,
this command can be used to recalculate the
dithered image in each window where the image is
displayed.
imageName write filename ?option value(s) ...?
Writes image data from imageName to a file named
filename. The following options may be specified:
-background color
If the color is specified, the data will not
contain any transparency information. In all
transparent pixels the color will be
replaced by the specified color.
-format format-name
Specifies the name of the image file format
handler to be used to write the data to the
file. Specifically, this subcommand
searches for the first handler whose name
matches a initial substring of format-name
and which has the capability to write an
image file. If this option is not given,
this subcommand uses the first handler that
has the capability to write an image file.
-from 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 cor
ners of the rectangular region. The
default, if this option is not given, is the
whole image.
-grayscale
If this options is specified, the data will
not contain color information. All pixel
data will be transformed into grayscale.
IMAGE FORMATS
The photo image code is structured to allow handlers for
additional image file formats to be added easily. The
photo image code maintains a list of these handlers.
call to Tk_CreatePhotoImageFormat. The standard Tk dis
tribution comes with handlers for PPM/PGM and GIF formats,
which are automatically registered on initialization.
When reading an image file or processing string data spec
ified with the -data configuration option, the photo image
code invokes each handler in turn until one is found that
claims to be able to read the data in the file or string.
Usually this will find the correct handler, but if it
doesn't, the user may give a format name with the -format
option to specify which handler to use. In fact the photo
image code will try those handlers whose names begin with
the string specified for the -format option (the compari
son is case-insensitive). For example, if the user speci
fies -format gif, then a handler named GIF87 or GIF89 may
be invoked, but a handler named JPEG may not (assuming
that such handlers had been registered).
When writing image data to a file, the processing of the
-format option is slightly different: the string value
given for the -format option must begin with the complete
name of the requested handler, and may contain additional
information following that, which the handler can use, for
example, to specify which variant to use of the formats
supported by the handler.
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 reason
able 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 True
Color 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 col
ors that a photo image uses with the -palette
fies 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 dis
play, by giving a single number rather than three numbers
separated by slashes.
CREDITS
The photo image type was designed and implemented by Paul
Mackerras, based on his earlier photo widget and some sug
gestions from John Ousterhout.
KEYWORDS
photo, image, color
Man(1) output converted with
man2html