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 or where it has been
       set transparent by the transparency set subcommand.


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
              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.

       -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:

       imageName blank
              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
                     specified, the default value is (x1,y1) plus
                     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.

              -compositingrule rule
                     Specifies  how  transparent  pixels  in  the
                     source  image are combined with the destina-
                     tion image.   When  a  compositing  rule  of
                     overlay is set, the old contents of the des-
                     tination image are visible, as if the source
                     image were printed on a piece of transparent
                     film and placed over the top of the destina-
                     tion.   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 default compositing rule is
                     overlay.

       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 han-
                     dler that has the  capability  to  read  the
                     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
              interpret  the  data  in  data,  and then reads the
              image encoded within into imageName  (the  destina-
              tion image).  If data does not match any known for-
              mat, an attempt  to  interpret  it  as  a  (top-to-
              bottom) list of scan-lines is made, with each scan-
              line being a (left-to-right) list of  pixel  colors
              (see  Tk_GetColor  for  a description of valid col-
              ors.)  Every scan-line must be of the same  length.
              Note that when data is a single color name, you are
              instructing Tk to fill a  rectangular  region  with
              that  color.   The  following options may be speci-
              fied:

              -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.

              -to x1 y1 ?x2 y2?
                     Specifies the coordinates  of  the  top-left
                     corner  (x1,y1)  of  the region of imageName
                     into which data  from  filename  are  to  be
                     read.   The  default  is (0,0).  If x2,y2 is
                     given and data is not large enough to  cover
                     the  rectangle specified by this option, the
                     image data extracted will  be  tiled  so  it
                     covers  the  entire  destination  rectangle.
                     Note that if data specifies a  single  color
                     value,  then  a region extending to the bot-
                     tom-right corner represented by (x2,y2) will
                     be filled with that color.

       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
                     default is (0,0).

       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 transparency subcommand ?arg arg ...?
              Allows  examination  and manipulation of the trans-
              parency information in the  photo  image.   Several
              subcommands are available:

              imageName transparency get x y
                     Returns a boolean indicating if the pixel at
                     (x,y) is transparent.

              imageName transparency set x y boolean
                     Makes the  pixel  at  (x,y)  transparent  if
                     boolean is true, and makes that pixel opaque
                     otherwise.

       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.  Han-
       dlers  are  added  to  the list by registering them with a
       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.  Note that not  all  image  han-
       dlers  may  support  writing  transparency data to a file,
       even where the target image format does.


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  configura-
       tion  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.


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
