netpbm



User manual for Netpbm(0)                            User manual for Netpbm(0)




NAME

       netpbm - netpbm library overview



Overview Of Netpbm

       Netpbm is a package of graphics programs and a programming library.

        There  are  over  220  separate programs in the package, most of which
       have ’pbm’, ’pgm’, ’ppm’, ’pam’, or ’pnm’ in their names.  For example,
       pamscale(1)and giftopnm(1).

       For  example, you might use pamscale to shrink an image by 10%.  Or use
       pamcomp to overlay one image on top of another.  Or use pbmtext to cre-
       ate  an image of text.  Or reduce the number of colors in an image with
       pnmquant.

       Netpbm is an open source software package, distributed via the  Source-
       forge  netpbm project .



The Netpbm Programs

       The Netpbm programs are generally useful run by a person from a command
       shell, but are also designed to be used by programs.  A common  charac-
       teristic of Netpbm programs is that they are simple, fundamental build-
       ing blocks.  They are most powerful when stacked in pipelines.   Netpbm
       programs  do  not  use graphical user interfaces (in fact, none of them
       display graphics at all, except for a very simple  Linux  Svgalib  dis-
       player) and do not seek input from a user.

       Each  of  these programs has its own manual, as linked in the directory
       below.

       The Netpbm programs can read and write files greater than 2  GiB  wher-
       ever the underlying system can.  There may be exceptions where the pro-
       grams use external libraries (The JPEG library, etc.) to  access  files
       and  the  external library does not have large file capability.  Before
       Netpbm 10.15 (April 2003), no Netpbm program could  read  a  file  that
       large.


   Common Options
       There are a few options that are present on all programs that are based
       on the Netpbm library, including virtually all Netpbm programs.   These
       are not mentioned in the individual manuals for the programs.

       You can use two hyphens instead of one on these options if you like.




       -quiet   Suppress  all  informational  messages that would otherwise be
              issued to Standard Error.  (To be precise, this  only  works  to
              the  extent  that  the program in question implements the Netpbm
              convention of issuing all informational messages via the pm_mes-
              sage() service of the Netpbm library).


       -version
              Instead  of  doing anything else, report the version of the lib-
              netpbm library linked with the program (it may have been  linked
              statically into the program, or dynamically linked at run time).
              Normally, the Netpbm programs and the library are  installed  at
              the  same time, so this tells you the version of the program and
              all the other Netpbm files it uses as well.


       -plain If the program generates an image in Netpbm format, generate  it
              in  the  "plain" (aka "ascii") version of the format, as opposed
              to the "raw" (aka "binary") version.

              This option was introduced in Netpbm 10.10 (October 2002).




   Directory
       Here is a complete list of all the Netpbm programs (with links to their
       manuals):

       Netpbmprogramdirectory(1)



   How To Use The Programs
       As  a  collection of primitive tools, the power of Netpbm is multiplied
       by the power of all the other unix tools you can use with them.   These
       notes  remind  you  of some of the more useful ways to do this.  Often,
       when people want to add high level functions to the Netpbm tools,  they
       have  overlooked  some  existing tool that, in combination with Netpbm,
       already does it.

       Often, you need to apply some conversion or edit to a  whole  bunch  of
       files.

       As  a  rule, Netpbm programs take one input file and produce one output
       file, usually on Standard Output.  This is for flexibility,  since  you
       so often have to pipeline many tools together.

       Here  is an example of a shell command to convert all your of PNG files
       (named *.png) to JPEG files named *.jpg:
       for i in *.png; do pngtopnm $i | ppmtojpeg >‘basename $i .png‘.jpg; done

       Or you might just generate a stream of individual shell  commands,  one
       per  file, with awk or perl.  Here’s how to brighten 30 YUV images that
       make up one second of a movie, keeping the images in the same files:

       ls *.yuv
          | perl -ne ’chomp;
          print yuvtoppm $_ | ppmbrighten -v 100 | ppmtoyuv >tmp$$.yuv;
          mv tmp$$.yuv $_
          ’
          | sh

       The tools find (with the -exec option) and xargs are  also  useful  for
       simple manipulation of groups of files.

       Some  shells’  ’process  substitution’  facility  can help where a non-
       Netpbm program expects you to identify a disk file for  input  and  you
       want it to use the result of a Netpbm manipulation.  Say the hypotheti-
       cal program printcmyk takes the filename of a Tiff CMYK file  as  input
       and what you have is a PNG file abc.png.

       Try:
       printcmyk <({ pngtopnm abc.png | pnmtotiffcmyk ; })

       It  works  in the other direction too, if you have a program that makes
       you name its output file and you want the output to go through a Netpbm
       tool.




