                  Extended Portable Bitmap Toolkit
                 BETA TEST distribution of 05feb91
                   Previous distribution 25jan91


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 (five parts if you count this
one, the zeroth part).  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 write 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.

The parts are also semi-independent; if you're only going to deal with
bitmaps, you don't have to install PGM and PPM, and this makes PNM run
faster; if you want PGM, you must install PBM but can leave PPM out;
but if you want PPM, you must install both PGM and PBM.  PNM is
optional but recommended.


INSTALLATION

    Unpack the files.
    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.
	Likewise edit pnm/Makefile.
	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 work ok, make install.
    
    If you want to use Imakefiles instead:

	Edit the top-level Imakefile, find each line with the string
	  "CONFIGURE", and follow the directions for setting configuration
	  options.
	Likewise edit pbmplus.h.
	Likewise edit pnm/Imakefile.
	Edit Makefile and */Makefile, look towards the end for the
	  definition of TOP, and change it to point to your X11 tree.
	Save the original Makefiles, in case you later want to switch back
	  to using them.
	Touch Imakefile, since you just editted Makefile.
	Make Makefile, make Makefiles, make depend, then make.
	When you're happy that things work ok, make install.

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, ucbvax, hplabs}!well!jef

When sending bug reports, be sure to mention what version you have (see
the head of this file), what system you are on, and what compiler you
used.  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.


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
    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
    LIBTIFF.PATCH	patch file with a minor but necessary change for libtiff

Files in pbm.shar?:

    Makefile		guess
    Imakefile		for X11-type installations

    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
    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
    pbmpaste.c		paste a rectangle into a portable 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
    pgmtops.c		convert portable graymap to Encapsulated PostScript

    pgmbentley.c	Bentleyize a portable graymap
    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

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

    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
    ppmtops.c		convert portable pixmap to color Encapsulated PostScript
    ppmtopuzz.c		convert portable pixmap to X11 "puzzle" file
    ppmtorgb3.c		separate a portable pixmap into three portable graymaps
    ppmtouil.c		convert portable pixmap to Motif UIL icon file
    ppmtoxpm.c		convert portable pixmap to XPM format

    ppmhist.c		print a histogram of a portable pixmap
    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
    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

    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
