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
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
118 input, subject to constraints of the Postscript language. In
119 particular, 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
143 option, issues a warning, and scales the image to fit on the
144 page.
145 -dpi=N[xN]
148 This option specifies the dots per inch resolution of your out‐
150 put device. The default is 300 dpi. In theory PostScript is
151 device-independent and you don't have to worry about this, but
152 in practice its raster rendering can have unsightly bands if the
153 device pixels and the image pixels aren't in sync.
154 Also this option is crucial to the working of the equalpixels
156 option.
157 If you specify NxN, the first number is the horizontal resolu‐
159 tion and the second number is the vertical resolution. If you
160 specify just a single number N, that is the resolution in both
161 directions.
162 -width, -height
165 These options specify the dimensions, in inches, of the page on
166 which the output is to be printed. This can affect the size of
167 the output image.
168 The page size has no effect, however, when you specify the
170 -imagewidth, -imageheight, or -equalpixels options.
171 These options may also affect positioning of the image on the
173 page and even the paper selected (or cut) by the printer/plotter
174 when the output is printed. See the -nosetpage option.
175 The default is 8.5 inches by 11 inches.
177 -turn
180 -noturn
183 These options control whether the image gets turned 90 degrees.
184 Normally, if an image fits the page better when turned (e.g. the
185 image is wider than it is tall, but the page is taller than it
186 is wide), it gets turned automatically to better fit the page.
187 If you specify the -turn option, pnmtops turns the image no
188 matter what its shape; If you specify -noturn, pnmtops does not
189 turn it no matter what its shape.
190 -rle
193 -runlength
196 These identical options tell pnmtops to use run length compres‐
197 sion in encoding the image in the Postscript program. This may
198 save time if the host-to-printer link is slow; but normally the
199 printer's processing time dominates, so -rle has no effect (and
200 in the absence of buffering, may make things slower).
201 This may, however, make the Postscript program considerable
203 smaller.
204 This usually doesn't help at all with a color image and -psfil‐
206 ter, because in that case, the Postscript program pnmtops cre‐
207 ates has the red, green, and blue values for each pixel
208 together, which means you would see long runs of identical bytes
209 only in the unlikely event that the red, green, and blue values
210 for a bunch of adjacent pixels are all the same. But without
211 -psfilter, the Postscript program has all the red values, then
212 all the green values, then all the blue values, so long runs
213 appear wherever there are long stretches of the same color.
214 Here is an explanation by Jef Poskanzer of why he invented the
216 -rle option:
217 I just spent a few hours modifying my pbmtops filter to produce
219 run length encoded PostScript output. The results are not spec‐
220 tacular for me - yes, the files are smaller, but the printing
221 times are about the same. But I'm printing over the network.
222 If you were stuck with the serial line, this would be a big win.
223 I've appended a sample program generated by my filter. If any‐
224 one sees ways to improve the code, please let me know, I'm not
225 much of a PostScript hacker. This version of pbmtops will be
226 distributed to comp.sources.misc and expo.lcs.mit.edu sometime
227 in October. - Jef
228 This is from a forum about Postscript ⟨http://www.lngpstscrpt.tk/re-
230 postscript-run-length-encoding-again⟩ , extracted in October 2010. Jef
231 added -rle in August 1988. In those days, RS-232 lines (referred to as
232 "serial" in the quotation) were typically 9600bps. 2400 bps lines were
233 still around. What the quotation calls "the network" is probably a 10
234 Mbps Ethernet connection.
235 -flate This option tells pnmtops to use "flate" compression (i.e. com‐
238 pression via the "Z" library -- the same as PNG).
239 See the -rle option for information about compression in gen‐
241 eral.
242 You must specify -psfilter if you specify -flate.
244 There exist modern versions of pnmtops that cannot do flate com‐
246 pression; these versions were built without the Z library and
247 built not to require the Z library. If you have such a version,
248 it fails with an explanatory error message when you specify
249 -flate.
250 This option was new in Netbpm 10.27 (March 2005).
252 Before Netpbm 10.32 (February 2006), you could not specify -rle
254 and -flate together.
255 -ascii85
259 By default, pnmtops uses "asciihex" encoding of the image
260 raster. The image raster is a stream of bits, while a Post‐
261 script program is text, so there has to be an encoding from bits
262 to text. Asciihex encoding is just the common hexadecimal rep‐
263 resentation of bits. E.g. 8 1 bits would be encoded as the two
264 characters "FF".
265 With the -ascii85 option, pnmtops uses "ascii85" encoding
267 instead. This is an encoding in which 32 bits are encoded into
268 five characters of text. Thus, it produces less text for the
269 same raster than asciihex. But ascii85 is not available in
270 Postscript Level 1, whereas asciihex is.
271 This option was new in Netbpm 10.27 (March 2005).
273 -psfilter
276 pnmtops can generate two different kinds of Encapsulated Post‐
277 script programs to represent an image. By default, it generates
278 a program that redefines readstring in a custom manner and
279 doesn't rely on any built-in Postscript filters. But with the
280 -psfilter option, pnmtops leaves readstring alone and uses the
281 built-in Postscript filters /ASCII85Decode, /ASCIIHexDecode,
282 /RunLengthDecode, and /FlateDecode.
283 This option was new in Netbpm 10.27 (March 2005). Before that,
285 pnmtops always used the custom readstring.
286 The custom code can't do flate or ascii85 encoding, so you must
288 use -psfilter if you want those (see -flate, -ascii85).
289 -level This option determines the level (version number) of Postscript
292 that pnmtops uses. By default, pnmtops uses Level 2. Some fea‐
293 tures of pnmtops are available only in higher Postscript levels,
294 so if you specify too low a level for your image and your
295 options, pnmtops fails. For example, pnmtops cannot do a color
296 image in Level 1.
297 This option was new in Netpbm 10.27 (March 2005). Before that,
299 pnmtops always used Level 2.
300 -dict This causes the Postscript program create a separated dictionary
303 for its local variables and remove it from the stack as it
304 exits.
305 This option was new in Netbpm 10.27 (March 2005).
307 -vmreclaim
310 This option causes the Postscript program to force a memory
311 garbage collection as it exits.
312 This option was new in Netbpm 10.27 (March 2005).
314 -nocenter
317 By default, pnmtops centers the image on the output page.
318 You can cause pnmtops to instead put the image against the
319 lower left corner of the page with the -nocenter
320 option. This is useful for programs which can include
321 PostScript files, but can't cope with pictures which are
322 not
323 positioned in the lower left corner.
324 If you want to position an image on the page arbitrarily,
326 use
327 pamcomp to create an image of the full page with the image
328 in
329 question at the proper place and the rest of the page
330 white, and use
331 pnmtops to convert the composed result to Encapsulated
332 Postscript.
333 For backward compatibility, pnmtops accepts the option
335 -center, but it has no effect.
336 -setpage
339 This causes pnmtops to include a "setpagedevice"
340 directive in the output. This causes the output to violate
341 specifications
342 of EPSF encapsulated Postscript, but if you're not using it
343 in an
344 encapsulated way, may be what you need. The directive
345 tells the
346 printer/plotter what size paper to use (or cut). The
347 dimensions it
348 specifies on this directive are those selected by the
349 -width and -height options or defaulted.
350 From January through May 2002, the default was to include
352 "setpagedevice" and this option did not exist. Before
353 January 2002, there was no way to include "setpagedevice"
354 and neither the -setpage nor -nosetpage option existed.
355 -nosetpage
358 This tells pnmtops not to include a "setpagedevice"
359 directive in the output. This is the default, so the
360 option has no
361 effect.
362 See the -setpage option for the history of this option.
364 -noshowpage
367 This tells pnmtops not to include a "showpage"
368 directive in the output. By default, pnmtops includes a
369 "showpage" at the end of the EPSF program. According to
370 EPSF specs, this is OK, and the program that includes the
371 EPSF is
372 supposed to redefine showpage so this doesn't cause unde‐
373 sirable
374 behavior. But it's often easier just not to have the show‐
375 page.
376 This options was new in Netpbm 10.27 (March 2005). Earlier
378 versions of pnmtops always include the showpage.
379 -showpage
382 This tells pnmtops to include a "showpage" directive
383 at the end of the EPSF output. This is the default, so the
384 option has
385 no effect.
386 This option was new in Netpbm 10.27 (March 2005).
388 -verbose
391 This causes informational messages about the conversion
392 process and
393 result.
394
399 If the PNM image has a maxval greater than 255, pnmtops will produce
400 output with 8 bits per sample resolution unless you specify -psfilter,
401 even though Postscript Level 2 has a 12 bits per sample format. pnm‐
402 tops's custom raster-generating code just doesn't know the 12 bit for‐
403 mat.
404
407 You can use the Postscript output a number of ways. Many printers take
408 Postscript input (but you still need some kind of printer driver to
409 transport the Postscript to the printer).
410 There is also the Ghostscript program (not part of Netpbm), which takes
412 Postscript as input and generates an output stream to control any of
413 myriad models of printer (but you still need some kind of printer
414 driver to transport that stream to the printer).
415 Ghostscript also can convert the Postscript file to PDF, which is a
417 very popular document and image format. Use Ghostscript's pdfwrite
418 output device type. The program ps2pdf (distributed with Ghostscript)
419 is a convenient way to run Ghostscript with pdfwrite.
420
424 Postscript is described in the Postscript Language Reference Manual
425 ⟨http://www.adobe.com/products/postscript/pdfs/PLRM.pdf⟩ .
426 bmpp(1) converts from Netpbm and other formats to Encapsulated Post‐
428 script.
429 bmpp has a few functions pnmtops does not, such as the ability to use
431 LZW compression.
432 pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
434 topsg3(1), ppmtopgm(1),
435
439 Copyright (C) 1989, 1991 by Jef Poskanzer.
440 Modified November 1993 by Wolfgang Stuerzlinger, wrzl@gup.uni-
442 linz.ac.at
443 The program was originally pbmtops. It became pgmtops in October 1988
445 and was merged with ppmtops to form pnmtops in January 1991. ppmtops
446 came into being some time before September 1989.
447
450 ·
451 SYNOPSIS ⟨#synopsis⟩
453 ·
455 DESCRIPTION ⟨#description⟩
457 ·
459 OPTIONS ⟨#options⟩
461 ·
463 LIMITATIONS ⟨#limitations⟩
465 ·
467 APPLICATIONS ⟨#applications⟩
469 ·
471 SEE ALSO ⟨#seealso⟩
473 ·
475 HISTORY ⟨#history⟩
477
479 This manual page was generated by the Netpbm tool 'makeman' from HTML
480 source. The master documentation is at
481 http://netpbm.sourceforge.net/doc/pnmtops.html
483netpbm documentation 20 April 2018 Pnmtops User Manual(0)