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

NAME

6       pstopnm - convert a PostScript file to a PNM image
7
8

SYNOPSIS

10       pstopnm
11
12       [-stdout]
13
14       [-forceplain]
15
16       [-help]
17
18       [-dpi=dpi]
19
20       [-xsize=pixels] [-ysize=pixels]
21
22       [-xborder=frac] [-yborder=frac] [-landscape]
23
24       [-portrait]
25
26       [-nocrop]
27
28       [-pbm
29
30       |-pgm
31
32       |-ppm]
33
34       [-llx=s] [-lly=s] [-urx=s] [-ury=s]
35
36       [-verbose]
37
38       [-xmax=pixels] [-ymax=pixels]
39
40       [-textalphabits={1,2,4}]
41
42
43       psfile[.ps]
44
45

OPTION USAGE

47       Minimum  unique abbreviation of option is acceptable.  You may use dou‐
48       ble hyphens instead of single hyphen to denote options.   You  may  use
49       white space in place of the equals sign to separate an option name from
50       its value.
51
52

DESCRIPTION

54       This program is part of Netpbm(1).
55
56       pstopnm reads a PostScript file as input and produces PBM, PGM, or  PPM
57       images  as  output.   This  program simply uses GhostScript to render a
58       PostScript file with its PNM device drivers.  If you don't have  Ghost‐
59       Script  installed  or the version you have installed was not built with
60       the relevant PNM device drivers, pstopnm will fail.  You can see if you
61       have  the  proper environment by issuing the command gs --help .  If it
62       responds and lists under "Available Devices" pbm, pbmraw, pgm,  pgmraw,
63       pnm, pnmraw, ppm, or ppmraw, you're in business.
64
65       It's important to understand that pstopnm is a Netpbm image file format
66       converter only in the broadest sense of the word, because Postscript is
67       far  from an image file format.  What pstopnm really is is a Postscript
68       renderer - an image generator.  One place you'll notice the  difference
69       is  where  you  expect pstopnm | pnmtops to be idempotent (which is not
70       the case).  There are details on this kind of conversion below.
71
72       pstopnm uses the value of the GHOSTSCRIPT environment variable  as  the
73       file  name  for  the  Ghostscript  program.  If GHOSTSCRIPT is not set,
74       pstopnm searches your PATH for a regular file named gs.  If it  doesn't
75       find one, it assumes Ghostscript is in the file /usr/bin/gs.
76
77       pstopnm does not use the Netpbm libraries to generate the output files,
78       so may not be entirely consistent with most Netpbm programs.
79
80       psfile[.ps] is the name of the input file.  pstopnm will add the ps  to
81       the end of the name you specify if no file exists by the exact name you
82       specify, but one with .psadded does.  For Standard Input, use - or just
83       don't give any argument.
84
85       If  you  use  the -stdout  option or your input is from Standard Input,
86       pstopnm outputs images of all the pages as a multi-image file to  Stan‐
87       dard  Output.  Otherwise, pstopnm creates one file for each page in the
88       Postscript input.  The files are named as follows: If the input file is
89       named   psfile.ps,  the  name  of  the  files  will  be  psfile001.ppm,
90       psfile002.ppm, etc.  The  filetype  suffix  is  .ppm,  .pgm,  or  .pbm,
91       depending  on  which  kind  of  output  you choose with your invocation
92       options.  If the input file name does not end in .ps,  the  whole  file
93       name  is  used in the output file name.  For example, if the input file
94       is named psfile.old, the output file name is psfile.old001.ppm, etc.
95
96       Note that the output file selection is inconsistent  with  most  Netpbm
97       programs,  because it does not default to Standard Output.  This is for
98       historical reasons, based on the fact that the Netpbm formats  did  not
99       always provide for a sequence of images in a single file.
100
101       When  your input is from Standard Input, you may feed multiple Encapsu‐
102       lated Postscript documents, one after  another,  and  pstopnm  converts
103       every document and places it in the Standard Output stream as an image.
104       But if your input is from a named file, pstopnm expects the file to  be
105       an Encapsulated Postscript file, which means it contains only one Enap‐
106       sulated Postscript document.  If the file  contains  multiple  concate‐
107       nated  documents,  pstopnm  ignores every document but the first.  This
108       distinction does not exist for non-EPSF Postscript input - pstopnm gen‐
109       erates an output image for each page of the input regardless of whether
110       the input is from Standard Input or from a named file.
111
112       Note that you can generate both kinds of files - concatenated EPSF  and
113       multi-page non-EPSF - with pnmtops, selecting with the -setpage option.
114
115       Each  output  image contains a rectangular area of the page to which it
116       pertains.  See the Dimensions section ⟨#dimensions⟩    for  details  on
117       what  part of the input image goes into the output image and how big it
118       is in the output and what borders and margins are in the output image.
119
120       It has been reported that on some Postscript Version  1  input,  Ghost‐
121       script, and therefore pstopnm, produces no output.  To solve this prob‐
122       lem, you can convert the file to Postscript Version 3 with the  program
123       ps2ps.  It is reported that the program pstops does not work.
124
125
126   Dimensions
127       This  section  describes  what part of the input image gets used in the
128       output and the dimensions of the output, including  borders  and  back‐
129       ground.
130
131       Note that an output image is associated with a single input page.
132
133       pstopnm  starts by taking a rectangular area from the input page.  That
134       is called the subject image.
135
136       pstopnm may add borders to the subject image to form what is called the
137       bordered subject image.
138
139       pstopnm  places  the bordered subject image in the center of the output
140       image and clips the edges as necessary to fit the computed output image
141       size.
142
143       The  location  of  the  subject  image  in the Postscript input page is
144       defined by four numbers, the lower left corner and the upper right cor‐
145       ner  x  and  y coordinates.  These coordinates are usually specified by
146       the BoundingBox DSC statement (a Postscript comment) in the  PostScript
147       file,  but they can be overridden by the user by specifying one or more
148       of the following options: -llx, -lly, -urx, and -ury.
149
150       The presence and thickness of a border to be added to the subject image
151       to  form the bordered subject image is controlled by the options -xbor‐
152       der and -yborder.  If pstopnm does not find a BoundingBox statement  in
153       the  input, and you don't specify image area coordinates on the command
154       line, pstopnm uses default values.  If  your  input  is  from  Standard
155       Input,  pstopnm  does  not  use  the BoundingBox values (because of the
156       technical difficulty of extracting that information and  still  feeding
157       the  file to Ghostscript), so you either have to specify the image area
158       coordinates or take the default.
159
160       The output image size is a confusing  thing.   In  a  Postscript  file,
161       things  have spatial dimensions.  For example, a particular line may be
162       3 centimeters long.  A Postscript printer is supposed to print the line
163       3  centimeters  long,  using  however  many  pixels that takes, without
164       regard to how big the sheet of paper on which it is printing is.  In  a
165       PNM  image,  by contrast, there is no spatial dimension; there are only
166       pixels.  You might have a line that is 100 pixels  long,  but  the  PNM
167       image  says  nothing  about  how  long that line should be on a printed
168       page.
169
170       pstopnm fills the role of a Postscript printer.  The  PNM  image  is  a
171       virtual  printed  page.  pstopnm must determine how many pixels it will
172       use in the output image to represent an inch of input image,  which  is
173       the  "output device resolution."  Think of it as the number of dots per
174       inch the virtual printer prints on the virtual page.
175
176       The simplest thing is for you  to  tell  pstopnm  exactly  what  output
177       device  resolution to use, using the -dpi option.  If you say for exam‐
178       ple -dpi=300 and the bordered subject image is 2 inches  by  3  inches,
179       the  PNM  output  will be 600 pixels by 900 pixels.  Using this method,
180       the output device resolution has to be the same in both directions.
181
182       Or you can set the output image dimensions with -xsize and -ysize.  For
183       example,  if  you  say -xsize=1200 -ysize=1800 and the bordered subject
184       image is 2 inches wide by 3 inches high, the output image  is  1200  by
185       1800 pixels, with each pixel representing 1/600 inch of input image.
186
187       In the unlikely event that you want different output device resolutions
188       in the two directions, you could use -xsize and -ysize to do that.   In
189       the  above  example,  if you change -ysize to 900, a pixel still repre‐
190       sents 1/600 inch horizontally, but 1/300 inch vertically.
191
192       If you specify one of -xsize and -ysize  and  not  the  other,  pstopnm
193       defaults  the  other such that the output device resolution is the same
194       in both directions.
195
196       The "x" and "y" of -xsize and -ysize refer to the image  being  printed
197       on the page, not the page.  So if pstopnm prints it in landscape orien‐
198       tation, "x" would pertain to the vertical direction on the  page,  i.e.
199       the vertical direction in the output PNM image.
200
201       If  you  specify  neither the output size nor the output device resolu‐
202       tion, pstopnm does some weird computation which exists mainly for  his‐
203       torical reasons:
204
205       If  you specify -nocrop, pstopnm uses the values of -xmax and -ymax for
206       the output image dimensions.  These default  to  612  and  792  pixels,
207       respectively.
208
209       The  final  case,  the  default, is where you don't specify any size or
210       resolution options or -nocrop.  This is the most complicated case.   In
211       this case, pstopnm first chooses an output device resolution that would
212       generate the number of pixels indicated by -xmax  and  -ymax  from  the
213       bordered  subject image.  Then, based on that resolution, it chooses an
214       output image size that is just large enough to accommodate the  subject
215       image  (no  borders).  Remember (above) that pstopnm trims the edges of
216       the bordered subject image to fit the computed output size.
217
218
219
220   Ghostscript Limitations
221       Tests done in 2013 with Ghostscript 8.71  indicate  that  Ghostscript's
222       pgmraw  output  driver  has some kind of rounding error that causes the
223       pixel values to change  slightly,  and  that  means  pstopnm  generates
224       incorrect  output  when you have monochrome Postscript input.  But with
225       color Postscript input, pstopnm uses Ghostscript's ppmraw output driver
226       and generates correct PPM output.
227
228
229
230   Usage Notes
231       There  is some good advice on converting to and from Postscript, in the
232       document  Postcript File Conversions" (1) by Andrew T. Young.
233
234       Reversible Conversion
235
236       If you're trying to do the equivalent of the naive pnmtops  |  pstopnm,
237       the following steps will do it.
238
239           $ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm > testimg.ps
240           $ pstopnm -xborder=0 -yborder=0 -xsize=XSIZE -ysize=YSIZE \
241               -portrait -stdout -quiet testimg.ps >testimg2.ppm
242
243       XSIZE  and YSIZE above are the image dimensions, which you can get from
244       testimg.ps like in the following example (the grep, awk and  echo  com‐
245       mands  are  just  to help demonstrate how the other commands work - you
246       wouldn't use those in a program).
247
248           $ grep "BoundingBox" testimg.ps
249           %%BoundingBox: 0 0 227 149
250
251           $ awk  '/%%BoundingBox/ {print $4,$5}' testimg.ps
252            227 149
253
254           $ xysize=$(awk  '/%%BoundingBox/ {print "-xsize="$4,"-ysize="$5}' testimg.ps)
255           $ echo $xysize
256
257            -xsize=227 -ysize=149
258
259           $ pstopnm -xborder=0 -yborder=0 $xysize -portrait ... testimg.ps
260
261       Note  that  Ghostscript  bugs  can  keep  this  from  doing  a  perfect
262       reversible conversion.
263
264
265

OPTIONS

267       In  addition  to  the options common to all programs based on libnetpbm
268       (most notably -quiet, see
269        Common Options ⟨index.html#commonoptions⟩ ),  pstopnm  recognizes  the
270       following command line options:
271
272
273
274       -forceplain
275               forces  the  output  file to be in plain (text) format.  Other‐
276              wise, it is in raw (binary) format.  See pbm(1), etc.  Use  this
277              instead  of  the  -plain  common option if you need plain format
278              output.
279
280
281       -llx=bx
282              selects bx as the lower left corner x coordinate (in inches)  on
283              the  Postscript  input  page  of  the  subject  image.   See the
284              Dimensions section ⟨#dimensions⟩ .
285
286
287       -lly=by
288              selects by as the lower left corner y coordinate (in inches)  on
289              the  Postscript  input  page  of  the  subject  image.   See the
290              Dimensions section ⟨#dimensions⟩ .
291
292
293       -landscape
294              renders the image in landscape orientation.
295
296              If you specify neither -portrait nor -landscape, pstopnm chooses
297              the orientation that best fits the image on the output page.
298
299              Landscape  means  printed  sideways on the page, not printed the
300              long way.  Those are different things if the long  edge  of  the
301              page is the top one.
302
303
304       -portrait
305              renders the image in portrait orientation.
306
307              See -landscape.
308
309
310       -nocrop
311              This  option causes pstopnm to make the output image exactly the
312              dimensions of the bordered subject image.  By  default,  pstopnm
313              makes  the  output  image  the dimensions specified by -xmax and
314              -ymax.  See the Dimensions section ⟨#dimensions⟩ .
315
316
317       -pbm
318
319       -pgm
320
321       -ppm   selects the format of the output file.  By  default,  all  files
322              are rendered as PPM.
323
324
325       -stdout
326              causes  output  to  go  to Standard Output instead of to regular
327              files, one per page (see description  of  output  files  above).
328              Use pnmsplit to extract individual pages from Standard Output.
329
330
331       -urx=tx
332              selects tx as the upper right corner x coordinate (in inches) on
333              the Postscript  input  page  of  the  subject  image.   See  the
334              Dimensions section ⟨#dimensions⟩ .
335
336
337       -ury=ty
338              selects ty as the upper right corner y coordinate (in inches) on
339              the Postscript  input  page  of  the  subject  image.   See  the
340              Dimensions section ⟨#dimensions⟩ .
341
342
343
344       -verbose
345              prints processing information to stdout.
346
347
348       -xborder=frac
349              specifies  that  the left and right borders added to the subject
350              image are to be frac times the subject image width.  The default
351              value is 0.1.  See the Dimensions section ⟨#dimensions⟩ .
352
353
354
355       -xmax=xmax
356              specifies  that the output image is to be xmax pixels wide.  The
357              default is 612.  See the Dimensions section ⟨#dimensions⟩ .
358
359
360
361       -xsize=xsize
362              specifies that the output image is to be xsize pixels wide.  See
363              the Dimensions section ⟨#dimensions⟩ .
364
365
366       -yborder=frac
367              specifies  that  the top and bottom borders added to the subject
368              image are to be  frac  times  the  subject  image  height.   The
369              default  value is 0.1.  See the Dimensions section ⟨#dimensions⟩
370              .
371
372
373
374       -ymax=ymax
375              specifies that the output image is to be ymax pixels high.   The
376              default is 792.  See the Dimensions section ⟨#dimensions⟩ .
377
378
379       -ysize=ysize
380              specifies  that the output image is to be ymax pixels high.  See
381              the Dimensions section ⟨#dimensions⟩ .
382
383
384       -dpi=dpi
385              specifies the output device resolution, in dots per inch, of the
386              Postscript  printer  that pstopnm simulates.  This is the number
387              of PNM pixels pstopnm generates for each inch of image.  See the
388              Dimensions section ⟨#dimensions⟩ .
389
390              This option was new in Netpbm 10.21 (March 2004).
391
392
393       -textalphabits={1,2,4}
394              This controls subsample antialiasing of text.  Antialiasing is a
395              form of smoothing that eliminates jagged  edges  on  characters.
396              Subsample  antialiasing is a kind of antialiasing that uses sub‐
397              pixels in a box, and the value of this option  is  the  size  of
398              that  box.   4 gives you the best looking output, while 1 causes
399              no antialiasing.  Smaller numbers  make  pnmtops  use  less  CPU
400              time.
401
402              Pstopnm uses Ghostscript's TextAlphaBits parameter for this.
403
404              The default is 4.
405
406              This option was new in Netpbm 10.53 (December 2010).  Older ver‐
407              sions of pstopnm do no antialiasing.
408
409
410
411
412

LIMITATIONS

414       The program will produce incorrect results with PostScript  files  that
415       initialize  the  current  transformation  matrix.  In these cases, page
416       translation and rotation will not have any  effect.   To  render  these
417       files, probably the best bet is to use the following options:
418
419           pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps
420
421       Additional options may be needed if the document is supposed to be ren‐
422       dered on a medium different from letter-size paper.
423
424

SEE ALSO

426       gs, pnmtops(1), psidtopgm(1), pbmtolps(1),  pbmtoepsi(1),  pnmsplit(1),
427       pstofits
428
429
430
431
433       Copyright (c) 1992 Smithsonian Astrophysical Observatory
434
435       PostScript is a Trademark of Adobe Systems Incorporated.
436
437
438

AUTHOR

440       Alberto Accomazzi, WIPL, Center for Astrophysics.
441

DOCUMENT SOURCE

443       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
444       source.  The master documentation is at
445
446              http://netpbm.sourceforge.net/doc/pstopnm.html
447
448netpbm documentation           06 December 2013         Pstopnm User Manual(0)
Impressum