pkmc_filt.1

speech signal process tools

.\" Copyright (c) 1992 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)pkmc_filt.1	1.7 4/3/97 ERL
.ds ]W (c) 1992 Entropic Research Laboratory, Inc.
.TH  PKMC_FILT 1\-ESPS 4/3/97
.SH NAME
.nf
pkmc_filt \- design an equiripple FIR filter using the Parks-McClellan algorithm
.fi
.SH SYNOPSIS
.B
pkmc_filt
.BI \-P " param_file"
[
.BI \-x " debug_level"
]
.I file.filter
.SH DESCRIPTION
.PP
The program \fIpkmc_filt\fR designs a linear-phase finite-impulse response
(FIR) filter that meets the specification defined in the parameter file 
\fIparam_file\fR.  The filter coefficients are saved in the output file
\fIfile.filter\fR.  If \fIfile.filter\fR is replaced by "-", the 
standard output is written.
.PP
The design method is based on the Parks-McClellan algorithm.  The resulting
filter minimizes the maximum-weighted approximation-error.  One of the
four standard FIR types is produced.  For a filter with multiple stopbands
and passbands, the Type 1 (symmetric and odd length) or Type 2 (symmetric and
even length) filter is designed.  For a differentiator or a Hilbert
Transformer, either the Type 3 (anti-symmetric and odd length) or
the Type 4 (anti-symmmetric and even length) is designed.
.PP
Frequency responses of Types 2 and 3 filters are equal to 0 at PI, which 
is undesirable for a highpass filter.  For multiple stopbands/passbands
filters, type 1 and 2 are used.  For differentiator and Hilbert transformer,
type 3 and 4 are used.
.PP
A generic Parks-McClellan algorithm is implemented here, without
numerical optimization.  Numerical problem occurs for filter with more
than 100 taps, narrow passbands/stopbands, large transition bands, and
non-symmetrical transition bands.  In some cases, 
the algorithm does not detect the problem.
Typically the filter gain for such cases are large, exceeding 1.0.  
Always check the result by \fIfiltspec (1\-ESPS)\fR and 
\fIplotspec (1\-ESPS)\fR.
.PP
Also see the shell script \fIxfir_filt(1\-ESPS)\fR that is a cover
script for this and other FIR filter design programs.
.PP
.SH OPTIONS
.PP
The following option is supported:
.TP
.BI \-x " debug_level \fR[0]\fP"
If \fIdebug_level\fR is positive, \fIpkmc_filt\fR prints debugging messages 
and other information on the standard error output.  The messages 
proliferate as the \fIdebug_level\fR increases.  If \fIdebug_level\fP 
is 0 (the default), no messages are printed.  
.SH ESPS PARAMETERS
The following parameters are read from the \fIparam_file\fR:
.TP
.I filt_type - string
The type of filter desired.  Use \fIMULTIBAND\fR for lowpass, 
highpass, bandpass, bandstop, and arbitrary multiple stop/passbands 
FIRs.  Use \fIDIFFERENTIATOR\fR for a differentiator and \fIHILBERT\fR for
Hilbert transform filter.
.TP
.I filt_length - int
Number of taps for the filter.
.TP
.I ngrid - int
This is an optional parameter. It specifies the number of grid points 
used for interpolation from 0 to PI/2.  The default value is 2 *
\fIfilt_length\fR.
.TP
.I samp_freq - float
The sampling frequency.  This number is used for rescaling the values
of bandedge parameters.
.TP
.I nbands - int
Number of bands from 0 to \fIsamp_freq/2\fR.  For example, 
for a \fIMULTIBAND\fR filter type, a lowpass filter has 2 bands -- 
a passband from 0 to some frequency \fIf1\fR and a stopband from 
some frequency \fIf2\fR to \fIsamp_freq/2\fR, where \fIf1<f2\fR.
For a differentiator, \fInbands\fR is 1 if a full band differentiator 
is desired, 2 otherwise. For a Hilbert transform filter, 
\fInbands\fR is always 1, and its band extend from 0 to \fIsamp_freq/2\fR.
.PP
The following set of the parameters have the forms of \fIband[i]_edge1\fR,
\fIband[i]_edge2\fR, \fIband[i]_des\fR, and \fIband[i]_wt\fR, where
\fIi\fR denotes the band number.  For example, \fIband2_edge1\fR is
a parameter for the left edge of the second band.  The number of sets of
these parameters must be equal to \fInbands\fR.
Band 1 is the left-most band, band \fInband\fR is the right-most band.
.PP
The response at the band edges is automatically determined by the
algorithm, the error on the band edge is the same equi-ripple error
of the band.  The generic header item \fIripple_db\fR in the output
file contains the equi-ripple error in dB that represents the
smallest approximation error that meets the specification.
.TP
.I band[i]_edge1 - float
The left edge of \fIi\fRth band.  It must be 0 for \fIband1_edge1\fR.
.TP
.I band[i]_edge2 - float
The right edge of \fIi\fRth band.  It must be \fIsamp_freq/2\fR for 
the last band.  \fIband[i]_edge2\fR and \fIband[i+1]_edge1\fR
can not be the same number.  In fact \fIband[i]_edge2 >
band[i+1]_edge1\fR.  
.TP
.I band[i]_des - float
For \fIMULTIBAND\fR filter type, it is the desired constant value for
the \fIi\fRth band.  For \fIDIFFERENTIATOR\fR filter type, it is the slope 
of the frequency response on the passband.  The slope is measured by
the amplitude response over normalized frequency axis.  
For \fIHILBERT\fR, it should be set to 1.
.TP
.I band[i]_wt - float
For \fIMULTIBAND\fR filter type, it is the constant weighting factor for the 
approximation error in \fIi\fRth band.  The weights in bands are relative
to one another.  For example, in a two band filter, \fIband1_wt\fR of 10
and \fIband2_wt\fR of 20 are the same as \fIband1_wt\fR of 1 and 2 for
the other band.  For \fIDIFFERENTIATOR\fR 
filter type, the weighting function \fI1/f\fR is appplied to the
the passband region of the differentiator. For \fIHILBERT\fR, it should
always be set to 1.
.PP
.SH ESPS COMMON
No ESPS common parameter processing is used.
.PP
.SH ESPS HEADERS
A new FEAFILT header is created for the  output  file.   The
program  fills  in  appropriate values in the common part of
the header as well as the  following  generic  header  items
associated with the FEAFILT type.
.PP
The \fIsamp_freq\fR generic header item contains value of the \fIsamp_req\fR
parameter.
.PP
The \fIband_edges\fR generic header item of size \fI2*nbands\fR is an array
containing the left and rights band edges of bands.
.PP
The \fIdesired_value\fR generic header item of size \fInbands\fR is an array
containing the \fIband[i]_des\fR parameters
.PP
The \fIdesired_weight\fR generic header item of size \fInbands\fR is an array
containing the \fIband[i]_wt\fR parameters
.PP
The \fIripple_db\fR generic header item of size \fInbands\fR is an array
containing the error in dB for each band.
.PP
In addition, the generic header item \fIdelay_samples\fR  (type  DOUBLE) is
added  to the header. \fIDelay_samples\fR  is  equal  to  
(filter length  -  1)/2.   
This represents  the  delay  to  the  center  of  the peak of the
impulse response.
.PP
.SH FUTURE CHANGES
.PP
.SH EXAMPLES
The following parameter file designs a bandpass filter with stop band
from 0 to 500 Hz, passband from 1000 to 2000 Hz, and stopband from
2500 to 4000 Hz.
.PP
.nf
	int filt_length = 32;
	float band1_edge1 = 0.000000;
	float band1_edge2 = 500.000000;
	float band1_des = 0.000000;
	float band1_wt = 1.000000;
	float band2_edge1 = 1000.000000;
	float band2_edge2 = 2000.000000;
	float band2_des = 1.000000;
	float band2_wt = 1.000000;
	float band3_edge1 = 2500.000000;
	float band3_edge2 = 4000.000000;
	float band3_des = 0.000000;
	float band3_wt = 1.000000;
	string filt_type = "MULTIBAND";
	float samp_freq = 8000.000000;
	int nbands = 3;
.fi
.PP
The unspecified regions from 500 to 1000 Hz and 2000 to 2500 Hz are
unspecified and are taken as transition bands which will have arbitray
repsonse.
.SH ERRORS AND DIAGNOSTICS
.PP
.SH BUGS
.PP
None known.
.SH REFERENCES
Oppenheim & Schafer, \fIDiscrete-Time Signal Processing\fR,
Prentice Hall, 1989
.PP
.SH "SEE ALSO"
xfir_filt(1\-ESPS), cb_filt(1\-ESPS), win_filt(1\-ESPS), 
notch_filt(1\-ESPS), FEA_FILT(5\-ESPS), 
atofilt(1\-ESPS), wmse_filt(1\-ESPS), iir_filt(1\-ESPS), sfconvert(1\-ESPS)
.PP
.SH AUTHOR
Derek Lin
.PP