Pnmtops User Manual(0)					Pnmtops User Manual(0)



NAME
       pnmtops - convert PNM image to PostScript


SYNOPSIS
       pnmtops	 [-scale=s]   [-dpi=N[xN]]   [-imagewidth=n]  [-imageheight=n]
       [-width=N] [-height=N] [-equalpixels] [-turn|-noturn] [-rle|-runlength]
       [-flate]	 [-ascii85]  [-nocenter]  [-nosetpage]	[-level=N] [-psfilter]
       [-noshowpage] [pnmfile]

       All options can be abbreviated to their shortest	 unique	 prefix.   You
       may  use	 two  hyphens instead of one.  You may separate an option name
       and its value with white space instead of an equals sign.


DESCRIPTION
       This program is part of Netpbm(1).

       pnmtops reads a Netpbm image stream as input and produces  Encapsulated
       PostScript (EPSF) as output.

       If  the	input  file is in color (PPM), pnmtops generates a color Post-
       Script file.  Some PostScript interpreters  can't  handle  color	 Post-
       Script.	 If  you  have	one  of	 these you will need to run your image
       through ppmtopgm first.

       If you specify no output dimensioning  options,	the  output  image  is
       dimensioned  as	if  you	 had specified -scale=1.0, which means aproxi-
       mately 72 pixels of the input image generate one	 inch  of  output  (if
       that fits the page).

       Use  -imagewidth,  -imageheight,	 -equalpixels,	-width,	 -height,  and
       -scale to adjust that.

       Each image in the input stream becomes one complete one-page Postscript
       program	in  the	 output.   (This  may  not be the best way to create a
       multi-page Postscript stream; someone who knows Postscript should  work
       on this).

       The  line  at  the top of the file produced by pnmtops is either '%!PS-
       Adobe-3.0 EPSF-3.0' or  just  '%!PS-Adobe-3.0'.	 The  numbers  do  not
       reflect	the Postscript language level, but the version of the DSC com-
       ment specification and EPS specification	 implmented.   The  Postscript
       language	 level	is  in	the "%%LanguageLevel:" comment.	 pnmtops omits
       "EPSF-3.0" if you specify -setpage, because it is  incorrect  to	 claim
       EPS compliance if the file uses setpagedevice.



   What is Encapsulated Postscript?
       Encapsulated  Postscript (EPSF) is a subset of Postscript (i.e. the set
       of streams that conform to EPSF is a subset of those  that  conform  to
       Postscript).   It is designed so that an EPSF stream can be embedded in
       another Postscript stream.  A typical reason to do  that	 is  where  an
       EPSF stream describes a picture you want in a larger document.

       An  Encapsulated	 Postscript  document  conforms	 to  the DSC (Document
       Structuring Convention).	 The  DSC  defines  some  Postscript  comments
       (they're	 comments  from	 a Postscript point of view, but have semantic
       value from a DSC point of view).

       More   information   about   Encapsulated    Postscript	  is	at
       http://www.cs.indiana.edu/docproject/programming/postscript/eps.html
       (1).

       Many of the ideas in pnmtops come from Dirk Krause's  bmeps.   See  SEE
       ALSO <#seealso>


