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