man.diff

speech signal process tools

.\" Copyright (c) 1987, 1989, 1990 Entropic Speech, Inc.; All rights reserved
.\" @(#)zero_pole.1	3.6 5/24/91 ESI
.TH ZERO_POLE 1\-ESPS 5/24/91
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH NAME
zero_pole \- convert complex ascii zero and pole locations to ESPS filter 
.SH SYNOPSIS
.B zero_pole
[
.BI \-x " debug_level"
]
[
.BI \-c " comment"
]
[
.BI \-g " gain"
]
[
.BI \-f " freq"
]
.I zero_file
[
.I pole_file
]
.I feafilt_file
.SH DESCRIPTION
.PP
The program
.I zero_pole
reads complex zero locations from the file
.I zero_file
and (optionally) complex pole locations from the file
.I pole_file,
computes the numerator and denominator coefficients,
and prints the coefficients, poles and zeros to the output FEAFILT
file 
.I feafilt_file. 
Zero and pole locations are specified by a real part followed by an imaginary
part.
Poles or zeros on the real axis need the imaginary part specified.
If a pole or zero is specified off the real axis (i.e. with a nonzero
imaginary part), its complex conjugate is automatically included.
This insures that the resulting filter coefficients are all real.
Any poles specified outside of the unit circle will result in
an error.
.PP
Both input files are in ascii format.
The 
.I zero_file
and the
.I pole_file
may be the same file, in which case the numerator coefficients should appear first.
In both
.I zero_file
and
.I pole_file
the first number should be an integer which tells how many zeros or poles are in the
file.  The zeros or poles follow.  Both real and imaginary part of each pole and
zero must be specified.  Any combination of spaces and newlines may separate the
data.
.PP
The program prompts the user for comments to be added to the comment field of
.I feafilt_file
unless the \-c option is used or unless any coefficients are being read from the
standard input.  The user should type in his comments and terminate
them with a ^D on a line by itself.  In either case the user added comment is limited to 2047
characters.  In addition to any user specified comments, the program automatically
specifies the source of the zero locations and (if appropriate) the pole locations
in the comment field.
.PP
If
.I feafilt_file
is "\-", the output goes to the standard output.  If
.I zero_file
is "\-", the zeros are read from standard input.  If
.I pole_file
is "\-", the poles are read from standard input also.
.SH OPTIONS
The following options are supported:
.TP
.BI \-x " debug_level"
A value of 0 (the default value) will cause
.I zero_pole
to do its work silently, unless there is an error.
A nonzero value will cause various parameters to be printed out
during program initialization.
.br
.TP
.BI \-c " comment"
The character string
.I comment
is added to the comment field of the output file header.  If this option is not used,
the program prompts the user for a comment string, which he should terminate with
a ^D.  
.br
.TP
.BI \-g " gain"
This is the gain of the filter at the "critical frequency" specified
by the
.BI \-f
option.  The default for
.I gain
is 1.0.
If neither the 
.BI \-g 
nor the 
.BI \-f 
option is used, the filter gain is not normalized.
.br
.TP
.BI \-f " freq"
This is the critical frequency at which the gain of the filter is normalized, expressed as a fraction of the sampling frequency.
The default for
.I freq
is 0.0.
If neither the 
.BI \-g 
nor the
.BI \-f 
option is used, the filter gain is not normalized.
.SH ESPS PARAMETERS
The parameter file is not accessed.
.SH ESPS COMMON
The Common file is not processed.
.SH ESPS HEADER
A new header is created for the output FEAFILT file.
The program fills in appropriate values in the common part of the header.
The generic header items 
.I max_num
and
.I max_denom
are set to the number of items in 
.I num_file
and 
.I denom_file,
respectively;
.I define_pz 
is set to YES
and
.I complex_filter
is set to NO; 
.I type 
is set to FILT_ARB and
.I method
is set to PZ_PLACE.  All other items take their null values.
The program enters the names of the input coefficient files in the comment field of
the header.
.SH DIAGNOSTICS
The program prints a warning to the standard error output if the total comment
field of the output file exceeds MAX_STRING.
.SH SEE ALSO
atofilt(1\-ESPS), notch_filt(1\-ESPS), 
wmse_filt(1\-ESPS), iir_filt(1\-ESPS), fea2filt(1\-ESPS),
filter (1-ESPS), fft_filter (1-ESPS), 
pz_to_co (3-ESPSsp),
init_feafilt_hd(3\-ESPSu),
allo_feafilt_rec(3\-ESPSu), 
put_feafilt_rec(3\-ESPSu),
ESPS(5\-ESPS), FEA(5\-ESPS), FEAFILT(5\-ESPS), 
FILT (5-ESPS)
.SH AUTHOR
Brian Sublett. Modified for ESPS 3.0 by David Burton. Modified for
FEAFILT output by Bill Byrne.