pstopnm



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




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 dou-
       ble 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,
       pgmraw, 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 Output.  Otherwise,  pstopnm  creates
       one file for each page in the Postscript document.  The files are named
       as follows: 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 provide 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 pro-
       gram 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  back-
       ground.

       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 cor-
       ner  x  and  y coordinates.  These coordinates are usually specified by
       the BoundingBox DSC statement (a Postscript comment) in the  PostScript
       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 -xbor-
       der 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 techni-
       cal 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  Postscript  file,
       things  have spatial dimensions.  For example, a particular line may be
       3 centimeters long.  A Postscript printer is supposed to print the line
       3  centimeters  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 represent 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 exam-
       ple -dpi=300 and the bordered 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  resolu-
       tion,  pstopnm does some weird computation which exists mainly for his-
       torical 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 resolution, 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.  Other-
              wise, 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 Dimen-
              sions 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 Dimen-
              sions 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 subject 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 Dimen-
              sions 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 Dimen-
              sions 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 Dimensions 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 Dimensions 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 PostScript files that
       initialize the current transformation matrix.   In  these  cases,  page
       translation  and  rotation  will  not have any effect.  To render these
       files, probably 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 supposed to be ren-
       dered 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)

Man(1) output converted with man2html