1Ppmdraw User Manual(0) Ppmdraw User Manual(0)
2
6 ppmdraw - draw lines, text, etc on a PPM image
7
10 ppmdraw
11 { -script=script | -scriptfile=filename } [-verbose]
13 [ppmfile]
15 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
24 This program is part of Netpbm(1).
25 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 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 setpos 50 50;
36 text_here 10 30 "hello";
37 setcolor black;
38 text_here 10 0 "there";
39 line_here 5 20;
40 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 If you don't specify ppmfile, ppmdraw reads its input PPM image from
50 Standard Input.
51 The output image goes to Standard Output.
53 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 If you just want to add a single line of text to an image, ppmlabel may
60 be more what you want.
61
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 -script=script
74 This option gives the script. See Script ⟨#script⟩ .
75 You may not specify both -script and -scriptfile.
77 -scriptfile=filename
80 This option names a file that contains the script. - means
81 Standard Input.
82 You may not specify both -script and -scriptfile.
84 You may not specify - (Standard Input) for both -scriptfile and
86 the input image file.
87
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 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 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 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 Your drawing instructions may involve positions not on the canvas. But
116 any pixels you draw there just get discarded.
117 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 At the start of the script, the current position is (0,0).
125 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 setlineclip
134 This effects a ppmd_setlineclip() call. Not yet documented.
135 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 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 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 The argument of this command is a file name. It is the name of
153 a Netpbm PPMD font file.
154 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 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 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 This command does not affect the current position.
174 line_here
177 This is like line, except it works in a more relative way.
178 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 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 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 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 This command does not affect the current position.
201 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 filledrectangle
209 This command draws a rectangle filled with the current color.
210 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 text This command draws text in the current color in the built-in
217 font. The 5 arguments are:
218 • column number of starting point of baseline
222 • row number of starting point of baseline
224 • height of characters, in pixels
226 • angle of baseline in degrees elevated from the horizontal
228 • text
230 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 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 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
249 ppmdraw was new in Netpbm 10.29 (August 2005).
250
254 ppmlabel(1), ppm(1) libnetpbm_draw(1)
255
257 This manual page was generated by the Netpbm tool 'makeman' from HTML
258 source. The master documentation is at
259 http://netpbm.sourceforge.net/doc/ppmdraw.html
261netpbm documentation 22 June 2005 Ppmdraw User Manual(0)