4.8. Signal Processing Objects

4.8. Signal Processing Objects
Prev	Chapter 4. Function Reference	Next

4.8.1. Convolution

This section describes the Convolution class provided by VSIPL++.

Applying a convolution object on a view performs a convolution on the view. Convolution supports different computations, depending on the element type and dimensionalities of the kernel, input and output views.

template <template <typename, typename> class ConstViewT,
          symmetry_type                       Symm,
          support_region_type                 Supp,
          typename                            T,
          unsigned                            N_times = 0,
          alg_hint_type                       A_hint = alg_time>
class Convolution;

Template parameters

ConstViewT: The convolution dimensionality: const_Vector for 1D convolutions; const_Matrix for 2D convolutions.
Symm: The symmetry of the kernel. See symmetry_type (section 2.7.10).
Supp: The support region of the convolution algorithm. See support_region_type (section 2.7.9).
T: The type of the elements in the views.
N_times: The expected number of times this object will be used. This is a hint how much effort to spend on upfront optimization. A value of 0 stands for infinity, and thus results in the most effort.
A_hint: One of alg_time, alg_space, or alg_none. This indicates how the implementation should optimize its computation or resource use. See alg_hint_type (section 2.7.1).

4.8.1.1. Constructor

Construct a 1D object

template <unspecified>
Convolution(const_Vector<T, unspecified> filter_coeffs,
            Domain<1> const&             input_size,
            length_type                  decimation = 1);

Construct a 2D object

template <unspecified>
Convolution(const_Matrix<T, unspecified> filter_coeffs,
            Domain<2> const&             input_size,
            length_type                  decimation = 1);

Description: Create a Convolution object of the given kernel view, input size, and decimation. The first version is available when the class's ConstViewT template parameter is const_Vector<T, unspecified>; the second when it is const_Matrix<T,unspecified>.

4.8.1.2. Call operators

template <unspecified>
Vector<T, unspecified>
operator()(
   const_Vector<T, unspecified> in, 
   Vector<T, unspecified>       out);

Description: Calls the Convolution on the given input vector. This version is available only when the class's ConstViewT template parameter is const_Vector<T, unspecified>.

Result: The result view is stored into the out argument, and is returned as return-value for convenience, too.

template <unspecified>
Matrix<T, unspecified>
operator()(
   const_Matrix<T, unspecified> in, 
   Matrix<T, unspecified>       out);

Description: Calls the Convolution on the given input matrix. This version is available only when the class's ConstViewT template parameter is const_Matrix<T, unspecified>.

Result: The result view is stored into the out argument, and is returned as return-value for convenience, too.

4.8.1.3. Example

// Declare a vector of kernel coefficients.
Vector<float> coeff(5);
...  // Initialize the coefficients.

// Declare a convolution object.
Convolution<const_Vector, nonsym, support_min, float>
   conv(coeff, Domain<1>(100), 1);

// Declare the input vector.
Vector<float> in(100);
...  // Initialize the input vector.

// Declare the output vector.
Vector<float> out(96);

// Perform the convolution of the input into the output.
conv(in, out);

See Also:

support_region_type: (section 2.7.9)
symmetry_type: (section 2.7.10)

4.8.2. Correlation

This section describes the Correlation class provided by VSIPL++.

Applying a correlation object on a view performs a correlation on the view. Correlation supports different computations, depending on the element type and dimensionalities of the kernel, input and output views.

template <template <typename, typename> class ConstViewT,
          support_region_type                 Supp,
          typename                            T,
          unsigned                            N_times = 0,
          alg_hint_type                       A_hint = alg_time>
class Correlation;

Template parameters

ConstViewT: The correlation dimensionality: const_Vector for 1D correlations; const_Matrix for 2D correlations.
Supp: The support region of the correlation algorithm. See support_region_type (section 2.7.9).
T: The type of the elements in the views.
N_times: The expected number of times this object will be used. This is a hint how much effort to spend on upfront optimization. A value of 0 stands for infinity, and thus results in the most effort.
A_hint: One of alg_time, alg_space, or alg_none. This indicates how the implementation should optimize its computation or resource use. See alg_hint_type xx (section 2.7.1).

