Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Pstopnm	User Manual(0)					Pstopnm	User Manual(0)

       pstopnm - convert a PostScript file to a	PNM image






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

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






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


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



       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.

       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.

       It's important to understand that pstopnm is a Netpbm image file	format
       converter only in the broadest sense of the word, because Postscript is
       far  from an image file format.	What pstopnm really is is a Postscript
       renderer	- an image generator.  One place you'll	notice the  difference
       is  where  you  expect pstopnm |	pnmtops	to be idempotent (which	is not
       the case).  There are details on	this kind of conversion	below.

       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 .psadded does.  For Standard Input, use - or just
       don't give any argument.

       If  you	use  the -stdout  option or your input is from Standard	Input,
       pstopnm outputs images of all the pages as a multi-image	file to	 Stan-
       dard  Output.  Otherwise, pstopnm creates one file for each page	in the
       Postscript input.  The files are	named as follows: If the input file is
       named,  the  name  of	 the  files will be psfile001.ppm, ps-
       file002.ppm, etc.  The filetype suffix is .ppm, .pgm, or	.pbm,  depend-
       ing  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 ps-
       file.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.

       When  your input	is from	Standard Input,	you may	feed multiple Encapsu-
       lated Postscript	documents, one after another, and pstopnm converts ev-
       ery  document  and places it in the Standard Output stream as an	image.
       But if your input is from a named file, pstopnm expects the file	to  be
       an Encapsulated Postscript file,	which means it contains	only one Enap-
       sulated Postscript document.  If	the file  contains  multiple  concate-
       nated  documents,  pstopnm  ignores every document but the first.  This
       distinction does	not exist for non-EPSF Postscript input	- pstopnm gen-
       erates an output	image for each page of the input regardless of whether
       the input is from Standard Input	or from	a named	file.

       Note that you can generate both kinds of	files -	concatenated EPSF  and
       multi-page non-EPSF - with pnmtops, selecting with the -setpage option.

       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.

       This  section  describes	 what part of the input	image gets used	in the
       output and the dimensions of the	output,	including  borders  and	 back-

       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

       The  location  of the subject image in the Postscript input page	is de-
       fined by	four numbers, the lower	left corner 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	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  In-
       put,  pstopnm does not use the BoundingBox values (because of the tech-
       nical difficulty	of extracting that information and still  feeding  the
       file  to	Ghostscript), so you either have to specify the	image area co-
       ordinates 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 re-
       gard 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 im-
       age 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 de-
       vice resolution to use, using the -dpi option.  If you say for  example
       -dpi=300	 and  the  bordered subject image is 2 inches by 3 inches, the
       PNM output will be 600 pixels by	900 pixels.  Using  this  method,  the
       output device resolution	has to be the same in both directions.

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

       In the unlikely event that you want different output device resolutions
       in  the two directions, you could use -xsize and	-ysize to do that.  In
       the above example, if you change	-ysize to 900, a  pixel	 still	repre-
       sents 1/600 inch	horizontally, but 1/300	inch vertically.

       If  you specify one of -xsize and -ysize	and not	the other, pstopnm de-
       faults the other	such that the output device resolution is the same  in
       both directions.

       The  "x"	 and "y" of -xsize and -ysize refer to the image being printed
       on the page, not	the page.  So if pstopnm prints	it in landscape	orien-
       tation,	"x"  would pertain to the vertical direction on	the page, i.e.
       the vertical direction in the output PNM	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, re-

       The final case, the default, is where you don't	specify	 any  size  or
       resolution  options or -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 accommodate the subject
       image (no borders).  Remember (above) that pstopnm trims	the  edges  of
       the bordered subject image to fit the computed output size.

   Ghostscript Limitations
       Tests  done  in	2013 with Ghostscript 8.71 indicate that Ghostscript's
       pgmraw output driver has	some kind of rounding error  that  causes  the
       pixel  values  to change	slightly, and that means pstopnm generates in-
       correct output when you have monochrome	Postscript  input.   But  with
       color Postscript	input, pstopnm uses Ghostscript's ppmraw output	driver
       and generates correct PPM output.

   Usage Notes
       There is	some good advice on converting to and from Postscript, in  the
       document	 Postcript File	Conversions" (1) by Andrew T. Young.

       Reversible Conversion

       If  you're  trying to do	the equivalent of the naive pnmtops | pstopnm,
       the following steps will	do it.

	   $ pnmtops -nocenter -equalpixels -dpi 72 -noturn testimg.ppm	>
	   $ pstopnm -xborder=0	-yborder=0 -xsize=XSIZE	-ysize=YSIZE \
	       -portrait -stdout -quiet >testimg2.ppm

       XSIZE and YSIZE above are the image dimensions, which you can get  from  like	 in the	following example (the grep, awk and echo com-
       mands are just to help demonstrate how the other	commands  work	-  you
       wouldn't	use those in a program).

	   $ grep "BoundingBox"
	   %%BoundingBox: 0 0 227 149

	   $ awk  '/%%BoundingBox/ {print $4,$5}'
	    227	149

	   $ xysize=$(awk  '/%%BoundingBox/ {print "-xsize="$4,"-ysize="$5}'
	   $ echo $xysize

	    -xsize=227 -ysize=149

	   $ pstopnm -xborder=0	-yborder=0 $xysize -portrait ...

       Note  that  Ghostscript	bugs  can  keep	 this from doing a perfect re-
       versible	conversion.

	       forces the output file to be in plain  (text)  format.	Other-
	      wise, it is in raw (binary) format.  See pbm(5), etc.

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

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

	      renders the image	in landscape orientation.

	      If you specify neither -portrait nor -landscape, pstopnm chooses
	      the orientation that best	fits the image on the output page.

	      Landscape	means printed sideways on the page,  not  printed  the
	      long  way.   Those  are different	things if the long edge	of the
	      page is the top one.

	      renders the image	in portrait orientation.

	      See -landscape.

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



       -ppm   selects  the  format  of the output file.	 By default, all files
	      are rendered as PPM.

	      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.

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

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

	      prints processing	information to stdout.

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

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

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

	      specifies	that the top and bottom	borders	added to  the  subject
	      image  are  to  be frac times the	subject	image height.  The de-
	      fault value is 0.1.  See the Dimensions section <#dimensions> .

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

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

	      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).

	      This controls subsample antialiasing of text.  Antialiasing is a
	      form of smoothing	that eliminates	jagged	edges  on  characters.
	      Subsample	 antialiasing is a kind	of antialiasing	that uses sub-
	      pixels in	a box, and the value of	this option  is	 the  size  of
	      that  box.   4 gives you the best	looking	output,	while 1	causes
	      no antialiasing.	Smaller	numbers	 make  pnmtops	use  less  CPU

	      Pstopnm uses Ghostscript's TextAlphaBits parameter for this.

	      The default is 4.

	      This option was new in Netpbm 10.53 (December 2010).  Older ver-
	      sions of pstopnm do no antialiasing.

       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

       Additional options may be needed	if the document	is supposed to be ren-
       dered on	a medium different from	letter-size paper.

       gs, pnmtops(1), psidtopgm(1), pbmtolps(1),  pbmtoepsi(1),  pnmsplit(1),

       Copyright (c) 1992 Smithsonian Astrophysical Observatory

       PostScript is a Trademark of Adobe Systems Incorporated.

       Alberto Accomazzi, WIPL,	Center for Astrophysics.

       This  manual  page was generated	by the Netpbm tool 'makeman' from HTML
       source.	The master documentation is at

netpbm documentation	       06 December 2013		Pstopnm	User Manual(0)


Want to link to this manual page? Use this URL:

home | help