The Netpbm Formats

       All  of  the  programs  work  with a set of graphics formats called the
       ’netpbm’ formats.  Specifically,  these  formats  are  pbm(1),  pgm(1),
       ppm(1), and pam(1).

       The first three of these are sometimes known generically as ’pnm’.

       Many  of  the  Netpbm  programs convert from a Netpbm format to another
       format or vice versa.  This is so you can use the  Netpbm  programs  to
       work on graphics of any format.  It is also common to use a combination
       of Netpbm programs to convert from one  non-Netpbm  format  to  another
       non-Netpbm  format.   Netpbm has converters for about 100 graphics for-
       mats, and as a package Netpbm lets you do more graphics format  conver-
       sions than any other computer graphics facility.

       The  Netpbm formats are all raster formats, i.e. they describe an image
       as a matrix of rows and columns of pixels.  In the PBM format, the pix-
       els are black and white.  In the PGM format, pixels are shades of gray.
       In the PPM format, the pixels are in full color.   The  PAM  format  is
       more  sophisticated.  A replacement for all three of the other formats,
       it can represent matrices of general data including but not limited  to
       black and white, grayscale, and color images.

       Programs  designed  to  work with PBM images have ’pbm’ in their names.
       Programs designed to work with PGM, PPM, and PAM images similarly  have
       ’pgm’, ’ppm’, and ’pam’ in their names.

       All  Netpbm  programs  designed to read PGM images see PBM images as if
       they were PGM too.  All Netpbm programs designed to read PPM images see
       PGM and PBM images as if they were PPM.  See
        Implied Format Conversion .

        Programs  that  have  ’pnm’  in their names read PBM, PGM, and PPM but
       unlike ’ppm’ programs, they distinguish between them and their function
       depends  on  the  format.   For  example,  pnmtopng(1)createsablackand-
       whitePNG output image if its input is PBM or PGM, but a color PNG  out-
       put  image if its input is PPM.  And pnmrotate produces an output image
       of the same format as the  input.   A  hypothetical  ppmrotate  program
       would  also read all three PNM input formats, but would see them all as
       PPM and would always generate PPM output.

       Programs that have "pam" in their names read all  the  Netpbm  formats:
       PBM,  PGM,  PPM, and PAM.  They sometimes treat them all as if they are
       PAM, using an implied conversion, but often they recognize the individ-
       ual  formats  and  behave  accordingly, like a "pnm" program does.  See
       Implied Format Conversion .

        If it seems wasteful to you to have three  separate  PNM  formats,  be
       aware  that  there  is  a  historical reason for it.  In the beginning,
       there were only PBMs.  PGMs came later, and then PPMs.  Much later came
       PAM,  which  realizes the possibility of having just one aggregate for-
       mat.

       The formats are described in  the  specifications  of  pbm(1),  pgm(1),
       ppm(1), and pam(1).


   Implied Format Conversion
       A  program  that  uses the PGM library subroutines to read an image can
       read a PBM image as well as a PGM image.   The  program  sees  the  PBM
       image  as  if  it  were the equivalent PGM image, with a maxval of 255.
       note: This sometimes confuses people who are looking at the formats  at
       a  lower  layer  than  they  ought  to be because a zero value in a PBM
       raster means white, while a zero value in a PGM raster means black.

       A program that uses the PPM library subroutines to read  an  image  can
       read  a  PGM  image as well as a PPM image and a PBM image as well as a
       PGM image.  The program sees the PBM or PGM image as  if  it  were  the
       equivalent PPM image, with a maxval of 255 in the PBM case and the same
       maxval as the PGM in the PGM case.

       A program that uses the PAM library subroutines to read  an  image  can
       read a PBM, PGM, or PPM image as well as a PAM image.  The program sees
       a PBM image as if it were the equivalent  PAM  image  with  tuple  type
       BLACKANDWHITE.   It  sees  a PGM image as if it were the equivalent PAM
       image with tuple type GRAYSCALE.  It sees a PPM image as if it were the
       equivalent PAM image with tuple type RGB.  But the program actually can
       see deeper if it wants to.  It can tell exactly which format the  input
       was  and may respond accordingly.  For example, a PAM program typically
       produces output in the same format as its input.


   Netpbm and Transparency
       In many graphics formats, there’s a means of  indicating  that  certain
       parts of the image are wholly or partially transparent, meaning that if
       it were displayed ’over’ another image,  the  other  image  would  show
       through there.  Netpbm formats deliberately omit that capability, since
       their purpose is to be extremely simple.

       In Netpbm, you handle transparency via a transparency mask in  a  sepa-
       rate  (slightly  redefined)  PGM image.  In this pseudo-PGM, what would
       normally be a pixel’s intensity is instead an  opaqueness  value.   See
       pgm(1).   pamcomp(1)isanexampleofaprogramthatuses  a  PGM  transparency
       mask.

       Another means of representing  transparency  information  has  recently
       developed  in Netpbm, using PAM images.  In spite of the argument given
       above that Netpbm formats should be too  simple  to  have  transparency
       information built in, it turns out to be extremely inconvenient to have
       to carry the transparency information around separately.  This is  pri-
       marily  because Unix shells don’t provide easy ways to have networks of
       pipelines.  You get one input and one output from  each  program  in  a
       pipeline.   So  you’d  like  to have both the color information and the
       transparency information for an image in the  same  pipe  at  the  same
       time.

       For that reason, some new (and recently renovated) Netpbm programs rec-
       ognize  and  generate  a  PAM  image  with  tuple  type  RGB_ALPHA   or
       GRAYSCALE_ALPHA,  which  contains a plane for the transparency informa-
       tion.  See thePAMspecification(1).






