Debian Codegraph @

upstream/debian-unstable/man1/pnmtops.1

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