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, ps‐
90       file002.ppm, etc.  The filetype suffix is .ppm, .pgm, or .pbm,  depend‐
91       ing  on  which  kind of output you choose with your invocation options.
92       If the input file name does not end in .ps, the whole file name is used
93       in  the  output file name.  For example, if the input file is named ps‐
94       file.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 ev‐
103       ery  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 de‐
144       fined by four numbers, the lower left corner and the upper right corner
145       x  and  y  coordinates.  These coordinates are usually specified by the
146       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  In‐
155       put,  pstopnm does not use the BoundingBox values (because of the tech‐
156       nical difficulty of extracting that information and still  feeding  the
157       file  to Ghostscript), so you either have to specify the image area co‐
158       ordinates 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 re‐
164       gard 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 im‐
167       age says nothing about how long that line should be on a printed page.
168
169       pstopnm  fills  the  role  of a Postscript printer.  The PNM image is a
170       virtual printed page.  pstopnm must determine how many pixels  it  will
171       use  in  the output image to represent an inch of input image, which is
172       the "output device resolution."  Think of it as the number of dots  per
173       inch the virtual printer prints on the virtual page.
174
175       The  simplest  thing is for you to tell pstopnm exactly what output de‐
176       vice resolution to use, using the -dpi option.  If you say for  example
177       -dpi=300  and  the  bordered subject image is 2 inches by 3 inches, the
178       PNM output will be 600 pixels by 900 pixels.  Using  this  method,  the
179       output device resolution has to be the same in both directions.
180
181       Or you can set the output image dimensions with -xsize and -ysize.  For
182       example, if you say -xsize=1200 -ysize=1800 and  the  bordered  subject
183       image  is  2  inches wide by 3 inches high, the output image is 1200 by
184       1800 pixels, with each pixel representing 1/600 inch of input image.
185
186       In the unlikely event that you want different output device resolutions
187       in  the two directions, you could use -xsize and -ysize to do that.  In
188       the above example, if you change -ysize to 900, a  pixel  still  repre‐
189       sents 1/600 inch horizontally, but 1/300 inch vertically.
190
191       If  you specify one of -xsize and -ysize and not the other, pstopnm de‐
192       faults the other such that the output device resolution is the same  in
193       both directions.
194
195       The  "x"  and "y" of -xsize and -ysize refer to the image being printed
196       on the page, not the page.  So if pstopnm prints it in landscape orien‐
197       tation,  "x"  would pertain to the vertical direction on the page, i.e.
198       the vertical direction in the output PNM image.
199
200       If you specify neither the output size nor the  output  device  resolu‐
201       tion,  pstopnm does some weird computation which exists mainly for his‐
202       torical reasons:
203
204       If you specify -nocrop, pstopnm uses the values of -xmax and -ymax  for
205       the  output image dimensions.  These default to 612 and 792 pixels, re‐
206       spectively.
207
208       The final case, the default, is where you don't  specify  any  size  or
209       resolution  options or -nocrop.  This is the most complicated case.  In
210       this case, pstopnm first chooses an output device resolution that would
211       generate  the  number  of  pixels indicated by -xmax and -ymax from the
212       bordered subject image.  Then, based on that resolution, it chooses  an
213       output  image size that is just large enough to accommodate the subject
214       image (no borders).  Remember (above) that pstopnm trims the  edges  of
215       the bordered subject image to fit the computed output size.
216
217
218
219   Ghostscript Limitations
220       Tests  done  in  2013 with Ghostscript 8.71 indicate that Ghostscript's
221       pgmraw output driver has some kind of rounding error  that  causes  the
222       pixel  values  to change slightly, and that means pstopnm generates in‐
223       correct output when you have monochrome  Postscript  input.   But  with
224       color Postscript input, pstopnm uses Ghostscript's ppmraw output driver
225       and generates correct PPM output.
226
227
228
229   Usage Notes
230       There is some good advice on converting to and from Postscript, in  the
231       document  Postcript File Conversions" (1) by Andrew T. Young.
232
233       Reversible Conversion
234
235       If  you're  trying to do the equivalent of the naive pnmtops | pstopnm,
236       the following steps will do it.
237
238           $ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm > testimg.ps
239           $ pstopnm -xborder=0 -yborder=0 -xsize=XSIZE -ysize=YSIZE \
240               -portrait -stdout -quiet testimg.ps >testimg2.ppm
241
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
262       Note  that  Ghostscript  bugs  can  keep  this from doing a perfect re‐
263       versible conversion.
264
265
266

