Creating Pass Filter Plugins

Kst provides header files to simplify the implementation of pass filter plugins. The use of these header files is described below.

The pass filter header file is located in `kst/plugins/pass_filters`

of
the Kst source tarball. The file is named `filters.h`

To use this file, include it in the source code for your plugin:

#include <../filters.h>(by convention, we will place the source code for the plugin one directory below where the header files are).

The `filters.h`

header file contains a single function that calculates the Fourier
transform of a supplied function, applies the supplied filter to the Fourier transform, and then calculates
the inverse Fourier transform of the filtered Fourier transform. To supply the filter, the following
function needs to be implemented in the source code for your plugin:

`double filter_calculate( double `

* dFreqValue*, const double

`inScalars[]`

This function should calculate the filtered amplitude for the frequency `dFreqValue`

.
`inScalars[]`

will contain the unaltered input scalars for the plugin, specified in the
XML file. Most likely `inScalars[]`

will contain cutoff frequencies or other
properties of the filter. For example, to implement a Butterworth high-pass filter,
`filter_calculate`

could be implemented as follows:

double filter_calculate( double dFreqValue, const double inScalars[] ) { double dValue; if( dFreqValue > 0.0 ) { dValue = 1.0 / ( 1.0 + pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) ); } else { dValue = 0.0; } return dValue; }

Once the required `filter_calculate`

has been implemented, the filter function
from the header file can be called:

`kst_pass_filter( `

* inArrays*,

`inArrayLens`

`inScalars`

`outArrays`

`outArrayLens`

`outScalars`

The arguments supplied to the exported C function can usually be passed to
`kst_pass_filter`

without modification. However, there are a few restrictions
on the arguments:

`inArrays[0]`

must contain the array of data to filter.`inScalars`

should contain the filter-specific parameters to be used by the`filter_calculate`

function.

After the function call, `outArrays[0]`

will contain the filtered array of data, and
`outArrayLens`

will be set appropriately. The `kst_pass_filter`

function does not use `outScalars`

.

The following is an example of a pass filter plugin that implements the Butterworth high-pass filter.

/* * Butterworth low pass filter plugin for KST. * Copyright 2004, The University of British Columbia * Released under the terms of the GPL. */ #include <stdlib.h> #include <math.h> #include "../filters.h" extern "C" int butterworth_highpass(const double *const inArrays[], const int inArrayLens[], const double inScalars[], double *outArrays[], int outArrayLens[], double outScalars[]); int butterworth_highpass(const double *const inArrays[], const int inArrayLens[], const double inScalars[], double *outArrays[], int outArrayLens[], double outScalars[]) { int iReturn; iReturn = kst_pass_filter( inArrays, inArrayLens, inScalars, outArrays, outArrayLens, outScalars ); return iReturn; } double filter_calculate( double dFreqValue, const double inScalars[] ) { double dValue; if( dFreqValue > 0.0 ) { dValue = 1.0 / ( 1.0 + pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) ); } else { dValue = 0.0; } return dValue; }

Would you like to make a comment or contribute an update to this page?

Send feedback to the KDE Docs Team