1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html><head><title>Ppmdraw User Manual</title></head>
<body>
<h1>ppmdraw</h1>
Updated: 22 June 2005
<br>
<a href="#index">Table Of Contents</a>
<h2>NAME</h2>
ppmdraw - draw lines, text, etc on a PPM image
<h2 id="synopsis">SYNOPSIS</h2>
<b>ppmdraw</b>
{
<b>-script=</b><i>script</i>
|
<b>-scriptfile=</b><i>filename</i>
}
[<b>-verbose</b>]
[<i>ppmfile</i>]
<p>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 value.
<h2 id="description">DESCRIPTION</h2>
<p>This program is part of <a href="index.html">Netpbm</a>.
<p><b>ppmdraw</b> draws lines, shapes, text, etc. on a PPM image. It is
essentially an easy-to-program front end to <b>libnetpbm</b>'s
"ppmd" subroutines. It lets you create a human-friendly
script to describe the drawing rather than write a C program.
<p>You supply drawing instructions with a script, which you supply either
in a file named by a <b>-scriptfile</b> option or as the value of a
<b>-script</b> option. Here is an example script:
<pre>
<code>
setpos 50 50;
text_here 10 30 "hello";
setcolor black;
text_here 10 0 "there";
line_here 5 20;
</code>
</pre>
<p>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."
<p>If you don't specify <i>ppmfile</i>, <b>ppmdraw</b> reads its input
PPM image from Standard Input.
<p>The output image goes to Standard Output.
<p><b>ppmdraw</b> 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),
<b>ppmdraw</b> ignored every image after the first.
<p>If you just want to add a single line of text to an image,
<b>ppmlabel</b> may be more what you want.
<h2 id="options">OPTIONS</h2>
<p>In addition to the options common to all programs based on libnetpbm
(most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
Common Options</a>), <b>ppmdraw</b> recognizes the following
command line options:
<dl compact>
<dt><b>-script=</b><i>script</i>
<dd>This option gives the script. See <a href="#script">Script</a>.
<p>You may not specify both <b>-script</b> and <b>-scriptfile</b>.
<dt><b>-scriptfile=</b><i>filename</i>
<dd>This option names a file that contains the script. <b>-</b>
means Standard Input.
<p>You may not specify both <b>-script</b> and <b>-scriptfile</b>.
<p>You may not specify <b>-</b> (Standard Input) for both
<b>-scriptfile</b> and the input image file.
</dl>
<h2 id="script">SCRIPT</h2>
<p>The heart of <b>ppmdraw</b> 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.
<p>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 quotation marks
is one token.
<p>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 arguments.
<p>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).
<p>Your drawing instructions may involve positions not on the canvas.
But any pixels you draw there just get discarded.
<dl>
<dt>setpos
<dd>Set the "current position" in the image. This affects
where subsequent commands draw things. The 2 arguments are the column
and row number.
<p>At the start of the script, the current position is (0,0).
<dt>setlinetype
<dd>The 1 argument is "normal" or "nodiag.". This
effects a <b>ppmd_setlinetype()</b> call. Further details are not yet
documented.
<dt>setlineclip
<dd>This effects a <b>ppmd_setlineclip()</b> call. Not yet documented.
<dt>setcolor
<dd>This sets the "current color", which determines the color
in which subsequent drawing commands draw. Before the first
<b>setcolor</b>, the current color is white.
<p>There is one argument. It specifies the color as described for the
<a href="libnetpbm_image.html#colorname">argument of the <b>pnm_parsecolor()</b>
library routine</a>.
<dt>setfont
<dd>This sets the "current font", which determines the font
in which subsequent text drawing commands draw. Before the first
<b>setfont</b>, the current font is a built in font called
"standard."
<p>The argument of this command is a file name. It is the name of a
Netpbm PPMD font file.
<p>A Netpbm PPMD font file typically has a name that ends in
".ppmdfont" and its first 8 bytes are the ASCII encoding of
"ppmdfont".
<p>There is only one of these fonts as far as we know. It is distributed with
Netpbm as the file <b>standard.ppmdfont</b>, 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 <b>ppmdfont.h</b>, but
you'll have to make your own tools to build it. The program <b>ppmdmkfont</b>
generates <b>standard.ppmdfont</b>, so you can use that as an example.
<dt>line
<dd>This draws a one pixel wide line in the current color. The 4 arguments
are: starting column, starting row, ending column, ending row.
<p>This command does not affect the current position.
<dt>line_here
<dd>This is like <b>line</b>, except it works in a more relative way.
<p>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.
<dt>spline3
<dd>This draws a spline in the current color between 2 points, using a third
as a control point. It approximates a cubic spline segment.
<p>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. Controlling the tangents allows you to connect this curve to
other curves generated the same way without having corners at the connection
points.
<p>The 6 arguments are the starting point column, starting point row, control
point column, control point row, ending point column, and ending point row.
<p>This command does not affect the current position.
<dt>circle
<dd>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.
<dt>filledrectangle
<dd>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.
<dt>text
<dd>This command draws text in the current color in the built-in font.
The 5 arguments are:
<ol>
<li>column number of starting point of baseline
<li>row number of starting point of baseline
<li>height of characters, in pixels
<li>angle of baseline in degrees elevated from the horizontal
<li>text
</ol>
<p>Note that if your text contains white space, you'll have to use double
quotes to cause it to be a single token.
<dt>text_here
<dd>This is like <b>text</b>, 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.
<p>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!
</dl>
<h2 id="history">HISTORY</h2>
<p><b>ppmdraw</b> was new in Netpbm 10.29 (August 2005).
<h2 id="seealso">SEE ALSO</h2>
<b><a href="ppmlabel.html">ppmlabel</a></b>,
<b><a href="ppm.html">ppm</a></b>
<b><a href="libnetpbm_draw.html">libnetpbm_draw</a></b>
<hr>
<h2 id="index">Table Of Contents</h2>
<ul>
<li><a href="#synopsis">SYNOPSIS</a>
<li><a href="#description">DESCRIPTION</a>
<li><a href="#options">OPTIONS</a>
<li><a href="#script">SCRIPT</a>
<li><a href="#history">HISTORY</a>
<li><a href="#seealso">SEE ALSO</a>
</ul>
</body>
</html>
|
