Help for COLORME

PURPOSE:
To convert uncalibrated rgb images into rgb images whose mean color is 
specified via a parameter.

EXECUTION:
typically:
colorme inp=(r,g,b) out=(ro,go,bo) device=alps monitor=left xyy=(.44,.4,35.)
or:
colorme inp=(r,b) out=(ro,go,bo) device=alps monitor=left xyy=(.44,.4,35.)
or:
colorme inp=(g) out=(ro,go,bo) device=alps monitor=left xyy=(.44,.4,35.)

WARNING:
The program lists the number of saturations. Every saturated pixel
is adjusted down in intensity to preserve the initial color balance.
To avoid this reduce the target Y tristimulus value (the
third value you specified with the XYY keyword) and try it again.
Y represents the scene brightness. 


METHOD:
   The program first computes the mean input rgb values above zero.
It then computes the target rgb values which resulted from the 
desired parameter xyY color for the specified device.
It then computes linear factors mapping the input dn's to the output such
that the mean input rgb's map to the target rgb's.

   The program reads in a calibration file for the specified device. This is 
an ascii file with data in records like this:
STEP#                Yn      x       y       R-DN    G-DN    B-DN
1               0.122616  0.278170  0.298730   0.0   0.0   0.0
2               1.267030  0.595390  0.329050  64.0   0.0   0.0
3               5.354223  0.627000  0.332000  128.0   0.0   0.0
4               12.874659  0.632610  0.333000  192.0   0.0   0.0

The first 3 records are skipped by the program so the first record read is:
1               0.122616  0.278170  0.298730   0.0   0.0   0.0

These correspond to a calibration giving the xyY values for a data cube of
all combinations of rgb dn values in some coarse interval like 32 or 64
dn steps. The file must end with a .2

   The method used is to create a 40 by 40 by 40 cube in Luv coordinates
spanning the range of xyY values in the calibration file. Each input pixel
in xyY is converted to Luv space and compared with the cube to see if
a mapping polynomial exists there. If it exists then the Luv value is
converted to rgb using the polynomial.
r=AL+Bu+Cv+D
g=EL+Fu+Gv+H
b=IL+Ju+Kv+M
If no polynomial exists it is computed and stored into the cube.
Equations (as above) are solved by least squares using the 8 nearest Luv
points (in the cube, one in each octant) to the cube coordinate.

Note:
This is not rigorous color processing. It is to be used when you don't know
anything but the average color of the result.

HISTORY:
6-30-96  J Lorre. 
COGNIZANT PROGRAMMER:  Jean Lorre