N E T P B M
Release 7 December 1993

INSTALLATION
SUPPORT
HOW TO FIND THE RIGHT CONVERTER
COPYRIGHTS
[README][make][make install][ ]

Netpbm is a toolkit for conversion of images between a variety of different formats, as well as to allow a few basic image operations.
The package is intended to be portable to many platforms. It has been tested under UNIX (BSD and SYSV, e.g. SGI, Sun4, Sun386i, DEC and Apollo DN 3500), VMS and Amiga OS. There are also compiler directives in it for MS-DOS.

You'll find the latest release of Netpbm at the following sites:

* wuarchive.wustl.edu (128.252.135.4),
  directory /graphics/graphics/packages/NetPBM
* ikaros.fysik4.kth.se (130.237.35.2), directory /pub/netpbm.
* ftp.informatik.uni-oldenburg.de (134.106.1.9). This site also carries
  binaries for the Amiga.
* peipa.essex.ac.uk (155.245.115.161), directory ipa/src/manip
* ftp.rahul.net (192.160.13.1), directory /pub/davidsen/source
* ftp.cs.ubc.ca, directory /ftp/archive/netpbm

You'll also find a mirror site at the BBS:
* sixhub.tmr.com, phone +1 518 3468033, in the "source" area.
Netpbm is based on the widely spread Pbmplus package (release: 10 Dec 91).
On top of that, a lot of improvements and additions have been made. After the latest release of Pbmplus, a lot of additional filters have been circulating on the net. The aim of Netpbm was, to collect these and to turn them into a package. This work has been performed by a group of programmers all over the world. If *you* have some code to add, please contact us, and we will incorporate it. There is a mailing list for discussions about Netpbm. You post a message to the list by writing to "netpbm@fysik4.kth.se".
If you want to be on the list, send a mail with the message "subscribe netpbm" to "majordomo@fysik4.kth.se".
If you want to report a bug, please send your report to netpbm@fysik4.kth.se, and to the author of Pbmplus, jef@netcom.com.

Please note, that this is not an official Pbmplus release. The code in this release is merely a collection of code from various sources around the world. Not all of the new code parts follow the high standard of programming of Pbmplus. We have tried to make the code portable to as many systems as possible, but we haven't cleaned up all routines. We hope that this release will help the many users of Pbmplus to upgrade their code all in one piece, instead of having to hunt down different code fragments at different sites around the world. We also hope, that our effort will help the author of Pbmplus, Jef Poskanzer, to make a new official release soon.

The file Netpbm lists all new featues and functions in netpbm.

Below this line follows the original README file from Pbmplus.


Extended Portable Bitmap Toolkit
Distribution of 10dec91
Previous distribution 30oct91

PBMPLUS is a toolkit for converting various image formats to and from portable formats, and therefore to and from each other. The idea is, if you want to convert among N image formats, you only need 2*N conversion filters, instead of the N^2 you would need if you wrote each one separately.

In addition to the converters, the package includes some simple tools for manipulating the portable formats.

The package is broken up into four parts. First is PBM, for bitmaps (1 bit per pixel). Then there is PGM, for grayscale images. Next is PPM, for full-color images. Last, there is PNM, which does content-independent manipulations on any of the three internal formats, and also handles external formats that have multiple types.

The parts are upwards compatible: PGM reads both PGM and PBM files and writes PGM; PPM reads all three and writes PPM; and PNM reads all three and writes, usually, the same type as it read. Whenever PNM makes an exception and "promotes" a file to a higher format, it lets you know.

INSTALLATION
Unpack the files.
If you have the TIFF library (./libtiff) and are going to use it, copy the appropriate Makefile into place, read the comments in libtiff/README, and edit libtiff/tiffconf.h or the Makefile to reflect your compiler and options.
Decide whether you want to use Imakefiles or Makefiles. If you want to use Makefiles:

Edit the top-level Makefile, find each line with the string "CONFIGURE", and follow the directions for setting configuration options.
Likewise edit pbmplus.h.
If you are using gnu make, you have to edit *all* the Makefiles and remove all the imake stuff at the ends, otherwise gnu make will overwrite the Makefiles.

Make.
When you're happy that things compiled ok, make install.

If you want to use Imakefiles:

Edit Pbmplus.tmpl, find each line with the string "CONFIGURE", and follow the directions for setting configuration options. Likewise edit pbmplus.h.
Save the original Makefiles, in case you later want to switch back to using them.
The usual X11 sequence of xmkmf, make Makefiles, make depend, then make should work. If you have the TIFF libraries, the second step should be "make SUBDIRS='./pbm ./pgm ./ppm ./pnm' Makefiles".
When you're happy that things compiled ok, make install and make install.man.

