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

LIMITATIONS

405       The program will produce incorrect results with PostScript  files  that
406       initialize  the  current  transformation  matrix.  In these cases, page
407       translation and rotation will not have any  effect.   To  render  these
408       files, probably the best bet is to use the following options:
409
410           pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps
411
412       Additional options may be needed if the document is supposed to be ren‐
413       dered on a medium different from letter-size paper.
414
415

SEE ALSO

417       gs, pnmtops(1), psidtopgm(1), pbmtolps(1),  pbmtoepsi(1),  pnmsplit(1),
418       pstofits
419
420
421
422
424       Copyright (c) 1992 Smithsonian Astrophysical Observatory
425
426       PostScript is a Trademark of Adobe Systems Incorporated.
427
428
429

AUTHOR

431       Alberto Accomazzi, WIPL, Center for Astrophysics.
432

DOCUMENT SOURCE

434       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
435       source.  The master documentation is at
436
437              http://netpbm.sourceforge.net/doc/pstopnm.html
438
439netpbm documentation           06 December 2013         Pstopnm User Manual(0)
Impressum