man.diff

来自「speech signal process tools」· DIFF 代码 · 共 436 行 · 第 1/2 页

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1991-1993 Entropic Research Laboratory, Inc.  All rights reserved.
.\" @(#)feafunc.1	1.8	01 Apr 1997 ESI/ERL
.TH FEAFUNC 1\-ESPS 01 Apr 1997
.ds ]W (c) 1991 Entropic Research Laboratory, Inc.
.if n .ds - ---
.if t .ds - \(em\h'-0.2m'\(em
.SH "NAME"

feafunc \- apply optional function, gain factor, additive constant, and type change to FEA fields
.SH "SYNOPSIS"
.B feafunc
[
.BI \-d " add_constant"
] [
.BI \-f " input_field"
[
.BI \-f " output_field"
]] [
.BI \-g " gain_factor"
] [
.BI \-r " range"
] [
.BI \-t " output_type"
] [
.BI \-x " debug_level"
] [
.BI \-F " function"
] [
.BI \-P " params"
]
.I "input output"
.SH "DESCRIPTION"
.PP
.I feafunc
accepts a FEA file \fIinput\fP containing arbitrary fields.
It produces a FEA file \fIoutput\fP with records that are copies of the
input records except that there is a field
.I output_field
containing the values of the functional form \fIg*F(element) + d\fP
for each element of the selected field \fIinput_field\fP.
Here \fIg\fP is a multiplicative constant,
\fIF\fP is a single-valued scalar function
(\fInone, abs, arg, atan, conj, cos, exp, exp10, im, log, log10, re,
recip, sgn, sin, sqrt, sqr, tan\fP), and \fId\fP is an additive constant.
The output field has the same size, rank, and dimensions as
.I input_field
and, by default, the same data type.
However, with the
.B \-t
option, the result may be converted to an arbitrary numeric data type.
Normally,
.I output_field
is a new field, different from any in the input file.
However, the output field may replace an existing field, including
.I input_field.
In that particular case, the program transforms the contents of
.I input_field
by applying the functional form to each element.
.PP
If \fIinput\fP is "\-", standard input is used for the input file.
If \fIoutput\fP is "\-", standard output is used for the output file.
The input and output should not be the same file;
however, it is okay to run the program as a filter by specifying "\-"
for both input and output.
.PP
The defaults for \fB\-F\fP, \fB\-g\fP, and \fB\-a\fP respectively 
are "none", 1, and 0.  ("None" is a function that just returns the
input value\*-i.e., it does not modify the argument.)  These defaults
imply no changes at all to the data, which is useful since
\fIfeafunc\fP can then be used to change the name or numeric type of 
a field.  
.PP
Note that the \fB-f\fP option is used to specify both the input and
output field names.  If an output name isn't specified (the option is
used once), the output name defaults to the input name followed by 
a suffix giving the name of the applied function.  
.PP
Function values 
.I F(element)
are computed by the ESPS function
.IR arr_func (3-ESPSsp).
See the
.I arr_func
manual entry for more information on particular functions
.I F.
The result is as though the input values were converted to DOUBLE_CPLX,
the computations done with complex arithmetic,
and the result converted to the output type.
A more direct method is actually used internally when the input and
output types and the multiplicative and additive constants permit;
for example, if these are all real, real arithmetic is used.
Type conversions are done by
.IR type_convert (3-ESPS).
Briefly, conversion from complex to real discards the imaginary part,
conversion from float or double to an integral type
rounds rather than truncating,
and conversion from one type to another type with a narrower numerical range
may entail clipping; in the latter case a warning message is printed.
See the
.I type_convert
manual page for more details on type conversions.
.PP
.I feafunc
preserves FEA subtype information\*-for example,
if the input is a FEA_SPEC file, the output file header will contain the
subtype code indicating a FEA_SPEC file,
and the output file will in fact be a FEA_SPEC file
if one precaution is observed.
Namely, if the output field is one that the FEA subtype specification
subjects to requirements, the requirements must not be violated.
It is unadvisable, for instance, though possible, to use
.I feafunc
with the
.B \-t
option to make a file that appears to be a FEA_SPEC file
but has a field named
.I re_spec_val
whose data type is LONG_CPLX.
(The
.IR FEA_SPEC (5-ESPS)
manual entry requires it to be FLOAT or BYTE.)
It is always legitimate to add a new field with a name not mentioned in the
subtype specification.
.PP
For scaling and shifting the data in FEA_SD files,
\fIcopysd\fP(1\-\s-1ESPS\s+1) is probably a better choice than \fIfeafunc\fP. 
For changing types and formats in FEA_SPEC files,
.IR copysps (1-ESPS)
is probably better.
For more general computations, consider \fIselect\fP(1\-\s-1ESPS\s+1).
.SH OPTIONS
.PP
The following options are supported.  Default values are shown in brackets.
.TP
.BI \-d " add_constant \fR[0]\fP"
Specifies an additive constant \fId\fP for the expression
\fIg*F(element) + d\fP that is computed for each element of
\fIinput_field\fP and stored in the output file.  The function \fIF\fP
and the multiplicative constant in the expression
are obtained respectively from the \fB\-F\fP and \fB\-g\fP options.
A complex constant is specified with a comma, in the form
.IB real_part , imaginary_part.
.TP
.BI \-f " field_name" "\fR [samples]"
.TP
.BI \-f " field_name" "\fR [(input field name plus suffix)]"
.TP
.B \-f \-
If this option is used once, it specifies the name of the source field
\fIinput_field\fP in \fIinput\fP.  If it is used twice, the second
time it specifies the name of the destination field \fIoutput_field\fP
in \fIoutput\fP.  The default name for the input field is "samples".
The default name for the output field is the input field followed by a
suffix identifying the function type (see \fB\-F\fP).
If the output field has the same name as some field in the input file,
the original contents of the field are lost.
A warning message is normally printed in that case.
However, if the output field is specified as "\-", the name of the input
field is used instead, and the warning message is suppressed.
.TP
.BI \-g " gain_factor \fR[1]\fP"
Specifies a multiplicative constant (gain factor) for the expression
\fIg*F(element) + d\fP that is computed for each element of the
\fIinput_field\fP and stored in the \fIoutput_field\fP.  The function
\fIF\fP and the additive constant in the expression are obtained
respectively from the \fB\-F\fP and \fB\-d\fP options.
A complex factor is specified with a comma, in the form
.IB real_part , imaginary_part.
.TP
.BI \-r " start" : "last" "\fR [1:(last in file)]"
.TP
.BI \-r " start" :+ "incr"
.TP
.BI \-r " start"
In the first form, a pair of unsigned integers specifies the range
of records to be processed.
Either
.I start
or
.I last
may be omitted; then the default value is used.
If
.IR last " = " start " + " incr,
the second form (with the plus sign) specifies the same range as the first.
The third form (omitting the colon) specifies a single record.
The \fB\-r\fP overrides the values of \fIstart\fP and \fInan\fP from 
the parameter file.
The value of
.I nan
becomes 1 +
.IR last " \- " start
(first form), 1 +
.I incr
(second form), or 1 (third form).
.TP
.BI \-t " output_type" "\fR [(same as input)]"
Specifies the type of the \fIoutput_field\fP.  Allowable values are
DOUBLE, FLOAT, LONG, SHORT, BYTE, (or CHAR), DOUBLE_CPLX, FLOAT_CPLX,
LONG_CPLX, SHORT_CPLX, and BYTE_CPLX.
The case doesn't matter:  upper is not distinguished from lower.
The default type is the same
type as that of the \fIinput_field\fP.
.TP
.BI \-x " debug_level" "\fR [0]"
A positive value specifies
that debugging output be printed on the standard error output.
Larger values result in more output.
The default is 0, for no output.
.TP
.BI \-F " function \fR[none]\fP"
Specifies a function \fIF\fP to be applied to each element of the
\fIinput_field\fP before storing \fIg*F(element) + d\fP in
the output file.  The possible functions are
\fIabs\fP (absolute magnitude),
\fIarg\fP (phase angle),
\fIatan\fP (arctangent),
\fIconj\fP (complex conjugate),