DESCRIPTION

This routine converts an image to a single matrix. The image is converted to
black and white by simple averaging of the pixels. This is not the standard
method which de-emphasizes blue. Further, the possiblity that the image is
not linear is ignored. Likely some for these considerations will be
implemenated as options at some point, but will require moving this routine
to i_color.c so that the options can be shared with other routines that
convert color images to black and white.
If the matrix pointed to is NULL, then it is created. If any are the wrong
size, they is is resized. Otherwise, the storage is recycled as is.

RETURNS

NO_ERROR on success, and ERROR on failure, with an appropriate error
message being set.

DISCLAIMER

This software is not adequatedly tested. It is recomended that
results are checked independantly where appropriate.