After installing the manual pages, you may want to create the "whatis" file by doing a catman -w -M <directory>, or whatever the equivalent is on your system.
SUPPORT
I've tested this stuff under SysV and BSD, on Sun 3's 4's and 386's and Sequents and Vaxen and HPs, with cc and gcc. Nevertheless, I'm sure bugs remain, and portability to systems like Amigas and IBM compatibles is an interesting question. Feedback is welcome; send bug reports, enhancements, etc. to this address:

jef@well.sf.ca.us
apple!well!jef
When sending bug reports, always include the output from running any PBMPLUS program with the -version flag. Also include the type of system you are on, what compiler you used, and whether you are using Makefiles or Imakefiles. I try to respond to bug reports and enhancements promptly; say, within a week.

Also, if there is a new format or feature you would like to have added to the package, feel free to drop me a line. If it's a format, include whatever documentation you have, and if possible a uuencoded sample. My response time will depend on how busy I am, and how easy the job looks. If you need it right away, or it's a complicated job, you might consider paying me; lately, that's how a lot of work on the package has gotten done.

Finally, if you have access to Usenet, there's a newsgroup called alt.graphics.pixutils which is specifically for discussion of image conversion and editing packages such as PBMPLUS. Posting stuff there is even better than mailing it to me, since it lets other people help out with the answers.

HOW TO FIND THE RIGHT CONVERTER
Some people get confused by all the different names. If you want to convert a pbm file to a Sun raster file, is it pbmtorast, pgmtorast, ppmtorast, or pnmtorast? In this case some of the confusion might be because previous versions of the package did in fact have both pbmtorast and ppmtorast. But mostly it's just too many different things to hold in your short term memory. Fine, so don't even try to remember what's what. That's what computers are for. Unix, at least BSD Unix, has this great indexing feature on the "man" program. You say "man -k <keyword>" and it gives you all the one-line descriptions with that keyword in them. All the PBMPLUS man pages have nice useful one-line descriptions, that mention all the relevant keywords. Try it, you'll like it.

COPYRIGHTS
All the software in this package, whether by me or by a contributer, has a copyright similar to this one:
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty.
Many people get confused by this legalese, especially the part about "without fee". Does this mean you can't charge for any product that uses PBMPLUS? No. All it means is that you don't have to pay me.
You can do what you want with this software. Build it into your package, steal code from it, whatever. Just be sure to let people know where it came from.

CONTENTS
Files in pbmplus.shar:

    README		this
    CHANGES		list of changes between the various versions of PBM
    TODO		list of things still to be done
    FORMATS		list of the formats supported
    OTHER.SYSTEMS	list of other free image-processing software
    Makefile		guess
    Imakefile		for X11-type installations
    Imakefile.tiff	for X11-type installations
    Pbmplus.tmpl	for X11-type installations
    pbmplus.h		header file for PBM, PGM, PPM, and PNM

    compat.csh		csh script for compatibility with old versions
    compat.ksh		ksh script for compatibility with old versions
    magic		additions for /etc/magic to recognize some image formats

