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] [-textalphabits={1,2,4} [-rle|-runlength] [-flate]
13 [-ascii85] [-nocenter|-center] [-nosetpage|-setpage] [-level=N] [-dict]
14 [-vmreclaim] [-psfilter] [-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 If the input file is in color (PPM), pnmtops generates a color Post‐
28 Script file. Some PostScript interpreters can't handle color Post‐
29 Script. If you have one of these you will need to run your image
30 through ppmtopgm first.
31 If you specify no output dimensioning options, the output image is
33 dimensioned as if you had specified -scale=1.0, which means aproxi‐
34 mately 72 pixels of the input image generate one inch of output (if
35 that fits the page).
36 Use -imagewidth, -imageheight, -equalpixels, -width, -height, and
38 -scale to adjust that.
39 Each image in the input stream becomes one complete one-page Postscript
41 program in the output. (This may not be the best way to create a
42 multi-page Postscript stream; someone who knows Postscript should work
43 on this).
44 The line at the top of the file produced by pnmtops is either '%!PS-
46 Adobe-3.0 EPSF-3.0' or just '%!PS-Adobe-3.0'. The numbers do not
47 reflect the Postscript language level, but the version of the DSC com‐
48 ment specification and EPS specification implmented. The Postscript
49 language level is in the "%%LanguageLevel:" comment. pnmtops omits
50 "EPSF-3.0" if you specify -setpage, because it is incorrect to claim
51 EPS compliance if the file uses setpagedevice.
52 What is Encapsulated Postscript?
56 Encapsulated Postscript (EPSF) is a subset of Postscript (i.e. the set
57 of streams that conform to EPSF is a subset of those that conform to
58 Postscript). It is designed so that an EPSF stream can be embedded in
59 another Postscript stream. A typical reason to do that is where an
60 EPSF stream describes a picture you want in a larger document.
61 An Encapsulated Postscript document conforms to the DSC (Document
63 Structuring Convention). The DSC defines some Postscript comments
64 (they're comments from a Postscript point of view, but have semantic
65 value from a DSC point of view).
66 More information about Encapsulated Postscript is at
68 http://http://www.tailrecursive.org/postscript/eps.html (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 -bitspersample=N
99 This option selects the number of bits for each component of
100 each pixel in the Postscript output. By default, pnmtops
101 chooses the value that corresponds to the maxval of the PNM
102 input, subject to constraints of the Postscript language. In
103 particular, if you don't select Postscript level 2 (-level) with
104 built-in Postscript (-psfilter), the most bits per pixel you can
105 have is 8.
106 The value must be 1, 2, 4, 8, or 12, with 12 being restricted to
108 the case described above.
109 This option was new in Netpbm 10.51 (June 2010).
111 -scale tells how big you want the image on the page. The value is the
114 number of inches of output image that you want 72 pixels of the
115 input to generate.
116 But pnmtops rounds the number to something that is an integral
118 number of output device pixels. E.g. if the output device is
119 300 dpi and you specify -scale=1.0, then 75 (not 72) pixels of
120 input becomes one inch of output (4 output pixels for each input
121 pixel). Note that the -dpi option tells pnmtops how many pixels
122 per inch the output device generates.
123 If the size so specified does not fit on the page (as measured
125 either by the -width and -height options or the default page
126 size of 8.5 inches by 11 inches), pnmtops ignores the -scale
127 option, issues a warning, and scales the image to fit on the
128 page.
129 -dpi=N[xN]
132 This option specifies the dots per inch resolution of your out‐
134 put device. The default is 300 dpi. In theory PostScript is
135 device-independent and you don't have to worry about this, but
136 in practice its raster rendering can have unsightly bands if the
137 device pixels and the image pixels aren't in sync.
138 Also this option is crucial to the working of the equalpixels
140 option.
141 If you specify NxN, the first number is the horizontal resolu‐
143 tion and the second number is the vertical resolution. If you
144 specify just a single number N, that is the resolution in both
145 directions.
146 -width, -height
149 These options specify the dimensions, in inches, of the page on
150 which the output is to be printed. This can affect the size of
151 the output image.
152 The page size has no effect, however, when you specify the
154 -imagewidth, -imageheight, or -equalpixels options.
155 These options may also affect positioning of the image on the
157 page and even the paper selected (or cut) by the printer/plotter
158 when the output is printed. See the -nosetpage option.
159 The default is 8.5 inches by 11 inches.
161 -turn
164 -noturn
167 These options control whether the image gets turned 90 degrees.
168 Normally, if an image fits the page better when turned (e.g. the
169 image is wider than it is tall, but the page is taller than it
170 is wide), it gets turned automatically to better fit the page.
171 If you specify the -turn option, pnmtops turns the image no
172 matter what its shape; If you specify -noturn, pnmtops does not
173 turn it no matter what its shape.
174 -textalphabits={1,2,4}
177 This controls subsample antialiasing of text. Antialiasing is a
178 form of smoothing that eliminates jagged edges on characters.
179 Subsample antialiasing is a kind of antialiasing that uses sub‐
180 pixels in a box, and the value of this option is the size of
181 that box. 4 gives you the best looking output, while 1 causes
182 no antialiasing. Smaller numbers make pnmtops use less CPU
183 time.
184 Pstopnm uses Ghostscript's TextAlphaBits parameter for this.
186 The default is 4.
188 This option was new in Netpbm 10.53 (December 2010). Older ver‐
190 sions of pnmtops do no antialiasing.
191 -rle
194 -runlength
197 These identical options tell pnmtops to use run length compres‐
198 sion in encoding the image in the Postscript program. This may
199 save time if the host-to-printer link is slow; but normally the
200 printer's processing time dominates, so -rle has no effect (and
201 in the absence of buffering, may make things slower).
202 This may, however, make the Postscript program considerable
204 smaller.
205 This usually doesn't help at all with a color image and -psfil‐
207 ter, because in that case, the Postscript program pnmtops cre‐
208 ates has the red, green, and blue values for each pixel
209 together, which means you would see long runs of identical bytes
210 only in the unlikely event that the red, green, and blue values
211 for a bunch of adjacent pixels are all the same. But without
212 -psfilter, the Postscript program has all the red values, then
213 all the green values, then all the blue values, so long runs
214 appear wherever there are long stretches of the same color.
215 Here is an explanation by Jef Poskanzer of why he invented the
217 -rle option:
218 I just spent a few hours modifying my pbmtops filter to produce
220 run length encoded PostScript output. The results are not spec‐
221 tacular for me - yes, the files are smaller, but the printing
222 times are about the same. But I'm printing over the network.
223 If you were stuck with the serial line, this would be a big win.
224 I've appended a sample program generated by my filter. If any‐
225 one sees ways to improve the code, please let me know, I'm not
226 much of a PostScript hacker. This version of pbmtops will be
227 distributed to comp.sources.misc and expo.lcs.mit.edu sometime
228 in October. - Jef
229 This is from a forum about Postscript ⟨http://www.lngpstscrpt.tk/re-
231 postscript-run-length-encoding-again⟩ , extracted in October 2010. Jef
232 added -rle in August 1988. In those days, RS-232 lines (referred to a
233 'serial' in the quotation) were typically 9600bps. 2400 bps lines were
234 still around. What the quotation calls 'the network' is probably a 10
235 Mbps ethernet connection.
236 -flate This option tells pnmtops to use 'flate' compression (i.e. com‐
239 pression via the 'Z' library -- the same as PNG).
240 See the -rle option for information about compression in gen‐
242 eral.
243 You must specify -psfilter if you specify -flate.
245 This option was new in Netbpm 10.27 (March 2005).
247 Before Netpbm 10.32 (February 2006), you could not specify -rle
249 and -flate together.
250 -ascii85
254 By default, pnmtops uses 'asciihex' encoding of the image
255 raster. The image raster is a stream of bits, while a Post‐
256 script program is text, so there has to be an encoding from bits
257 to text. Asciihex encoding is just the common hexadecimal rep‐
258 resentation of bits. E.g. 8 1 bits would be encoded as the two
259 characters 'FF'.
260 With the -ascii85 option, pnmtops uses 'ascii85' encoding
262 instead. This is an encoding in which 32 bits are encoded into
263 five characters of text. Thus, it produces less text for the
264 same raster than asciihex. But ascii85 is not available in
265 Postscript Level 1, whereas asciihex is.
266 This option was new in Netbpm 10.27 (March 2005).
268 -psfilter
271 pnmtops can generate two different kinds of Encapsulated Post‐
272 script programs to represent an image. By default, it generates
273 a program that redefines readstring in a custom manner and
274 doesn't rely on any built-in Postscript filters. But with the
275 -psfilter option, pnmtops leaves readstring alone and uses the
276 built-in Postscript filters /ASCII85Decode, /ASCIIHexDecode,
277 /RunLengthDecode, and /FlateDecode.
278 This option was new in Netbpm 10.27 (March 2005). Before that,
280 pnmtops always used the custom readstring.
281 The custom code can't do flate or ascii85 encoding, so you must
283 use -psfilter if you want those (see -flate, -ascii85).
284 -level This option determines the level (version number) of Postscript
287 that pnmtops uses. By default, pnmtops uses Level 2. Some fea‐
288 tures of pnmtops are available only in higher Postscript levels,
289 so if you specify too low a level for your image and your
290 options, pnmtops fails. For example, pnmtops cannot do a color
291 image in Level 1.
292 This option was new in Netpbm 10.27 (March 2005). Before that,
294 pnmtops always used Level 2.
295 -dict This causes the Postscript program create a separated dictionary
298 for its local variables and remove it from the stack as it
299 exits.
300 This option was new in Netbpm 10.27 (March 2005).
302 -vmreclaim
305 This option causes the Postscript program to force a memory
306 garbage collection as it exits.
307 This option was new in Netbpm 10.27 (March 2005).
309 -nocenter
312 By default, pnmtops centers the image on the output page.
313 You can cause pnmtops to instead put the image against the
314 lower left corner of the page with the -nocenter
315 option. This is useful for programs which can include
316 PostScript files, but can't cope with pictures which are
317 not
318 positioned in the lower left corner.
319 For backward compatibility, pnmtops accepts the option
321 -center, but it has no effect.
322 -setpage
325 This causes pnmtops to include a 'setpagedevice'
326 directive in the output. This causes the output to violate
327 specifications
328 of EPSF encapsulated Postscript, but if you're not using it
329 in an
330 encapsulated way, may be what you need. The directive
331 tells the
332 printer/plotter what size paper to use (or cut). The
333 dimensions it
334 specifies on this directive are those selected by the
335 -width and -height options or defaulted.
336 From January through May 2002, the default was to include
338 'setpagedevice' and this option did not exist. Before
339 January 2002, there was no way to include 'setpagedevice'
340 and neither the -setpage nor -nosetpage option existed.
341 -nosetpage
344 This tells pnmtops not to include a 'setpagedevice'
345 directive in the output. This is the default, so the
346 option has no
347 effect.
348 See the -setpage option for the history of this option.
350 -noshowpage
353 This tells pnmtops not to include a 'showpage'
354 directive in the output. By default, pnmtops includes a
355 'showpage' at the end of the EPSF program According to
356 EPSF specs, this is OK, and the program that includes the
357 EPSF is
358 supposed to redefine showpage so this doesn't cause unde‐
359 sirable
360 behavior. But it's often easier just not to have the show‐
361 page.
362 This options was new in Netpbm 10.27 (March 2005). Earlier
364 versions of pnmtops always include the showpage.
365 -showpage
368 This tells pnmtops to include a 'showpage' directive
369 at the end of the EPSF output. This is the default, so the
370 option has
371 no effect.
372 This option was new in Netpbm 10.27 (March 2005).
374 -verbose
377 This causes informational messages about the conversion
378 process and
379 result.
380
385 If the PNM image has a maxval greater than 255, pnmtops will produce
386 output with 8 bits per sample resolution unless you specify -psfilter,
387 even though Postscript Level 2 has a 12 bits per sample format. pnm‐
388 tops's custom raster-generating code just doesn't know the 12 bit for‐
389 mat.
390
394 Postscript is described in the Postscript Language Reference Manual
395 ⟨http://www.adobe.com/products/postscript/pdfs/PLRM.pdf⟩ .
396 bmeps ⟨http://bmeps.sourceforge.net⟩ converts from Netpbm and other
398 formats to Encapsulated Postscript. It is suitable for hooking up to
399 dvips so you can include an image in a Latex document just with an
400 \includegraphics directive.
401 bmeps has a few functions pnmtops does not, such as the ability to
403 include a transparency mask in the Postscript program (but not from PAM
404 input -- only from PNG input).
405 pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
407 topsg3(1), ppmtopgm(1),
408
412 Copyright (C) 1989, 1991 by Jef Poskanzer.
413 Modified November 1993 by Wolfgang Stuerzlinger, wrzl@gup.uni-
415 linz.ac.at
416 The program was originally pbmtops. It became pgmtops in October 1988
418 and was merged with ppmtops to form pnmtops in January 1991. ppmtops
419 came into being some time before September 1989.
420
423 ·
424 SYNOPSIS ⟨#synopsis⟩
426 ·
428 DESCRIPTION ⟨#description⟩
430 ·
432 OPTIONS ⟨#options⟩
434 ·
436 LIMITATIONS ⟨#limitations⟩
438 ·
440 SEE ALSO ⟨#seealso⟩
442 ·
444 HISTORY ⟨#history⟩
446netpbm documentation 10 December 2010 Pnmtops User Manual(0)