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] [-turn|-no‐
12 turn] [-rle|-runlength] [-flate] [-ascii85] [-nocenter|-center]
13 [-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 di‐
37 mensioned as if you had specified -scale=1.0, which means approximately
38 72 pixels of the input image generate one inch of output (if that fits
39 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 re‐
51 flect the Postscript language level, but the version of the DSC comment
52 specification and EPS specification implemented. The Postscript lan‐
53 guage 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; pn‐
69 mtops 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
84 In addition to the options common to all programs based on libnetpbm
85 (most notably -quiet, see
86 Common Options ⟨index.html#commonoptions⟩ ), pnmtops recognizes the
87 following command line options:
88 -imagewidth, -imageheight
92 Tells how wide and high you want the image on the page, in
93 inches. The aspect ratio of the image is preserved, so if you
94 specify both of these, the image on the page will be the largest
95 image that will fit within the box of those dimensions.
96 If these dimensions are greater than the page size, you get
98 Postscript output that runs off the page.
99 You cannot use imagewidth or imageheight with -scale or
101 -equalpixels.
102 -equalpixels
105 This option causes the output image to have the same number of
106 pixels as the input image. So if the output device is 600 dpi
107 and your image is 3000 pixels wide, the output image would be 5
108 inches wide.
109 You cannot use -equalpixels with -imagewidth, -imageheight, or
111 -scale.
112 -bitspersample=N
115 This option selects the number of bits for each component of
116 each pixel in the Postscript output. By default, pnmtops
117 chooses the value that corresponds to the maxval of the PNM in‐
118 put, subject to constraints of the Postscript language. In par‐
119 ticular, if you don't select Postscript level 2 (-level) with
120 built-in Postscript (-psfilter), the most bits per pixel you can
121 have is 8.
122 The value must be 1, 2, 4, 8, or 12, with 12 being restricted to
124 the case described above.
125 This option was new in Netpbm 10.51 (June 2010).
127 -scale tells how big you want the image on the page. The value is the
130 number of inches of output image that you want 72 pixels of the
131 input to generate.
132 But pnmtops rounds the number to something that is an integral
134 number of output device pixels. E.g. if the output device is
135 300 dpi and you specify -scale=1.0, then 75 (not 72) pixels of
136 input becomes one inch of output (4 output pixels for each input
137 pixel). Note that the -dpi option tells pnmtops how many pixels
138 per inch the output device generates.
139 If the size so specified does not fit on the page (as measured
141 either by the -width and -height options or the default page
142 size of 8.5 inches by 11 inches), pnmtops ignores the -scale op‐
143 tion, issues a warning, and scales the image to fit on the page.
144 -dpi=N[xN]
147 This option specifies the dots per inch resolution of your out‐
149 put device. The default is 300 dpi. In theory PostScript is
150 device-independent and you don't have to worry about this, but
151 in practice its raster rendering can have unsightly bands if the
152 device pixels and the image pixels aren't in sync.
153 Also this option is crucial to the working of the equalpixels
155 option.
156 If you specify NxN, the first number is the horizontal resolu‐
158 tion and the second number is the vertical resolution. If you
159 specify just a single number N, that is the resolution in both
160 directions.
161 -width, -height
164 These options specify the dimensions, in inches, of the page on
165 which the output is to be printed. This can affect the size of
166 the output image.
167 The page size has no effect, however, when you specify the -im‐
169 agewidth, -imageheight, or -equalpixels options.
170 These options may also affect positioning of the image on the
172 page and even the paper selected (or cut) by the printer/plotter
173 when the output is printed. See the -nosetpage option.
174 The default is 8.5 inches by 11 inches.
176 -turn
179 -noturn
182 These options control whether the image gets turned 90 degrees.
183 Normally, if an image fits the page better when turned (e.g. the
184 image is wider than it is tall, but the page is taller than it
185 is wide), it gets turned automatically to better fit the page.
186 If you specify the -turn option, pnmtops turns the image no
187 matter what its shape; If you specify -noturn, pnmtops does not
188 turn it no matter what its shape.
189 -rle
192 -runlength
195 These identical options tell pnmtops to use run length compres‐
196 sion in encoding the image in the Postscript program. This may
197 save time if the host-to-printer link is slow; but normally the
198 printer's processing time dominates, so -rle has no effect (and
199 in the absence of buffering, may make things slower).
200 This may, however, make the Postscript program considerable
202 smaller.
203 This usually doesn't help at all with a color image and -psfil‐
205 ter, because in that case, the Postscript program pnmtops cre‐
206 ates has the red, green, and blue values for each pixel to‐
207 gether, which means you would see long runs of identical bytes
208 only in the unlikely event that the red, green, and blue values
209 for a bunch of adjacent pixels are all the same. But without
210 -psfilter, the Postscript program has all the red values, then
211 all the green values, then all the blue values, so long runs ap‐
212 pear wherever there are long stretches of the same color.
213 Here is an explanation by Jef Poskanzer of why he invented the
215 -rle option:
216 I just spent a few hours modifying my pbmtops filter to produce
218 run length encoded PostScript output. The results are not spec‐
219 tacular for me - yes, the files are smaller, but the printing
220 times are about the same. But I'm printing over the network.
221 If you were stuck with the serial line, this would be a big win.
222 I've appended a sample program generated by my filter. If any‐
223 one sees ways to improve the code, please let me know, I'm not
224 much of a PostScript hacker. This version of pbmtops will be
225 distributed to comp.sources.misc and expo.lcs.mit.edu sometime
226 in October. - Jef
227 This is from a forum about Postscript ⟨http://www.lngpstscrpt.tk/re-
229 postscript-run-length-encoding-again⟩ , extracted in October 2010. Jef
230 added -rle in August 1988. In those days, RS-232 lines (referred to as
231 "serial" in the quotation) were typically 9600bps. 2400 bps lines were
232 still around. What the quotation calls "the network" is probably a 10
233 Mbps Ethernet connection.
234 -flate This option tells pnmtops to use "flate" compression (i.e. com‐
237 pression via the "Z" library -- the same as PNG).
238 See the -rle option for information about compression in gen‐
240 eral.
241 You must specify -psfilter if you specify -flate.
243 There exist modern versions of pnmtops that cannot do flate com‐
245 pression; these versions were built without the Z library and
246 built not to require the Z library. If you have such a version,
247 it fails with an explanatory error message when you specify
248 -flate.
249 This option was new in Netbpm 10.27 (March 2005).
251 Before Netpbm 10.32 (February 2006), you could not specify -rle
253 and -flate together.
254 -ascii85
258 By default, pnmtops uses "asciihex" encoding of the image
259 raster. The image raster is a stream of bits, while a Post‐
260 script program is text, so there has to be an encoding from bits
261 to text. Asciihex encoding is just the common hexadecimal rep‐
262 resentation of bits. E.g. 8 1 bits would be encoded as the two
263 characters "FF".
264 With the -ascii85 option, pnmtops uses "ascii85" encoding in‐
266 stead. This is an encoding in which 32 bits are encoded into
267 five characters of text. Thus, it produces less text for the
268 same raster than asciihex. But ascii85 is not available in
269 Postscript Level 1, whereas asciihex is.
270 This option was new in Netbpm 10.27 (March 2005).
272 -psfilter
275 pnmtops can generate two different kinds of Encapsulated Post‐
276 script programs to represent an image. By default, it generates
277 a program that redefines readstring in a custom manner and
278 doesn't rely on any built-in Postscript filters. But with the
279 -psfilter option, pnmtops leaves readstring alone and uses the
280 built-in Postscript filters /ASCII85Decode, /ASCIIHexDecode,
281 /RunLengthDecode, and /FlateDecode.
282 This option was new in Netbpm 10.27 (March 2005). Before that,
284 pnmtops always used the custom readstring.
285 The custom code can't do flate or ascii85 encoding, so you must
287 use -psfilter if you want those (see -flate, -ascii85).
288 -level This option determines the level (version number) of Postscript
291 that pnmtops uses. By default, pnmtops uses Level 2. Some fea‐
292 tures of pnmtops are available only in higher Postscript levels,
293 so if you specify too low a level for your image and your op‐
294 tions, pnmtops fails. For example, pnmtops cannot do a color
295 image in Level 1.
296 This option was new in Netpbm 10.27 (March 2005). Before that,
298 pnmtops always used Level 2.
299 -dict This causes the Postscript program create a separated dictionary
302 for its local variables and remove it from the stack as it ex‐
303 its.
304 This option was new in Netbpm 10.27 (March 2005).
306 -vmreclaim
309 This option causes the Postscript program to force a memory
310 garbage collection as it exits.
311 This option was new in Netbpm 10.27 (March 2005).
313 -nocenter
316 By default, pnmtops centers the image on the output page.
317 You can cause pnmtops to instead put the image against the
318 lower left corner of the page with the -nocenter
319 option. This is useful for programs which can include
320 PostScript files, but can't cope with pictures which are
321 not
322 positioned in the lower left corner.
323 If you want to position an image on the page arbitrarily,
325 use
326 pamcomp to create an image of the full page with the image
327 in
328 question at the proper place and the rest of the page
329 white, and use
330 pnmtops to convert the composed result to Encapsulated
331 Postscript.
332 For backward compatibility, pnmtops accepts the option
334 -center, but it has no effect.
335 -setpage
338 This causes pnmtops to include a "setpagedevice"
339 directive in the output. This causes the output to violate
340 specifications
341 of EPSF encapsulated Postscript, but if you're not using it
342 in an
343 encapsulated way, may be what you need. The directive
344 tells the
345 printer/plotter what size paper to use (or cut). The di‐
346 mensions it
347 specifies on this directive are those selected by the
348 -width and -height options or defaulted.
349 From January through May 2002, the default was to include
351 "setpagedevice" and this option did not exist. Before
352 January 2002, there was no way to include "setpagedevice"
353 and neither the -setpage nor -nosetpage option existed.
354 -nosetpage
357 This tells pnmtops not to include a "setpagedevice"
358 directive in the output. This is the default, so the op‐
359 tion has no
360 effect.
361 See the -setpage option for the history of this option.
363 -noshowpage
366 This tells pnmtops not to include a "showpage"
367 directive in the output. By default, pnmtops includes a
368 "showpage" at the end of the EPSF program. According to
369 EPSF specs, this is OK, and the program that includes the
370 EPSF is
371 supposed to redefine showpage so this doesn't cause unde‐
372 sirable
373 behavior. But it's often easier just not to have the show‐
374 page.
375 This options was new in Netpbm 10.27 (March 2005). Earlier
377 versions of pnmtops always include the showpage.
378 -showpage
381 This tells pnmtops to include a "showpage" directive
382 at the end of the EPSF output. This is the default, so the
383 option has
384 no effect.
385 This option was new in Netpbm 10.27 (March 2005).
387 -verbose
390 This causes informational messages about the conversion
391 process and
392 result.
393
398 If the PNM image has a maxval greater than 255, pnmtops will produce
399 output with 8 bits per sample resolution unless you specify -psfilter,
400 even though Postscript Level 2 has a 12 bits per sample format. pnm‐
401 tops's custom raster-generating code just doesn't know the 12 bit for‐
402 mat.
403
406 You can use the Postscript output a number of ways. Many printers take
407 Postscript input (but you still need some kind of printer driver to
408 transport the Postscript to the printer).
409 There is also the Ghostscript program (not part of Netpbm), which takes
411 Postscript as input and generates an output stream to control any of
412 myriad models of printer (but you still need some kind of printer
413 driver to transport that stream to the printer).
414 Ghostscript also can convert the Postscript file to PDF, which is a
416 very popular document and image format. Use Ghostscript's pdfwrite
417 output device type. The program ps2pdf (distributed with Ghostscript)
418 is a convenient way to run Ghostscript with pdfwrite.
419
423 bmpp(1) converts from Netpbm and other formats to Encapsulated Post‐
424 script.
425 bmpp has a few functions pnmtops does not, such as the ability to use
427 LZW compression.
428 pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
430 topsg3(1), ppmtopgm(1),
431
435 Copyright (C) 1989, 1991 by Jef Poskanzer.
436 Modified November 1993 by Wolfgang Stuerzlinger, wrzl@gup.uni-
438 linz.ac.at
439 The program was originally pbmtops. It became pgmtops in October 1988
441 and was merged with ppmtops to form pnmtops in January 1991. ppmtops
442 came into being some time before September 1989.
443
446 •
447 SYNOPSIS ⟨#synopsis⟩
449 •
451 DESCRIPTION ⟨#description⟩
453 •
455 OPTIONS ⟨#options⟩
457 •
459 LIMITATIONS ⟨#limitations⟩
461 •
463 APPLICATIONS ⟨#applications⟩
465 •
467 SEE ALSO ⟨#seealso⟩
469 •
471 HISTORY ⟨#history⟩
473
475 This manual page was generated by the Netpbm tool 'makeman' from HTML
476 source. The master documentation is at
477 http://netpbm.sourceforge.net/doc/pnmtops.html
479netpbm documentation 20 April 2018 Pnmtops User Manual(0)