Files in pbm.shar?:

    Makefile		guess
    Imakefile		for X11-type installations

    atktopbm.c		convert Andrew Toolkit raster object to portable bitmap
    brushtopbm.c	convert Xerox doodle brushes to portable bitmap
    cmuwmtopbm.c	convert CMU window manager format to portable bitmap
    g3topbm.c		convert Group 3 FAX to portable bitmap
    icontopbm.c		convert Sun icon to portable bitmap
    gemtopbm.c		convert GEM .img format to portable bitmap
    macptopbm.c		convert MacPaint to portable bitmap
    mgrtopbm.c		convert MGR format to portable bitmap
    pi3topbm.c		convert Atari Degas .pi3 to portable bitmap
    xbmtopbm.c		convert X10 or X11 bitmap to portable bitmap
    ybmtopbm.c		convert Bennet Yee "face" file into portable bitmap

    pbmto10x.c		convert portable bitmap to Gemini 10x printer graphics
    pbmtoascii.c	convert portable bitmap to ASCII graphic form
    pbmtoatk.c		convert portable bitmap to Andrew Toolkit raster object
    pbmtobbnbg.c	convert portable bitmap to BBN BitGraph graphics
    pbmtocmuwm.c	convert portable bitmap to CMU window manager format
    pbmtoepson.c	convert portable bitmap to Epson printer graphics
    pbmtog3.c		convert portable bitmap to Group 3 FAX
    pbmtogem.c		convert portable bitmap into GEM .img file
    pbmtogo.c		convert portable bitmap to GraphOn graphics
    pbmtoicon.c		convert portable bitmap to Sun icon
    pbmtolj.c		convert portable bitmap to HP LaserJet graphics
    pbmtomacp.c		convert portable bitmap to MacPaint
    pbmtomgr.c		convert portable bitmap to MGR format
    pbmtopi3.c		convert portable bitmap to Atari Degas .pi3
    pbmtoplot.c		convert portable bitmap into Unix plot(5) file
    pbmtoptx.c		convert portable bitmap to Printronix graphics
    pbmtoxbm.c		convert portable bitmap to X11 bitmap
    pbmtox10bm.c	convert portable bitmap to X10 bitmap
    pbmtoybm.c		convert portable bitmap into Bennet Yee "face" file
    pbmtozinc.c		convert portable bitmap to Zinc Interface Library icon

    pbmlife.c		apply Conway's rules of Life to a portable bitmap
    pbmmake.c		create a blank bitmap of a specified size
    pbmmask.c		create a mask bitmap from a regular bitmap
    pbmreduce.c		reduce a portable bitmap N times, using Floyd-Steinberg
    pbmtext.c		render text into a bitmap
    pbmupc.c		create a Universal Product Code bitmap

    libpbm[1-5].c	a few utility routines
    pbmmerge.c		merge wrapper routine
    pbm.h		header file for libpbm
    pbmfont.h		header file for font routines in libpbm
    libpbm.h		internal header file for libpbm
    g3.h		definitions for Group 3 FAX
    macp.h		definitions for MacPaint files
    bitreverse.h	useful include file
    *.1			manual entries for all of the tools
    pbm.5		manual entry for the pbm format
    libpbm.3		manual entry for the pbm library

Files in pgm.shar?:

    Makefile		guess
    Imakefile		for X11-type installations

    fitstopgm.c		convert FITS format to portable graymap
    fstopgm.c		convert Usenix FaceSaver(tm) format to portable graymap
    hipstopgm.c		convert HIPS format to portable graymap
    lispmtopgm.c	convert a Lisp Machine bitmap file into pgm format
    psidtopgm.c		convert PostScript "image" data to portable graymap
    rawtopgm.c		convert raw grayscale bytes to portable graymap

    pgmtofits.c		convert portable graymap to FITS format
    pgmtofs.c		convert portable graymap to Usenix FaceSaver(tm) format
    pgmtolispm.c	convert a portable graymap into Lisp Machine format
    pgmtopbm.c		convert portable graymap to portable bitmap

    pgmbentley.c	Bentleyize a portable graymap
    pgmcrater.c		create cratered terrain by fractal forgery
    pgmedge.c		edge-detect a portable graymap
    pgmenhance.c	edge-enhance a portable graymap
    pgmhist.c		print a histogram of the values in a portable graymap
    pgmnorm.c		normalize contrast in a portable graymap
    pgmoil.c		turn a portable graymap into an oil painting
    pgmramp.c		generate a grayscale ramp
    pgmtexture.c	calculate textural features on a portable graymap

    libpgm[1-3].c	a few utility routines
    pgmmerge.c		merge wrapper routine
    pgm.h		header file for libpgm
    libpgm.h		internal header file for libpgm
    dithers.h		useful include file
    *.1			manual entries for all of the tools
    pgm.5		manual entry for the pgm format
    libpgm.3		manual entry for the pgm library

