1Pnmtops User Manual(0)                                  Pnmtops User Manual(0)
2
3
4

NAME

6       pnmtops - convert PNM image to Postscript
7
8

SYNOPSIS

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
16       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
20

DESCRIPTION

22       This program is part of Netpbm(1).
23
24       pnmtops  reads a Netpbm image stream as input and produces Encapsulated
25       Postscript (EPSF) as output.
26
27       (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
31       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
36       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
41       Use  -imagewidth,  -imageheight,  -equalpixels,  -width,  -height,  and
42       -scale to adjust that.
43
44       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
49       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
57
58
59   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
66       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
71       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
76       More information about Encapsulated Postscript is at   http://www.tail
77       recursive.org/postscript/eps.html" (1).
78
79       Many  of  the  ideas in pnmtops come from Dirk Krause's bmeps.  See SEE
80       ALSO ⟨#seealso⟩ .
81
82

OPTIONS

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
89
90
91       -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
97              If  these  dimensions  are  greater  than the page size, you get
98              Postscript output that runs off the page.
99
100              You  cannot  use  imagewidth  or  imageheight  with  -scale   or
101              -equalpixels.
102
103
104       -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
110              You cannot use -equalpixels with -imagewidth,  -imageheight,  or
111              -scale.
112
113
114       -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
123              The value must be 1, 2, 4, 8, or 12, with 12 being restricted to
124              the case described above.
125
126              This option was new in Netpbm 10.51 (June 2010).
127
128
129       -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
133              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
140              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
145
146       -dpi=N[xN]
147
148              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
154              Also this option is crucial to the working  of  the  equalpixels
155              option.
156
157              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
162
163       -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
168              The page size has no effect, however, when you specify the  -im‐
169              agewidth, -imageheight, or -equalpixels options.
170
171              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
175              The default is 8.5 inches by 11 inches.
176
177
178       -turn
179
180
181       -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
190
191       -rle
192
193
194       -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
201              This  may,  however,  make  the  Postscript program considerable
202              smaller.
203
204              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
214              Here is an explanation by Jef Poskanzer of why he  invented  the
215              -rle option:
216
217              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
228       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
235
236       -flate This  option tells pnmtops to use "flate" compression (i.e. com‐
237              pression via the "Z" library -- the same as PNG).
238
239              See the -rle option for information about  compression  in  gen‐
240              eral.
241
242              You must specify -psfilter if you specify -flate.
243
244              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
250              This option was new in Netbpm 10.27 (March 2005).
251
252              Before  Netpbm 10.32 (February 2006), you could not specify -rle
253              and -flate together.
254
255
256
257       -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
265              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
271              This option was new in Netbpm 10.27 (March 2005).
272
273
274       -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
283              This  option was new in Netbpm 10.27 (March 2005).  Before that,
284              pnmtops always used the custom readstring.
285
286              The custom code can't do flate or ascii85 encoding, so you  must
287              use -psfilter if you want those (see -flate, -ascii85).
288
289
290       -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
297              This option was new in Netpbm 10.27 (March 2005).  Before  that,
298              pnmtops always used Level 2.
299
300
301       -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
305              This option was new in Netbpm 10.27 (March 2005).
306
307
308       -vmreclaim
309              This  option  causes  the  Postscript  program to force a memory
310              garbage collection as it exits.
311
312              This option was new in Netbpm 10.27 (March 2005).
313
314
315       -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
324                   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
333                   For backward compatibility, pnmtops accepts the option
334                   -center, but it has no effect.
335
336
337       -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
350              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
355
356       -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
362              See the -setpage option for the history of this option.
363
364
365       -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
376              This options was new in Netpbm 10.27 (March 2005).  Earlier
377                   versions of pnmtops always include the showpage.
378
379
380       -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
386              This option was new in Netpbm 10.27 (March 2005).
387
388
389       -verbose
390                  This causes  informational  messages  about  the  conversion
391              process and
392                  result.
393
394
395
396

LIMITATIONS

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
404

APPLICATIONS

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
410       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
415       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
420
421

SEE ALSO

423       bmpp(1)  converts  from  Netpbm and other formats to Encapsulated Post‐
424       script.
425
426       bmpp has a few functions pnmtops does not, such as the ability  to  use
427       LZW compression.
428
429       pnm(1),  gs,  psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
430       topsg3(1), ppmtopgm(1),
431
432
433

HISTORY

435       Copyright (C) 1989, 1991 by Jef Poskanzer.
436
437       Modified  November  1993  by   Wolfgang   Stuerzlinger,   wrzl@gup.uni-
438       linz.ac.at
439
440       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
444

Table Of Contents

446
447
448              SYNOPSIS ⟨#synopsis⟩
449
450
451
452              DESCRIPTION ⟨#description⟩
453
454
455
456              OPTIONS ⟨#options⟩
457
458
459
460              LIMITATIONS ⟨#limitations⟩
461
462
463
464              APPLICATIONS ⟨#applications⟩
465
466
467
468              SEE ALSO ⟨#seealso⟩
469
470
471
472              HISTORY ⟨#history⟩
473

DOCUMENT SOURCE

475       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
476       source.  The master documentation is at
477
478              http://netpbm.sourceforge.net/doc/pnmtops.html
479
480netpbm documentation             20 April 2018          Pnmtops User Manual(0)
Impressum