The Netpbm Library

       The Netpbm programming library, libnetpbm(1),makesiteasytowriteprograms
       that manipulate graphic images.  Its main function is to read and write
       files in the Netpbm formats, and because the  Netpbm  package  contains
       converters  for all the popular graphics formats, if your program reads
       and writes the Netpbm formats, you can use it with any formats.

       But the library also contain some utility functions, such as  character
       drawing and RGB/YCrCb conversion.

       The  library has the conventional C linkage.  Virtually all programs in
       the Netpbm package are based on the Netpbm library.




netpbm-config

       In a standard installation of Netpbm, there is a program named  netpbm-
       config  in  the  regular program search path.  We don’t consider this a
       Netpbm program -- it’s just an ancillary part of a Netpbm installation.
       This  program  tells you information about the Netpbm installation, and
       is intended to be run by other programs that interface with Netpbm.  In
       fact, netpbm-config is really a configuration file, like those you typ-
       ically see in the /etc/ directory of a Unix system.

       Example:
           $netpbm-config --datadir
           /usr/local/netpbm/data

       If you write a program that needs to access a Netpbm data file, it  can
       use such a shell command to find out where the Netpbm data files are.

       netpbm-config  is  the  only  file that must be installed in a standard
       directory (it must be in a directory that is  in  the  default  program
       search path).  You can use netpbm-config as a bootstrap to find all the
       other Netpbm files.

       There is no detailed documentation of netpbm-config.  If  you’re  in  a
       position  to use it, you should have no trouble reading the file itself
       to figure out how to use it.