Files in ppm.shar?:

    Makefile		guess
    Imakefile		for X11-type installations

    giftoppm.c		convert GIF to portable pixmap
    gouldtoppm.c	convert Gould scanner file to portable pixmap
    ilbmtoppm.c		convert IFF ILBM to portable pixmap
    imgtoppm.c		convert Img-whatnot to portable pixmap
    mtvtoppm.c		convert MTV ray-tracer output to portable pixmap
    pcxtoppm.c		convert PC Paintbrush format to portable pixmap
    pgmtoppm.c		colorize a portable graymap into a portable pixmap
    pi1toppm.c		convert Atari Degas .pi1 to portable pixmap
    picttoppm.c		convert Macintosh PICT to portable pixmap
    pjtoppm.c		convert HP PaintJet file to portable pixmap
    qrttoppm.c		convert QRT ray-tracer output to portable pixmap
    rawtoppm.c		convert raw RGB bytes to portable pixmap
    rgb3toppm.c		combine three portable graymaps into one portable pixmap
    sldtoppm.c		convert an AutoCAD slide file into a portable pixmap
    spctoppm.c		convert Atari compressed Spectrum to portable pixmap
    sputoppm.c		convert Atari uncompressed Spectrum to portable pixmap
    tgatoppm.c		convert TrueVision Targa file to portable pixmap
    ximtoppm.c		convert Xim to portable pixmap
    xpmtoppm.c		convert XPM format to portable pixmap
    yuvtoppm.c		convert Abekas YUV format to portable pixmap

    ppmtoacad.c		convert portable pixmap to AutoCAD database or slide
    ppmtogif.c		convert portable pixmap to GIF
    ppmtoicr.c		convert portable pixmap to NCSA ICR graphics
    ppmtoilbm.c		convert portable pixmap to IFF ILBM
    ppmtopcx.c		convert portable pixmap to PC Paintbrush format
    ppmtopgm.c		convert portable pixmap to portable graymap
    ppmtopi1.c		convert portable pixmap to Atari Degas .pi1
    ppmtopict.c		convert portable pixmap to Macintosh PICT
    ppmtopj.c		convert portable pixmap to HP PaintJet file
    ppmtopuzz.c		convert portable pixmap to X11 "puzzle" file
    ppmtorgb3.c		separate a portable pixmap into three portable graymaps
    ppmtosixel.c	convert portable pixmap to DEC sixel format
    ppmtotga.c		convert portable pixmap to TrueVision Targa file
    ppmtouil.c		convert portable pixmap to Motif UIL icon file
    ppmtoxpm.c		convert portable pixmap to XPM format
    ppmtoyuv.c		convert portable pixmap to Abekas YUV format

    ppmdither.c		ordered dither for color images
    ppmforge.c		fractal forgeries of clouds, planets, and starry skies
    ppmhist.c		print a histogram of a portable pixmap
    ppmmake.c		create a pixmap of a specified size and color
    ppmpat.c		create a pretty pixmap
    ppmquant.c		quantize colors down to a specified number
    ppmquantall		script to run ppmquant on a set of pixmaps
    ppmrelief.c		run a Laplacian Relief filter on a portable pixmap

    libppm[1-5].c	a few utility routines
    ppmmerge.c		merge wrapper routine
    ppm.h		header file for libppm
    ppmcmap.h		header file for colormap routines in libppm
    ppmdraw.h		header file for simple drawing routines in libppm
    libppm.h		internal header file for libppm
    autocad.h		definitions for AutoCAD files
    tga.h		definitions for TrueVision Targa files
    xim.h		definitions for Xim files
    *.1			manual entries for all of the tools
    ppm.5		manual entry for the ppm format
    libppm.3		manual entry for the ppm library

Files in pnm.shar?:

    Makefile		guess
    Imakefile		for X11-type installations

    anytopnm		script to attempt to convert any format to P?M
    rasttopnm.c		convert Sun raster file to portable anymap
    tifftopnm.c		convert TIFF file to portable anymap
    xwdtopnm.c		convert X10 or X11 window dump to portable anymap

    pnmtops.c		convert portable anymap to PostScript
    pnmtorast.c		convert portable anymap to Sun raster file
    pnmtotiff.c		convert portable anymap to TIFF file
    pnmtoxwd.c		convert portable anymap to X11 window dump

    pnmarith.c		perform arithmetic on two portable anymaps
    pnmcat.c		concatenate portable anymaps
    pnmconvol.c		general MxN convolution on a portable anymap
    pnmcrop.c		crop all like-colored borders off a portable anymap
    pnmcut.c		select a rectangular region from a portable anymap
    pnmdepth.c		change the maxval in a portable anymap
    pnmenlarge.c	enlarge a portable anymap N times
    pnmfile.c		describe a portable anymap
    pnmflip.c		perform one or more flip operations on a portable anymap
    pnmgamma.c		perform gamma correction on a portable anymap
    pnmindex		script to build a visual index of a bunch of anymaps
    pnminvert.c		invert a portable anymap
    pnmmargin		script to add a margin to a portable anymap
    pnmnoraw.c		force a portable anymap into ASCII format
    pnmpaste.c		paste a rectangle into a portable anymap
    pnmrotate.c		rotate a portable anymap
    pnmscale.c		scale a portable anymap
    pnmshear.c		shear a portable anymap
    pnmsmooth		script that uses pnmconvol to smooth a anymap
    pnmtile.c		replicate a portable anymap into a specified size

    libpnm[1-4].c	a few utility routines
    pnmmerge.c		merge wrapper routine
    pnm.h		header file for libpnm
    rast.h		definitions for Sun raster files
    x10wd.h		definitions for X10 window dumps
    x11wd.h		definitions for X11 window dumps
    *.1			manual entries for all of the tools
    pnm.5		manual entry for the pnm format
    libpnm.3		manual entry for the pnm library