README for cement utils.
by laura, as at 17 August, 2000

These utils will work on the following file types:
P5 (pgm): Grayscale, unsigned char (0 - 255)
P6 (ppm): Color, unsigned char (0 - 255)
P7 (pdm): Grayscale, double (0 - 255)
P8 (pdm): Color, double (0 - 255)
P9 (plm): Grayscale, double (up to max double)
PA (plm): Color, double (up to max double)

I have never come across a P[0-4], though they apparently exist out there 
somewhere.
P[5,6] are generally known as PNMs, P[7,8] are PDMs, P[9,A] are PLMs.
Some of these utils work with jpegs, some don't, so you'll have to experiment.

pnms are converted to plms by raising to some exponent. This corrects for 
the intrinsic non-linearity in the camera response function, and allows a 
greater dynamic range. The exponent depends on the reponse function of the 
camera used to generate the image, and the plms generated using a well 
chosen exponent should be compatible with one another despite have different 
exponents. 

However, plms generated with arbitrary exponents will probably not be 
compatible. One future task is to find some way of converting images 
made up of plms with differing, arbitrary exponents.

The cement tools rely on a lookup tables (lut) to convert between plm 
and pnm format. The lut corresponding to the correct exponent must be 
used if you don't want to get junk. So before cementing, create the 
necessary lut with "makeLookup".


DEFAULT EXPONENT: This is defined in cement.h. If no exponent is 
specified in the file or in command line args, this is used. So it is 
particularly important that the lut for this exponent has been generated
using makeLookup.


MAKELOOKUP: Creates a lookup table with a particular exponent (eg: 
powLookup??.txt). If no command line args, it uses the default exponent. 
To specify an exponent, enter a two-digit number as a command line arg.
Leave out the decimal point.
eg "makeLookup 22"   	creates a lut called powLookup22.txt with exponent 2.2
   "makeLookup"		creates powLookup??.txt with default exponent.


CEMENTINIT: Converts pnms to plms. If you don't specify an exponent or 
lut file using the -lut option, the default exponent will be used. 
"cementinit" for usage.


PLM2PNM: Converts plms to pnms. The exponent is taken from the header of 
the plm file. If the lut for that exponent doesn't exist, the prog will 
crash or behave erratically.
"plm2pnm" for usage.


PNM2PDM: Converts pnms to pdms. No exponents here, so the conversion is
nice and simple.
"pnm2pdm" for usage.


PDM2PNM: Ditto.
"pdm2pnm" for usage.


******* Note for conversion utils ******* 
If you get yucky output files, the first things to check are the exponent 
and lut. Does the lut exist? Is there a conflict between lut and exponent?


CEMENTI: This cements a pnm into a plm. The exponent used in the pgm
conversion is the same as the exponent in the plm. Again, the lut for that 
exponent must exist. The RGB values specify the color of the image that is 
cemented in. The plm you enter as the first arg will be altered, although it 
can be reverted using cemento. You end up with two superimposed images in the 
same plm image file.
"cementi" for usage.


CEMENTO: This removes a pgm from a plm. Uses the same exponent as in the
plm. Will change the first arg, the plm. 
Check the image header to find the cementi calls that resulted in this 
image, and the RGB values used on each call. 
"cemento" for usage.