OptiVec: MF_convolve

MF_convolve

MD_convolve

ME_convolve

MF_convolvewEdit

MD_convolvewEdit

ME_convolvewEdit

MFb_convolve

MDb_convolve

MEb_convolve

MFb_convolvewEdit

MDb_convolvewEdit

MEb_convolvewEdit

Function

convolution with a spatial response function

Syntax C/C++	#include <MFstd.h> void MF_convolve( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, ui ht, ui len ); void MF_convolvewEdit( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, ui ht, ui len, fComplex thresh ); void MFb_convolve( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, ui ht, ui len, fVector Buf ); void MFb_convolvewEdit( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, ui ht, ui len, fComplex thresh, fVector Buf );
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); void matrix<T>::convolvewEdit( matrix<T> Flt, const matrix<T>& MX, const matrix<T> Rsp, complex<T> thresh); void matrix<T>::convolvewEdit( matrix<T>* Flt, const matrix<T>& MX, const matrix<T> Rsp, complex<T> thresh); void matrix<T>::b_convolve( matrix<T> Flt, const matrix<T>& MX, const matrix<T> Rsp, vector<T> Buf); void matrix<T>::b_convolve( matrix<T>* Flt, const matrix<T>& MX, const matrix<T> Rsp, vector<T> Buf); void matrix<T>::b_convolvewEdit( matrix<T> Flt, const matrix<T>& MX, const matrix<T> Rsp, complex<T> thresh, vector<T> Buf); void matrix<T>::b_convolvewEdit( matrix<T>* Flt, const matrix<T>& MX, const matrix<T> Rsp, complex<T> thresh, vector<T> Buf);
Pascal/Delphi	uses MFstd; procedure MF_convolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UIntSize ); procedure MF_convolvewEdit( MY, MFlt, MX, MRsp:fMatrix; ht, len:UIntSize; thresh:fComplex ); procedure MFb_convolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UIntSize; Buf:fVector ); procedure MFb_convolvewEdit( MY, MFlt, MX, MRsp:fMatrix; ht, len:UIntSize; thresh:fComplex; Buf:fVector );

CUDA function C/C++

#include <cudaMFstd.h>
int cudaMF_convolve( fMatrix d_MY, fMatrix d_MFlt, fMatrix d_MX, fMatrix d_MRsp, ui ht, ui len );
void MFcu_convolve( fMatrix h_MY, fMatrix h_MFlt, fMatrix h_MX, fMatrix h_MRsp, ui ht, ui len );
int cudaMF_convolvewEdit( fMatrix d_MY, fMatrix d_MFlt, fMatrix d_MX, fMatrix d_MRsp, ui ht, ui len, fComplex thresh );
void MFcu_convolvewEdit( fMatrix h_MY, fMatrix h_MFlt, fMatrix h_MX, fMatrix h_MRsp, ui ht, ui len, fComplex thresh );

CUDA funcktion Pascal/Delphi

uses MFstd;
function cudaMF_convolve( d_MY, d_MFlt, d_MX, d_MRsp:fMatrix; ht, len:UIntSize ): IntBool;
procedure MFcu_convolve( h_MY, h_MFlt, h_MX, h_MRsp:fMatrix; ht, len:UIntSize );
function cudaMF_convolvewEdit( d_MY, d_MFlt, d_MX, d_MRsp:fMatrix; ht, len:UIntSize; thresh:fComplex ): IntBool;
procedure MFcu_convolvewEdit( h_MY, h_MFlt, h_MX, h_MRsp:fMatrix; ht, len:UIntSize; thresh:fComplex );

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.

A response function which attenuates some spatial frequences so much that any information about them is lost (e.g., high frequencies for a low-cut filter) is marked by very small values in MFlt for the respective frequencies. Here, "very small" means that they are in the order of round-off error. In order to minimize round-off error, MF_convolve replaces such small values in Flt by 0.
All one- and two-dimensional convolutions and deconvolutions use the same default threshold for this implicit filter editing. It can be retrieved by VF_setRspEdit. If you wish to set a different threshold for all calls to VF / MF_convolve and VF / MF_deconvolve, you may use VF_setRspEdit. However, this method is not thread-safe and should not be used to set different thresholds for different calls to VF / MF_convolve or VF / MF_deconvolve. Here, you have to use the variant MF_convolvewEdit, which takes the desired threshold as the argument thresh (and ignores the default threshold). As MFlt consists of complex numbers, and as it is sometimes desirable to treat real and imaginary parts differently, thresh is complex as well.

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.

Internally, MF_convolve / MF_convolvewEdit allocates and frees additional workspace memory. For repeated calls, this would be inefficient. In such a case, it is recommended to use MFb_convolve / MFb_convolvewEdit instead. The size of Buf must be:
C/C++: sizeof(Buf) >= ht*(len+4)

Pascal/Delphi: sizeof(Buf) >= ht*len

Additionally, Buf must be 128-bit (P8) or 256-bit (P9) aligned. This usually means you can only take a vector allocated by the VF_vector family as Buf.

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.