OPTIONS
       -imagewidth, -imageheight
	      Tells  how  wide	and  high  you	want the image on the page, in
	      inches.  The aspect ratio of the image is preserved, so  if  you
	      specify both of these, the image on the page will be the largest
	      image that will fit within the box of those dimensions.

	      If these dimensions are greater than  the	 page  size,  you  get
	      Postscript output that runs off the page.

	      You   cannot  use	 imagewidth  or	 imageheight  with  -scale  or
	      -equalpixels.


       -equalpixels
	      This option causes the output image to have the same  number  of
	      pixels  as  the input image.  So if the output device is 600 dpi
	      and your image is 3000 pixels wide, the output image would be  5
	      inches wide.

	      You  cannot  use -equalpixels with -imagewidth, -imageheight, or
	      -scale.


       -scale tells how big you want the image on the page.  The value is  the
	      number  of inches of output image that you want 72 pixels of the
	      input to generate.

	      But pnmtops  rounds the number to something that is an  integral
	      number  of  output  device pixels.  E.g. if the output device is
	      300 dpi and you specify -scale=1.0, then 75 (not 72)  pixels  of
	      input becomes one inch of output (4 output pixels for each input
	      pixel).  Note that the -dpi option tells pnmtops how many pixels
	      per inch the output device generates.

	      If  the  size so specified does not fit on the page (as measured
	      either by the -width and -height options	or  the	 default  page
	      size  of	8.5  inches  by 11 inches), pnmtops ignores the -scale
	      option, issues a warning, and scales the image  to  fit  on  the
	      page.


       -dpi=N[xN]

	      This  option specifies the dots per inch resolution of your out-
	      put device.  The default is 300 dpi.  In	theory	PostScript  is
	      device-independent  and  you don't have to worry about this, but
	      in practice its raster rendering can have unsightly bands if the
	      device pixels and the image pixels aren't in sync.

	      Also  this  option  is crucial to the working of the equalpixels
	      option.

	      If you specify NxN, the first number is the  horizontal  resolu-
	      tion  and	 the second number is the vertical resolution.	If you
	      specify just a single number N, that is the resolution  in  both
	      directions.


       -width, -height
	       These options specify the dimensions, in inches, of the page on
	      which the output is to be printed.  This can affect the size  of
	      the output image.

	      The  page	 size  has  no	effect,	 however, when you specify the
	      -imagewidth, -imageheight, or -equalpixels options.

	      These options may also affect positioning of the	image  on  the
	      page and even the paper selected (or cut) by the printer/plotter
	      when the output is printed.  See the -nosetpage option.

	      The default is 8.5 inches by 11 inches.


       -turn


       -noturn
	      These options control whether the image gets turned 90  degrees.
	      Normally, if an image fits the page better when turned (e.g. the
	      image is wider than it is tall, but the page is taller  than  it
	      is  wide),  it gets turned automatically to better fit the page.
	      If you specify the -turn option, pnmtops	 turns	the  image  no
	      matter  what its shape; If you specify -noturn, pnmtops does not
	      turn it no matter what its shape.


       -rle


       -runlength
	      These identical options tell pnmtops to use run length  compres-
	      sion  in encoding the image in the Postscript program.  This may
	      save time if the host-to-printer link is slow; but normally  the
	      printer's	 processing time dominates, so -rle has no effect (and
	      in the absence of buffering, may make things slower).

	      This may, however,  make	the  Postscript	 program  considerable
	      smaller.

	      This  usually doesn't help at all with a color image and -psfil-
	      ter, because in that case, the Postscript program	 pnmtops  cre-
	      ates  has	 the  red,  green,  and	 blue  values  for  each pixel
	      together, which means you would see long runs of identical bytes
	      only  in the unlikely event that the red, green, and blue values
	      for a bunch of adjacent pixels are all the  same.	  But  without
	      -psfilter,  the  Postscript program has all the red values, then
	      all the green values, then all the blue  values,	so  long  runs
	      appear wherever there are long stretches of the same color.


       -flate This  option tells pnmtops to use 'flate' compression (i.e. com-
	      pression via the 'Z' library -- the same as PNG).

	      See the -rle option for information about	 compression  in  gen-
	      eral.

	      You must specify -psfilter if you specify -flate.

	      This option was new in Netbpm 10.27 (March 2005).

	      Before  Netpbm 10.32 (February 2006), you could not specify -rle
	      and -flate together.

	      This sometimes produces what is probably an incorrect  image  --
	      one  that	 is  missing  the  lower  rows.	 This appears to be an
	      implementation problem in the flate  compressor,	but  we	 don't
	      know  what it is.	 We also don't know on which images it has the
	      problem.	(January 2007).	 We provide an example <flatebug.png>
	      of  an  image  with  which  pnmtops appears to have the problem.
	      (Convert it to PGM with pngtopam and feed that to pnmtops).


       -ascii85
	      By default,  pnmtops  uses  'asciihex'  encoding	of  the	 image
	      raster.	The  image  raster  is a stream of bits, while a Post-
	      script program is text, so there has to be an encoding from bits
	      to  text.	 Asciihex encoding is just the common hexadecimal rep-
	      resentation of bits.  E.g. 8 1 bits would be encoded as the  two
	      characters 'FF'.

	      With  the	 -ascii85  option,  pnmtops  uses  'ascii85'  encoding
	      instead.	This is an encoding in which 32 bits are encoded  into
	      five  characters	of  text.  Thus, it produces less text for the
	      same raster than asciihex.  But  ascii85	is  not	 available  in
	      Postscript Level 1, whereas asciihex is.

	      This option was new in Netbpm 10.27 (March 2005).


       -psfilter
	      pnmtops  can  generate two different kinds of Encapsulated Post-
	      script programs to represent an image.  By default, it generates
	      a	 program  that	redefines  readstring  in  a custom manner and
	      doesn't rely on any built-in Postscript filters.	But  with  the
	      -psfilter	 option,  pnmtops leaves readstring alone and uses the
	      built-in	Postscript  filters  /ASCII85Decode,  /ASCIIHexDecode,
	      /RunLengthDecode, and /FlateDecode.

	      This  option was new in Netbpm 10.27 (March 2005).  Before that,
	      pnmtops always used the custom readstring.

	      The custom code can't do flate or ascii85 encoding, so you  must
	      use -psfilter if you want those (see -flate, -ascii85).


       -level This  option determines the level (version number) of Postscript
	      that pnmtops uses.  By default, pnmtops uses Level 2.  Some fea-
	      tures of pnmtops are available only in higher Postscript levels,
	      so if you specify too low	 a  level  for	your  image  and  your
	      options,	pnmtops fails.	For example, pnmtops cannot do a color
	      image in Level 1.

	      This option was new in Netpbm 10.27 (March 2005).	 Before	 that,
	      pnmtops always used Level 2.


       -dict  This causes the Postscript program create a separated dictionary
	      for its local variables and remove  it  from  the	 stack	as  it
	      exits.

	      This option was new in Netbpm 10.27 (March 2005).


       -vmreclaim
	      This  option  causes  the	 Postscript  program to force a memory
	      garbage collection as it exits.

	      This option was new in Netbpm 10.27 (March 2005).


       -nocenter
		   By default, pnmtops centers the image on the output page.
		   You can cause pnmtops to instead put the image against the
		   lower left corner of the page with the -nocenter
		   option.  This is useful for programs which can include
		   PostScript files, but can't cope with  pictures  which  are
	      not
		   positioned in the lower left corner.

		   For backward compatibility, pnmtops accepts the option
		   -center, but it has no effect.


       -setpage
		   This causes pnmtops to include a 'setpagedevice'
		   directive in the output.  This causes the output to violate
	      specifications
		   of EPSF encapsulated Postscript, but if you're not using it
	      in an
		   encapsulated	 way,  may  be	what  you need.	 The directive
	      tells the
		   printer/plotter what size  paper  to	 use  (or  cut).   The
	      dimensions it
		   specifies on this directive are those selected by the
		   -width and -height options or defaulted.

	      From January through May 2002, the default was to include
		   'setpagedevice' and this option did not exist.  Before
		   January 2002, there was no way to include 'setpagedevice'
		   and neither the -setpage nor -nosetpage option existed.


       -nosetpage
		   This tells pnmtops not to include a 'setpagedevice'
		   directive  in  the  output.	 This  is  the default, so the
	      option has no
		   effect.

	      See the -setpage option for the history of this option.


       -noshowpage
		   This tells pnmtops not to include a 'showpage'
		   directive in the output.  By default, pnmtops includes a
		   'showpage' at the end of the EPSF program  According to
		   EPSF specs, this is OK, and the program that	 includes  the
	      EPSF is
		   supposed  to	 redefine showpage so this doesn't cause unde-
	      sirable
		   behavior.  But it's often easier just not to have the show-
	      page.

	      This options was new in Netpbm 10.27 (March 2005).  Earlier
		   versions of pnmtops always include the showpage.


       -showpage
		  This tells pnmtops to include a 'showpage' directive
		  at  the end of the EPSF output.  This is the default, so the
	      option has
		  no effect.

	      This option was new in Netpbm 10.27 (March 2005).





