HELP ARRAY_HALFSIZE                                 David Young
                                                    February 1997

LIB * ARRAY_HALFSIZE reduces an array to half its size along each
dimension.

array_halfsize(_____arrin, ______region, ____________arrout_false, ______option) -> ______arrout
        _____arrin is the input array, of any number of dimensions (except
        for certain options - see below), and containing numbers only.
        The data are taken from the region specified by the ______region
        argument, which is a *boundslist type list of limits on each
        dimension, or <false>, in which case the whole of _____arrin is used.

        If ____________arrout_false is <false>, a new array is created and returned.
        Otherwise, ____________arrout_false must be an array of the same number of
        dimensions as _____arrin and of adequate size (see below) in which
        the results will be stored, and which is returned.

        The ______option argument specifies the type of sampling. This may be
        one of the words "average", "sample", "field1" or "field2". The
        last two are only usable with 2-D arrays. ______option may also be
        <false>, which is equivalent to "average".

________Sampling_ _________behaviour

For all options, as much of the array is used as possible; the final
element of a 1-D array, or the final row and or/column of a 2-D array
may be ignored. Similarly for higher-dimensioned arrays. For all options
except the "field2" option, sampling starts at the lower limit of the
bounds.

The "average" option means that small regions of the array are averaged
(with equal weighting on the pixels) to produce each output value.
Details are as follows; if _____arrin is a 1-D array and ______region is [__x0 __x1],
then:

    If the number of elements _N = __x1-__x0+1 is even, then _N/2 values will
    be stored in ______arrout. If _N is odd, then the last input element,
    _____arrin(__x1), is ignored, and (_N-1)/2 output values are stored.

    If __x0 is even, the output will start at ______arrout(__x0/2) and the mapping
    is defined by

            ______arrout(_i) = (_____arrin(2*_i) + _____arrin(2*_i+1)) / 2.

    If __x0 is odd, the output will start at ______arrout( (__x0+1)/2 ) and

            ______arrout(_i) = (_____arrin(2*_i-1) + _____arrin(2*_i)) / 2.

    If _____arrin has more than 1 dimension, the rules above apply to each
    dimension separately. Each element of ______arrout will be the average of
    2**_D elements of arrin, where _D is the number of dimensions.

The "sample" option means that alternate pixels on each dimension are
ignored. For the 1-D array case:

    If _N is even, _N/2 values are stored. If _N is odd, then (_N+1)/2
    values are stored.

    If __x0 is even, the output will start at ______arrout(__x0/2) and

            ______arrout(_i) = _____arrin(2*_i)

    If __x0 is odd, the output will start at ______arrout( (__x0+1)/2 ) and

            ______arrout(_i) = _____arrin(2*_i-1)

    These rules apply for each dimension of multidimensional arrays.

The "field1" and "field2" options are for the special case where an
image has been obtained with a raster-scan device which produces an
interleaved image, with alternate rows belonging to different fields.
These may have to be separated to avoid blatant motion blur. The
"field1" option samples the first dimension of a 2-D array by averaging
and the second dimension by sampling alternate pixels. The rules above
are used in each case. The "field2" option is the same, except that the
first raster line (the pixels whose second index equals the lower bound)
are ignored, and sampling starts on the next row.


--- ______________________________$popvision/help/array_halfsize
--- _________Copyright __________University __of ______Sussex _____1997. ___All ______rights _________reserved.