1Ppmtoarbtxt User Manual(0)                          Ppmtoarbtxt User Manual(0)
2
3
4

NAME

6       ppmtoarbtxt - generate image in arbitrary text format from PPM image
7
8

SYNOPSIS

10       ppmtoarbtxt bodytmpl [-hd headtmpl] [-tl tailtmpl] [ppmfile]
11
12

DESCRIPTION

14       This program is part of Netpbm(1).
15
16       ppmtoarbtxt  generates simple text-based graphics formats based on for‐
17       mat descriptions given as input.  A text-based graphics format  is  one
18       in  which  an  image is represented by text (like PNM plain format, but
19       unlike PNM raw format).
20
21       ppmtoarbtxt reads a PPM image as input.  For each pixel in  the  image,
22       ppmtoarbtxt  writes  the  contents  of the template file bodytmpl, with
23       certain substitutions based on the value of the pixel, to Standard Out‐
24       put.
25
26       You  may  also  supply  a head template file, in which case ppmtoarbtxt
27       generates text from the template file, based on the  image  dimensions,
28       and includes it in the output before anything else.
29
30       Likewise,  you  may  supply  a  tail  template file to cause text to be
31       placed at the end of the output.
32
33
34
35   Template Files
36       The text that ppmtoarbtxt generates from a template file is the literal
37       text  of the template file, except with substitution specifier replaced
38       with something else.  The program recognizes a  substitution  specifier
39       as text of the form #(...).
40
41       ppmtoarbtxt  treats  white  space in the template files the same as any
42       other characters, placing it in the output, with one exception: If  the
43       template  file ends with a newline character, ppmtoarbtxt ignores it --
44       it does not include it in the output.
45
46       Many substitution specifiers use format strings (another form  of  tem‐
47       plate)  to  specify  the  substitution.   You  should make these format
48       strings as minimal as possible, placing literal text outside  the  sub‐
49       stitution specifier instead of inside the format string.  For example,
50
51       Wrong: #(flum %%%2.2f 0 1)
52
53       Right: %#(flum %2.2f 0 1)
54
55       The  valid  substitution  specifiers are as follows.  Text that has the
56       form of a substitution  specifier  but  is  not  actually  valid  (e.g.
57       #(random  junk)  usually just specifies its literal value, but if it is
58       close enough to something valid, ppmtoarbtxt assumes you made a mistake
59       and fails.
60
61       Useful  in  a  body template, to do substitutions based on a particular
62       pixel:
63
64
65
66       #(ired format blackref whiteref)
67              generates an integer in the range blackref to whiteref in a for‐
68              mat  specified  by  format representing the red intensity of the
69              pixel.  A red intensity of 0 becomes blackref; a  red  intensity
70              of  maxval becomes whiteref, with the rest linearly interpolated
71              in between.
72
73              format is a printf-like format specifier like "%d".  ppmtoarbtxt
74              uses as the entire format string to a fprintf POSIX library call
75              whose only other argument is the red itensity as an integer data
76              type.   ppmtoarbtxt does not necessarily verify that your format
77              string makes sense; there are  values  you  could  specify  that
78              could  even  crash  the  program.  To avoid unexpected behavior,
79              keep format strings simple and hardcoded, and  never  include  a
80              per cent sign or newline.
81
82              #(ired) is equivalent to #(ired %d 0 255).
83
84
85       #(igreen format blackref whiteref)
86              Same as #(ired..., but for green.
87
88
89       #(iblue format blackref whiteref)
90              Same as #(ired..., but for blue.
91
92
93       #(ilum format blackref whiteref)
94              Same   as   #(ired...,  but  representing  the  luminance  value
95              (0.299*red + 0.587*green + 0.114*blue) of the pixel.
96
97
98       #(fred format blackref whiteref)
99              Same as #(ired..., but generates a floating point number instead
100              of an integer.
101
102              In  this case, the second argument to the fprintf that uses for‐
103              mat has a double precision floating point data type.
104
105              #(fred) is equivalent to #(fred %f 0.0 1.0).
106
107
108       #(fgreen format blackref whiteref)
109              Same as #(fred..., but for green.
110
111
112       #(fblue format blackref whiteref)
113              Same as #(fred..., but for blue.
114
115
116       #(flum format blackref whiteref)
117              Same  as  #(fred...,  but  representing  the   luminance   value
118              (0.299*red + 0.587*green + 0.114*blue) of the pixel.
119
120
121       #(posx format)
122              Generates  the  horizontal position of the pixel, in pixels from
123              the left edge of the image.
124
125              The second argument to the  fprintf  that  uses  format  has  an
126              unsigned integer data type.
127
128              format defaults to %u
129
130
131       #(posy format)
132              Same as #(width..., but for the vertical position.
133
134
135
136       If  you  use any of the above substitution specifiers in a head or tail
137       template, the result is undefined.
138
139       Useful in a head or tail template, to do substitutions based on  whole-
140       image attributes:
141
142
143
144       #(width format)
145              Generates the width in pixels of the image.
146
147              The  second  argument  to  the  fprintf  that uses format has an
148              unsigned integer data type.
149
150              format defaults to %u
151
152
153       #(height format)
154              Same as #(width..., but for the height of the image.
155
156
157
158
159

OPTIONS

161       In addition to the options common to all programs  based  on  libnetpbm
162       (most notably -quiet, see
163        Common  Options  ⟨index.html#commonoptions⟩  ), ppmtoarbtxt recognizes
164       the following command line options:
165
166
167
168       -hd headtmpl
169              This option specifies a head template (headtmpl is the  name  of
170              the head template file); it causes ppmtoarbtxt to place the con‐
171              tents of the file named headtmpl at the beginning of the output
172
173
174       -tl tailtmpl
175              This option specifies a tail template; it is analogous to -hd.
176
177
178
179

EXAMPLES

181   gray inversion
182       Here we generate a PGM plain-format image  with  gray  inversion  (like
183       ppmtopgm | pnminvert).
184
185       Contents of our head template file:
186
187       P2
188       #(width) #(height)
189       255
190
191       Contents of our body skeleton file:
192
193       #(ilum %d 255 0)
194
195
196   povray file
197       Here  we  generate  a  povray file where each pixel is represented by a
198       sphere at location (x,y,z) = (posx,height-posy,luminance).   The  color
199       of the sphere is the color of the pixel.
200
201       Contents of our head skeleton:
202
203       #include "colors.inc"
204       #include "textures.inc"
205       camera {
206          location  <#(width) * 0.6, #(height) * 0.7, 80>
207          look_at   <#(width) * 0.5, #(height) * 0.5, 0>
208       }
209
210       light_source { <#(width) * 0.5, #(height) * 0.5, 25> color White
211       }
212
213       Contents of our body skeleton:
214
215       sphere { <#(posx),#(height)-#(posy),#(ilum %d 0 10)>, 0.5
216         texture {
217           pigment {
218             color rgb <#(fred),#(fgreen),#(fblue)>
219           }
220           finish {
221             phong 1
222           }
223         }
224       }
225
226

SEE ALSO

228       pnmtoplainpnm(1) pamtable(1) ppm(1)
229
230

HISTORY

232       ppmtoarbtxt  was  added  to  Netpbm  in Release 10.14 (March 2003).  It
233       existed under the name ppmtotxt since 1995.
234
235

AUTHOR

237       Copyright (C) 1995 by Peter Kirchgessner
238

DOCUMENT SOURCE

240       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
241       source.  The master documentation is at
242
243              http://netpbm.sourceforge.net/doc/ppmtoarbtxt.html
244
245netpbm documentation           26 November 2014     Ppmtoarbtxt User Manual(0)
Impressum