Pstopnm User Manual(0)                   Pstopnm User Manual(0)



Table Of Contents


NAME
       pstopnm - convert a PostScript file to a PNM image


SYNOPSIS
       pstopnm

       [-stdout]

       [-forceplain]

       [-help]

       [-dpi=dpi]

       [-xsize=pixels] [-ysize=pixels]

       [-xborder=frac] [-yborder=frac]

       [-landscape]

       [-portrait]

       [-nocrop]

       [-pbm

       |-pgm

       |-ppm]

       [-llx=s] [-lly=s] [-urx=s] [-ury=s]

       [-verbose]

       [-xmax=pixels] [-ymax=pixels]


       psfile[.ps]


OPTION USAGE
       Minimum  unique  abbreviation  of  option is acceptable.
       You may use double hyphens instead of single  hyphen  to
       denote options.  You may use white space in place of the
       equals sign to separate an option name from its value.


DESCRIPTION
       This program is part of Netpbm(1).

       pstopnm reads a PostScript file as  input  and  produces
       PBM,  PGM, or PPM images as output.  This program simply
       uses GhostScript to render a PostScript  file  with  its
       PNM  device  drivers.   If  you  don't  have GhostScript
       installed or the version  you  have  installed  was  not
       built with the relevant PNM device drivers, pstopnm will
       fail.  You can see if you have the proper environment by
       issuing  the  command  gs  --help  .  If it responds and
       lists under 'Available Devices' pbm, pbmraw,  pgm,  pgm-
       raw, pnm, pnmraw, ppm, or ppmraw, you're in business.

       pstopnm  uses  the  value of the GHOSTSCRIPT environment
       variable as the file name for the  Ghostscript  program.
       If  GHOSTSCRIPT  is  not set, pstopnm searches your PATH
       for a regular file named gs.  If it doesn't find one, it
       assumes Ghostscript is in the file /usr/bin/gs.

       pstopnm  does  not  use the Netpbm libraries to generate
       the output files, so may not be entirely consistent with
       most Netpbm programs.

       psfile[.ps] is the name of the input file.  pstopnm will
       add the ps to the end of the name you specify if no file
       exists by the exact name you specify, but one with added
       does.  Use - to indicate Standard Input.

       If you use the -stdout  option, pstopnm  outputs  images
       of  all the pages as a multi-image file to Standard Out-
       put.  Otherwise, pstopnm creates one file for each  page
       in the Postscript document.  The files are named as fol-
       lows: If the input file is named psfile.ps, the name  of
       the  files  will  be  psfile001.ppm, psfile002.ppm, etc.
       The filetype suffix is .ppm, .pgm, or .pbm, depending on
       which  kind  of  output  you choose with your invocation
       options.  If the input file name does not  end  in  .ps,
       the  whole  file  name  is used in the output file name.
       For example, if the input file is named psfile.old,  the
       output file name is psfile.old001.ppm, etc.

       Note that the output file selection is inconsistent with
       most Netpbm programs, because it  does  not  default  to
       Standard  Output.  This is for historical reasons, based
       on the fact that the Netpbm formats did not always  pro-
       vide for a sequence of images in a single file.

       Each  output  image  contains  a rectangular area of the
       page to which it pertains.  See the Dimensions section
       for  details  on  what part of the input image goes into
       the output image and how big it is  in  the  output  and
       what borders and margins are in the output image.

       It  has  been reported that on some Postscript Version 1
       input, Ghostscript, and therefore pstopnm,  produces  no
       output.  To solve this problem, you can convert the file
       to Postscript Version 3 with the program ps2ps.   It  is
       reported that the program pstops does not work.


   Dimensions
       This section describes what part of the input image gets
       used in the output and the  dimensions  of  the  output,
       including borders and background.

       Note  that  an  output image is associated with a single
       input page.

       pstopnm starts by taking a  rectangular  area  from  the
       input page.  That is called the subject image.

       pstopnm  may  add  borders  to the subject image to form
       what is called the bordered subject image.

       pstopnm places the bordered subject image in the  center
       of  the output image and clips the edges as necessary to
       fit the computed output image size.

       The location of the  subject  image  in  the  Postscript
       input  page  is  defined by four numbers, the lower left
       corner and the upper right corner x and  y  coordinates.
       These coordinates are usually specified by the Bounding-
       Box DSC statement (a Postscript comment)  in  the  Post-
       Script  file,  but they can be overridden by the user by
       specifying one or more of the following  options:  -llx,
       -lly, -urx, and -ury.

       The  presence  and  thickness of a border to be added to
       the subject image to form the bordered subject image  is
       controlled  by  the  options  -xborder and -yborder.  If
       pstopnm does not find a  BoundingBox  statement  in  the
       input,  and  you don't specify image area coordinates on
       the command line, pstopnm uses default values.  If  your
       input  is  from Standard Input, pstopnm does not use the
       BoundingBox values (due to the technical  difficulty  of
       extracting  that  information and still feeding the file
       to Ghostscript), so you either have to specify the image
       area coordinates or take the default.

       The  output image size is a confusing thing.  In a Post-
       script file, things have spatial dimensions.  For  exam-
       ple,  a  particular  line  may be 3 centimeters long.  A
       Postscript printer is supposed to print the line 3  cen-
       timeters  long,  using  however  many pixels that takes,
       without regard to how big the sheet of paper on which it
       is  printing  is.  In a PNM image, by contrast, there is
       no spatial dimension; there are only pixels.  You  might
       have  a  line that is 100 pixels long, but the PNM image
       says nothing about how long that line  should  be  on  a
       printed page.

       pstopnm fills the role of a Postscript printer.  The PNM
       image is a virtual printed page.  pstopnm must determine
       how  many pixels it will use in the output image to rep-
       resent an inch of input  image,  which  is  the  "output
       device  resolution."   Think of it as the number of dots
       per inch the virtual printer prints on the virtual page.

       The  simplest  thing  is for you to tell pstopnm exactly
       what output device resolution to  use,  using  the  -dpi
       option.   If  you  say for example -dpi=300 and the bor-
       dered subject image is 2 inches by  2  inches,  the  PNM
       output will be 600 pixels by 600 pixels.

       Or  you  can set the output image dimensions with -xsize
       and  -ysize.   For  example,  if  you  say   -xsize=1000
       -ysize=1000  and  the bordered subject image is 2 inches
       by 2 inches, the output image is 1000  by  1000  pixels,
       with  each pixel representing 1/500 inch of input image.

       If you specify one of -xsize  and  -ysize  and  not  the
       other,  pstopnm  defaults the other such that the output
       image has the same aspect ratio as the bordered  subject
       image.

       If  you  specify  neither the output size nor the output
       device resolution, pstopnm does some  weird  computation
       which exists mainly for historical reasons:

       If you specify -nocrop, pstopnm uses the values of -xmax
       and  -ymax  for  the  output  image  dimensions.   These
       default to 612 and 792 pixels, respectively.

       The  final case, the default, is where you don't specify
       any size or resolution options of -nocrop.  This is  the
       most  complicated  case.   In  this  case, pstopnm first
       chooses an output device resolution that would  generate
       the  number  of pixels indicated by -xmax and -ymax from
       the bordered subject image.  Then, based on that resolu-
       tion, it chooses an output image size that is just large
       enough to accomodate the  subject  image  (no  borders).
       Remember  (above)  that  pstopnm  trims the edges of the
       bordered subject image to fit the computed output  size.



