pnmtops



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
       PostScript file.   Some  PostScript  interpreters  can’t  handle  color
       PostScript.   If  you have one of these you will need to run your image
       through ppmtopgm first.

       pnmotps produces Level 2 Postscript.  (i.e. the line it places  at  the
       top of the file to indicate the version is ’%%!PS-Adobe-2.0 EPSF-2.0’).

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


   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



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  may not use this option together with -rle.  You must spec-
              ify -psfilter if you specify -flate.

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


       -ascii85
              By default, pnmtops uses ’asciihex’ encoding of the sample  val-
              ues in the image raster.  E.g. it would encode the number twenty
              as the two characters ’14’.  (Note that a Postscript program  is
              composed of text, so the numbers that make up the raster have to
              be encoded into text somehow).

              With  the  -ascii85  option,  pnmtops  uses  ’ascii85’  encoding
              instead.  I don’t know what that is, but it appears to be a code
              in which a byte is represented by 5 odd characters.  I can’t see
              how this could be preferable to asciihex.

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


       -psfilter
              pnmtops   can  generate  two  different  kinds  of  Encapsulated
              Postscript programs to represent an image.  By default, it  gen-
              erates  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
                   upper 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 upper 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).





       bmeps    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             07 March 2005          Pnmtops User Manual(0)

Man(1) output converted with man2html