Debian Codegraph @

upstream/debian-unstable/man1/ppmdraw.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Ppmdraw User Manual" 1 "17 mAY 2025" "netpbm documentation"
7
8 .SH NAME
9 ppmdraw - draw lines, text, etc on a PPM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmdraw\fP
15
16 {
17 \fB-script=\fP\fIscript\fP
18 |
19 \fB-scriptfile=\fP\fIfilename\fP
20 }
21 [\fB-verbose\fP]
22
23 [\fIppmfile\fP]
24 .PP
25 All options can be abbreviated to their shortest unique prefix.
26 You may use two hyphens instead of one to designate an option. You
27 may use either white space or an equals sign between an option name
28 and its value.
29
30
31 .UN description
32 .SH DESCRIPTION
33 .PP
34 This program is part of
35 .BR "Netpbm" (1)\c
36 \&.
37 .PP
38 \fBppmdraw\fP draws lines, shapes, text, etc. on a PPM image. It is
39 essentially an easy-to-program front end to \fBlibnetpbm\fP's
40 "ppmd" subroutines. It lets you create a human-friendly
41 script to describe the drawing rather than write a C program.
42 .PP
43 You supply drawing instructions with a script, which you supply either
44 in a file named by a \fB-scriptfile\fP option or as the value of a
45 \fB-script\fP option. Here is an example script:
46
47 .nf
48 \f(CW
49 setpos 50 50;
50 text_here 10 30 "hello";
51 setcolor black;
52 text_here 10 0 "there";
53 line_here 5 20;
54 \fP
55
56 .fi
57 .PP
58 This example starts at Column 50, Row 50 of the input image and
59 writes the word "hello" there in 10 pixel high white letters
60 at a 30 degree angle up from horizontal. Then, from where that leaves
61 off, the script writes "there" in 10 pixel high black
62 letters horizontally. Finally, it draws a black line to a point 5
63 pixels over and 20 pixels down from the end of "there."
64 .PP
65 If you don't specify \fIppmfile\fP, \fBppmdraw\fP reads its input
66 PPM image from Standard Input.
67 .PP
68 The output image goes to Standard Output.
69 .PP
70 \fBppmdraw\fP works on multi-image streams. It executes the same
71 script on each input image and produces an output stream with one image
72 for each input image. But before Netpbm 10.32 (February 2006),
73 \fBppmdraw\fP ignored every image after the first.
74 .PP
75 If you just want to add a single line of text to an image,
76 \fBppmlabel\fP may be more what you want.
77
78
79 .UN options
80 .SH OPTIONS
81 .PP
82 In addition to the options common to all programs based on libnetpbm
83 (most notably \fB-quiet\fP, see
84 .UR index.html#commonoptions
85 Common Options
86 .UE
87 \&), \fBppmdraw\fP recognizes the following
88 command line options:
89
90
91
92 .TP
93 \fB-script=\fP\fIscript\fP
94 This option gives the script. See
95 .UR #script
96 Script
97 .UE
98 \&.
99 .sp
100 You may not specify both \fB-script\fP and \fB-scriptfile\fP.
101
102 .TP
103 \fB-scriptfile=\fP\fIfilename\fP
104 This option names a file that contains the script. \fB-\fP
105 means Standard Input.
106 .sp
107 You may not specify both \fB-script\fP and \fB-scriptfile\fP.
108 .sp
109 You may not specify \fB-\fP (Standard Input) for both
110 \fB-scriptfile\fP and the input image file.
111
112
113
114
115 .UN script
116 .SH SCRIPT
117 .PP
118 The heart of \fBppmdraw\fP function is its script. The script is
119 a character stream. The stream consists of commands. Commands are
120 separated by semicolons. White space is regarded just like in C: Any
121 contiguous stretch of unquoted white space is equivalent to a single
122 space character. Note that this means newlines have no particular
123 significance.
124 .PP
125 A command is composed of tokens, separated from each other by
126 white space. To write a token that contains white space, enclose
127 it in double quotes. Everything between two matched quotation marks
128 is one token.
129 .PP
130 The first token of a command is the verb, which determines the
131 basic function of the command. The rest of the tokens of the command
132 are arguments, the meaning of which depends upon the verb. The
133 following list gives all the valid verbs, and for each its meaning and
134 its arguments.
135 .PP
136 Many commands have arguments that specify a position on the canvas,
137 which you specify by row and column. Row 0 is the top row. Column 0
138 is the leftmost column. You may specify negative numbers (but such
139 a position would necessarily be off the canvas).
140 .PP
141 Your drawing instructions may involve positions not on the canvas.
142 But any pixels you draw there just get discarded.
143
144
145 .TP
146 setpos
147 Set the "current position" in the image. This affects
148 where subsequent commands draw things. The 2 arguments are the column
149 and row number.
150 .sp
151 At the start of the script, the current position is (0,0).
152
153 .TP
154 setlinetype
155 The 1 argument is "normal" or "nodiag.". This
156 effects a \fBppmd_setlinetype()\fP call. Further details are not yet
157 documented.
158
159 .TP
160 setlineclip
161 This effects a \fBppmd_setlineclip()\fP call. Not yet documented.
162
163 .TP
164 setcolor
165 This sets the "current color", which determines the color
166 in which subsequent drawing commands draw. Before the first
167 \fBsetcolor\fP, the current color is white.
168 .sp
169 There is one argument. It specifies the color as described for the
170 .UR libnetpbm_image.html#colorname
171 argument of the \fBpnm_parsecolor()\fP library routine
172 .UE
173 \&.
174
175 .TP
176 setfont
177 This sets the "current font", which determines the font
178 in which subsequent text drawing commands draw. Before the first
179 \fBsetfont\fP, the current font is a built in font called
180 "standard."
181 .sp
182 The argument of this command is a file name. It is the name of a
183 Netpbm PPMD font file.
184 .sp
185 A Netpbm PPMD font file typically has a name that ends in
186 ".ppmdfont" and its first 8 bytes are the ASCII encoding of
187 "ppmdfont".
188 .sp
189 There is only one of these fonts as far as we know. It is distributed with
190 Netpbm as the file \fBstandard.ppmdfont\fP, but you don't need to use that
191 file because the same font is built into the Netpbm library and is the
192 default. If you want to make a new font, you can find the format of a
193 ppmdfont file in the Netpbm interface header file \fBppmdfont.h\fP, but
194 you'll have to make your own tools to build it. The program \fBppmdmkfont\fP
195 generates \fBstandard.ppmdfont\fP, so you can use that as an example.
196
197 .TP
198 line
199 This draws a one pixel wide line in the current color. The 4 arguments
200 are: starting column, starting row, ending column, ending row.
201 .sp
202 This command does not affect the current position.
203
204 .TP
205 line_here
206 This is like \fBline\fP, except it works in a more relative way.
207 .sp
208 The line starts at the current point. The two arguments are the
209 rightward and downward displacement from there to the terminal point.
210 The command moves the current position to the terminal point after drawing.
211
212 .TP
213 spline3
214 This draws a spline in the current color between 2 points, using a third
215 as a control point. It approximates a cubic spline segment.
216 .sp
217 The shape of the curve is such that it passes through the specified
218 endpoints, and lines tangent to the curve at those endpoints intersect at the
219 control point. Controlling the tangents allows you to connect this curve to
220 other curves generated the same way without having corners at the connection
221 points.
222 .sp
223 The 6 arguments are the starting point column, starting point row, control
224 point column, control point row, ending point column, and ending point row.
225 .sp
226 This command does not affect the current position.
227
228 .TP
229 circle
230 This command draws a circle in the current color. The three
231 arguments are the column number and row number of the center of the
232 circle and the radius of the circle in pixels.
233
234 .TP
235 filledcircle
236 This is the same as \fBcircle\fP except that the circle is filled with
237 the current color. This command class was new Netpbm 10.59 (June 2012).
238
239 .TP
240 filledrectangle
241 This command draws a rectangle filled with the current color.
242
243 The 4 arguments are the column and row numbers of the upper left corner
244 of the rectangle, the width of the rectangle, and the height of the
245 rectangle.
246
247 .TP
248 text
249 This command draws text in the current color in the built-in font.
250 The 5 arguments are:
251
252
253 .IP \(bu
254 column number of starting point of baseline
255 .IP \(bu
256 row number of starting point of baseline
257 .IP \(bu
258 height of characters, in pixels
259 .IP \(bu
260 angle of baseline in degrees elevated from the horizontal
261 .IP \(bu
262 text
263
264 .sp
265 Note that if your text contains white space, you'll have to use double
266 quotes to cause it to be a single token.
267
268 .TP
269 text_here
270 This is like \fBtext\fP, except that the baseline starts at
271 the current position and the command updates the current position to the
272 other end of the baseline after it draws.
273 .sp
274 Bear in mind that a script starts with the current position in the
275 top line, so if you leave it there, only the bottom line of your text
276 will be within the image!
277
278
279
280 .UN history
281 .SH HISTORY
282 .PP
283 \fBppmdraw\fP was new in Netpbm 10.29 (August 2005).
284
285
286 .UN seealso
287 .SH SEE ALSO
288 .BR "ppmlabel" (1)\c
289 \&,
290 .BR "ppm" (1)\c
291 \&
292 .BR "libnetpbm_draw" (1)\c
293 \&
294 .SH DOCUMENT SOURCE
295 This manual page was generated by the Netpbm tool 'makeman' from HTML
296 source. The master documentation is at
297 .IP
298 .B http://netpbm.sourceforge.net/doc/ppmdraw.html
299 .PP