4.8.2.1. Constructor

Construct a 1D object

Correlation(Domain<1> const&   ref_size,
            Domain<1> const&   input_size);

Construct a 2D object

Correlation(Domain<2> const&   ref_size,
            Domain<2> const&   input_size);

Description: Creates a Correlation object with the given kernel size and input size. The first version is available when the class's ConstViewT template parameter is const_Vector<T, unspecified>; the second when it is const_Matrix<T,unspecified>.

4.8.2.2. Call operators

template <unspecified>
Vector<T, unspecified>
operator()(
    bias_type                    bias,
    const_Vector<T, unspecified> ref,
    const_Vector<T, unspecified> in, 
    Vector<T, unspecified>       out);

Description: Calls the Correlation on the given kernel, input and output vectors. This version is available only when the class's ConstViewT template parameter is const_Vector<T, unspecified>. The parameter bias must be a member of the enumeration bias_type. See (section 2.7.2).

Result: The result view is stored into the out argument, and is returned as return-value for convenience, too.

template <unspecified>
Matrix<T, unspecified>
operator()(
    bias_type                    bias,
    const_Matrix<T, unspecified> ref,
    const_Matrix<T, unspecified> in,
    Matrix<T, unspecified>       out);

Description: Calls the Correlation on the given kernel, input and output matrices. This version is available only when the class's ConstViewT template parameter is const_Matrix<T, unspecified>. The parameter bias must be a member of the enumeration bias_type. See (section 2.7.2).

Result: The result view is stored into the out argument, and is returned as return-value for convenience, too.

4.8.2.3. Example

// Declare a correlation object.
Correlation<const_Vector, support_min, float>
    corr(Domain<1>(5), Domain<1>(100));

// Declare a vector of kernel items.
Vector<float> kernel(5);
...  // Initialize the kernel.

// Declare the input vector.
Vector<float> in(100);
...  // Initialize the input vector.

// Declare the output vector.
Vector<float> out(96);

// Perform the correlation of the input into the output.
corr(biased, kernel, in, out);

See Also:

support_region_type: (section 2.7.9)
bias_type: (section 2.7.2)

4.8.3. `FIR Filter`

This section describes the Fir class provided by VSIPL++.

Applying a Fir object to a view performs a FIR filter on the view.

template <typename  T,
          symmetry_type S = nonsym, 
          obj_state C = state_save,
          unsigned  N = 0,  
          alg_hint_type H = alg_time>
class Fir;

Template parameters

T: The type of the elements in the views.
S: The symmetry of the kernel. See symmetry_type (section 2.7.10).
C: state_no_save or state_save. An Fir object can maintain state between invocations of its call operator. See obj_state (section 2.7.4).
N: The expected number of times this object will be used. This is a hint how much effort to spend on upfront optimization. A value of 0 stands for infinity, and thus results in the most effort.
H: One of alg_time, alg_space, or alg_none. This indicates how the implementation should optimize its computation or resource use. See alg_hint_type (section 2.7.1).

4.8.3.1. Constructor

template <unspecified>
    Fir(
        const_Vector<T,unspecified> kernel,
        length_type input_size,
        length_type decimation = 1)

Description: Construct an Fir object with a vector of kernel coefficients and the indicated size of input vector and decimation.

Fir(Fir const &fir)

Description: Construct a new Fir object from an existing one..

4.8.3.2. Accessor Functions

length_type kernel_size()
length_type filter_order()
length_type input_size()
length_type output_size()
length_type decimation()
obj_state continuous_filtering()

Description: Report the various attributes of this Fir object.

4.8.3.3. Call operator

template <unspecified>
length_type operator()(
    const_Vector<T, unspecified> in,
    Vector<T, unspecified>       out
    )

Description: Apply the Fir object to the vector in and write results in the vector out. The length of the output vector is returned.

4.8.3.4. Assignment operator

Fir &operator= (Fir const &fir)

Description: Copy one Fir object into another.

4.8.3.5. Example

// Declare the kernel vector.
Vector<float> kernel(5);
...  // Initialize the kernel vector.

// Declare an FIR object.
Fir<float,nonsym,state_save> fir(kernel, 100, 1);

