Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Ppmdraw	User Manual(0)					Ppmdraw	User Manual(0)

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


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


       All  options  can  be abbreviated to their shortest unique prefix.  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

       This program is part of Netpbm(1).

       ppmdraw draws lines, shapes, text, etc. on a PPM	image.	It  is	essen-
       tially  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.   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.

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

	      This option gives	the script.  See Script	<#script> .

	      You may not specify both -script and -scriptfile.

	      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.

       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 charac-
       ter.  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 to-

       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 ar-
       guments,	the meaning of which depends upon  the	verb.	The  following
       list  gives all the valid verbs,	and for	each its meaning and its argu-

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

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

	      This effects a ppmd_setlineclip()	call.  Not yet documented.

	      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.

	      There is one argument.  It specifies the color as	described  for
	      the   argument   of   the	  pnm_parsecolor()   library   routine
	      <libnetpbm_image.html#colorname> .

	      This sets	the "current font", which determines the font in which
	      subsequent  text	drawing	 commands draw.	 Before	the first set-
	      font, 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 ".pp-
	      mdfont" and its first 8 bytes are	the ASCII encoding  of	"ppmd-

	      There  is	only one of these fonts	as far as we know.  It is dis-
	      tributed 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.  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.

	      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  downward displacement from there to the terminal
	      point.  The command moves	the current position to	 the  terminal
	      point after drawing.

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

	      The shape	of the curve is	such that it passes through the	speci-
	      fied endpoints, and lines	tangent	to the	curve  at  those  end-
	      points intersect at the control point.  Controlling 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 column, control point row, ending point  col-
	      umn, and ending point row.

	      This command does	not affect the current position.

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

	      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 5 arguments are:

       o      column number of starting	point of baseline

       o      row number of starting point of baseline

       o      height of	characters, in pixels

       o      angle of baseline	in degrees elevated from the horizontal

       o      text

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

	      This  is	like text, except that the baseline starts at the cur-
	      rent 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!

       ppmdraw was new in Netpbm 10.29 (August 2005).

       ppmlabel(1), ppm(5) libnetpbm_draw(3)

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

netpbm documentation		 22 June 2005		Ppmdraw	User Manual(0)


Want to link to this manual page? Use this URL:

home | help