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       This  example starts at Column 50, Row 50 of the input image and writes
42       the word "hello" there in 10 pixel high white letters at  a  30  degree
43       angle up from horizontal.  Then, from where that leaves off, the script
44       writes "there" in 10 pixel high black letters  horizontally.   Finally,
45       it  draws a black line to a point 5 pixels over and 20 pixels down from
46       the end of "there."
47
48       If you don't specify ppmfile, ppmdraw reads its input  PPM  image  from
49       Standard Input.
50
51       The output image goes to Standard Output.
52
53       ppmdraw  works  on multi-image streams.  It executes the same script on
54       each input image and produces an output stream with one image for  each
55       input  image.  But before Netpbm 10.32 (February 2006), ppmdraw ignored
56       every image after the first.
57
58       If you just want to add a single line of text to an image, ppmlabel may
59       be more what you want.
60
61
62

OPTIONS

64       -script=script
65              This option gives the script.  See Script ⟨#script⟩ .
66
67              You may not specify both -script and -scriptfile.
68
69
70       -scriptfile=filename
71              This  option  names  a  file  that contains the script.  - means
72              Standard Input.
73
74              You may not specify both -script and -scriptfile.
75
76              You may not specify - (Standard Input) for both -scriptfile  and
77              the input image file.
78
79
80
81
82

SCRIPT

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

HISTORY

240       ppmdraw was new in Netpbm 10.29 (August 2005).
241
242
243

SEE ALSO

245       ppmlabel(1), ppm(1) libnetpbm_draw(1)
246

DOCUMENT SOURCE

248       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
249       source.  The master documentation is at
250
251              http://netpbm.sourceforge.net/doc/ppmdraw.html
252
253netpbm documentation             22 June 2005           Ppmdraw User Manual(0)
Impressum