Debian Codegraph @

upstream/debian-unstable/man1/ppmtoarbtxt.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 "Ppmtoarbtxt User Manual" 1 "26 November 2014" "netpbm documentation"
7
8 .SH NAME
9 ppmtoarbtxt - generate image in arbitrary text format from PPM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmtoarbtxt\fP
15 \fIbodytmpl\fP
16 [\fB-hd\fP \fIheadtmpl\fP]
17 [\fB-tl\fP \fItailtmpl\fP]
18 [\fIppmfile\fP]
19
20 .UN description
21 .SH DESCRIPTION
22 .PP
23 This program is part of
24 .BR "Netpbm" (1)\c
25 \&.
26 .PP
27 \fBppmtoarbtxt\fP generates simple text-based graphics formats based on
28 format descriptions given as input. A text-based graphics format is one in
29 which an image is represented by text (like PNM plain format, but unlike
30 PNM raw format).
31
32 \fBppmtoarbtxt\fP reads a PPM image as input. For each pixel in the
33 image, \fBppmtoarbtxt\fP writes the contents of the template file
34 \fIbodytmpl\fP, with certain substitutions based on the value of the
35 pixel, to Standard Output.
36 .PP
37 You may also supply a head template file, in which case \fBppmtoarbtxt\fP
38 generates text from the template file, based on the image dimensions, and
39 includes it in the output before anything else.
40 .PP
41 Likewise, you may supply a tail template file to cause text to be placed
42 at the end of the output.
43
44
45 .UN templatefiles
46 .SS Template Files
47 .PP
48 The text that \fBppmtoarbtxt\fP generates from a template file is the
49 literal text of the template file, except with substitution specifier replaced
50 with something else. The program recognizes a substitution specifier as
51 text of the form \fB#(\fP...\fB)\fP.
52 .PP
53 \fBppmtoarbtxt\fP treats white space in the template files the same as any
54 other characters, placing it in the output, with one exception: If the
55 template file ends with a newline character, \fBppmtoarbtxt\fP ignores it --
56 it does not include it in the output.
57 .PP
58 Many substitution specifiers use format strings (another form of template)
59 to specify the substitution. You should make these format strings as minimal
60 as possible, placing literal text outside the substitution specifier instead
61 of inside the format string. For example,
62 .PP
63 Wrong: \f(CW#(flum %%%2.2f 0 1) \fP
64 .PP
65 Right: \f(CW%#(flum %2.2f 0 1) \fP
66 .PP
67 The valid substitution specifiers are as follows. Text that has the
68 form of a substitution specifier but is not actually valid (e.g.
69 \fB#(random junk)\fP usually just specifies its literal value, but if it is
70 close enough to something valid, \fBppmtoarbtxt\fP assumes you made a mistake
71 and fails.
72 .PP
73 Useful in a body template, to do substitutions based on a particular pixel:
74
75
76 .TP
77 \fB#(ired\fP\fI format blackref whiteref\fP\fB)\fP
78 generates an integer in the range \fIblackref\fP to
79 \fIwhiteref\fP in a format specified by \fIformat\fP representing the red
80 intensity of the pixel. A red intensity of 0 becomes \fIblackref\fP; a red
81 intensity of maxval becomes \fIwhiteref\fP, with the rest linearly
82 interpolated in between.
83 .sp
84 \fIformat\fP is a printf-like format specifier like "%d".
85 \fBppmtoarbtxt\fP uses as the entire format string to a \fBfprintf\fP POSIX
86 library call whose only other argument is the red itensity as an integer data
87 type. \fBppmtoarbtxt\fP does not necessarily verify that your format string
88 makes sense; there are values you could specify that could even crash the
89 program. To avoid unexpected behavior, keep format strings simple and
90 hardcoded, and never include a per cent sign or newline.
91 .sp
92 \fB#(ired)\fP is equivalent to \fB#(ired %d 0 255)\fP.
93
94 .TP
95 \fB#(igreen\fP\fI format blackref whiteref\fP\fB)\fP
96 Same as \fB#(ired...\fP, but for green.
97
98 .TP
99 \fB#(iblue\fP\fI format blackref whiteref\fP\fB)\fP
100 Same as \fB#(ired...\fP, but for blue.
101
102 .TP
103 \fB#(ilum\fP\fI format blackref whiteref\fP\fB)\fP
104 Same as \fB#(ired...\fP, but representing the luminance value
105 (0.299*red + 0.587*green + 0.114*blue) of the pixel.
106
107 .TP
108 \fB#(fred\fP\fI format blackref whiteref\fP\fB)\fP
109 Same as \fB#(ired...\fP, but generates a floating point number instead
110 of an integer.
111 .sp
112 In this case, the second argument to the \fBfprintf\fP that uses
113 \fIformat\fP has a double precision floating point data type.
114 .sp
115 \fB#(fred)\fP is equivalent to \fB#(fred %f 0.0 1.0)\fP.
116
117 .TP
118 \fB#(fgreen \fP\fIformat blackref whiteref\fP\fB)\fP
119 Same as \fB#(fred...\fP, but for green.
120
121 .TP
122 \fB#(fblue \fP\fIformat blackref whiteref\fP\fB)\fP
123 Same as \fB#(fred...\fP, but for blue.
124
125 .TP
126 \fB#(flum \fP\fIformat blackref whiteref\fP\fB)\fP
127 Same as \fB#(fred...\fP, but representing the luminance value
128 (0.299*red + 0.587*green + 0.114*blue) of the pixel.
129
130 .TP
131 \fB#(posx \fP\fIformat\fP\fB)\fP
132 Generates the horizontal position of the pixel, in pixels from the left
133 edge of the image.
134 .sp
135 The second argument to the \fBfprintf\fP that uses \fIformat\fP has an
136 unsigned integer data type.
137 .sp
138 \fIformat\fP defaults to \fB%u\fP
139
140 .TP
141 \fB#(posy \fP\fIformat\fP\fB)\fP
142 Same as \fB#(width...\fP, but for the vertical position.
143
144
145 .PP
146 If you use any of the above substitution specifiers in a head or tail
147 template, the result is undefined.
148 .PP
149 Useful in a head or tail template, to do substitutions based on whole-image
150 attributes:
151
152
153 .TP
154 \fB#(width \fP\fIformat\fP\fB)\fP
155 Generates the width in pixels of the image.
156 .sp
157 The second argument to the \fBfprintf\fP that uses \fIformat\fP
158 has an unsigned integer data type.
159 .sp
160 \fIformat\fP defaults to \fB%u\fP
161
162 .TP
163 \fB#(height \fP\fIformat\fP\fB)\fP
164 Same as \fB#(width...\fP, but for the height of the image.
165
166
167
168
169 .UN options
170 .SH OPTIONS
171 .PP
172 In addition to the options common to all programs based on libnetpbm
173 (most notably \fB-quiet\fP, see
174 .UR index.html#commonoptions
175 Common Options
176 .UE
177 \&), \fBppmtoarbtxt\fP recognizes the following
178 command line options:
179
180
181 .TP
182 \fB-hd\fP \fIheadtmpl\fP
183 This option specifies a head template (\fIheadtmpl\fP is the name of the
184 head template file); it causes \fBppmtoarbtxt\fP to place the contents of the
185 file named \fIheadtmpl\fP at the beginning of the output
186
187 .TP
188 \fB-tl\fP \fItailtmpl\fP
189 This option specifies a tail template; it is analogous to \fB-hd\fP.
190
191
192
193 .UN examples
194 .SH EXAMPLES
195
196 .SS gray inversion
197 .PP
198 Here we generate a PGM plain-format image with gray inversion
199 (like \fBppmtopgm | pnminvert\fP).
200 .PP
201 Contents of our head template file:
202
203 .nf
204 P2
205 #(width) #(height)
206 255
207
208 .fi
209 .PP
210 Contents of our body skeleton file:
211
212 .nf
213 #(ilum %d 255 0)
214
215 .fi
216
217 .SS povray file
218 .PP
219 Here we generate a povray file where each pixel is represented by a
220 sphere at location (x,y,z) = (posx,height-posy,luminance). The color
221 of the sphere is the color of the pixel.
222 .PP
223 Contents of our head skeleton:
224
225 .nf
226 #include "colors.inc"
227 #include "textures.inc"
228 camera {
229 location <#(width) * 0.6, #(height) * 0.7, 80>
230 look_at <#(width) * 0.5, #(height) * 0.5, 0>
231 }
232
233 light_source { <#(width) * 0.5, #(height) * 0.5, 25> color White
234 }
235
236 .fi
237 .PP
238 Contents of our body skeleton:
239
240 .nf
241 sphere { <#(posx),#(height)-#(posy),#(ilum %d 0 10)>, 0.5
242 texture {
243 pigment {
244 color rgb <#(fred),#(fgreen),#(fblue)>
245 }
246 finish {
247 phong 1
248 }
249 }
250 }
251
252 .fi
253
254 .UN seealso
255 .SH SEE ALSO
256 .BR "pnmtoplainpnm" (1)\c
257 \&
258 .BR "pamtable" (1)\c
259 \&
260 .BR "ppm" (1)\c
261 \&
262
263 .UN history
264 .SH HISTORY
265 .PP
266 \fBppmtoarbtxt\fP was added to Netpbm in Release 10.14 (March 2003).
267 It existed under the name \fBppmtotxt\fP since 1995.
268
269 .UN author
270 .SH AUTHOR
271
272 Copyright (C) 1995 by Peter Kirchgessner
273 .SH DOCUMENT SOURCE
274 This manual page was generated by the Netpbm tool 'makeman' from HTML
275 source. The master documentation is at
276 .IP
277 .B http://netpbm.sourceforge.net/doc/ppmtoarbtxt.html
278 .PP