ppmdraw

                                    ppmdraw

   Updated: 22 June 2005
   Table Of Contents

NAME

   ppmdraw - draw lines, text, etc on a PPM image

SYNOPSIS

   ppmdraw  {  -script=script | -scriptfile=filename } [-verbose]
[ppmfile]

   All options can be abbreviated to their shortest  unique  pre-
fix. You may use
   two hyphens instead of one to designate an option. You may use
either white
   space or an equals sign between an option name and its  value.

DESCRIPTION

   This  program  is part of Netpbm. ppmdraw draws lines, shapes,
text, etc. on a
   PPM image. It is essentially an easy-to-program front  end  to
libnetpbm’s
   "ppmd" subroutines. It lets you create a human-friendly script
to describe
   the drawing rather than write a C program.

   You supply drawing instructions with a script, which you  sup-
ply either in a
   file  named  by  a  -scriptfile  option  or  as the value of a
-script option. Here
   is an example script:

setpos 50 50; text_here 10 30 "hello"; setcolor black;  text_here
10 0 "there"; line_here 5 20;

   This  example  starts  at Column 50, Row 50 of the input image
and writes the
   word "hello" there in 10 pixel high white letters at a 30  de-
gree angle up
   from  horizontal. Then, from where that leaves off, the script
writes "there"
   in 10 pixel high black letters horizontally. Finally, it draws
a black line
   to  a  point  5 pixels over and 20 pixels down from the end of
"there."

   If  you  don’t specify ppmfile, ppmdraw reads  its  input  PPM
image from
   Standard Input.

   The output image goes to Standard Output.

   If  you  just  want  to add a single line of text to an image,
ppmlabel may be
   more what you want.

OPTIONS

   The arguments on the ppmlabel command line are not options  in
the strict
   sense;  they  are commands which control the placement and ap-
pearance of the
   text being added to the input pixmap. They are  executed  left
to right, and
   any number of arguments may appear.
   -script=script
          This option gives the script. See Script.
          You may not specify both -script and -scriptfile.
   -scriptfile=filename
          This  options  names a file that contains the script. -
means Standard
          Input.
          You may not specify both -script and -scriptfile.
          You  may  not  specify  -  (Standard  Input)  for  both
-scriptfile and the
          input image file.

SCRIPT

   The  heart  of ppmdraw function is its script. The script is a
character
   stream.  The  stream  consists  of commands. Commands are sep-
arated by
   semicolons.  White  space is regarded just like in C: Any con-
tiguous stretch
   of unquoted white space is equivalent to a single space  char-
acter. Note that
   this means newlines have no particular significance.

   A  command is composed of tokens, separated from each other by
white space.
   To write a token that contains white space, enclose it in dou-
ble quotes.
   Everything between two matched quotation marks is one token.

   The   first   token of a command is the verb, which determines
the basic
   function of the command. The rest of the token of the  command
are arguments,
   the meaning of which depends upon the verb. The following list
gives all the
   valid verbs, and for each its meaning and its arguments.

   setpos
          Set  the  "current  position"  in the image.  This  af-
fects where
          subsequent  commands  draw  things. The 2 arguments are
the column and
          row number.

          At the start of the script,  the  current  position  is
(0,0).

   setlinetype
          The   1   argument   is  "normal"  or  "nodiag.".  This
effects a
          ppmd_setlinetype() call. Further details  are  not  yet
documented.

   setlineclip
          This  effects  a ppmd_setlineclip() call. Not yet docu-
mented.

   setcolor
          This sets the "current  color",  which  determines  the
color in which
          subsequent drawing commands draw. Before the first set-
color, the
          current color is white.

   setfont
          This sets the "current font", which determines the font
in which
          subsequent text drawing commands draw. Before the first
setfont, the
          current color is a built in font called "standard."

          The argument of this command is a file name. It is  the
name of a
          Netpbm PPMD font file.

          A  Netpbm PPMD font file typically has a name that ends
in ".ppmdfont"
          and its first 8 bytes are the ASCII encoding of  "ppmd-
font".

          There  is only one of these fonts as far as we know. It
is distributed
          with Netpbm as  the  file  standard.ppmdfont,  but  you
don’t need to use
          that  file  because  the  same  font  is built into the
Netpbm library and
          is the default. If you want to make a new font, you can
find the
          format   of   a  ppmdfont  file in the Netpbm interface
header file
          ppmdfont.h, but you’ll have to make your own  tools  to
build it.

   line
          This  draws  a  one pixel wide line in the current col-
or. The 4
          arguments are: starting column,  starting  row,  ending
column, ending
          row.

          This command does not affect the current position.

   line_here
          This  is  like line, except it works in a more relative
way.

          The line starts at the current point. The two arguments
are the
          rightward  and  downard  displacement from there of the
terminal point.
          The command moves the current position to the  terminal
point after
          drawing.

   spline3
          This  draws  a  spline  in  the current color through 3
points. The 6
          arguments are the starting column, starting row, middle
column,
          middle row, ending column, and ending row.

          This command does not affect the current position.

   circle
          This  command  draws a circle in the current color. The
three arguments
          are the column number and row number of the  center  of
the circle and
          the radius of the circle in pixels.

   filled_rectangle
          This  command draws a rectangle filled with the current
color. The 4
          arguments are the column and row numbers of  the  upper
left corner of
          the  rectangle,  the  width  of  the rectangle, and the
height of the
          rectangle.

   text
          This command draws text in the  current  color  in  the
built-in font.
          The 6 arguments are:

         1. column number of starting point of baseline
         2. row number of starting point of baseline
         3. height of characters, in pixels
         4.  angle of baseline in degrees elevated from the hori-
zontal
         5. text

          Note that if your text  contains  white  space,  you’ll
have to use
          double quotes to cause it to be a single token.

   text_here
          This  is  like text, except that the baseline starts at
the current
          position and the command updates the  current  position
to the other
          end of the baseline after it draws.

          Bear  in mind that a script starts with the current po-
sition in the
          top line, so if you leave it  there,  only  the  bottom
line of your text
          will be within the image!

HISTORY

   ppmdraw was new in Netpbm 10.29 (August 2005).

SEE ALSO

   ppmlabel, ppm
     _________________________________________________________________



Table Of Contents

     * SYNOPSIS
     * DESCRIPTION
     * OPTIONS
     * SCRIPT
     * SEE ALSO