man > ppmdraw(1)

Ppmdraw User Manual(1)                 General Commands Manual                Ppmdraw User Manual(1)

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 prefix.  You may use two hyphens in‐
       stead of one to designate an option.  You may use either white space or an  equals  sign  be‐
       tween an option name and its value.



DESCRIPTION
       This program is part of Netpbm(1).

       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 supply 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 degree angle up from horizontal.  Then, from where
       that leaves off, the script writes "there" in 10 pixel high black letters horizontally.   Fi‐
       nally,  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.

       ppmdraw works on multi-image streams.  It executes the same script on each  input  image  and
       produces an output stream with one image for each input image.  But before Netpbm 10.32 (Feb‐
       ruary 2006), ppmdraw ignored every image after the first.

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



OPTIONS
       In addition to the options common to all programs based on libnetpbm  (most  notably  -quiet,
       see ]8;;index.html#commonoptions\ Common Options]8;;\ ), ppmdraw recognizes the following command line options:




       -script=script
              This option gives the script.  See ]8;;#script\Script]8;;\ .

              You may not specify both -script and -scriptfile.


       -scriptfile=filename
              This option 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 separated by semicolons.  White space  is  regarded  just
       like  in  C:  Any  contiguous stretch of unquoted white space is equivalent to a single space
       character.  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 double quotes.  Everything between two matched quo‐
       tation 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 tokens 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 argu‐
       ments.

       Many command have arguments that specify a position on the canvas, which you specify  by  row
       and  column.   Row 0 is the top row.  Column 0 is the leftmost column.  You may specify nega‐
       tive numbers (but such a position would necessarily be off the canvas).

       Your drawing instructions may involve positions not on the canvas.  But any pixels  you  draw
       there just get discarded.



       setpos Set  the "current position" in the image.  This affects 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 documented.


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

              There is one argument.  It specifies the color as described  for  the  ]8;;libnetpbm_image.html#colorname\argument of the
              pnm_parsecolor() library routine]8;;\ .


       setfont
              This sets the "current font", which determines the font in which subsequent text draw‐
              ing  commands  draw.   Before  the  first setfont, the current font 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 "ppmdfont".

              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 ppmd‐
              font.h, but you'll have to make your own tools to build it.   The  program  ppmdmkfont
              generates standard.ppmdfont, so you can use that as an example.


       line   This  draws a one pixel wide line in the current color.  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  down‐
              ward displacement from there to the terminal point.  The command moves the current po‐
              sition to the terminal point after drawing.


       spline3
              This  draws a spline in the current color between 2 points, using a third as a control
              point.  It approximates a cubic spline segment.

              The shape of the curve is such that it passes through  the  specified  endpoints,  and
              lines  tangent  to  the curve at those endpoints intersect at the control point.  Con‐
              trolling the tangents allows you to connect this curve to other curves  generated  the
              same way without having corners at the connection points.

              The  6 arguments are the starting point column, starting point row, control point col‐
              umn, control point row, ending point column, and ending point 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 pix‐
              els.


       filledrectangle
              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 rectan‐
              gle, 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 5 arguments
              are:



       •      column number of starting point of baseline

       •      row number of starting point of baseline

       •      height of characters, in pixels

       •      angle of baseline in degrees elevated from the horizontal

       •      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 position 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(1), ppm(1) libnetpbm_draw(1)

DOCUMENT SOURCE
       This  manual  page  was  generated by the Netpbm tool 'makeman' from HTML source.  The master
       documentation is at

              http://netpbm.sourceforge.net/doc/ppmdraw.html

netpbm documentation                        22 June 2005                      Ppmdraw User Manual(1)