


PBM(n)                         Tcl Extensions                          PBM(n)



Name
  PBM - Portable Bit Map access for Tcl

Syntax
  pbm_new _p_i_c_t-_n_a_m_e ?_o_p_t_i_o_n_s? _f_i_l_e_n_a_m_e
  pbm_new _p_i_c_t-_n_a_m_e ?_o_p_t_i_o_n_s? _w_i_d_t_h _h_e_i_g_h_t
  pbm_text ?_o_p_t_i_o_n_s? _t_e_x_t
  pbm_list
  pbm_list_fonts

  _p_i_c_t delete
  _p_i_c_t size
  _p_i_c_t output ?-gif? ?-ppm? ?-interlace? _f_i_l_e_n_a_m_e
  _p_i_c_t duplicate _n_e_w_n_a_m_e
  _p_i_c_t paste _p_p_i_c_t ?-anchor _p_o_s? ?-stencil _c_o_l_o_r? _x _y
  _p_i_c_t pour ?-color _p_c_o_l? ?-pattern _p_p_i_c_t?  ?-anchor _p_o_s? ?-bleed _b_c_o_l?  ?-
  8neighbor? _x _y
  _p_i_c_t cut _n_e_w_n_a_m_e x y dx dy
  _p_i_c_t crop


Description
  This Tcl extension provides operations for manipulating images stored in
  PBM and GIF formats.  It is derived directly from the PBM sources, so is
  completely compatible with the PBM programs.

  The central concept of the extension is the _p_i_c_t_u_r_e or _p_i_c_t, which holds a
  single rectangular image.  A pict has three attributes: width, height, and,
  optionally, a color that is used to represent transparency, plus the con-
  tents of the image itself.  Picts can be read from files, written to files,
  created, destroyed, and combined in various ways.

  There are four top-level commands, ppbbmm__nneeww, ppbbmm__tteexxtt, ppbbmm__lliisstt, and
  ppbbmm__lliisstt__ffoonnttss.

Creating Pictures
  The ppbbmm__nneeww command creates a new pict:

  pbm_new _p_i_c_t-_n_a_m_e ?_o_p_t_i_o_n_s? _f_i_l_e_n_a_m_e
       Create a new pict by reading a file that contains a GIF or PNM (PBM,
       PGM, or PPM) image.  The type will be determined automatically from
       the contents of the file.

  pbm_new _p_i_c_t-_n_a_m_e ?_o_p_t_i_o_n_s? _w_i_d_t_h _h_e_i_g_h_t
       Create an empty pict of the specified size.  The pict will initially
       be filled with, in order of preference, the --ffiillll color, the --
       ttrraannssppaarreenntt color, or white.

  The ppbbmm__nneeww command returns the name of the pict created and creates a Tcl
  command of that _n_a_m_e, which is used later to manipulate the pict.

  The available options are:

  -transparent _c_o_l_o_r
       Specifies a color that will be treated as "transparent".  This color
       will be ignored in an image when pasting it onto another image, and,
       when a GIF file is written, the transparency option will be set
       appropriately.  This option will be silently ignored if a GIF file
       with the transparency option is read (because the transparency color
       is already determined).  The specific color used is unimportant, and
       the color can be different for different picts.  The only thing that
       matters is that the transparency color should not appear in the actual
       image.  rreedd, ggrreeeenn, and bblluuee are often good choices.  Any of the color
       formats used by PBM may be used to specify the color.  (See _p_p_m_t_o_-
       _g_i_f(1).)

       If _c_o_l_o_r is given as aauuttoo, the transparency color is determined
       automatically by examining the colors of the four corner pixels.  If
       they are all the same, that color is used as the transparency color.
       An error is returned if a transparency color can't be determined.

  -fill _c_o_l_o_r
       Specifies a color to fill the new pict with.  This option may not be
       used when reading the image from a file.

  -maxval _v_a_l_u_e
       Sets the maximum pixel value used in this image, an internal PBM
       parameter.  See the manual pages for _p_g_m(5) or _p_p_m(5).  The default
       (255) should almost always be used.  This option may not be used when
       reading the image from a file, because the maximum value is determined
       from the file.

  The ppbbmm__lliisstt command lists the existing picts, including their sizes and
  any options that are active for them (-maxval and -transparent).