// Declare the input vector.
Vector<float> in(100);
...  // Initialize the input vector.

// Declare the output vector.
Vector<float> out(96);

// Perform the FIR filter on the input into the output.
fir(in, out);

See Also:

obj_state: (section 2.7.4)
symmetry_type: (section 2.7.10)

4.8.4. Fft - Fast Fourier Transform

Applying an FFT object on a view performs a single Fast Fourier Transform on the entire view. Fft supports different computations, dependent on the input element type, output element type, a specified direction or a special dimension, and the dimensionalities of the input and output views.

template <template <typename, typename> class ViewT,
          typename InputT,
          typename OutputT,
          int SD = 0,
          return_mechanism_type ReturnMechanism = by_value,
          unsigned Number = 0,
          alg_hint_type Hint = alg_time>
class Fft;

Template parameters

ViewT

Used to indicate the FFT dimensionality:

const_Vector for 1D FFTs, const_Matrix for 2D FFTs, and const_Tensor for 3D FFTs.

InputT, OutputT

The input and output value-types of the Fourier transform, respectively. For a complex transform, both types need to be identical. For a real transform, one of them is complex, the other real.

SD

The special dimension / direction. In case of a real FFT, its value indicates which dimension has different input and output sizes. In case of a complex FFT, its value indicates whether to perform a forward or inverse transform.

ReturnMechanism

The return-mechanism-type indicates whether to return the output-view by-value or by-reference.

Number

The expected number of times this object will be used. This is a hint how much effort to spend on upfront optimization. A value of 0 stands for infinity, and thus results in the most effort.

Hint

One of alg_time, alg_space, or alg_none. This indicates how the implementation should optimize its computation or resource use.

FFT parameters should fulfill the following requirements. Input and output sizes are specified during construction, the other parameters are template arguments.

View	input-type / output-type	SD	input size	output size
Vector	`complex<T>` / `complex<T>`	`fft_fwd`	`M`	`M`
	`complex<T>` / `complex<T>`	`fft_inv`	`M`	`M`
	`T` / `complex<T>`	`0`	`M`	`M/2 + 1`
	`complex<T>` / `T`	`0`	`M/2 + 1`	`M`
Matrix	`complex<T>` / `complex<T>`	`fft_fwd`	`M`x`N`	`M`x`N`
	`complex<T>` / `complex<T>`	`fft_inv`	`M`x`N`	`M`x`N`
	`T` / `complex<T>`	`0`	`M`x`N`	`M`x`(N/2 + 1)`
	`T` / `complex<T>`	`1`	`M`x`N`	`(M/2 + 1)`x`N`
	`complex<T>` / `T`	`0`	`M`x`(N/2 + 1)`	`M`x`N`
	`complex<T>` / `T`	`1`	`(M/2 + 1)`x`N`	`M`x`N`
Tensor	`complex<T>` / `complex<T>`	`fft_fwd`	`M`x`N`x`P`	`M`x`N`x`P`
	`complex<T>` / `complex<T>`	`fft_inv`	`M`x`N`x`P`	`M`x`N`x`P`
	`T` / `complex<T>`	`0`	`M`x`N`x`P`	`M`x`N`x`(P/2 + 1)`
	`T` / `complex<T>`	`1`	`M`x`N`x`P`	`M`x`(N/2 + 1)`x`P`
	`T` / `complex<T>`	`2`	`M`x`N`x`P`	`M`x`N`x`(P/2 + 1)`
	`complex<T>` / `T`	`0`	`M`x`N`x`(P/2 + 1)`	`M`x`N`x`P`
	`complex<T>` / `T`	`1`	`M`x`(N/2 + 1)`x`P`	`M`x`N`x`P`
	`complex<T>` / `T`	`2`	`M`x`N`x`(P/2 + 1)`	`M`x`N`x`P`

4.8.4.1. Constructor

Fft(Domain<dim> const& dom, scalar_type scale);

Description: Creates an Fft object of the given size, with the given scaling factor.

Requirements: dim is the Fft dimensionality.

4.8.4.2. Accessor functions

