HELP ARRAY_EQUALISE                             David Young
                                                January 1994

LIB * ARRAY_EQUALISE provides a procedure for carrying out histogram
equalisation. Arrays of any time and any number of dimensions are
handled. LIB * VISION must be loaded to give access to this and related
libraries.

array_equalise(ARRIN, REGION, OUTVALS, ARROUT_FALSE) -> ARROUT
        ARRIN is the input array. It may have any number of dimensions.
        It must be arrayed "by row" (the default - see REF *ARRAYS).

        Data is taken from the part of array specified by REGION in
        boundslist style. REGION is a list twice as long as the number
        of dimensions of ARRIN, giving the minimum and maximum indices
        of the data region along the first dimension, then along the
        second dimension, and so on. If REGION is given as <false>, it
        defaults to the boundslist of ARRIN - the whole array is used.

        OUTVALS specifies the values to store in the output array. It
        may be:

            An integer giving the number of different values to output.
            The output values run from 0 to OUTVALS-1.

            A list containing two integers, say [N0 N1].  Values from N0
            to N1 inclusive are output; the number of different values
            is N1 - N0 + 1.

            A vector of values to output.

        ARROUT_FALSE may be <false>, in which case a new array with
        boundslist given by REGION is created, receives the results, and
        is returned. The new array's arrayvector has the same key as
        ARRIN's. To avoid creating garbage, or to fill part of an
        existing array, ARROUT_FALSE may an array, in which case the
        results are placed in the part of it specified by REGION, and it
        is returned. If it is an array, ARROUT_FALSE must have the same
        number of dimensions as ARRIN and must be arrayed by row.

        The elements of ARROUT are chosen to give as far as possible a
        flat histogram, whilst preserving the ordering of ARRIN,
        possibly mapped through OUTVALS if that is a vector. The
        histogram of the original array is measured using 256 bins.


--- $popvision/help/array_equalise
--- Copyright University of Sussex 1994. All rights reserved.
