Man Pages

pstopnm(1) - phpMan pstopnm(1) - phpMan

Command: man perldoc info search(apropos)  


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 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, 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 Out-
       put.  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 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  cor-
       ner and the upper right corner 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 specify-
       ing 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 Postscript 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 deter-
       mine 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 example -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 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 resolution,
       it chooses an output image size that is just large enough to accomodate the subject image (no borders).  Remem-
       ber (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  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 PPM.


       -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 sub-
              ject 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  sub-
              ject 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 Dimensions sec-
              tion .



       -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 sec-
              tion .


       -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 simu-
              lates.  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, 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 supposed 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)