OPTIONS

268       In addition to the options common to all programs  based  on  libnetpbm
269       (most notably -quiet, see
270        Common  Options  ⟨index.html#commonoptions⟩  ), pstopnm recognizes the
271       following command line options:
272
273
274
275       -forceplain
276               forces the output file to be in plain  (text)  format.   Other‐
277              wise,  it is in raw (binary) format.  See pbm(1), etc.  Use this
278              instead of the -plain common option if  you  need  plain  format
279              output.
280
281
282       -llx=bx
283              selects  bx as the lower left corner x coordinate (in inches) on
284              the Postscript  input  page  of  the  subject  image.   See  the
285              Dimensions section ⟨#dimensions⟩ .
286
287
288       -lly=by
289              selects  by as the lower left corner y coordinate (in inches) on
290              the Postscript  input  page  of  the  subject  image.   See  the
291              Dimensions section ⟨#dimensions⟩ .
292
293
294       -landscape
295              renders the image in landscape orientation.
296
297              If you specify neither -portrait nor -landscape, pstopnm chooses
298              the orientation that best fits the image on the output page.
299
300              Landscape means printed sideways on the page,  not  printed  the
301              long  way.   Those  are different things if the long edge of the
302              page is the top one.
303
304
305       -portrait
306              renders the image in portrait orientation.
307
308              See -landscape.
309
310
311       -nocrop
312              This option causes pstopnm to make the output image exactly  the
313              dimensions  of  the bordered subject image.  By default, pstopnm
314              makes the output image the dimensions  specified  by  -xmax  and
315              -ymax.  See the Dimensions section ⟨#dimensions⟩ .
316
317
318       -pbm
319
320       -pgm
321
322       -ppm   selects  the  format  of the output file.  By default, all files
323              are rendered as PPM.
324
325
326       -stdout
327              causes output to go to Standard Output  instead  of  to  regular
328              files,  one  per  page  (see description of output files above).
329              Use pnmsplit to extract individual pages from Standard Output.
330
331
332       -urx=tx
333              selects tx as the upper right corner x coordinate (in inches) on
334              the  Postscript  input  page  of  the  subject  image.   See the
335              Dimensions section ⟨#dimensions⟩ .
336
337
338       -ury=ty
339              selects ty as the upper right corner y coordinate (in inches) on
340              the  Postscript  input  page  of  the  subject  image.   See the
341              Dimensions section ⟨#dimensions⟩ .
342
343
344
345       -verbose
346              prints processing information to stdout.
347
348
349       -xborder=frac
350              specifies that the left and right borders added to  the  subject
351              image are to be frac times the subject image width.  The default
352              value is 0.1.  See the Dimensions section ⟨#dimensions⟩ .
353
354
355
356       -xmax=xmax
357              specifies that the output image is to be xmax pixels wide.   The
358              default is 612.  See the Dimensions section ⟨#dimensions⟩ .
359
360
361
362       -xsize=xsize
363              specifies that the output image is to be xsize pixels wide.  See
364              the Dimensions section ⟨#dimensions⟩ .
365
366
367       -yborder=frac
368              specifies that the top and bottom borders added to  the  subject
369              image  are  to  be frac times the subject image height.  The de‐
370              fault value is 0.1.  See the Dimensions section ⟨#dimensions⟩ .
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
422       Additional options may be needed if the document is supposed to be ren‐
423       dered on a medium different from letter-size paper.
424
425

SEE ALSO

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

AUTHOR

441       Alberto Accomazzi, WIPL, Center for Astrophysics.
442

DOCUMENT SOURCE

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