| 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 |