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	Ghost-
       Script  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 <#dimensions>    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,	Ghost-
       script, and therefore pstopnm, produces no output.  To solve this prob-
       lem, 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	 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
	      Dimensions section <#dimensions> .


       -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 <#dimensions> .


       -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 <#dimensions> .


       -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  subject  image.   See the
	      Dimensions section <#dimensions> .


       -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 <#dimensions> .



       -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 <#dimensions> .



       -xmax=xmax
	      specifies that the output image is to be xmax pixels wide.   The
	      default is 612.  See the Dimensions section <#dimensions> .



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


       -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	 <#dimensions>
	      .



       -ymax=ymax
	      specifies	 that the output image is to be ymax pixels high.  The
	      default is 792.  See the Dimensions section <#dimensions> .


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


       -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 <#dimensions> .

	      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)