1Ppmdraw User Manual(0)                                  Ppmdraw User Manual(0)
2
3
4

NAME

6       ppmdraw - draw lines, text, etc on a PPM image
7
8

SYNOPSIS

10       ppmdraw
11
12       { -script=script | -scriptfile=filename } [-verbose]
13
14       [ppmfile]
15
16       All  options  can  be abbreviated to their shortest unique prefix.  You
17       may use two hyphens instead of one to designate an option.  You may use
18       either  white  space  or  an equals sign between an option name and its
19       value.
20
21
22

DESCRIPTION

24       This program is part of Netpbm(1).
25
26       ppmdraw draws lines, shapes, text, etc. on a PPM image.  It  is  essen‐
27       tially  an easy-to-program front end to libnetpbm's "ppmd" subroutines.
28       It lets you create a human-friendly  script  to  describe  the  drawing
29       rather than write a C program.
30
31       You  supply drawing instructions with a script, which you supply either
32       in a file named by a -scriptfile option or as the value  of  a  -script
33       option.  Here is an example script:
34
35       setpos 50 50;
36       text_here 10 30 "hello";
37       setcolor black;
38       text_here 10 0 "there";
39       line_here 5 20;
40
41
42       This  example starts at Column 50, Row 50 of the input image and writes
43       the word "hello" there in 10 pixel high white letters at  a  30  degree
44       angle up from horizontal.  Then, from where that leaves off, the script
45       writes "there" in 10 pixel high black letters  horizontally.   Finally,
46       it  draws a black line to a point 5 pixels over and 20 pixels down from
47       the end of "there."
48
49       If you don't specify ppmfile, ppmdraw reads its input  PPM  image  from
50       Standard Input.
51
52       The output image goes to Standard Output.
53
54       ppmdraw  works  on multi-image streams.  It executes the same script on
55       each input image and produces an output stream with one image for  each
56       input  image.  But before Netpbm 10.32 (February 2006), ppmdraw ignored
57       every image after the first.
58
59       If you just want to add a single line of text to an image, ppmlabel may
60       be more what you want.
61
62
63

OPTIONS