Domain<dim> const& input_size() const;
Domain<dim> const& output_size() const;
scalar_type scale() const;
bool forward() const;

Description: Report the various attributes of this Fft object. forward() returns true for a forward transform, false otherwise.

4.8.4.3. Call operators

template <class ViewT>
<undefined> operator()(ViewT in);

Description: Calls the Fft on the given input, out-of-place.

Requirements: This operator is available for ReturnMechanismType=by_value only. ViewT has to obey they above requirements for type and dimensions.

Result: Returns a new view containing the output.

template <class InViewT, class OutViewT>
OutViewT operator()(InViewT in, OutViewT out);

Description: Calls the Fft on the given input, out-of-place

Requirements: This operator is available for ReturnMechanismType=by_reference only. InViewT and OutViewT have to obey the above requirements for type and dimensions.

Result: The result view is stored into the out argument, and is returned as return-value for convenience, too.

template <class ViewT>
ViewT operator()(ViewT inout);

Description: Calls the Fft on the given input, in-place.

Requirements: This operator is available only for complex FFT objects, with ReturnMechanismType=by_reference. ViewT has to obey the above requirements for type and dimensions.

Result: The result is stored in-place into the inout view, and is also returned as return-value for convenience

4.8.5. Class template Fftm<>

Applying an Fftm object on a Matrix performs multiple fast Fourier transforms on the rows or columns of a Matrix. A Multiple FFT treats a matrix as a collection of either rows or columns and applies an FFT to each row or column.

template <typename InputT,
          typename OutputT,
          int A = row,
          int D = fft_fwd,
          return_mechanism_type ReturnMechanism = by_value,
          unsigned Number = 0,
          alg_hint_type Hint = alg_time>
class Fftm;

Template parameters

InputT, OutputT: The input and output value-types of the Fourier transform, respectively. For a complex transform, both types need to be identical. For a real transform, one of them is complex, the other real.
Axis: The dimension along which to apply the Ffts.
Direction: The direction of the Ffts, either fft_fwd or fft_inv.
ReturnMechanism: The return-mechanism-type indicates whether to return the output-view by-value or by-reference.
Number: The expected number of times this object will be used. This is a hint how much effort to spend on upfront optimization. A value of 0 stands for infinity, and thus results in the most effort.
Hint: A alg_hint_type (section 2.7.1), indicating how the implementation should optimize its computation or resource use.

FFTM parameters should fulfill the following requirements. Input and output sizes are specified during construction, the other parameters are template arguments.

input-type / output-type	axis	direction	input size	output size
`complex<T>` / `complex<T>`	`0` or `1`	`fft_fwd`	`M`x`N`	`M`x`N`
`complex<T>` / `complex<T>`	`0` or `1`	`fft_inv`	`M`x`N`	`M`x`N`
`T` / `complex<T>`	`0`	`fft_fwd`	`M`x`N`	`M`x`(N/2 + 1)`
`T` / `complex<T>`	`1`	`fft_fwd`	`M`x`N`	`(M/2 + 1)`x`N`
`complex<T>` / `T`	`0`	`fft_inv`	`M`x`(N/2 + 1)`	`M`x`N`
`complex<T>` / `T`	`1`	`fft_inv`	`(M/2 + 1)`x`N`	`M`x`N`

4.8.5.1. Constructor

Fftm(Domain<2> const& dom, scalar_type scale);

Description: Creates an Fftm object of the given size, with the given scaling factor.

4.8.5.2. Accessor functions

Domain<2> const& input_size() const;
Domain<2> const& output_size() const;
scalar_type scale() const;
bool forward() const;

Description: Report the various attributes of this Fftm object. forward() returns true for a forward transform, false otherwise.

4.8.5.3. Call operators

template <class MatrixT>
<undefined> operator()(MatrixT in);

Description: Calls the Fftm on the given input, out-of-place.

Requirements: This operator is available for ReturnMechanismType=by_value only. MatrixT has to obey the above requirements for type and dimensions.

Result: Returns a new matrix containing the output.

template <class InMatrixT, class OutMatrixT>
OutMatrixT operator()(InMatrixT in, OutMatrixT out);

Description: Calls the Fftm on the given input, out-of-place.