Other Graphics Software

       Netpbm contains primitive building blocks.  It certainly is not a  com-
       plete graphics software library.


   Graphics Viewers
       The  first  thing  you will want to make use of any of these tools is a
       viewer.  (On GNU/Linux, you can use ppmsvgalib in a pinch,  but  it  is
       pretty  limiting).   zgv  is  a  good  full  service viewer to use on a
       GNU/Linux system with the SVGALIB graphics display driver library.  You
       can  find  zgv  at  ftp://ftp.ibiblio.org/pub/Linux/apps/graphics/view-
       ers/svga .

       zgv even has a feature in it wherein you can visually crop an image and
       write an output file of the cropped image using pamcut(1).

       See the -s option to zgv.

       For the X inclined, there is also xzgv.

       xloadimage  and  its  extension  xli  are also common ways to display a
       graphic image in X.

       gqview is a more modern X-based image viewer.

       qiv is a small, very fast viewer for X.

       To play mpeg movies, such as produced by ppmtompeg, try xine .

       See ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X .


   Visual Graphics Software
       Visual graphics software is modern point-and-click software  that  dis-
       plays  an  image and lets you work on it and see the results as you go.
       This is fundamentally different from what Netpbm programs do.

       ImageMagick is like a visual version of  Netpbm.   Using  the  X/Window
       system  on  Unix, you can do basic editing of images and lots of format
       conversions.  The package does include at least some non-visual  tools.
       convert,  mogrify,  montage,  and animate are popular programs from the
       ImageMagick package.  ImageMagick runs on Unix,  Windows,  Windows  NT,
       Macintosh, and VMS.

       xv  is  a  very  old  and  very popular simple image editor in the Unix
       world.  It does not have much in the way of current support, or mainte-
       nance, though.

       The  Gimp is a visual image editor for Unix and X, in the same category
       as the more famous, less capable, and much more expensive Adobe  Photo-
       shop, etc. for Windows.  See http://www.gimp.org .

       Electric  Eyes,  kuickshow,  and gthumb are also visual editors for the
       X/Window system, and KView and gwenview are specifically for KDE.


   Programming Tools
       If you’re writing a program in C to draw and manipulate  images,  check
       out  gd  .   Netpbm  contains a C library for drawing images, but it is
       probably not as capable or documented as gd.  You can  easily  run  any
       Netpbm  program  from  a C program with the pm_system function from the
       Netpbm programming library, but that is less efficient  than  gd  func-
       tions that do the same thing.

       Ilib  is  a  C  subroutine library with functions for adding text to an
       image (as you might do at a higher level with pbmtext, pamcomp,  etc.).
       It    works    with    Netpbm   input   and   output.    Find   it   at
       http://www.radix.net/~cknudsen/Ilib .  Netpbm also  includes  character
       drawing  functions  in the libnetpbm(1)library,buttheydonothaveas fancy
       font capabilities (see ppmlabel(1) for an example of use of the  Netpbm
       character drawing functions).

       GD  is  a  library  of graphics routines that is part of PHP.  It has a
       subset of Netpbm’s functions and has been found to resize  images  more
       slowly and with less quality.


   Tools For Specific Graphics Formats
       To  create  an animated GIF, or extract a frame from one, use gifsicle.
       gifsicle converts between animated GIF and still GIF, and you  can  use
       ppmtogif  and  giftopnm to connect up to all the Netpbm utilities.  See
       http://www.lcdf.org/gifsicle .

       To convert an image of text to text (optical  character  recongition  -
       OCR), use gocr (think of it as an inverse of pbmtext).  See http://alt-
       mark.nat.uni-magdeburg.de/~jschulen/ocr/ .


       http://schaik.com/pngsuite  contains a PNG test suite -- a whole  bunch
       of PNG images exploiting the various features of the PNG format.

       Another     version     of    Netpbm’s    pnmtopng/pngtopnm    is    at
       http://www.schaik.com/png/pnmtopng.html(1).

       The version in Netpbm was actually based on that package  a  long  time
       ago,  and you can expect to find better exploitation of the PNG format,
       especially recent enhancements, in that package.  It may  be  a  little
       less  consistent  with the Netpbm project and less exploitive of recent
       Netpbm format enhancements, though.


       pngwriter  is a C++ library for creating PNG images.  With it, you plot
       an  image  pixel by pixel.  You can also render text with the FreeType2
       library.

       jpegtran Does some of the same transformations as Netpbm is famous for,
       but  does them specifically on JPEG files and does them without loss of
       information.  By contrast, if you were to use Netpbm, you  would  first
       decompress  the  JPEG image to Netpbm format, then transform the image,
       then compress it back to JPEG format.  In that recompression, you  lose
       a  little  image  information  because JPEG is a lossy compression.  Of
       course, only a few  kinds  of  lossless  transformation  are  possible.
       jpegtran comes with the Independent Jpeg Group’s ( http://www.ijg.org)
       JPEG library.

        Some tools to deal with EXIF files (see also Netpbm’s  jpegtopnm(1)and
       pnmtojpeg(1)):

       To  dump  (interpret)  an  EXIF header: Exifdump (( http://topo.math.u-
       psud.fr/~bousch/exifdump.py) ) or Jhead (  http://www.sentex.net/~mwan-
       del/jhead.  )

       A Python EXIF library and dumper: http://pyexif.sourceforge.net.

       Here’s  some software to work with IOCA (Image Object Content Architec-
       ture): ImageToolbox  ($2500, demo available).  This  can  convert  from
       TIFF -> IOCA and back again.  Ameri-Imager(1) ($40 Windows only).

       pnm2ppa  converts  to  HP’s  ’Winprinter’ format (for HP 710, 720, 820,
       1000, etc).  It is  a  superset  of  Netpbm’s  pbmtoppa   and  handles,
       notably, color.  However, it is more of a printer driver than a Netpbm-
       style  primitive   graphics   building   block.    See   http://source-
       forge.net/project/?group_id=1322 .


   Document/Graphics Software
       There  is  a large class of software that does document processing, and
       that is somewhat related to graphics because documents contain graphics
       and a page of a document is for many purposes a graphic image.  Because
       of this slight intersection with graphics, I cover document  processing
       software  here briefly, but it is for the most part beyond the scope of
       this document.

       First, we look at where Netpbm meets document processing.  pstopnm con-
       verts from Postscript and PDF to PNM.  It effectively renders the docu-
       ment into images of printed pages.  pstopnm is nothing but a convenient
       wrapper  for  Ghostscript  ,  and  in  particular  Netpbm-format device
       drivers that are part of it.  pnmtops and pbmtoepsi convert a PNM image
       to  a Postscript program for printing the image.  But to really use PDF
       and Postscript files, you generally need more complex document process-
       ing software.

       Adobe  invented Postscript and PDF and products from Adobe are for many
       purposes the quintessential Postscript and PDF tools.

       Adobe’s free Acrobat Reader displays PDF and  converts  to  Postscript.
       The  Acrobat  Reader  for unix has a program name of ’acroread’ and the
       -toPostScript option (also see the -level2 option) is useful.

       Other software from Adobe, available for purchase, interprets and  cre-
       ates  Postscript  and  PDF files.  ’Distill’ is a program that converts
       Postscript to PDF.

       xpdf  also reads PDF files.

       GSview, ghostview, gv, ggv, and kghostview are some other  viewers  for
       Postscript and PDF files.

       The  program  ps2pdf,  part of Ghostscript, converts from Postscript to
       PDF.

       Two packages that produce more kinds of  Encapsulated  Postscript  than
       the Netpbm programs, including compressed kinds, are bmeps  and imgtops
       .

       dvips converts from DVI format to Postscript.  DVI is the  format  that
       Tex  produces.   Netpbm  can convert from Postscript to PNM.  Thus, you
       can use these in combination to work with Tex/Latex  documents  graphi-
       cally.

       wvware  converts a Microsoft Word document (.doc file) to various other
       formats.  While the web page doesn’t seem to mention it, it  reportedly
       can extract an embedded image in a Word document as a PNG.

       Latex2html  converts  Latex  document  source  to HTML document source.
       Part of that involves graphics, and Latex2html uses  Netpbm  tools  for
       some  of  that.  But Latex2html through its history has had some rather
       esoteric codependencies with Netpbm.   Older  Latex2html  doesn’t  work
       with current Netpbm.  Latex2html-99.2beta8 works, though.


   Other
       The file program looks at a file and tells you what kind of file it is.
       It recognizes most of the graphics formats with which Netpbm deals,  so
       it  is  pretty handy for graphics work.  Netpbm’s anytopnm(1)programde-
       pendsonfile.  See ftp://ftp.astron.com/pub/file .

       The Utah Raster Toolkit serves a lot of the same purpose as Netpbm, but
       without  the  emphasis on format conversions.  This package is based on
       the RLE format, which you can convert to and from the  Netpbm  formats.
       http://www.cs.utah.edu/gdc/projects/urt.html(1)  gives some information
       on the Utah Raster Toolkit, but does not tell where to get it.

       Ivtools is a suite of free X Windows drawing  editors  for  Postscript,
       Tex,  and web graphics production, as well as an embeddable and extend-
       able vector  graphic  shell.   It  uses  the  Netpbm  facilities.   See
       http://www.ivtools.org .

       The  program morph morphs one image into another.  It uses Targa format
       images, but you can use tgatoppm and ppmtotga to deal with that format.
       You  have  to  use the graphical (X/Tk) Xmorph to create the mesh files
       that you must feed to morph.  morph is part of the Xmorph package.  See
       http://www.colorado-research.com/~gourlay/software/Graphics/Xmorph .



Other Graphics Formats

       People never seem to tire of inventing new graphics formats, often com-
       pletely redundant with pre-existing ones.  Netpbm cannot keep  up  with
       them.   Here  is  a  list  of a few that we know Netpbm does not handle
       (yet).

       Various commercial Windows software  handles  dozens  of  formats  that
       Netpbm  does  not,  especially formats typically used with Windows pro-
       grams.  ImageMagick is probably the most used free  image  format  con-
       verter and it also handles lots of formats Netpbm does not.




       ·       VRML (Virtual Reality Modelling Language)


       ·        CAL (originated by US Department Of Defense, favored by archi-
              tects).      http://www.landfield.com/faqs/graphics/fileformats-
              faq/part3/section-24.html(1)


       ·       array formats dx, general, netcdf, CDF, hdf, cm

       ·       CGM+

       ·        Windows  Meta File (.WMF).  Libwmf converts from WMF to things
              like Latex, PDF, PNG.  Some of these can be input to Netpbm.

       ·       Microsoft Word, RTF.  Microsoft keeps  a  proprietary  hold  on
              these  formats.   Any  software  you see that can handle them is
              likely to cost money.

       ·       DXF (AutoCAD)

       ·       IOCA (Image Object Content Architecture) The  specification  of
              this format is documented by IBM:
               Data  Stream  and  Object  Architectures:  Image Object Content
              Architecture Reference .  See above for software that  processes
              this format.


       ·      SVG.  Find out about this vector graphics format and software to
              use with it at this Worldwide Web Consortium web page .


       ·      OpenEXR   is   an   HDR   format   (like    PFM(1)).     See
              http://www.openexr.org/about.html (1).


       ·      Xv  Visual  Schnauzer  thumbnail  image.  This is a rather anti-
              quated format used by the Xv program.  In Netpbm circles, it  is
              best  known  for the fact that it is very similar to Netpbm for-
              mats and uses the same signature (’P7’) as PAM  because  it  was
              developed as sort of a fork of the Netpbm format specifications.


       ·      YUV 4:2:0, aka YUV 420, and the simlar YUV 4:4:4, YUV 4:2:2, YUV
              4:1:1, YUV 4:1:1s, and YUV 4:1:0.  Video systems often use this.





History

       Netpbm has a long history, starting with Jef Poskanzer’s Pbmplus  pack-
       age  in  1988.   The  file HISTORY in the Netpbm source code contains a
       historical overview as well as a detailed history release by release.



Author

       Netpbm is based on the Pbmplus package by  Jef  Poskanzer,  first  dis-
       tributed  in  1988  and  maintained by him until 1991.  But the package
       contains work by countless other authors, added  since  Jef’s  original
       work.   In  fact,  the  name is derived from the fact that the work was
       contributed by people all over the world via the  Internet,  when  such
       collaboration  was still novel enough to merit naming the package after
       it.

       Bryan Henderson has been maintaining Netpbm since 1999.  In addition to
       packaging  work  by others, Bryan has also written a significant amount
       of new material for the package.



netpbm documentation             15 April 2005       User manual for Netpbm(0)

Man(1) output converted with man2html