Debian Codegraph @

upstream/debian-unstable/man1/ppmlabel.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 "Ppmlabel User Manual" 1 "15 April 2006" "netpbm documentation"
7
8 .SH NAME
9 ppmlabel - add text to a PPM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmlabel\fP
15
16 [\fB-angle\fP \fIangle\fP]
17
18 [\fB-background\fP { \fBtransparent\fP | \fIcolor\fP } ]
19
20 [\fB-color\fP \fIcolor\fP]
21
22 [\fB-file\fP \fIfilename\fP]
23
24 [\fB-size\fP
25
26 \fItextsize\fP]
27
28 [\fB-text\fP \fItext_string\fP]
29
30 [\fB-x\fP \fIcolumn\fP]
31
32 [\fB-y\fP \fIrow\fP]
33
34 \&...
35
36 [\fIppmfile\fP]
37
38
39 .UN example
40 .SH EXAMPLE
41
42 .nf
43 \f(CW
44 ppmlabel -x 50 -y 50 -text hello \e
45 -angle -30 -text there \e
46 testimg.ppm
47 \fP
48
49 .fi
50
51 .UN description
52 .SH DESCRIPTION
53 .PP
54 This program is part of
55 .BR "Netpbm" (1)\c
56 \&.
57 .PP
58 \fBppmlabel\fP uses the text drawing facilities of \fBlibnetpbm\fP's
59 "ppmd" component to add text to a PBM image. You control
60 the location, size, baseline angle, color of the text, and background
61 color (if any) with command line arguments. You can specify the text
62 on the command line or supply it in files.
63 .PP
64 You can add any number of separate labels in a single invocation of
65 \fBppmlabel\fP, limited only by any restrictions your environment has
66 on the number and size of program arguments (e.g. a shell's command
67 size limit).
68 .PP
69 If you don't specify \fIppmfile\fP, \fBppmlabel\fP reads its input
70 PPM image from Standard Input.
71 .PP
72 The output image goes to Standard Output.
73 .PP
74 A more sophisticated way to add a label to an image is to use
75 \fBpbmtext\fP or \fBpbmtextps\fP to create an image of the text, then
76 \fBpamcomp\fP to overlay it onto the base image.
77 .PP
78 Another more general program is \fBppmdraw\fP. It is slightly harder
79 to use for simple labelling.
80
81 .UN options
82 .SH OPTIONS
83 .PP
84 In addition to the options common to all programs based on libnetpbm
85 (most notably \fB-quiet\fP, see
86 .UR index.html#commonoptions
87 Common Options
88 .UE
89 \&), \fBppmlabel\fP recognizes the following
90 command line options:
91 .PP
92 The arguments on the \fBppmlabel\fP command line are not options in
93 the strict sense; they are commands which control the placement and
94 appearance of the text being added to the input image. They are
95 executed left to right, and any number of arguments may appear.
96 .PP
97 You can abbreviate any option to its shortest unique prefix.
98
99
100 .TP
101 \fB-angle\fP\fI angle\fP
102 This option sets the angle of the baseline of subsequent text.
103 \fIangle\fP is an integral number of degrees, measured
104 counterclockwise from the row axis of the image.
105
106 .TP
107 \fB-background\fP { \fBtransparent\fP | \fIcolor\fP }
108 If the argument is \fBtransparent\fP, \fBppmlabel\fP draws the
109 text over the existing pixels in the image. If you specify a
110 \fIcolor\fP (see the \fB-color\fP option below for information on
111 how to specify colors), \fBppmlabel\fP generates background rectangles
112 enclosing subsequent text, and those rectangles are filled with that
113 color.
114
115 .TP
116 \fB-color\fP \fIcolor\fP
117 This option sets the color for subsequent text.
118 .sp
119 Specify the color (\fIcolor\fP) as described for the
120 .UR libnetpbm_image.html#colorname
121 argument of the \fBpnm_parsecolor()\fP library routine
122 .UE
123 \&.
124 .sp
125 \fB-colour\fP is an acceptable alternate spelling.
126
127 .TP
128 \fB-file\fP \fIfilename\fP
129 This option causes \fBppmlabel\fP to read lines of text from the file
130 named \fIfilename\fP and draw it on successive lines.
131
132 .TP
133 \fB-size\fP \fItextsize\fP
134 This option sets the height of the tallest characters above the
135 baseline to \fItextsize\fP pixels.
136
137 .TP
138 \fB-text\fP \fItext_string\fP
139 This option causes \fBppmlabel\fP to draw the specified text
140 string. It advances the location for subsequent text down 1.75 times
141 the current \fItextsize\fP. That lets you draw multiple lines of
142 text in a reasonable manner without specifying the position of each
143 line.
144 .sp
145 Note that if you invoke \fBppmlabel\fP via a shell command and your
146 text string contains spaces, you'll have to quote it so the shell treats
147 the whole string as a single token. E.g.
148 .nf
149 $ ppmlabel -text "this is my text" baseimage.ppm >annotatedimage.ppm
150
151 .fi
152
153
154 .TP
155 \fB-x\fP \fIcolumn\fP
156 This option sets the pixel column at which subsequent text will
157 be left justified. Depending on the shape of the first character, the
158 actual text may begin a few pixels to the right of this point.
159
160 .TP
161 \fB-y\fP \fIrow\fP
162 This option sets the pixel row which will form the baseline of
163 subsequent text. Characters with descenders, such as "y," will extend
164 below this line.
165
166
167
168 .UN limitations
169 .SH LIMITATIONS
170 .PP
171 Text strings are restricted to 7 bit ASCII. The text font used by
172 \fBppmlabel\fP doesn't include definitions for 8 bit ISO 8859/1 characters.
173 .PP
174 When drawing multiple lines of text with a non-transparent
175 background, it should probably fill the space between the lines with
176 the background color. This is tricky to get right when the text is
177 rotated to a non-orthogonal angle.
178
179 .UN seealso
180 .SH SEE ALSO
181 .BR "ppmmake" (1)\c
182 \&,
183 .BR "ppmdraw" (1)\c
184 \&,
185 .BR "pbmtext" (1)\c
186 \&,
187 .BR "pbmtextps" (1)\c
188 \&,
189 .BR "pamcomp" (1)\c
190 \&,
191 .BR "ppm" (1)\c
192 \&
193
194
195 .UN author
196 .SH AUTHOR
197
198 Copyright (C) 1995 by John Walker (\[email protected]\fP)
199 WWW home page:
200 .UR http://www.fourmilab.ch/
201 http://www.fourmilab.ch/
202 .UE
203 \&
204 .PP
205 Permission to use, copy, modify, and distribute this software and
206 its documentation for any purpose and without fee is hereby granted,
207 without any conditions or restrictions. This software is provided
208 ``as is'' without express or implied warranty.
209 .SH DOCUMENT SOURCE
210 This manual page was generated by the Netpbm tool 'makeman' from HTML
211 source. The master documentation is at
212 .IP
213 .B http://netpbm.sourceforge.net/doc/ppmlabel.html
214 .PP