65       In  addition  to  the options common to all programs based on libnetpbm
66       (most notably -quiet, see
67        Common Options ⟨index.html#commonoptions⟩ ),  ppmdraw  recognizes  the
68       following command line options:
69
70
71
72
73       -script=script
74              This option gives the script.  See Script ⟨#script⟩ .
75
76              You may not specify both -script and -scriptfile.
77
78
79       -scriptfile=filename
80              This  option  names  a  file  that contains the script.  - means
81              Standard Input.
82
83              You may not specify both -script and -scriptfile.
84
85              You may not specify - (Standard Input) for both -scriptfile  and
86              the input image file.
87
88
89
90
91

SCRIPT

93       The heart of ppmdraw function is its script.  The script is a character
94       stream.  The stream consists of commands.  Commands  are  separated  by
95       semicolons.   White  space  is  regarded just like in C: Any contiguous
96       stretch of unquoted white space is equivalent to a single space charac‐
97       ter.  Note that this means newlines have no particular significance.
98
99       A  command  is  composed  of tokens, separated from each other by white
100       space.  To write a token that contains white space, enclose it in  dou‐
101       ble  quotes.  Everything between two matched quotation marks is one to‐
102       ken.
103
104       The first token of a command is the verb, which  determines  the  basic
105       function of the command.  The rest of the tokens of the command are ar‐
106       guments, the meaning of which depends upon  the  verb.   The  following
107       list  gives all the valid verbs, and for each its meaning and its argu‐
108       ments.
109
110       Many command have arguments that specify  a  position  on  the  canvas,
111       which  you  specify by row and column.  Row 0 is the top row.  Column 0
112       is the leftmost column.  You may specify negative numbers (but  such  a
113       position would necessarily be off the canvas).
114
115       Your drawing instructions may involve positions not on the canvas.  But
116       any pixels you draw there just get discarded.
117
118
119
120       setpos Set the "current position" in the  image.   This  affects  where
121              subsequent commands draw things.  The 2 arguments are the column
122              and row number.
123
124              At the start of the script, the current position is (0,0).
125
126
127       setlinetype
128              The 1  argument  is  "normal"  or  "nodiag.".   This  effects  a
129              ppmd_setlinetype()  call.   Further  details  are  not yet docu‐
130              mented.
131
132
133       setlineclip
134              This effects a ppmd_setlineclip() call.  Not yet documented.
135
136
137       setcolor
138              This sets the "current color", which  determines  the  color  in
139              which  subsequent  drawing commands draw.  Before the first set‐
140              color, the current color is white.
141
142              There is one argument.  It specifies the color as described  for
143              the   argument   of   the   pnm_parsecolor()   library   routine
144              ⟨libnetpbm_image.html#colorname⟩ .
145
146
147       setfont
148              This sets the "current font", which determines the font in which
149              subsequent  text  drawing  commands draw.  Before the first set‐
150              font, the current font is a built in font called "standard."
151
152              The argument of this command is a file name.  It is the name  of
153              a Netpbm PPMD font file.
154
155              A  Netpbm PPMD font file typically has a name that ends in ".pp‐
156              mdfont" and its first 8 bytes are the ASCII encoding  of  "ppmd‐
157              font".
158
159              There  is only one of these fonts as far as we know.  It is dis‐
160              tributed with Netpbm as  the  file  standard.ppmdfont,  but  you
161              don't  need to use that file because the same font is built into
162              the Netpbm library and is the default.  If you want  to  make  a
163              new  font,  you  can  find  the format of a ppmdfont file in the
164              Netpbm interface header file ppmdfont.h, but you'll have to make
165              your  own  tools  to build it.  The program ppmdmkfont generates
166              standard.ppmdfont, so you can use that as an example.
167
168
169       line   This draws a one pixel wide line in the current  color.   The  4
170              arguments  are:  starting  column,  starting row, ending column,
171              ending row.
172
173              This command does not affect the current position.
174
175
176       line_here
177              This is like line, except it works in a more relative way.
178
179              The line starts at the current point.  The two arguments are the
180              rightward  and  downward displacement from there to the terminal
181              point.  The command moves the current position to  the  terminal
182              point after drawing.
183
184
185       spline3
186              This draws a spline in the current color between 2 points, using
187              a third as a control point.  It approximates a cubic spline seg‐
188              ment.
189
190              The shape of the curve is such that it passes through the speci‐
191              fied endpoints, and lines tangent to the  curve  at  those  end‐
192              points intersect at the control point.  Controlling the tangents
193              allows you to connect this curve to other curves  generated  the
194              same way without having corners at the connection points.
195
196              The  6  arguments  are the starting point column, starting point
197              row, control point column, control point row, ending point  col‐
198              umn, and ending point row.
199
200              This command does not affect the current position.
201
202
203       circle This command draws a circle in the current color.  The three ar‐
204              guments are the column number and row number of  the  center  of
205              the circle and the radius of the circle in pixels.
206
207
208       filledrectangle
209              This command draws a rectangle filled with the current color.
210
211              The 4 arguments are the column and row numbers of the upper left
212              corner of the rectangle, the width of  the  rectangle,  and  the
213              height of the rectangle.
214
215
216       text   This  command  draws  text  in the current color in the built-in
217              font.  The 5 arguments are:
218
219
220
221       •      column number of starting point of baseline
222
223       •      row number of starting point of baseline
224
225       •      height of characters, in pixels
226
227       •      angle of baseline in degrees elevated from the horizontal
228
229       •      text
230
231
232              Note that if your text contains white space, you'll have to  use
233              double quotes to cause it to be a single token.
234
235
236       text_here
237              This  is  like text, except that the baseline starts at the cur‐
238              rent position and the command updates the  current  position  to
239              the other end of the baseline after it draws.
240
241              Bear  in  mind that a script starts with the current position in
242              the top line, so if you leave it there, only the bottom line  of
243              your text will be within the image!
244
245
246
247

HISTORY

249       ppmdraw was new in Netpbm 10.29 (August 2005).
250
251
252

SEE ALSO

254       ppmlabel(1), ppm(1) libnetpbm_draw(1)
255

DOCUMENT SOURCE

257       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
258       source.  The master documentation is at
259
260              http://netpbm.sourceforge.net/doc/ppmdraw.html
261
262netpbm documentation             22 June 2005           Ppmdraw User Manual(0)
Impressum