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]
12       [-turn|-noturn]  [-rle|-runlength] [-flate] [-ascii85] [-nocenter|-cen‐
13       ter] [-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
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
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
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
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;
69       pnmtops 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
83

OPTIONS

85       -imagewidth, -imageheight
86              Tells how wide and high you want  the  image  on  the  page,  in
87              inches.   The  aspect ratio of the image is preserved, so if you
88              specify both of these, the image on the page will be the largest
89              image that will fit within the box of those dimensions.
90
91              If  these  dimensions  are  greater  than the page size, you get
92              Postscript output that runs off the page.
93
94              You  cannot  use  imagewidth  or  imageheight  with  -scale   or
95              -equalpixels.
96
97
98       -equalpixels
99              This  option  causes the output image to have the same number of
100              pixels as the input image.  So if the output device is  600  dpi
101              and  your image is 3000 pixels wide, the output image would be 5
102              inches wide.
103
104              You cannot use -equalpixels with -imagewidth,  -imageheight,  or
105              -scale.
106
107
108       -bitspersample=N
109              This  option  selects  the  number of bits for each component of
110              each pixel  in  the  Postscript  output.   By  default,  pnmtops
111              chooses  the  value  that  corresponds  to the maxval of the PNM
112              input, subject to constraints of the  Postscript  language.   In
113              particular, if you don't select Postscript level 2 (-level) with
114              built-in Postscript (-psfilter), the most bits per pixel you can
115              have is 8.
116
117              The value must be 1, 2, 4, 8, or 12, with 12 being restricted to
118              the case described above.
119
120              This option was new in Netpbm 10.51 (June 2010).
121
122
123       -scale tells how big you want the image on the page.  The value is  the
124              number  of inches of output image that you want 72 pixels of the
125              input to generate.
126
127              But pnmtops  rounds the number to something that is an  integral
128              number  of  output  device pixels.  E.g. if the output device is
129              300 dpi and you specify -scale=1.0, then 75 (not 72)  pixels  of
130              input becomes one inch of output (4 output pixels for each input
131              pixel).  Note that the -dpi option tells pnmtops how many pixels
132              per inch the output device generates.
133
134              If  the  size so specified does not fit on the page (as measured
135              either by the -width and -height options  or  the  default  page
136              size  of  8.5  inches  by 11 inches), pnmtops ignores the -scale
137              option, issues a warning, and scales the image  to  fit  on  the
138              page.
139
140
141       -dpi=N[xN]
142
143              This  option specifies the dots per inch resolution of your out‐
144              put device.  The default is 300 dpi.  In  theory  PostScript  is
145              device-independent  and  you don't have to worry about this, but
146              in practice its raster rendering can have unsightly bands if the
147              device pixels and the image pixels aren't in sync.
148
149              Also  this  option  is crucial to the working of the equalpixels
150              option.
151
152              If you specify NxN, the first number is the  horizontal  resolu‐
153              tion  and  the second number is the vertical resolution.  If you
154              specify just a single number N, that is the resolution  in  both
155              directions.
156
157
158       -width, -height
159               These options specify the dimensions, in inches, of the page on
160              which the output is to be printed.  This can affect the size  of
161              the output image.
162
163              The  page  size  has  no  effect,  however, when you specify the
164              -imagewidth, -imageheight, or -equalpixels options.
165
166              These options may also affect positioning of the  image  on  the
167              page and even the paper selected (or cut) by the printer/plotter
168              when the output is printed.  See the -nosetpage option.
169
170              The default is 8.5 inches by 11 inches.
171
172
173       -turn
174
175
176       -noturn
177              These options control whether the image gets turned 90  degrees.
178              Normally, if an image fits the page better when turned (e.g. the
179              image is wider than it is tall, but the page is taller  than  it
180              is  wide),  it gets turned automatically to better fit the page.
181              If you specify the -turn option, pnmtops   turns  the  image  no
182              matter  what its shape; If you specify -noturn, pnmtops does not
183              turn it no matter what its shape.
184
185
186       -rle
187
188
189       -runlength
190              These identical options tell pnmtops to use run length  compres‐
191              sion  in encoding the image in the Postscript program.  This may
192              save time if the host-to-printer link is slow; but normally  the
193              printer's  processing time dominates, so -rle has no effect (and
194              in the absence of buffering, may make things slower).
195
196              This may, however,  make  the  Postscript  program  considerable
197              smaller.
198
199              This  usually doesn't help at all with a color image and -psfil‐
200              ter, because in that case, the Postscript program  pnmtops  cre‐
201              ates  has  the  red,  green,  and  blue  values  for  each pixel
202              together, which means you would see long runs of identical bytes
203              only  in the unlikely event that the red, green, and blue values
204              for a bunch of adjacent pixels are all the  same.   But  without
205              -psfilter,  the  Postscript program has all the red values, then
206              all the green values, then all the blue  values,  so  long  runs
207              appear wherever there are long stretches of the same color.
208
209              Here  is  an explanation by Jef Poskanzer of why he invented the
210              -rle option:
211
212              I just spent a few hours modifying my pbmtops filter to  produce
213              run length encoded PostScript output.  The results are not spec‐
214              tacular for me - yes, the files are smaller,  but  the  printing
215              times  are  about  the same.  But I'm printing over the network.
216              If you were stuck with the serial line, this would be a big win.
217              I've  appended a sample program generated by my filter.  If any‐
218              one sees ways to improve the code, please let me know,  I'm  not
219              much  of  a  PostScript hacker.  This version of pbmtops will be
220              distributed to comp.sources.misc and  expo.lcs.mit.edu  sometime
221              in October. - Jef
222
223       This  is  from  a forum about Postscript ⟨http://www.lngpstscrpt.tk/re-
224       postscript-run-length-encoding-again⟩ , extracted in October 2010.  Jef
225       added -rle in August 1988.  In those days, RS-232 lines (referred to as
226       "serial" in the quotation) were typically 9600bps.  2400 bps lines were
227       still  around.  What the quotation calls "the network" is probably a 10
228       Mbps Ethernet connection.
229
230
231       -flate This option tells pnmtops to use "flate" compression (i.e.  com‐
232              pression via the "Z" library -- the same as PNG).
233
234              See  the  -rle  option for information about compression in gen‐
235              eral.
236
237              You must specify -psfilter if you specify -flate.
238
239              There exist modern versions of pnmtops that cannot do flate com‐
240              pression;  these  versions  were built without the Z library and
241              built not to require the Z library.  If you have such a version,
242              it  fails  with  an  explanatory  error message when you specify
243              -flate.
244
245              This option was new in Netbpm 10.27 (March 2005).
246
247              Before Netpbm 10.32 (February 2006), you could not specify  -rle
248              and -flate together.
249
250
251
252       -ascii85
253              By  default,  pnmtops  uses  "asciihex"  encoding  of  the image
254              raster.  The image raster is a stream of  bits,  while  a  Post‐
255              script program is text, so there has to be an encoding from bits
256              to text.  Asciihex encoding is just the common hexadecimal  rep‐
257              resentation  of bits.  E.g. 8 1 bits would be encoded as the two
258              characters "FF".
259
260              With  the  -ascii85  option,  pnmtops  uses  "ascii85"  encoding
261              instead.   This is an encoding in which 32 bits are encoded into
262              five characters of text.  Thus, it produces less  text  for  the
263              same  raster  than  asciihex.   But  ascii85 is not available in
264              Postscript Level 1, whereas asciihex is.
265
266              This option was new in Netbpm 10.27 (March 2005).
267
268
269       -psfilter
270              pnmtops can generate two different kinds of  Encapsulated  Post‐
271              script programs to represent an image.  By default, it generates
272              a program that redefines  readstring  in  a  custom  manner  and
273              doesn't  rely  on any built-in Postscript filters.  But with the
274              -psfilter option, pnmtops leaves readstring alone and  uses  the
275              built-in  Postscript  filters  /ASCII85Decode,  /ASCIIHexDecode,
276              /RunLengthDecode, and /FlateDecode.
277
278              This option was new in Netbpm 10.27 (March 2005).  Before  that,
279              pnmtops always used the custom readstring.
280
281              The  custom code can't do flate or ascii85 encoding, so you must
282              use -psfilter if you want those (see -flate, -ascii85).
283
284
285       -level This option determines the level (version number) of  Postscript
286              that pnmtops uses.  By default, pnmtops uses Level 2.  Some fea‐
287              tures of pnmtops are available only in higher Postscript levels,
288              so  if  you  specify  too  low  a  level for your image and your
289              options, pnmtops fails.  For example, pnmtops cannot do a  color
290              image in Level 1.
291
292              This  option was new in Netpbm 10.27 (March 2005).  Before that,
293              pnmtops always used Level 2.
294
295
296       -dict  This causes the Postscript program create a separated dictionary
297              for  its  local  variables  and  remove  it from the stack as it
298              exits.
299
300              This option was new in Netbpm 10.27 (March 2005).
301
302
303       -vmreclaim
304              This option causes the Postscript  program  to  force  a  memory
305              garbage collection as it exits.
306
307              This option was new in Netbpm 10.27 (March 2005).
308
309
310       -nocenter
311                   By default, pnmtops centers the image on the output page.
312                   You can cause pnmtops to instead put the image against the
313                   lower left corner of the page with the -nocenter
314                   option.  This is useful for programs which can include
315                   PostScript  files,  but  can't cope with pictures which are
316              not
317                   positioned in the lower left corner.
318
319                   If you want to position an image on the  page  arbitrarily,
320              use
321                   pamcomp  to create an image of the full page with the image
322              in
323                   question at the proper place  and  the  rest  of  the  page
324              white, and use
325                   pnmtops  to  convert  the  composed  result to Encapsulated
326              Postscript.
327
328                   For backward compatibility, pnmtops accepts the option
329                   -center, but it has no effect.
330
331
332       -setpage
333                   This causes pnmtops to include a "setpagedevice"
334                   directive in the output.  This causes the output to violate
335              specifications
336                   of EPSF encapsulated Postscript, but if you're not using it
337              in an
338                   encapsulated way, may be  what  you  need.   The  directive
339              tells the
340                   printer/plotter  what  size  paper  to  use  (or cut).  The
341              dimensions it
342                   specifies on this directive are those selected by the
343                   -width and -height options or defaulted.
344
345              From January through May 2002, the default was to include
346                   "setpagedevice" and this option did not exist.  Before
347                   January 2002, there was no way to include "setpagedevice"
348                   and neither the -setpage nor -nosetpage option existed.
349
350
351       -nosetpage
352                   This tells pnmtops not to include a "setpagedevice"
353                   directive in the output.   This  is  the  default,  so  the
354              option has no
355                   effect.
356
357              See the -setpage option for the history of this option.
358
359
360       -noshowpage
361                   This tells pnmtops not to include a "showpage"
362                   directive in the output.  By default, pnmtops includes a
363                   "showpage" at the end of the EPSF program.  According to
364                   EPSF  specs,  this is OK, and the program that includes the
365              EPSF is
366                   supposed to redefine showpage so this doesn't  cause  unde‐
367              sirable
368                   behavior.  But it's often easier just not to have the show‐
369              page.
370
371              This options was new in Netpbm 10.27 (March 2005).  Earlier
372                   versions of pnmtops always include the showpage.
373
374
375       -showpage
376                  This tells pnmtops to include a "showpage" directive
377                  at the end of the EPSF output.  This is the default, so  the
378              option has
379                  no effect.
380
381              This option was new in Netpbm 10.27 (March 2005).
382
383
384       -verbose
385                  This  causes  informational  messages  about  the conversion
386              process and
387                  result.
388
389
390
391

