HELP CONVOLVE_2D David Young February 1992 revised October 2001 Carries out a 2-D convolution, using C single-precision floats. convolve_2d(_____arrin, ____mask, ______arrout, ______region) -> ______arrout convolve_2d(_____arrin, ______sample, ____mask, ______arrout, ______region) -> ______arrout convolve_2d(_____arrin, _____sampx, _____sampy, ____mask, ______arrout, ______region) -> ______arrout The procedure convolves _____arrin with ____mask, both of which are 2-D arrays of numbers, and returns the result ______arrout. For efficiency, the arrays should be constructed using *newsfloatarray, or any other procedure that gives a packed arrayvector of single floats. The last two arguments may be given as , and the ______sample, _____sampx and _____sampy arguments omitted for straightforward use. Without the sample arguments, the formula is:   ARROUT (X,Y) = SUM ARRIN (X-x, Y-y) * MASK (x, y)   x,y where the sum is taken over all (x,y) lying inside the bounds of the mask array. The boundslist of the mask array is therefore important in determining any translation between the input and output arrays. For example, if ____mask is created with newsfloatarray([0 0 0 0], 1), then convolution is an identity operation; convolution with newsfloatarray([3 3 2 2], 1) would result in a shift 3 pixels right and 2 pixels down. If ______arrout and ______region are on entry, a new array will be created and returned. The convolution will be run over the whole of _____arrin, and the array that is returned will be smaller than _____arrin by an amount depending on the size of ____mask, to allow for the fact that the mask has to be wholly within _____arrin all the time. If on one dimension the input bounds are from i0 to i1, and the mask bounds are from m0 to m1, then on that dimension the output bounds will be from i0+m1 to i1+m0; likewise on the other dimension. If ______arrout is non-false and not an array on entry, an array is created and returned as if ______arrout was , except that oldsfloatarray (see ____HELP * ________OLDARRAY) is used to create the output array, with the given value of ______arrout as the tag. This allows arrays to be recycled to avoid creating garbage. On entry, ______arrout may be a 2-D array, for best efficiency created using *newsfloatarray or the like. In this case the results are stored in this array and it is returned. Its bounds must include the region in which output data is to be stored, determined as above if ______region is . (This is a non-compatible change, from Oct 2001, to previous versions in which the output region was trimmed to fit into the array supplied.) (On entry, ______arrout may also be a 5-element list, where the head of the list is an initialisation value and the tail of the list is the boundslist of an array to create and return. This mechanism is retained for compatibility with an old version of the routine, but is probably best avoided.) If not , ______region must be a 4-element list. This specifies, in *boundslist form, the region of the output array in which to store data. Together with the mask bounds and the sample arguments (see below) it implies a region of the input array from which to read values. This region must be contained within _____arrin's bounds. If ______arrout is supplied, its bounds must contain ______region; if it is , then ______region specifies the bounds of the array that is created. If _____sampx and _____sampy are supplied, they must be integers. They specify the amount to shift the mask in the input array between evaluations of adjacent points in the output array. They are in effect magnification factors between the output and input. The formula becomes   ARROUT(X,Y) = SUM ARRIN(X*sampx-x, Y*sampy-y) * MASK (x,y)   x,y This is equivalent to carrying out the normal convolution, and then sampling the output every _____sampx'th column and every _____sampy'th row (but much faster). The input and output regions are adjusted appropriately. The (0,0) point of the mask is always centred on an input array pixel whose _x, _y coordinates are zero mod _____sampx and _____sampy respectively. If _____sampx and _____sampy are omitted, this is equivalent to setting them to 1. If a single ______sample argument is given, this is equivalent to setting both _____sampx and _____sampy to the value given. convolve_2d_sizeout(_____arrin, ____mask) -> ______bounds convolve_2d_sizeout(_____arrin, ______sample, ____mask) -> ______bounds convolve_2d_sizeout(_____arrin, _____sampx, _____sampy, ____mask) -> ______bounds Computes the size of the output region, without actually doing the convolution. Arguments are as for convolve_2d except that the last two are missing, and _____arrin and ____mask can be boundslists rather than actual arrays. The result is the size of the output array needed, expressed as a boundslist. convolve_2d_sizein(_____arrin, ____mask, __________out_region) -> ______bounds convolve_2d_sizein(_____arrin, ______sample, ____mask, __________out_region) -> ______bounds convolve_2d_sizein(_____arrin, _____sampx, _____sampy, ____mask, __________out_region) -> ______bounds Computes the size of the input region needed to fill a given output region. Arguments are as for convolve_2d, except that: _____arrin can be an array or list, but in either case its contents are ignored; ____mask and __________out_region can be boundslists or arrays. The result is the size of the input region from which data will be taken to fill __________out_region, expressed as a boundslist. --- ___________________________$popvision/help/convolve_2d --- _________Copyright __________University __of ______Sussex _____2001. ___All ______rights _________reserved.