Requirements: This operator is available for ReturnMechanismType=by_reference only. InMatrixT and OutMatrixT have to obey the above requirements for type and dimensions.

Result: The result matrix is stored into the out argument, and is returned as return-value for convenience, too.

template <class MatrixT>
MatrixT operator()(MatrixT inout);

Description: Calls the Fftm on the given input, in-place.

Requirements: This operator is available only for complex FFTM objects, with ReturnMechanismType=by_reference. MatrixT has to obey the above requirements for type and dimensions.

Result: The result is stored in-place into the inout matrix, and is also returned as return-value for convenience.

4.8.6. Histogram

This section describes the Histogram class provided by VSIPL++.

Applying a histogram object to a view computes a histogram of the view. Histogram supports different computations, depending on the indicated element type and dimensionality.

        template <template <unspecified>
                  class const_View = const_Vector,
                  typename T>
        class Histogram;

Template parameters

const_View: The histogram dimensionality: const_Vector for 1D histograms; const_Matrix for 2D histograms.
T: The type of the elements in the views.

4.8.6.1. Constructor

        Histogram(T min_value, T max_value, length_type num_bin);

Description: Create a Histogram object to collect results constrained by these values:

min_value: The first element of the result vector accumulates results for all input items that are less than this value.
max_value: The last element of the result vector accumulates results for all input items that are greater than or equal to this value.
num_bin: The number of elements in the result vector.

For each input element V such that min_value <= V < max_value, the result element I is incremented. I is computed as ((V-min_value)/delta)+1, where delta is (max_value-min_value)/(num_bin-2).

4.8.6.2. Call operators

        template <unspecified>
        const_Vector<scalar_i>
        operator()(const_Vector<T, Block> data,
                   bool accumulate = false)

Description: Calls the Histogram on the given input vector. When the parameter accumulate is true, the results for this call are added to previous results.

Requirements: This call operator is available only when the template parameter const_View is const_Vector.

Result: The result vector view is returned as return-value.

        template <unspecified>
        const_Vector<scalar_i>
        operator()(const_Matrix<T, Block> data,
                   bool accumulate = false)

Description: Calls the Histogram on the given input matrix. When the parameter accumulate is true, the results for this call are added to previous results.

Requirements: This call operator is available only when the template parameter const_View is const_Matrix.

Result: The result vector view is returned as return-value.

4.8.6.3. Example

// Declare a histogram object.
Histogram<const_Vector, float> h(0, 8, 10);

// Declare the input vector.
Vector<float> in(100);
...  // Initialize the input vector.

// Declare the output vector.
Vector<scalar_i> out(10);

// Compute the histogram of the input into the output.
out = h(in);

4.8.7. IIR Filter

This section describes the Infinite Impulse Response filter provided by VSIPL++.

4.8.7.1. Class template Iir<>

template <typename T = float,
	  object_state Save = state_save,
	  unsigned Number = 0,
	  alg_hint_type Hint = 0>
class Iir;

Template parameters

T: The value-type of the Iir filter
obj_state: If this object is to be called repeatedly on subsequent chunks of a long vector, use state_save, else state_nosave
Number: The expected number of times this object will be used. This is a hint to the library how much effort to spend on upfront optimization. A value of 0 stands for infinity, and thus results in the most effort.
Hint: One of alg_time, alg_space, or alg_none. This indicates how the library should optimize its computation or resource use.

4.8.7.1.1. Constructor

Iir(const_Matrix<T, unspecified> b, 
    const_Matrix<T, unspecified> a,
    length_type i);

Description: Creates an Iir object...

4.8.7.1.2. Accessor functions

length_type kernel_size() const;
length_type filter_order() const;
length_type input_size() const;
length_type output_size() const;

Description: Report the various attributes of this Iir filter.

4.8.7.1.3. Call operators

template <class InViewT, class OutViewT>
OutViewT operator()(InViewT in, OutViewT out);

Description: Calls the Iir filter on in, storing the result in out.

Result: Returns a new view containing the output.

Prev	Up	Next
4.7. Signal Processing Functions	Home	Chapter 5. Advanced VSIPL++ Data Types