LIMITATIONS
       If the PNM image has a maxval greater than 255,	pnmtops	 will  produce
       output  with 8 bits per sample resolution unless you specify -psfilter,
       even though Postscript Level 2 has a 12 bits per sample	format.	  pnm-
       tops's  custom raster-generating code just doesn't know the 12 bit for-
       mat.



SEE ALSO
       Postscript is described in the  Postscript  Language  Reference	Manual
       <http://www.adobe.com/products/postscript/pdfs/PLRM.pdf> .

       bmeps  <http://bmeps.sourceforge.net>	converts from Netpbm and other
       formats to Encapsulated Postscript.  It is suitable for hooking	up  to
       dvips  so  you  can  include  an image in a Latex document just with an
       \includegraphics directive.

       bmeps has a few functions pnmtops does not,  such  as  the  ability  to
       include a transparency mask in the Postscript program (but not from PAM
       input -- only from PNG input).

       pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1),  pbmtoepsi(1),  pbm-
       topsg3(1), ppmtopgm(1),


AUTHOR
       Copyright (C) 1989, 1991 by Jef Poskanzer.

       Modified	  November   1993   by	Wolfgang  Stuerzlinger,	 wrzl@gup.uni-
       linz.ac.at



netpbm documentation		21 January 2007		Pnmtops User Manual(0)