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] [-bitspersample=N]
12 [-turn|-noturn] [-rle|-runlength] [-flate] [-ascii85] [-nocenter|-cen‐
13 ter] [-nosetpage|-setpage] [-level=N] [-dict] [-vmreclaim] [-psfilter]
14 [-noshowpage] [-verbose] [pnmfile]
15 All options can be abbreviated to their shortest unique prefix. You
17 may use two hyphens instead of one. You may separate an option name
18 and its value with white space instead of an equals sign.
19
22 This program is part of Netpbm(1).
23 pnmtops reads a Netpbm image stream as input and produces Encapsulated
25 Postscript (EPSF) as output.
26 (Note: people usually render the name as "PostScript," but we use stan‐
28 dard typography in the Netpbm manual, so capitalize only the first let‐
29 ter).
30 If the input file is in color (PPM), pnmtops generates a color Post‐
32 script file. Some Postscript interpreters can't handle color Post‐
33 script. If you have one of these you will need to run your image
34 through ppmtopgm first.
35 If you specify no output dimensioning options, the output image is
37 dimensioned as if you had specified -scale=1.0, which means approxi‐
38 mately 72 pixels of the input image generate one inch of output (if
39 that fits the page).
40 Use -imagewidth, -imageheight, -equalpixels, -width, -height, and
42 -scale to adjust that.
43 Each image in the input stream becomes one complete one-page Postscript
45 program in the output. (This may not be the best way to create a
46 multi-page Postscript stream; someone who knows Postscript should work
47 on this).
48 The line at the top of the file produced by pnmtops is either "%!PS-
50 Adobe-3.0 EPSF-3.0" or just "%!PS-Adobe-3.0". The numbers do not
51 reflect the Postscript language level, but the version of the DSC com‐
52 ment specification and EPS specification implemented. The Postscript
53 language level is in the "%%LanguageLevel:" comment. pnmtops omits
54 "EPSF-3.0" if you specify -setpage, because it is incorrect to claim
55 EPS compliance if the file uses setpagedevice.
56 What is Encapsulated Postscript?
60 Encapsulated Postscript (EPSF) is a subset of Postscript (i.e. the set
61 of streams that conform to EPSF is a subset of those that conform to
62 Postscript). It is designed so that an EPSF stream can be embedded in
63 another Postscript stream. A typical reason to do that is to have an
64 EPSF stream that describes a picture you can put in a larger document.
65 But EPSF is not an image format -- converting from Netpbm format to
67 EPSF really means generating a program to print that Netpbm image on
68 paper. Note that there are myriad ways to print an image on paper;
69 pnmtops command line options let you control some of them.
70 An Encapsulated Postscript document conforms to the DSC (Document
72 Structuring Convention). The DSC defines some Postscript comments
73 (they're comments from a Postscript point of view, but have semantic
74 value from a DSC point of view).
75 More information about Encapsulated Postscript is at http://www.tail‐
77 recursive.org/postscript/eps.html" (1).
78 Many of the ideas in pnmtops come from Dirk Krause's bmeps. See SEE
80 ALSO ⟨#seealso⟩ .
81
85 -imagewidth, -imageheight
86 Tells how wide and high you want the image on the page, in
87 inches. The aspect ratio of the image is preserved, so if you
88 specify both of these, the image on the page will be the largest
89 image that will fit within the box of those dimensions.
90 If these dimensions are greater than the page size, you get
92 Postscript output that runs off the page.
93 You cannot use imagewidth or imageheight with -scale or
95 -equalpixels.
96 -equalpixels
99 This option causes the output image to have the same number of
100 pixels as the input image. So if the output device is 600 dpi
101 and your image is 3000 pixels wide, the output image would be 5
102 inches wide.
103 You cannot use -equalpixels with -imagewidth, -imageheight, or
105 -scale.
106 -bitspersample=N
109 This option selects the number of bits for each component of
110 each pixel in the Postscript output. By default, pnmtops
111 chooses the value that corresponds to the maxval of the PNM
112 input, subject to constraints of the Postscript language. In
113 particular, if you don't select Postscript level 2 (-level) with
114 built-in Postscript (-psfilter), the most bits per pixel you can
115 have is 8.
116 The value must be 1, 2, 4, 8, or 12, with 12 being restricted to
118 the case described above.
119 This option was new in Netpbm 10.51 (June 2010).
121 -scale tells how big you want the image on the page. The value is the
124 number of inches of output image that you want 72 pixels of the
125 input to generate.
126 But pnmtops rounds the number to something that is an integral
128 number of output device pixels. E.g. if the output device is
129 300 dpi and you specify -scale=1.0, then 75 (not 72) pixels of
130 input becomes one inch of output (4 output pixels for each input
131 pixel). Note that the -dpi option tells pnmtops how many pixels
132 per inch the output device generates.
133 If the size so specified does not fit on the page (as measured
135 either by the -width and -height options or the default page
136 size of 8.5 inches by 11 inches), pnmtops ignores the -scale
137 option, issues a warning, and scales the image to fit on the
138 page.
139 -dpi=N[xN]
142 This option specifies the dots per inch resolution of your out‐
144 put device. The default is 300 dpi. In theory PostScript is
145 device-independent and you don't have to worry about this, but
146 in practice its raster rendering can have unsightly bands if the
147 device pixels and the image pixels aren't in sync.
148 Also this option is crucial to the working of the equalpixels
150 option.
151 If you specify NxN, the first number is the horizontal resolu‐
153 tion and the second number is the vertical resolution. If you
154 specify just a single number N, that is the resolution in both
155 directions.
156 -width, -height
159 These options specify the dimensions, in inches, of the page on
160 which the output is to be printed. This can affect the size of
161 the output image.
162 The page size has no effect, however, when you specify the
164 -imagewidth, -imageheight, or -equalpixels options.
165 These options may also affect positioning of the image on the
167 page and even the paper selected (or cut) by the printer/plotter
168 when the output is printed. See the -nosetpage option.
169 The default is 8.5 inches by 11 inches.
171 -turn
174 -noturn
177 These options control whether the image gets turned 90 degrees.
178 Normally, if an image fits the page better when turned (e.g. the
179 image is wider than it is tall, but the page is taller than it
180 is wide), it gets turned automatically to better fit the page.
181 If you specify the -turn option, pnmtops turns the image no
182 matter what its shape; If you specify -noturn, pnmtops does not
183 turn it no matter what its shape.
184 -rle
187 -runlength
190 These identical options tell pnmtops to use run length compres‐
191 sion in encoding the image in the Postscript program. This may
192 save time if the host-to-printer link is slow; but normally the
193 printer's processing time dominates, so -rle has no effect (and
194 in the absence of buffering, may make things slower).
195 This may, however, make the Postscript program considerable
197 smaller.
198 This usually doesn't help at all with a color image and -psfil‐
200 ter, because in that case, the Postscript program pnmtops cre‐
201 ates has the red, green, and blue values for each pixel
202 together, which means you would see long runs of identical bytes
203 only in the unlikely event that the red, green, and blue values
204 for a bunch of adjacent pixels are all the same. But without
205 -psfilter, the Postscript program has all the red values, then
206 all the green values, then all the blue values, so long runs
207 appear wherever there are long stretches of the same color.
208 Here is an explanation by Jef Poskanzer of why he invented the
210 -rle option:
211 I just spent a few hours modifying my pbmtops filter to produce
213 run length encoded PostScript output. The results are not spec‐
214 tacular for me - yes, the files are smaller, but the printing
215 times are about the same. But I'm printing over the network.
216 If you were stuck with the serial line, this would be a big win.
217 I've appended a sample program generated by my filter. If any‐
218 one sees ways to improve the code, please let me know, I'm not
219 much of a PostScript hacker. This version of pbmtops will be
220 distributed to comp.sources.misc and expo.lcs.mit.edu sometime
221 in October. - Jef
222 This is from a forum about Postscript ⟨http://www.lngpstscrpt.tk/re-
224 postscript-run-length-encoding-again⟩ , extracted in October 2010. Jef
225 added -rle in August 1988. In those days, RS-232 lines (referred to as
226 "serial" in the quotation) were typically 9600bps. 2400 bps lines were
227 still around. What the quotation calls "the network" is probably a 10
228 Mbps Ethernet connection.
229 -flate This option tells pnmtops to use "flate" compression (i.e. com‐
232 pression via the "Z" library -- the same as PNG).
233 See the -rle option for information about compression in gen‐
235 eral.
236 You must specify -psfilter if you specify -flate.
238 There exist modern versions of pnmtops that cannot do flate com‐
240 pression; these versions were built without the Z library and
241 built not to require the Z library. If you have such a version,
242 it fails with an explanatory error message when you specify
243 -flate.
244 This option was new in Netbpm 10.27 (March 2005).
246 Before Netpbm 10.32 (February 2006), you could not specify -rle
248 and -flate together.
249 -ascii85
253 By default, pnmtops uses "asciihex" encoding of the image
254 raster. The image raster is a stream of bits, while a Post‐
255 script program is text, so there has to be an encoding from bits
256 to text. Asciihex encoding is just the common hexadecimal rep‐
257 resentation of bits. E.g. 8 1 bits would be encoded as the two
258 characters "FF".
259 With the -ascii85 option, pnmtops uses "ascii85" encoding
261 instead. This is an encoding in which 32 bits are encoded into
262 five characters of text. Thus, it produces less text for the
263 same raster than asciihex. But ascii85 is not available in
264 Postscript Level 1, whereas asciihex is.
265 This option was new in Netbpm 10.27 (March 2005).
267 -psfilter
270 pnmtops can generate two different kinds of Encapsulated Post‐
271 script programs to represent an image. By default, it generates
272 a program that redefines readstring in a custom manner and
273 doesn't rely on any built-in Postscript filters. But with the
274 -psfilter option, pnmtops leaves readstring alone and uses the
275 built-in Postscript filters /ASCII85Decode, /ASCIIHexDecode,
276 /RunLengthDecode, and /FlateDecode.
277 This option was new in Netbpm 10.27 (March 2005). Before that,
279 pnmtops always used the custom readstring.
280 The custom code can't do flate or ascii85 encoding, so you must
282 use -psfilter if you want those (see -flate, -ascii85).
283 -level This option determines the level (version number) of Postscript
286 that pnmtops uses. By default, pnmtops uses Level 2. Some fea‐
287 tures of pnmtops are available only in higher Postscript levels,
288 so if you specify too low a level for your image and your
289 options, pnmtops fails. For example, pnmtops cannot do a color
290 image in Level 1.
291 This option was new in Netpbm 10.27 (March 2005). Before that,
293 pnmtops always used Level 2.
294 -dict This causes the Postscript program create a separated dictionary
297 for its local variables and remove it from the stack as it
298 exits.
299 This option was new in Netbpm 10.27 (March 2005).
301 -vmreclaim
304 This option causes the Postscript program to force a memory
305 garbage collection as it exits.
306 This option was new in Netbpm 10.27 (March 2005).
308 -nocenter
311 By default, pnmtops centers the image on the output page.
312 You can cause pnmtops to instead put the image against the
313 lower left corner of the page with the -nocenter
314 option. This is useful for programs which can include
315 PostScript files, but can't cope with pictures which are
316 not
317 positioned in the lower left corner.
318 If you want to position an image on the page arbitrarily,
320 use
321 pamcomp to create an image of the full page with the image
322 in
323 question at the proper place and the rest of the page
324 white, and use
325 pnmtops to convert the composed result to Encapsulated
326 Postscript.
327 For backward compatibility, pnmtops accepts the option
329 -center, but it has no effect.
330 -setpage
333 This causes pnmtops to include a "setpagedevice"
334 directive in the output. This causes the output to violate
335 specifications
336 of EPSF encapsulated Postscript, but if you're not using it
337 in an
338 encapsulated way, may be what you need. The directive
339 tells the
340 printer/plotter what size paper to use (or cut). The
341 dimensions it
342 specifies on this directive are those selected by the
343 -width and -height options or defaulted.
344 From January through May 2002, the default was to include
346 "setpagedevice" and this option did not exist. Before
347 January 2002, there was no way to include "setpagedevice"
348 and neither the -setpage nor -nosetpage option existed.
349 -nosetpage
352 This tells pnmtops not to include a "setpagedevice"
353 directive in the output. This is the default, so the
354 option has no
355 effect.
356 See the -setpage option for the history of this option.
358 -noshowpage
361 This tells pnmtops not to include a "showpage"
362 directive in the output. By default, pnmtops includes a
363 "showpage" at the end of the EPSF program. According to
364 EPSF specs, this is OK, and the program that includes the
365 EPSF is
366 supposed to redefine showpage so this doesn't cause unde‐
367 sirable
368 behavior. But it's often easier just not to have the show‐
369 page.
370 This options was new in Netpbm 10.27 (March 2005). Earlier
372 versions of pnmtops always include the showpage.
373 -showpage
376 This tells pnmtops to include a "showpage" directive
377 at the end of the EPSF output. This is the default, so the
378 option has
379 no effect.
380 This option was new in Netpbm 10.27 (March 2005).
382 -verbose
385 This causes informational messages about the conversion
386 process and
387 result.
388
393 If the PNM image has a maxval greater than 255, pnmtops will produce
394 output with 8 bits per sample resolution unless you specify -psfilter,
395 even though Postscript Level 2 has a 12 bits per sample format. pnm‐
396 tops's custom raster-generating code just doesn't know the 12 bit for‐
397 mat.
398
402 You can use the Postscript output a number of ways. Many printers take
403 Postscript input (but you still need some kind of printer driver to
404 transport the Postscript to the printer).
405 There is also the Ghostscript program (not part of Netpbm), which takes
407 Postscript as input and generates an output stream to control any of
408 myriad models of printer (but you still need some kind of printer
409 driver to transport that stream to the printer).
410 Ghostscript also can convert the Postscript file to PDF, which is a
412 very popular document and image format. Use Ghostscript's pdfwrite
413 output device type. The program ps2pdf (distributed with Ghostscript)
414 is a convenient way to run Ghostscript with pdfwrite.
415
419 Postscript is described in the Postscript Language Reference Manual
420 ⟨http://www.adobe.com/products/postscript/pdfs/PLRM.pdf⟩ .
421 bmeps ⟨http://bmeps.sourceforge.net⟩ converts from Netpbm and other
423 formats to Encapsulated Postscript. It is suitable for hooking up to
424 dvips so you can include an image in a Latex document just with an
425 \includegraphics directive.
426 bmeps has a few functions pnmtops does not, such as the ability to
428 include a transparency mask in the Postscript program (but not from PAM
429 input -- only from PNG input).
430 pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
432 topsg3(1), ppmtopgm(1),
433
437 Copyright (C) 1989, 1991 by Jef Poskanzer.
438 Modified November 1993 by Wolfgang Stuerzlinger, wrzl@gup.uni-
440 linz.ac.at
441 The program was originally pbmtops. It became pgmtops in October 1988
443 and was merged with ppmtops to form pnmtops in January 1991. ppmtops
444 came into being some time before September 1989.
445
448 ·
449 SYNOPSIS ⟨#synopsis⟩
451 ·
453 DESCRIPTION ⟨#description⟩
455 ·
457 OPTIONS ⟨#options⟩
459 ·
461 LIMITATIONS ⟨#limitations⟩
463 ·
465 SEE ALSO ⟨#seealso⟩
467 ·
469 HISTORY ⟨#history⟩
471
473 This manual page was generated by the Netpbm tool 'makeman' from HTML
474 source. The master documentation is at
475 http://netpbm.sourceforge.net/doc/pnmtops.html
477netpbm documentation 30 July 2011 Pnmtops User Manual(0)