1Pnmtops User Manual(0) Pnmtops User Manual(0)
2
6 pnmtops - convert PNM image to PostScript
7
10 pnmtops [-scale=s] [-dpi=N[xN]] [-imagewidth=n] [-imageheight=n]
11 [-width=N] [-height=N] [-equalpixels] [-turn|-noturn] [-rle|-runlength]
12 [-flate] [-ascii85] [-nocenter] [-nosetpage] [-level=N] [-psfilter]
13 [-noshowpage] [pnmfile]
14 All options can be abbreviated to their shortest unique prefix. You
16 may use two hyphens instead of one. You may separate an option name
17 and its value with white space instead of an equals sign.
18
21 This program is part of Netpbm(1).
22 pnmtops reads a Netpbm image stream as input and produces Encapsulated
24 PostScript (EPSF) as output.
25 If the input file is in color (PPM), pnmtops generates a color Post‐
27 Script file. Some PostScript interpreters can't handle color Post‐
28 Script. If you have one of these you will need to run your image
29 through ppmtopgm first.
30 If you specify no output dimensioning options, the output image is
32 dimensioned as if you had specified -scale=1.0, which means aproxi‐
33 mately 72 pixels of the input image generate one inch of output (if
34 that fits the page).
35 Use -imagewidth, -imageheight, -equalpixels, -width, -height, and
37 -scale to adjust that.
38 Each image in the input stream becomes one complete one-page Postscript
40 program in the output. (This may not be the best way to create a
41 multi-page Postscript stream; someone who knows Postscript should work
42 on this).
43 The line at the top of the file produced by pnmtops is either '%!PS-
45 Adobe-3.0 EPSF-3.0' or just '%!PS-Adobe-3.0'. The numbers do not
46 reflect the Postscript language level, but the version of the DSC com‐
47 ment specification and EPS specification implmented. The Postscript
48 language level is in the "%%LanguageLevel:" comment. pnmtops omits
49 "EPSF-3.0" if you specify -setpage, because it is incorrect to claim
50 EPS compliance if the file uses setpagedevice.
51 What is Encapsulated Postscript?
55 Encapsulated Postscript (EPSF) is a subset of Postscript (i.e. the set
56 of streams that conform to EPSF is a subset of those that conform to
57 Postscript). It is designed so that an EPSF stream can be embedded in
58 another Postscript stream. A typical reason to do that is where an
59 EPSF stream describes a picture you want in a larger document.
60 An Encapsulated Postscript document conforms to the DSC (Document
62 Structuring Convention). The DSC defines some Postscript comments
63 (they're comments from a Postscript point of view, but have semantic
64 value from a DSC point of view).
65 More information about Encapsulated Postscript is at
67 http://www.cs.indiana.edu/docproject/programming/postscript/eps.html
68 (1).
69 Many of the ideas in pnmtops come from Dirk Krause's bmeps. See SEE
71 ALSO ⟨#seealso⟩
72
75 -imagewidth, -imageheight
76 Tells how wide and high you want the image on the page, in
77 inches. The aspect ratio of the image is preserved, so if you
78 specify both of these, the image on the page will be the largest
79 image that will fit within the box of those dimensions.
80 If these dimensions are greater than the page size, you get
82 Postscript output that runs off the page.
83 You cannot use imagewidth or imageheight with -scale or
85 -equalpixels.
86 -equalpixels
89 This option causes the output image to have the same number of
90 pixels as the input image. So if the output device is 600 dpi
91 and your image is 3000 pixels wide, the output image would be 5
92 inches wide.
93 You cannot use -equalpixels with -imagewidth, -imageheight, or
95 -scale.
96 -scale tells how big you want the image on the page. The value is the
99 number of inches of output image that you want 72 pixels of the
100 input to generate.
101 But pnmtops rounds the number to something that is an integral
103 number of output device pixels. E.g. if the output device is
104 300 dpi and you specify -scale=1.0, then 75 (not 72) pixels of
105 input becomes one inch of output (4 output pixels for each input
106 pixel). Note that the -dpi option tells pnmtops how many pixels
107 per inch the output device generates.
108 If the size so specified does not fit on the page (as measured
110 either by the -width and -height options or the default page
111 size of 8.5 inches by 11 inches), pnmtops ignores the -scale
112 option, issues a warning, and scales the image to fit on the
113 page.
114 -dpi=N[xN]
117 This option specifies the dots per inch resolution of your out‐
119 put device. The default is 300 dpi. In theory PostScript is
120 device-independent and you don't have to worry about this, but
121 in practice its raster rendering can have unsightly bands if the
122 device pixels and the image pixels aren't in sync.
123 Also this option is crucial to the working of the equalpixels
125 option.
126 If you specify NxN, the first number is the horizontal resolu‐
128 tion and the second number is the vertical resolution. If you
129 specify just a single number N, that is the resolution in both
130 directions.
131 -width, -height
134 These options specify the dimensions, in inches, of the page on
135 which the output is to be printed. This can affect the size of
136 the output image.
137 The page size has no effect, however, when you specify the
139 -imagewidth, -imageheight, or -equalpixels options.
140 These options may also affect positioning of the image on the
142 page and even the paper selected (or cut) by the printer/plotter
143 when the output is printed. See the -nosetpage option.
144 The default is 8.5 inches by 11 inches.
146 -turn
149 -noturn
152 These options control whether the image gets turned 90 degrees.
153 Normally, if an image fits the page better when turned (e.g. the
154 image is wider than it is tall, but the page is taller than it
155 is wide), it gets turned automatically to better fit the page.
156 If you specify the -turn option, pnmtops turns the image no
157 matter what its shape; If you specify -noturn, pnmtops does not
158 turn it no matter what its shape.
159 -rle
162 -runlength
165 These identical options tell pnmtops to use run length compres‐
166 sion in encoding the image in the Postscript program. This may
167 save time if the host-to-printer link is slow; but normally the
168 printer's processing time dominates, so -rle has no effect (and
169 in the absence of buffering, may make things slower).
170 This may, however, make the Postscript program considerable
172 smaller.
173 This usually doesn't help at all with a color image and -psfil‐
175 ter, because in that case, the Postscript program pnmtops cre‐
176 ates has the red, green, and blue values for each pixel
177 together, which means you would see long runs of identical bytes
178 only in the unlikely event that the red, green, and blue values
179 for a bunch of adjacent pixels are all the same. But without
180 -psfilter, the Postscript program has all the red values, then
181 all the green values, then all the blue values, so long runs
182 appear wherever there are long stretches of the same color.
183 -flate This option tells pnmtops to use 'flate' compression (i.e. com‐
186 pression via the 'Z' library -- the same as PNG).
187 See the -rle option for information about compression in gen‐
189 eral.
190 You must specify -psfilter if you specify -flate.
192 This option was new in Netbpm 10.27 (March 2005).
194 Before Netpbm 10.32 (February 2006), you could not specify -rle
196 and -flate together.
197 This sometimes produces what is probably an incorrect image --
199 one that is missing the lower rows. This appears to be an
200 implementation problem in the flate compressor, but we don't
201 know what it is. We also don't know on which images it has the
202 problem. (January 2007). We provide an example ⟨flatebug.png⟩
203 of an image with which pnmtops appears to have the problem.
204 (Convert it to PGM with pngtopam and feed that to pnmtops).
205 -ascii85
208 By default, pnmtops uses 'asciihex' encoding of the image
209 raster. The image raster is a stream of bits, while a Post‐
210 script program is text, so there has to be an encoding from bits
211 to text. Asciihex encoding is just the common hexadecimal rep‐
212 resentation of bits. E.g. 8 1 bits would be encoded as the two
213 characters 'FF'.
214 With the -ascii85 option, pnmtops uses 'ascii85' encoding
216 instead. This is an encoding in which 32 bits are encoded into
217 five characters of text. Thus, it produces less text for the
218 same raster than asciihex. But ascii85 is not available in
219 Postscript Level 1, whereas asciihex is.
220 This option was new in Netbpm 10.27 (March 2005).
222 -psfilter
225 pnmtops can generate two different kinds of Encapsulated Post‐
226 script programs to represent an image. By default, it generates
227 a program that redefines readstring in a custom manner and
228 doesn't rely on any built-in Postscript filters. But with the
229 -psfilter option, pnmtops leaves readstring alone and uses the
230 built-in Postscript filters /ASCII85Decode, /ASCIIHexDecode,
231 /RunLengthDecode, and /FlateDecode.
232 This option was new in Netbpm 10.27 (March 2005). Before that,
234 pnmtops always used the custom readstring.
235 The custom code can't do flate or ascii85 encoding, so you must
237 use -psfilter if you want those (see -flate, -ascii85).
238 -level This option determines the level (version number) of Postscript
241 that pnmtops uses. By default, pnmtops uses Level 2. Some fea‐
242 tures of pnmtops are available only in higher Postscript levels,
243 so if you specify too low a level for your image and your
244 options, pnmtops fails. For example, pnmtops cannot do a color
245 image in Level 1.
246 This option was new in Netpbm 10.27 (March 2005). Before that,
248 pnmtops always used Level 2.
249 -dict This causes the Postscript program create a separated dictionary
252 for its local variables and remove it from the stack as it
253 exits.
254 This option was new in Netbpm 10.27 (March 2005).
256 -vmreclaim
259 This option causes the Postscript program to force a memory
260 garbage collection as it exits.
261 This option was new in Netbpm 10.27 (March 2005).
263 -nocenter
266 By default, pnmtops centers the image on the output page.
267 You can cause pnmtops to instead put the image against the
268 lower left corner of the page with the -nocenter
269 option. This is useful for programs which can include
270 PostScript files, but can't cope with pictures which are
271 not
272 positioned in the lower left corner.
273 For backward compatibility, pnmtops accepts the option
275 -center, but it has no effect.
276 -setpage
279 This causes pnmtops to include a 'setpagedevice'
280 directive in the output. This causes the output to violate
281 specifications
282 of EPSF encapsulated Postscript, but if you're not using it
283 in an
284 encapsulated way, may be what you need. The directive
285 tells the
286 printer/plotter what size paper to use (or cut). The
287 dimensions it
288 specifies on this directive are those selected by the
289 -width and -height options or defaulted.
290 From January through May 2002, the default was to include
292 'setpagedevice' and this option did not exist. Before
293 January 2002, there was no way to include 'setpagedevice'
294 and neither the -setpage nor -nosetpage option existed.
295 -nosetpage
298 This tells pnmtops not to include a 'setpagedevice'
299 directive in the output. This is the default, so the
300 option has no
301 effect.
302 See the -setpage option for the history of this option.
304 -noshowpage
307 This tells pnmtops not to include a 'showpage'
308 directive in the output. By default, pnmtops includes a
309 'showpage' at the end of the EPSF program According to
310 EPSF specs, this is OK, and the program that includes the
311 EPSF is
312 supposed to redefine showpage so this doesn't cause unde‐
313 sirable
314 behavior. But it's often easier just not to have the show‐
315 page.
316 This options was new in Netpbm 10.27 (March 2005). Earlier
318 versions of pnmtops always include the showpage.
319 -showpage
322 This tells pnmtops to include a 'showpage' directive
323 at the end of the EPSF output. This is the default, so the
324 option has
325 no effect.
326 This option was new in Netpbm 10.27 (March 2005).
328
334 If the PNM image has a maxval greater than 255, pnmtops will produce
335 output with 8 bits per sample resolution unless you specify -psfilter,
336 even though Postscript Level 2 has a 12 bits per sample format. pnm‐
337 tops's custom raster-generating code just doesn't know the 12 bit for‐
338 mat.
339
343 Postscript is described in the Postscript Language Reference Manual
344 ⟨http://www.adobe.com/products/postscript/pdfs/PLRM.pdf⟩ .
345 bmeps ⟨http://bmeps.sourceforge.net⟩ converts from Netpbm and other
347 formats to Encapsulated Postscript. It is suitable for hooking up to
348 dvips so you can include an image in a Latex document just with an
349 \includegraphics directive.
350 bmeps has a few functions pnmtops does not, such as the ability to
352 include a transparency mask in the Postscript program (but not from PAM
353 input -- only from PNG input).
354 pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
356 topsg3(1), ppmtopgm(1),
357
360 Copyright (C) 1989, 1991 by Jef Poskanzer.
361 Modified November 1993 by Wolfgang Stuerzlinger, wrzl@gup.uni-
363 linz.ac.at
364netpbm documentation 21 January 2007 Pnmtops User Manual(0)