LIMITATIONS

393       If the PNM image has a maxval greater than 255,  pnmtops  will  produce
394       output  with 8 bits per sample resolution unless you specify -psfilter,
395       even though Postscript Level 2 has a 12 bits per sample  format.   pnm‐
396       tops's  custom raster-generating code just doesn't know the 12 bit for‐
397       mat.
398
399
400

APPLICATIONS

402       You can use the Postscript output a number of ways.  Many printers take
403       Postscript  input  (but  you  still need some kind of printer driver to
404       transport the Postscript to the printer).
405
406       There is also the Ghostscript program (not part of Netpbm), which takes
407       Postscript  as  input  and generates an output stream to control any of
408       myriad models of printer (but you  still  need  some  kind  of  printer
409       driver to transport that stream to the printer).
410
411       Ghostscript  also  can  convert  the Postscript file to PDF, which is a
412       very popular document and image  format.   Use  Ghostscript's  pdfwrite
413       output  device type.  The program ps2pdf (distributed with Ghostscript)
414       is a convenient way to run Ghostscript with pdfwrite.
415
416
417

SEE ALSO

419       Postscript is described in the  Postscript  Language  Reference  Manual
420http://www.adobe.com/products/postscript/pdfs/PLRM.pdf⟩ .
421
422       bmpp(1)  converts  from  Netpbm and other formats to Encapsulated Post‐
423       script.
424
425       bmpp has a few functions pnmtops does not, such as the ability  to  use
426       LZW compression.
427
428       pnm(1),  gs,  psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm‐
429       topsg3(1), ppmtopgm(1),
430
431
432

HISTORY

434       Copyright (C) 1989, 1991 by Jef Poskanzer.
435
436       Modified  November  1993  by   Wolfgang   Stuerzlinger,   wrzl@gup.uni-
437       linz.ac.at
438
439       The  program was originally pbmtops.  It became pgmtops in October 1988
440       and was merged with ppmtops to form pnmtops in January  1991.   ppmtops
441       came into being some time before September 1989.
442
443

Table Of Contents

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

DOCUMENT SOURCE

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