Creating Text Pictures
  The ppbbmm__tteexxtt command creates a new pict consisting of user-supplied text:

  pbm_text ?_o_p_t_i_o_n_s? _t_e_x_t
       Create a new pict by rendering the given _t_e_x_t.  Newlines in _t_e_x_t cause
       it to be put on multiple lines.  Tabs are expanded to 8-character
       tabstops.  (This assumes a fixed-width font, which is not good assump-
       tion).

  The ppbbmm__tteexxtt command returns the name of the pict created and creates a Tcl
  command of that _n_a_m_e, which is used later to manipulate the pict.

  The available options are:

  -fg _c_o_l_o_r
       Specifies the color for the characters.  The default is black.  Any of
       the color formats used by PBM may be used to specify the color.  (See
       _p_p_m_t_o_g_i_f(1).)

  -bg _c_o_l_o_r
       Specifies the color for the background.  By default, the background is
       set to be transparent, with white as the transparency color.  If the
       --bbgg option is given, the background will no longer be transparent.
       (Since text picts will almost always be pasted onto other picts, which
       can have their own transparency colors, the choice of the transparency
       color doesn't matter here.)

  -margin _n
       Add a margin _n pixels wide around the text.

  -font _f_o_n_t_n_a_m_e
       The given font is used for the text.  _f_o_n_t_n_a_m_e can be the name of one
       of the built-in fonts or the name of a font file in X "BDF" format.
       (BDF files have the word "STARTFONT" on the first line.) The built-in
       fonts are named bbddff, which is variable-width (the default) or ffiixxeedd..

  -name _p_i_c_t_n_a_m_e
       _p_i_c_t_n_a_m_e will be used for the name of the pict.  By default, an
       internally-generated name is used.  The default names begin with a
       '%', so the pict is temporary (see below).

  The ppbbmm__lliisstt__ffoonnttss command lists the fonts that have been loaded.


Working With Pictures
  Once a pict has been created, it is manipulated by invoking the pict's name
  as a Tcl command.  For example, if a pict is named "map", then it can be
  deleted with the Tcl command "map delete".  The first argument always
  determines the operation, and may be any of:

  _p_i_c_t delete
       Delete the pict.

  _p_i_c_t size
       Return the (x,y) size of the pict, as a two-item list.

  _p_i_c_t output ?-gif? ?-ppm? ?-interlace? _f_i_l_e_n_a_m_e
       Write the pict to the given file.  -gif and -ppm force an output for-
       mat, otherwise it is determined by looking at the extension of
       _f_i_l_e_n_a_m_e (.gif or .ppm).  -interlace forces "interlace" format for
       GIFs, which lets some Web browsers do better incrementally display of
       images.

  _p_i_c_t duplicate _n_e_w_n_a_m_e
       Create an exact copy of _p_i_c_t, giving it the name _n_e_w_n_a_m_e.

  _p_i_c_t paste _p_p_i_c_t ?-anchor _p_o_s? ?-stencil _c_o_l_o_r? _x _y
       _p_p_i_c_t is pasted onto _p_i_c_t at the coordinates specified by _x and _y,
       with (0,0) at the upper left corner.  _p_i_c_t and _p_p_i_c_t must refer to
       different picts.  If _x is negative, it specifies the distance from the
       right edge.  If _y is negative, it specifies the distance from the bot-
       tom edge.  If any part of _p_p_i_c_t falls outside the bounds of _p_i_c_t,
       _p_p_i_c_t is silently clipped.

       The --aanncchhoorr option specifies which point on _p_p_i_c_t is placed at the
       location determined by (_x,_y).  It is a point of the compass, as
       defined in Tk: n, ne, e, se, s, sw, w, nw, or center.  If the --aanncchhoorr
       option isn't given, the anchor point is determined by the signs of _x
       and _y:
               coord   anchor-position
               +x +y   -nw
               +x -y   -sw
               -x +y   -ne
               -x -y   -se

       The --sstteenncciill option makes _p_p_i_c_t be treated as a stencil: any part of
       _p_p_i_c_t that is not transparent will be painted with the given color.
       Any colors that are associated with _p_p_i_c_t are ignored.

  _p_i_c_t pour ?-color _p_c_o_l? ?-pattern _p_p_i_c_t?  ?-anchor _p_o_s? ?-bleed _b_c_o_l?  ?-
       8neighbor? _x _y
       Paint is poured into the picture at the location determined by (_x,_y).
       The paint flows out and fills all contiguous pixels that had the same
       initial color as (_x,_y).  A pixel is contiguous to its north, south,
       east and west neighbors.  The paint can either be of the solid color
       _p_c_o_l or the pattern _p_p_i_c_t.  If a pattern is specified, it overrides
       any specified color.  If neither is specified, the color defaults to
       black.

       The --aanncchhoorr option specifies which point on _p_p_i_c_t is aligned with
       (_x,_y).  It is specified and interpreted as in the ppaassttee command,
       above.

       The --bblleeeedd option causes the poured color to bleed out one pixel into
       the border, if that color matches _b_c_o_l.  The --88nneeiigghhbboorrss option causes
       paint to flow from a pixel to all eight of its neighbors, rather than
       just the normal four.  This causes a more thorough fill, but is very
       likely to bleed through thin diagonal lines.

  _p_i_c_t cut _n_e_w_n_a_m_e x y dx dy
       The portion of _p_i_c_t specified by (_x,_y) and (_d_x,_d_y) is extracted and
       used to create a new pict, which is given the name _n_e_w_n_a_m_e.  If any
       part of the specified rectangle falls outside of _p_i_c_t, an error is
       returned.

       (_x,_y) determines one corner of the rectangle.  If _x is negative, it
       specifies the distance from the right edge.  If _y is negative, it
       specifies the distance from the bottom edge.  (_d_x,_d_y) must both be
       positive, and determine the size of the rectangle extracted.  The dis-
       tance is always counted moving away from the reference edge.  That is,
       the command "pict cut newpict 5 -5 10 10" will cut a 10x10 pixel
       square out of _p_i_c_t.  The lower-left corner of the extracted square
       will be 5 pixels away from the lower-left corner of _p_i_c_t.

  _p_i_c_t crop Remove all borders of the pict that consist entirely of the same
       color. If the pict has a transparency color, that color is cropped
       away.  Otherwise, the color to remove is determined automatically, as
       follows.  The four corner pixels are examined.  If they are all the
       same color, that color is used.  Otherwise, the pict is not changed.


Temporary Picts
  Sometimes a pict will be used only once after it is created.  In this case,
  it is useful to make the pict temporary.  If a pict's name begins with a
  '%', it will be deleted after it is used.  The most common use for this is
  with text picts, where the pict will be generated, used in a ppaassttee opera-
  tion, and then discarded.  By default, text picts' names begin with a '%'.

  Operations on a pict that modify that pict in place do not delete it.  The
  ppaassttee and ccrroopp are the only two such operations.

  This example reads a pbm file, generates some text, pastes it into the
  pict, and writes the result to a gif file:
          pbm_new template template.pbm
          template paste [pbm_text "Here is some text"] +2 -2
          template output test.gif

  This example generates some red text and outputs it to a gif file:
          [pbm_text -fg red  "Here is\nsome more text"] output text.gif
  In both of these examples, the pict generated by ppbbmm__tteexxtt is automatically
  deleted.


Author
  Glenn Trewitt, Digital Equipment Corporation, Network Systems Laboratory
  Ramsey Haddad, Digital Equipment Corporation, Western Research Laboratory
  The PBM package, which this software is derived from, is

  Copyright (C) 1991 by Jeff Poskanzer

  Permission to use, copy, modify, and distribute this software and its docu-
  mentation for any purpose and without fee is hereby granted, provided that
  the above copyright notice appear in all copies and that both that copy-
  right notice and this permission notice appear in supporting documentation.
  This software is provided "as is" without express or implied warranty.






