feaop.1

speech signal process tools

.\" Copyright (c) 1993 Entropic Research Laboratory, Inc. All rights reserved.
.\" @(#)feaop.1	1.3 4/1/97 ERL
.ds ]W (c) 1993 Entropic Research Laboratory, Inc.
.if n .ds - ---
.if t .ds - \(em\h'-0.2m'\(em
.TH  FEAOP 1\-ESPS 4/1/97
.SH NAME

feaop \- element-by-element binary operations on fields of FEA files
.SH SYNOPSIS
.B feaop
[
.BI \-f " in_field1"
[
.BI \-f " in_field2"
[
.BI \-f " out_field"
]]] [
.BI \-g " gain_factor"
] [
.BI \-r " range1"
[
.BI \-r " range2"
]] [
.BI \-t " output_type"
] [
.BI \-x " debug_level"
] [
.B \-z
] [
.B \-I
] [
.BI \-O " operation"
] [
.BI \-P " param_file"
] [
.B \-R
]
.I file1.in
.I file2.in
.I file.out
.SH DESCRIPTION
.PP
.I feaop
performs binary operations on numbers taken from two input files
and places the results in an output file.
For example,
it can be used to subtract values in one file from values in another,
to multiply values from two files,
or to combine pairs of real values from two files to form complex numbers.
The program accepts two input FEA files
.I file1.in
and
.I file2.in.
It combines the contents of a specified field in
.I file1.in,
element by element and record by record,
with the contents of a specified field in
.I file2.in
using a specified binary operation.
The records in the output file,
.I file.out,
are copies of records from the second input file except
that there is a field containing the results of the operation.
Normally this is a new field, different from any in
.I file2.in,
but it may replace an existing field, including the input field in
.I file2.in.
A warning is issued unless the input fields,
.I in_field1
in
.I file1.in
and
.I in_field2
in
.I file2.in,
have the same rank and dimensions.
However, processing continues
as long as the fields have the same number of elements.
The rank and dimensions of the output field,
.I out_field
in
.I file.out,
are taken from
.I in_field2.
.PP
It is possible to scale the data values in
.I in_field1
by a ``gain factor''
.I g
before using them as operands.
(See the
.B \-g
option.)
Thus this option provides a convenient way
of adding various levels of noise to a sampled-data signal.
Moreover, the roles of the operands may be interchanged with the
.B \-I
option.
So, for example, by specifying the subtraction operation, SUB,
it is possible to obtain output values of the form
.IR gx " \- " y,
or
.IR y " \- " gx,
where
.I x
is a value from
.I file1.in
and
.I y
is a corresponding value from
.I file2.in
.PP
The default data type of the output field
is selected to ``cover'' the two input types
(see
.RI cover_type (3\-ESPS)).
That is, all values of the input types can be stored in the output type.
For example, if one input field has type SHORT_CPLX,
and the other is FLOAT, the default output type is FLOAT_CPLX.
However, with the
.B \-t
option or the
.I output_type
parameter, the output data type may be chosen arbitrarily.
The rule for the default output type was chosen for simplicity;
for some operations another type
may actually be better for representing the result.
For example, PWR (raising to a power) may yield complex results
even when both operands are real.
In fact an exception to the rule is made for the operation CPLX,
whose entire purpose is to take real operands and yield complex results:
the default output type is always complex if the operation is CPLX.
The output value is what would be obtained by performing the operation
in a data type ``sufficiently large'' for the operation
(typically DOUBLE_CPLX)
and then converting to the output type by using
.IR type_convert (3\-ESPS).
However, a more direct method is actually be used internally
when the input and output types permit.
If the output type is real, the imaginary part of the result
is in effect discarded in conversion from complex to real;
in actual fact it simply is not computed.
See the discussions of the individual operations for
more information on result types.
.PP
Ordinarily,
.I feaop
starts with the first record in each file
and proceeds through the two files in step,
pairing each record from
.I file1.in
with a record from
.I file2.in
and stopping when the end of one file or the other is reached.
However, it is possible
to specify different starting points in the two files
and to restrict processing to a subrange of each file
(see the
.B \-r
option).
Moreover, with the
.B \-R
option, it is possible to reuse the data from
.I file1.in
cyclically, stopping only at the end of the data from
.I file2.in.
.PP
If either input file is "\-", standard input is used; however,
.I file1.in
cannot be standard input if the
.B \-R
option is used,
and the input files cannot both be standard input.
Aside from that restriction,
.I file1.in
and
.I file2.in
may be the same file.
If
.I file.out
is "\-", standard output is used.
The output file must not be the same as either input file;
however, it is okay to run the program as a filter by specifying
standard input for one input file and standard output for the output file.
.PP
.I feaop
copies generic header items from
.I file2.in
to the output
and preserves FEA subtype information\*-for example, if
.I file2.in
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 feaop
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
Notes on the individual operations follow.
In the formulas,
.I x
and
.I y
denote the first and second operands of the operation.
.TP
ADD
The sum of the operands,
.RI ( x " + " y ).
.TP
SUB
The difference of the operands,
.RI ( x " \- " y ).
.TP
MUL
The product of the operands,
.RI ( xy ).
.TP
DIV
The quotient of the operands,
.RI ( x "/" y ).
For integer input types, this is not an integer division
such as C and other programming languages perform on integer operands.
(An IDIV operation may be added in a later version of the program.)
The result is the best approximation to the exact quotient
that can be represented in the output type.
For example, suppose
.IR x "= 2"
and
.IR y "= 3".
The result is 0.6666..., not 0.0, if the output type is for FLOAT or DOUBLE;
when the output type is an integer type such as SHORT, the result
is the result of rounding 0.6666... to the nearest integer, 1,
not truncating to 0.
.TP
PWR
The result of raising
.I x
to the power
.I y,
.if n .RI ( x "^" y ).
.if t .RI ( "\x'0'x\v'-24u'\s-3\|y\s+3\|\v'24u'" ).
If
.I x
is 0, then the result is 1 if
.I y
is 0, 0 if
.I y
has a positive real part, and undefined otherwise.
If
.I x
is not 0, the result is mathematically defined by
.RI "exp (" y " log " x ).
The result may be complex even for real operands.
For example \-4 to the power 0.25 yields the result
.RI "1 + " i.
If the result type is specified as (or defaults to) a real type,
the imaginary part is lost, and the result becomes 1.
.TP
CPLX
The complex number with given real and imaginary parts,
.RI ( x " + " iy ).
This operation is mainly intended for use with real operands.
If complex operands are given,
the result is that given by the formula,
though the real and imaginary parts of the result
are no longer equal to
.I x
and
.I y.
.PP
While this program subsumes the main functionality of both
.IR addsd (1\-ESPS)
and
.IR multsd (1\-ESPS),
it isn't yet competitive with them for speed on their special domain:
single-channel FEA_SD files.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-f " field" " \fR[(input:) samples]"
.TP
.BI \-f " field" " \fR[(output: derived from input field names)]"
.TP
.BI \-f " \-"
This option may be used at most three times.
If used once, it specifies the name of the source fields
.I in_field1
and
.I in_field2
in the two input files\*-the same name for both.
If used twice, it specifies
.I in_field1
the first time and
.I in_field2
the second time.
If it is used three times,
the third occurrence specifies the name of the result field
.I out_field
in the output file.
The default name for the two input fields is "samples".
The default name for the output field normally consists of the names
of the first input field, the operation (see
.BR \-O ),
and the second input field, in that order,
connected by underscore characters\*-for example "samples_ADD_samples".
The field names are interchanged if the
.B \-I
option is used.
If the output field has the same name as a field in the second 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 second input field is used instead,
and the warning message is suppressed.
.TP
.BI \-g " gain_factor" " \fR[1]"
Specifies a constant (gain factor)
by which each element of the first input field is multiplied
before being used as an operand.
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"
Determines the range of record to be taken from one or both input files.
In the first form, a pair of unsigned integers gives the numbers
of the first and last records of the range.
(Counting starts with 1 for the first record in the file.)
Either
.I start
or
.I last
may be omitted; then the default value is used:
1 for
.I start
and the last record in the  file for
.I last.
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 implied value of
.I nan
is 1 +
.IR last " \- " start
(first form), 1 +
.I incr