PBMBAT 1.1 (September 8, 1994) -- README

TABLE OF CONTENTS

(1) WHAT IS PBMPLUS?

(2) WHAT IS NETPBM?

(3) PROBLEM (A) HOW TO FIND THE RIGHT CONVERTER?

(4) PROBLEM (B) CREATING AND DELETING PROGRAMS 

(5) THE PBMBAT PROGRAM

***************************************************************

(1) WHAT IS PBMPLUS?

Here is an excerpt from the original README file for 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.

***************************************************************

(2) WHAT IS NETPBM?

Here is an excerpt from the original README file for NETPBM

***************************************************************

NETPBM Release 7 December 1993

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.

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 program-
mers all over the world.

***************************************************************

(3) PROBLEM (A) HOW TO FIND THE RIGHT CONVERTER?

(From the original README file for PBMPLUS)

***************************************************************

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. 

***************************************************************

(4) PROBLEM (B) CREATING AND DELETING PROGRAMS 

(From the original README.DOS file for Mike
Castle's DOS port of PBMPLUS using the djgpp compiler
(gcc/g++))

***************************************************************

On unix systems, you can do what is called a 'link' to a file.
Essentially what this does is gives the same file different
names.	When the file is an executable, the name returned by
argv[0] is what ever name you invoked it by. Some programs can
examine argv[0] and change their functionality as a result.
compress/uncompress/zcat does this. All three programs are
identical (and on many systems, the exact same file with
multiple links). Pbmplus uses this functionality to make
smaller 'merged' binaries. Instead of compiling each program
with main(), each program in compiled with filename_main(). A
dispatch program (the p?mmerge.c file) calls the appropriate
filename_main() based on what is in argv[0]. The result is you
get one binary, slightly bigger than any individual binaries,
but smaller than all of them put together becuase you are only
linking in one copy of fprintf(), one copy of fopen(), one
copy of ppm_readfile(), etc.

Now, since dos does not support links in its filesystem, you
have to result to copying to get the functionality of the
programs.

For example, if you want to take a 24-bit Targa file and
quantize it to an 8 bit gif file for viewing, you would do the
following:

copy ppmmerge.exe tgatoppm.exe

copy ppmmerge.exe ppmqvga.exe

copy ppmmerge.exe ppmtogif.exe

tgatoppm my.tga | ppmqvga | ppmtogif > my.gif

Of course, if you use a certain utility a lot, you keep that
one around. If you occasionally need a certain functionality,
you can copy the merged binary to the appropriate name, use
it, then delete it. If you want to keep the entire ppmplus
package on line, I would recommend building it yourself. 
Takes about 4 megs to keep all the stubbed exe's around. What
I do is keep unmerged copies of the files I use all the time
and the p?mmerge files. When I occasionally come across
something I don't have, I can use the merged binary. You can
usually figure out which merged binary to use by the name of
the program you want. Any program that handles multiple p?m
types will be in the higher ranking of the merged binaries.
ie, pbmtopgm is in pgmmerge, pgmtoppm is in ppmmerge, etc

****************************************************************

(5) THE PBMBAT PROGRAM

****************************************************************

The PBMBAT program solves problems (A) and (B) for you by
creating exactly the batch files you want.

EXAMPLE 1.

You want to convert the GIF file "image.gif" into the GEM file
"image.img".

You type "pbmbat giftogem image.gif image.img > xx.bat"

This creates the following batch file xx.bat:

rem xx.bat
echo giftoppm
echo ppmtopgm
echo pgmtopbm
echo pbmtogem
if exist ~pbm.? del ~pbm.?
copy ppmmerge.exe giftoppm.exe >nul
giftoppm.exe  image.gif >~pbm.0
del giftoppm.exe
copy ppmmerge.exe ppmtopgm.exe >nul
ppmtopgm.exe ~pbm.0 >~pbm.1
del ppmtopgm.exe
copy pgmmerge.exe pgmtopbm.exe >nul
pgmtopbm.exe ~pbm.1 >~pbm.0
del pgmtopbm.exe
copy pbmmerge.exe pbmtogem.exe >nul
pbmtogem.exe ~pbm.0 >~pbm.1
del pbmtogem.exe
del ~pbm.0
if exist image.img del image.img
ren ~pbm.1 image.img

This batch file can then be run and deleted. That's all!

NOTE

I always use the batch file pbm.bat to make this process
even easier:

rem pbm.bat
echo off
pbmbat.exe %1 %2 %3 %4 %5 %6 %7 %8 %9 >~pbm.bat
call ~pbm.bat
del ~pbm.bat
if not "%2"=="" goto exit
echo (%0) Usage: %0 program [arguments] outputfile
echo (%0) Example: %0 giftext "<"text.txt text.gif
echo (%0) (This command converts text.txt to text.gif)
:exit

So I simply type "pbm giftogem image.gif image.img"

EXAMPLE 2.

You want to make a pretty picture. Type:

call pbm ppmpat -squig 640 480 tempfile
call pbm ppmquant 128 tempfile tempfile 
call pbm ppmtogif tempfile pretty.gif
del tempfile

USING THE PROGRAM:

USAGE: "pbmbat program [arguments] outputfile [>batchfile]"

INPUT: atk brush cmuwm fits fs g3 gem gif gould hips icon ilbm img lispm
  macp mgr mtv pbm pcx pgm pi1 pi3 pict pj pnm ppm psid qrt rast raw
  rgb3 sld spc spu tga xbm xim xpm xwd ybm yuv                    (N=41)

OUTPUT: 10x acad ascii atk bbnbg cmuwm epson fits fs g3 gem gif go icon
  icr ilbm lispm lj macp mgr pbm pcx pgm pi1 pi3 pict pj plot pnm ppm ps
  ptx puzz rast rgb3 sixel tga uil x10bm xbm xpm xwd ybm yuv zinc (N=45)

IMAGE GENERATORS: $crater $forge $make $pat $ramp $text $upc       (N=7)
  where $ is a string from OUTPUT

FILTERS: pbmlife pbmmask pbmreduce pgmbentley pgmedge pgmenhance pgmhist
  pgmnorm pgmoil pgmtexture pnmarith pnmcat pnmcomp pnmconvol pnmcrop
  pnmcut pnmdepth pnmenlarge pnmfile pnmflip pnmgamma pnminvert pnmnoraw
  pnmpaste pnmrotate pnmscale pnmshear pnmtile ppmdither ppmhist
  ppmquant ppmqvga ppmrelief                                      (N=33)

EXAMPLES: pbmbat atkto10x pic.atk pic.10x
          pbmbat giftext "<"text.txt text.gif

(Note the quotation marks around the redirection character!)

AUTHOR

(c) Gert-Jan C. Lokhorst,
lokhorst@filint.fwb.eur.nl,
8 Sep 1994

All comments are very welcome!