OPTIONS
       -forceplain
               forces  the  output  file  to be in plain (text)
              format.  Otherwise, it is in raw (binary) format.
              See pbm(1), etc.


       -llx=bx
              selects  bx as the lower left corner x coordinate
              (in inches) on the Postscript input page  of  the
              subject image.  See the Dimensions section .


       -lly=by
              selects  by as the lower left corner y coordinate
              (in inches) on the Postscript input page  of  the
              subject image.  See the Dimensions section .


       -landscape
              renders the image in landscape orientation.


       -portrait
              renders the image in portrait orientation.


       -nocrop
              This  option  causes  pstopnm  to make the output
              image exactly the dimensions of the bordered sub-
              ject image.  By default, pstopnm makes the output
              image  the  dimensions  specified  by  -xmax  and
              -ymax.  See the Dimensions section .


       -pbm

       -pgm

       -ppm   selects  the  format  of  the  output  file.   By
              default,  all  files  are  rendered  as  portable
              pixmaps (ppm format).


       -stdout
              causes output to go to Standard Output instead of
              to regular files, one per page  (see  description
              of  output files above).  Use pnmsplit to extract
              individual pages from Standard Output.


       -urx=tx
              selects tx as the upper right corner x coordinate
              (in  inches)  on the Postscript input page of the
              subject image.  See the Dimensions section .


       -ury=ty
              selects ty as the upper right corner y coordinate
              (in  inches)  on the Postscript input page of the
              subject image.  See the Dimensions section .



       -verbose
              prints processing information to stdout.


       -xborder=frac
              specifies that the left and right  borders  added
              to  the  subject  image  are to be frac times the
              subject image width.  The default value  is  0.1.
              See the Dimensions section .



       -xmax=xmax
              specifies  that  the  output  image is to be xmax
              pixels wide.  The default is 612.  See the Dimen-
              sions section .



       -xsize=xsize
              specifies  that  the  output image is to be xsize
              pixels wide.  See the Dimensions section .


       -yborder=frac
              specifies that the top and bottom  borders  added
              to  the  subject  image  are to be frac times the
              subject image height.  The default value is  0.1.
              See the Dimensions section .



       -ymax=ymax
              specifies  that  the  output  image is to be ymax
              pixels high.  The default is 792.  See the Dimen-
              sions section .


       -ysize=ysize
              specifies  that  the  output  image is to be ymax
              pixels high.  See the Dimensions section .


       -dpi=dpi
              specifies the output device resolution,  in  dots
              per  inch, of the Postscript printer that pstopnm
              simulates.  This is  the  number  of  PNM  pixels
              pstopnm  generates  for  each inch of image.  See
              the Dimensions section .

              This option was new in Netpbm 10.21 (March 2004).





LIMITATIONS
       The  program  will  produce incorrect results with Post-
       Script files that initialize the current  transformation
       matrix.   In  these cases, page translation and rotation
       will not have any effect.  To render these files, proba-
       bly the best bet is to use the following options:

           pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps

       Additional options may be needed if the document is sup-
       posed to be rendered on a medium different from  letter-
       size paper.


SEE ALSO
       gs, pnmtops(1), psidtopgm(1), pbmtolps(1), pbmtoepsi(1),
       pnmsplit(1), pstofits




COPYRIGHT
       Copyright (c) 1992 Smithsonian Astrophysical Observatory

       PostScript is a Trademark of Adobe Systems Incorporated.



AUTHOR
       Alberto Accomazzi, WIPL, Center for Astrophysics.



netpbm documentation      28 May 2003    Pstopnm User Manual(0)
