HELP SQUARED_GRADIENTS                              David Young
                                                    February 1995

LIB * squared_gradients provides a procedure to calculate the squared
total gradient at each point in an image.

For straightforward use, the procedure can be called thus:

squared_gradients(_____arrin, _____sigma, false, false) -> ______arrout
        _____arrin is a 2-D array containing numbers. The procedure is
        fastest if _____arrin is created using *newsfloatarray.

        _____sigma is a positive number giving the standard deviation of the
        Gaussian mask used for smoothing.

        ______arrout is an arrout containing estimates of total squared
        gradient. That is, ______arrout(_x, _y) is an estimate of

                             2                        2
            (d/dx _____arrin(_x,_y))   +   (d/dy _____arrin(_x, _y))

        The estimates are formed by convolving _____arrin with the first
        derivatives of Gaussian functions, using *convolve_gauss_2d.
        ______arrout will be smaller than _____arrin by a few pixels on each side;
        the size of the margin omitted depends on _____sigma, and is chosen
        such that ______arrout only contains data where a proper estimate can
        be made. The size of the margin may be obtained using
        diffgaussmask_limit(_____sigma) (see *gaussmask).

It is possible to control the region of the array for which the
calculation is performed, and to supply an output array to reduce
garbage creation, as follows:

squared_gradients(_____arrin, _____sigma, ______arrout, ______region) -> ______arrout
        _____arrin and _____sigma are as above.

        If not <false>, ______arrout may be an array, preferably created using
        *newsfloatarray, which will receive the results and which will
        be returned. Alternatively, ______arrout may be a 4-element list, in
        which case a new array with this boundslist is created and
        returned. Finally, ______arrout may be a 5-element list, in which case
        its head is used to initialise the new array and its tail
        becomes the boundslist.

        If not <false>, ______region must be a boundslist-type specification
        of the region of ______arrout in which results are to be stored.

        If ______arrout is non-false and ______region is <false>, then ______region is set
        to the boundslist of ______arrout.

        If ______arrout is <false> and ______region is non-false, then a new array
        whose boundslist is ______region is created and returned.

        If both ______region and ______arrout are <false>, then ______region is set to the
        largest region that will receive valid data given _____arrin and
        _____sigma, as above.

        If ______arrout and ______region are both non-false, then ______region must lie
        within the bounds of ______arrout.  Any part of ______arrout that is outside
        ______region is left unchanged (or if ______arrout was specified as a list,
        will have the initialisation value).

        In all cases, if part of ______region is outside the region which can
        receive valid data given _____arrin and _____sigma, that part is set to
        zero.

For example, to make a new output array which is the same size as the
input array, but which will have zeros in the margin where there are no
valid results, do

    squared_gradients(arrin, sigma, boundslist(arrin), false) -> arrout

To fill as much as possible of an existing array ______array2 with results,
without affecting any of its elements for which there are no results
available, it is necessary to do

    squared_gradients(arrin, sigma, array2,
        region_intersect(array2,
            region_expand(arrin, -diffgaussmask_limit(sigma))
        )
    ) -> array2;

The boundlist manipulation routines used here are from
* BOUNDSLIST_UTILS. The result of the call to region_expand gives the
valid output data region, and this is intersected with the output array
bounds to give the region in which to store data.


--- _________________________________$popvision/help/squared_gradients
--- _________Copyright __________University __of ______Sussex _____1995. ___All ______rights _________reserved.