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



Table Of Contents

NAME
       netpbm - netpbm library overview


Overview Of Netpbm
       Netpbm  is a package of graphics programs and a program-
       ming 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 create 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 Sourceforge  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 characteristic of Netpbm programs
       is that they are simple,  fundamental  building  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 displayer)  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  wherever the underlying system can.  There
       may  be  exceptions  where  the  programs  use  external
       libraries  (The  JPEG library, etc.) to access files and
       the external library does not have large  file  capabil-
       ity.   Before  Netpbm 10.15 (April 2003), no Netpbm pro-
       gram 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 virtu-
       ally 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 conven-
              tion of issuing all  informational  messages  via
              the  pm_message() service of the Netpbm library).


       -version
              Instead of doing anything else, report  the  ver-
              sion  of  the  libnetpbm  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 for-
              mat, 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 (Octo-
              ber 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 combi-
       nation 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 pro-
       duce 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  hypothetical  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  pro-
       gram  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 for-
       mats 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  pro-
       grams  to  convert from one non-Netpbm format to another
       non-Netpbm format.  Netpbm has converters for about  100
       graphics  formats,  and  as a package Netpbm lets you do
       more graphics format conversions 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 pixels 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)createsablackandwhitePNG  output
       image if its input is PBM or PGM, but a color PNG output
       image if its input is PPM.  And  pnmrotate  produces  an
       output  image  of the same format as the input.  A hypo-
       thetical 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 con-
       version, but often they recognize the individual 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  real-
       izes  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 equiva-
       lent PGM image, with a maxval of 255.  note: This  some-
       times  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  typi-
       cally 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 separate (slightly redefined) PGM image.  In
       this pseudo-PGM, what would normally be a pixel's inten-
       sity  is instead an opaqueness value.  See pgm(1).  pam-
       comp(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  sepa-
       rately.   This  is  primarily  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 informa-
       tion  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 recognize and generate a PAM image with
       tuple type RGB_ALPHA or GRAYSCALE_ALPHA, which  contains
       a  plane  for the transparency information.  See thePAM-
       specification(1).





The Netpbm Library
       The  Netpbm  programming   library,   libnetpbm(1),make-
       siteasytowriteprograms  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 config-
       uration file, like those you typically 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 trou-
       ble reading the file itself to figure out how to use it.



Other Graphics Software
       Netpbm contains primitive building blocks.  It certainly
       is not a complete 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 sys-
       tem  with  the  SVGALIB graphics display driver library.
       You     can     find     zgv     at      ftp://ftp.ibib-
       lio.org/pub/Linux/apps/graphics/viewers/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/view-
       ers/X .


   Visual Graphics Software
       Visual graphics software is modern point-and-click soft-
       ware  that displays an image and lets you work on it and
       see the results as you go.  This is  fundamentally  dif-
       ferent 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, Win-
       dows, 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 maintenance, 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 Photoshop, 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 functions 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 qual-
       ity.


   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://altmark.nat.uni-magde-
       burg.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/~mwandel/jhead.  )

       A Python EXIF library and dumper:  http://pyexif.source-
       forge.net.

       Here's  some  software  to  work with IOCA (Image Object
       Content Architecture): ImageToolbox  ($2500, demo avail-
       able).   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 docu-
       ment 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 process-
       ing.  pstopnm converts from Postscript and PDF  to  PNM.
       It  effectively  renders  the  document  into  images of
       printed pages.  pstopnm  is  nothing  but  a  convenient
       wrapper  for Ghostscript , and in particular Netpbm-for-
       mat 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 Post-
       script  files,  you generally need more complex document
       processing software.

       Adobe invented Postscript  and  PDF  and  products  from
       Adobe  are  for  many  purposes the quintessential Post-
       script 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 creates Postscript and PDF files.   'Dis-
       till' 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  com-
       pressed 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 combina-
       tion to work with Tex/Latex documents graphically.

       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  embed-
       ded image in a Word document as a PNG.

       Latex2html  converts Latex document source to HTML docu-
       ment  source.   Part  of  that  involves  graphics,  and
       Latex2html  uses  Netpbm  tools  for  some of that.  But
       Latex2html through its history has had some rather  eso-
       teric  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  for-
       mats  with which Netpbm deals, so it is pretty handy for
       graphics  work.   Netpbm's  anytopnm(1)programdependson-
       file.  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  conver-
       sions.   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 extendable 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 for-
       mats, often completely 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 typi-
       cally used with Windows programs.  ImageMagick is proba-
       bly  the  most  used  free image format converter and it
       also handles lots of formats Netpbm does not.




       o       VRML (Virtual Reality Modelling Language)


       o       CAL (originated by  US  Department  Of  Defense,
              favored    by    architects).    http://www.land-
              field.com/faqs/graphics/fileformats-
              faq/part3/section-24.html(1)


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

       o       CGM+

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

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

       o       DXF (AutoCAD)

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


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


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


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




History
       Netpbm has a long history, starting with Jef Poskanzer's
       Pbmplus package 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  distributed  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 contrib-
       uted by people all over the world via the Internet, when
       such collaboration was still novel enough to merit  nam-
       ing 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 2005User manual for Netpbm(0)
