OptiVec: MF_convolve

MF_convolve

MD_convolve

ME_convolve

Function

convolution with a spatial response function

Syntax C/C++	#include <MFstd.h> void MF_convolve( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, unsigned ht, unsigned len );
C++ MatObj	#include <OptiVec.h> void matrix<T>::convolve( matrix<T> Flt, const matrix<T>& MX, const matrix<T> Rsp); void matrix<T>::convolve( matrix<T>* Flt, const matrix<T>& MX, const matrix<T> Rsp);
Pascal/Delphi	uses MFstd; procedure MF_convolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UInt );

Description

The convolution of MX with the response function MRsp is calculated and stored in MY. A filter MFlt is also calculated. If more than one matrix is to be convolved with the same MRsp, use MF_convolve only once and use MF_filter for the other matrices.

The response has to be stored in MRsp in wrap-around order in both dimensions: in each row i of MRsp, the response for zero and positive x-values is stored in MRsp_i,0 to MRsp_i,len/2 and the response for negative x-values (beginning with the most negative x) in MRsp_i,len/2+1 to MRsp_i,len-1.
Similarly, in each column of MRsp, the response for zero and positive y-values is stored in MRsp_0,j to MRsp_len/2,j and the response for negative y-values (beginning with the most negative y) in MRsp_len/2+1,j to MRsp_len-1,j.
You may wish to use MF_Rows_rotate and MF_Cols_rotate, or MF_Rows_reflect and MF_Cols_reflect to achieve this wrap-around order and to construct the response matrix.

The result of the convolution appears scaled with the sum of all elements of MRsp. Normally, therefore, MRsp should be normalized to 1.0.

MX, MY, MRsp, and MFlt must all be of the same dimensions. Both len and ht have to be integer powers of 2. MX may be overwritten by MY, MRsp may be overwritten by MFlt, but MX and MFlt as well as MY and MRsp have to be distinct from each other.

As in the one-dimensional case, the treatment of round-off errors in the construction of MFlt may be modified by VF_setRspEdit.
The input matrix is assumed to be periodic in both dimensions. See the description of VF_convolve on how to avoid end effects, in case it is not periodic.
About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of http://www.optivec.com/vecfuncs/.

Error handling

If either len or ht is not a power of 2, VF_FFT (on which MF_convolve is based) complains "Size must be an integer power of 2" and the program is aborted.