?preface
This file is intended for display by the gfft 'help' facilities. However,
it also currently constitutes the most complete gfft manual, so, if you
really want to read a lot about GFFT, you might want to read it with
MORE or search for key strings using your favorite searching,
text-editing, or searching program.
The format is intended to be compatible with that used by the GNUPLOT
help/manual file, so one day I will be able to print out hardcopy
documents my massaging this file and using troff, tex, postscript, etc.
(A suitable massage might even render it in AmigaGUIDE format).
?organization
This document is organized as follows:
Preface
Organization
Introduction
General Topics
Workbench Gadgets
CLI Commands
Appendixes
?introduction
(In the following discussion, additional help topics are highlighted with
angle brackets like this: >introduction<. A list of additional help
>topics< is also available. These topics may be displayed using the HELP
requester or command.)
GFFT is an FFT-based spectrum analysis program with many features. It is
intended to provide higher resolution and higher quality than most
real-time FFT-based spectrum analyzers, and, in conjunction with a
suitable plotting program (such as GNUPLOT, a separate program written by
others which GFFT can invoke and control) it can produce high quality
spectrum plots on screen or paper (including the output of Postscript or
TeX files if desired). GFFT can be run either through a Workbench
graphical interface or from the CLI in either interactive or batch (single
command) modes.
GFFT can also do such things as control GNUPLOT to plot several spectra on
the same screen or page (see >Workbench Plot-Combine< or >CombinePlots<),
and re-plot previously stored spectrum data files (see >Workbench
Spectrum-File-Open< or >Open<).
WORKBENCH USAGE
---------------
From the Workbench, GFFT may be started by double-clicking on its icon.
The GFFT Dialog Window then appears. Within the GFFT Dialog Window, you
may select sample files to analyze either by using the ASL file requester
(which comes up after you click on the 'SELECT' gadget), or by entering
their name(s) into the 'Sample File' string gadget. Note that the ASL
file requester requires Workbench 2.0 or higher.
If you prefer, you may use 'extended selection' to select one or more
sample files in advance. This is done by first single-clicking on the
GFFT icon, and then holding down the Shift key while clicking on a series
of one or more icons representing the sample files you wish to analyze.
You double-click on the last sample icon selected to start GFFT.
GFFT is also distributed with a sample whose icon automatically invokes
GFFT (i.e., the icon is a project icon which specifies GFFT as its tool).
Within the GFFT dialog window, you use the 'OK' button to actually begin a
spectrum analysis, the 'NEXT' button to advance to the next selected
sample file (if more than one was selected on the Workbench), the close
gadget (at the top left of the window border) to terminate GFFT, and the
'CLI' button to continue the GFFT session in CLI mode (if you need to
activate one of the few features available only in the GFFT CLI
interface). (You can then return to the GFFT Dialog Window by giving the
'Workbench' command.) There are also many other gadgets in the dialog
window which allow you to view and adjust parameters and use other
features. Notably, the '3D-Time' button brings up a requester allowing
you to do 3D analysis using time as the third dimension, and the 'CAL'
button brings up a requester allowing you to specify one or more
calibration files to be applied to the spectral data.
Help for any gadget in the GFFT Dialog Window may be displayed by holding
the CTRL key when clicking on that gadget. (String gadgets may need to be
de-selected first.) Additional information may be displayed by using the
Help Requester which comes up when you click on the 'HELP' button.
If you click the Version/Copyright button, a requester providing
information about the author, your rights to modify and distribute GFFT,
additional services available, disclaimers, and so on will be displayed.
The GFFT icon or the sample icon may specify tooltypes which are treated
as GFFT commands to be executed before the the GFFT Dialog Window is
displayed. The order of execution is as follows: (1) execute the .gfft
startup file (see below), (2) execute tooltypes in the GFFT icon, (3)
execute tooltypes for the sample icon. If more than one sample icon was
selected, the tooltypes for each sample icon are processed just before the
dialog session for that sample is started. GFFT tooltypes are ignored if
GFFT is started from the CLI. Tooltype may be specified in the typical
"tooltype" format, for example:
bins=1024
Tooltypes beginning with semicolon (;), pound sign (#), exclamation point
(!), or left parenthesis (() are ignored by GFFT, as are usual EXEC
tooltypes (they are processed by EXEC before GFFT starts), and the
tooltype 'FILETYPE.' You will some examples of useful GFFT tooltypes
in the default GFFT.info icon. (They are commented out by default.)
CLI USAGE
---------
From the CLI, GFFT may be run as an >interactive< program which prompts
for each argument or command, or as a >batch< program for which all
arguments and commands have been specified as command-line arguments.
If no arguments are given, or, if the WORKBENCH argument is given, GFFT
will start in Workbench mode.
If the CLI argument is given, GFFT will start in CLI-interactive mode.
Otherwise if one or more arguments are given, GFFT will run in CLI-batch
mode.
For more information about the CLI commands available in GFFT, give the
'Help' command while running GFFT in CLI-interactive mode, or give the
batch mode question-mark (?) command.
shell> gfft ?
OR
sys> gfft CLI
gfft> help
From the Workbench, you can go back to the CLI session (if it was
interactive) by clicking the CLI button.
sys> gfft
[partial workbench session ended with click on CLI button]
gfft> ok
gfft> quit
Since GFFT is designed to work in conjunction with GNUPLOT, you should
install GNUPLOT before running GFFT. You should also follow the other
instructions included in your GFFT distribution in the file named
INSTALLATION.
STARTUP FILE
------------
When starting, GFFT looks for a file named .gfft either in the current
directory (which is the one in which GFFT itself is found, if started from
the Workbench), or if not found there, in the system S: directory. This
file can contain a series of GFFT CLI commands, one per line. Lines
beginning with ; # or ! are ignored, as are blank lines. This file is
executed before GFFT does anything else. By using a .gfft file, you can
'customize' the GFFT defaults and other features to match your application
or environment.
HOW TO LEARN MORE
-----------------
If spectrum analysis is new to you, consider reading the HELP topic
>data-windowing<, but don't be discouraged if it is a little hard to
understand at first.
Also, check the >References< topic.
?General-Topics
?Topics
Help is also available for any additional topic named <topic> by entering
help <topic>
From the WORKBENCH, help is available for these topics through the
HELP requester which comes up after the HELP button has been clicked.
The additional topics are:
introduction topics interactive-CLI batch
code contributors financial contributors idea contributors
accuracy speed memory references
floating-point-errors CLI-commands
GFFT-Dialog-Window Workbench-Message-Display
More-About-Bins temporary-files Data-Windowing
zoom
?zoom
GNUPLOT, which GFFT uses, does not have an interactive 'zoom' capability.
But, using GFFT it is possible (if not extremely fast) to zoom in or out
from a spectrum using the following gadgets:
Low Freq (Low Frequency)
High Freq (High Frequency)
Low Y
High Y
(The 'Low Y' and 'High Y' gadgets are available in the Calibration and
Magnification requester which comes up when you click on the 'Cal & Mag'
button.)
Once you modify one or more of these parameters to explore the part of the
spectrum you are most interested in, you need not repeat the entire
analysis; it is only necessary to repeat the plotting phase, and this is
accomplished through using the RePlot button.
If you are using the interactive CLI interface, the corresponding commands
are LowFrequency, HighFrequency, LowY, HighY, and RePlot.
See the help information for these buttons or commands for further
discussion.
?More-About-Bins
?Data-Windowing
[This is somewhat technical, but may help you understand some of the
parameters in GFFT. If you don't understand it, don't worry; you can
usually just use the GFFT defaults, adjusting the Bins parameter downward
to about 1024 or less if you are short on memory.]
When dealing with functions that are sampled at evenly spaced intervals in
time, it is appropriate to use the 'discrete Fourier transforms.' These
equations map N complex numbers from the 'time domain' to the 'frequency
domain' (and back again). The 'fast Fourier' techniques use various
symmetries to reduce the computation times from O(N times N) to O(N log
N), but one price paid for this is that N must be a integer power of 2.
This is also true if our N is the number of real sampled data points, or
one-sided (positive frequency only) frequency 'bins,' though it will
take 2 real data points to yield an amplitude estimate at each positive
frequency (which has been averaged with the amplitude at a corresponding
negative frequency).
Another problem with Fourier transformation 'periodograms' (arrays of
frequency values computed from time-sampled values) is that the variance
(random error) can be quite high.
We can deal with both of these problems by using data windowing. Rather
than choosing the largest N (being a power of 2) that we could use with
our number of real sampled data points, we may choose a smaller N (still
being a power of 2), compute a series of periodograms, one from each
successive segment or 'window' of N times 2 data points, and then average
their results. This reduces the variance considerably (at the price of
lowering the number of frequencies in the averaged periodogram, which is
frequently not a problem). Next, we can overlap the last full window with
another window such that any remainder of data points are accounted for.
In fact, there is no reason why we can't overlap ALL of the windows by
50%, as that can reduce the total variance 9/11 as much as having twice as
much data to average over to begin with (see Press, et. al, 1988, page
445).
Unfortunately, there are some problems with having N's of finite length,
which is even exacerbated by averaging periodograms from smaller windows.
(Ideally, we would have an infinite N.) We tend to get spurious
'sidelobes' around each spectral peak. This occurs because the window
truncates the real signal, usually at some non-zero point. Sidelobing
(and other artifacts) can be reduced by using more sophisticated windows.
The trivial window type (assumed above) is rectangular, we simply take the
data points in each window as-is. This is the same as if we multiplied
each of the data points within our window by 1, and all data points
outside the window by zero. There are a huge variety of window functions
which begin at a low multiplier or zero at the beginning of the window,
ramp up to 1 in the middle, and then return to a low multiplier or zero at
the end. Each of these window 'types' has tradeoffs, but the Rectangle
window has the worst tendency to generate sidelobes because it truncates
the signal on both sides most abruptly.
GFFT includes the following window types.
>Rectangle<
>Triangle<
>Parzen<
>Welch<
>Hann<
>Hamming<
>74-dB-Blackman-Harris<
>92-dB-Blackman-Harris<
These are listed roughly in order of increasing ability to suppress
spurious sidelobes.
Refer to the HELP message provided for each one of these for further
information. See also the HELP messages for >Bins<, >Overlap<, and
>Parseval<.
?Accuracy
?Speed
?Floating-Point-Errors
GFFT uses double precision floating point for the values related to time
and frequency, and single precision for the values related to amplitude
(or power, etc.). In the standard version, the Motorola Fast Floating
Point (FFP) math library is used--this reduces the precision of double
precision to approximately that of single precision, and (seems to) reduce
the precision of single precision somewhat also. The benefit is about a
4x improvement in overall (!) performance without a floating point unit
(FPU). Despite limited precision, I believe FFP is good enough for most
graphical purposes, and it is probably superior in accuracy to using
scaled integer arithmetic.
On systems with an FPU, the GFFT-FPU version is another 10% or more
faster, and it doesn't compromise the double precision and single
precision accuracy in any way.
The standard FFP version doesn't handle errors such as divide by zero very
well, but GFFT attempts to detect problems like this before they would
occur so they shouldn't occur often.
The FPU version uses in-line FPU code, which I have found to be much
faster than using the IEEE library. Even on a machine with an FPU, using
the IEEE library is actually slower than using the FFP library which
doesn't even use the FPU.
?Memory
?More-About-Bins
?Temporary-Files
The amount of memory GFFT allocates depends mainly on the number of Bins
used. If you are having trouble with running out of memory, try using a
smaller number of bins. By default, GFFT will use as many bins as can be
meaningfully used on the sample file being analyzed. Use the Bins command
or the Bins gadget to adjust the set the number of bins. 1024 is a
typical number of bins people use, though I prefer to use more. (The
number of bins determines your frequency resolution. However, when fewer
bins are used, more averaging is done, so the results may be more
accurate. GFFT will always try to use all data present in the most
intensive way, unless limited by options such as Frames and NoOverlap.)
Note that the number of bins must be a power of two, but GFFT will round
up to the next power of two if you specify a value which is not a power of
two.
There is also a 'Savememory' command available from the CLI which will
reduce the dynamic memory requirements of GFFT somewhat, while increasing
the fft computation times slightly on most processors. The difference in
execution time is barely measurable in most cases.
GFFT also stores temporary command files in RAM: and temporary data files
in T:. During a GFFT session, temporary data files may accumulate in T:,
and thereby fill up memory (if T: is assigned to RAM:T, as is typically
done.) You may reduce the memory requirements for temporary data files by
reassigning T: to your harddrive, as in any of the following examples (use
whichever is more appropriate):
Assign t: dh0:t
Assign t: dh1:t
Assign t: work:t
Assign t: df0:t
Alternatively, you can purge unused files from T: as necessary. Upon
termination, GFFT will delete all temporary data files from T: for you.
You can also choose to use named data files (using the Write command or
the Spectrum File gadget) instead of temporary data files, and store them
in particular directories on you harddrive or floppy disk. In this case,
temporary data files will not be used.
The temporary command files stored in RAM: are so small as to be of little
consequence. They are deleted upon the termination of GFFT.
GFFT may leave some extra libraries in ram upon termination. If you are
very short of memory, you may choose to use the following command (in
AmigaDOS 2.0 and later) to remove them after terminating GFFT:
Avail /flush
?Interactive-CLI
To run GFFT in the CLI 'interactive' mode, simply enter the command 'GFFT
CLI' (without the apostrophes) at you shell command prompt. If you
specify any other arguments in the GFFT command line, GFFT will start in
'batch' mode instead. For example:
shell> gfft CLI
GFFT> read pianolowc.iff
GFFT> ok
[A spectrum plot is shown.]
GFFT> quit
shell>
In interactive mode, GFFT will display a verbose header with copyright and
other information, and then begin prompting for additional commands with a
GFFT> prompt. If you would like a list of available commands, enter the
'help' command. Note that any command may be abbreviated to its minimum
unambiguous string, and GFFT is not case sensitive regarding commands.
Here is a sample session:
GFFT> read piano.iff
GFFT> ok
The OK command (which has the alias GO) actually starts the fft
processing. If no file has been specified, or there is other incomplete
or invalid information, GFFT will give an error message and return another
prompt, so that you may make corrections. Note that if the input file is
unformatted, you must specify the sampling rate using the 'rate' command.
For large sample files, it is also advisable to specify a specific number
of bins with the 'bins' command, or else GFFT will attempt to use the
maximum number of bins that could be useful with the number of data points
(or 'frames') in the file and other parameters. To see a list of most of
the current parameter settings, use the 'ShowSettings' command.
In interactive mode, the Plot option is turned on by default. If you do
not specify a spectrum file with the Write command, GFFT will create (but
not delete) a temporary file for you, and run GNUPLOT automatically to
plot the spectrum when it is completed. Alternatively, you can specify a
file to write the results to using the Write command, and disable Plot
mode with the NoPlot command if you didn't want to see the plot now.
Most commands actually set parameters rather than initiating any
particular action. However, it is not necessary (or possible, currently)
to use an explicit 'set' command; it is just implied. Thus, to enable
plot mode, you enter the command 'plot' instead of 'set plot mode.' Then,
plotting will be performed during the execution of the 'OK' command.
?Batch-Mode
?Batch
To run GFFT in batch mode, enter the command 'GFFT' followed by a series
of GFFT commands as they would be entered in 'interactive' mode. A
fairly large number (around 30 or so) commands may be entered in this
fashion, on several lines (so long as you do not press RETURN unescaped).
When you have entered all the commands that you wish gfft to process,
enter RETURN. GFFT will process all the commands possible, after
which your command prompt will be returned.
You can get a list of the available GFFT commands in batch mode by using
the question-mark (?) command, i.e.:
gfft ?
Unlike 'interactive' and 'workbench' modes, plot mode is disabled by
default in batch mode. You must specify 'plot' explicitly if you want a
plot to be created at the end of fft processing.
Also, an 'OK' command is usually not required in batch mode; it is implied
by the end of the command list if there is a read not followed by an OK
command.
Batch mode is intended to be an 'Amiga' compliant CLI mode (Commodore
discourages interactive CLI programs like GNUPLOT), and is particularly
useful for doing a series of analyses. A command file may be written and
then executed as a CLI script if desired. For example, you could write
a script like this:
gfft read white write white.fft bins 8192 lowf 0 highf 200 psd
gfft read white append white.fft bins 2048 lowf 200 highf 400 psd
gfft read white append white.fft bins 1024 lowf 400 highf 800 psd
gfft read white append white.fft bins 512 lowf 800 highf 1600 psd
gfft read white append white.fft bins 256 lowf 1600 highf 3200 psd
gfft read white append white.fft bins 128 lowf 3200 highf 6400 psd
gfft read white append white.fft bins 64 lowf 6400 psd
This would append a series of fft 'bands' to a output file named white.fft,
with successively lower resolution at higher frequencies (desireable for
logarithmic display of the frequency axis). (Note that an alternative
approach would be to use 'SmoothingSegments' with 'LogX' enabled.)
?Workbench Low-Frequency
The Low-Frequency gadget allows you to select the lowest frequency to be
output (and plotted, if applicable). By default, GFFT outputs and plots
the lowest non-zero frequency, and this is shown in the gadget if it can
be computed. You may enter zero or any integer or floating point number
into the Low-Frequency gadget.
Although the FFT process yields a value for the 0 frequency (e.g. D.C.),
typical FFT analyzers do not display it because it may display some offset
caused by the sampler. With GFFT, this is also the default, but you may
also choose to display the zero frequency by entering 0 into the
Low-Frequency gadget.
If no Low-Frequency has been entered, GFFT will display the lowest
frequency which will be plotted for each file, which depends on the
sampling rate, number of bins, and other factors. This default low
frequency is the same as the spacing between frequencies in the FFT, i.e.,
the frequency resolution.
Once you enter a new Low-Frequency it will remain in effect for the
current Sample File and any additional files processed in the same GFFT
session. However, you may restore the default by deleting the number
shown in the Low-Frequency gadget and pressing RETURN.
Note that a specified Low-Frequency is handled differently by the RePlot
button than by the OK and ReOutput buttons. See the help for the RePlot
button for further details.
?Workbench High-Frequency
The High-Frequency gadget allows you to select the highest frequency to be
output (and plotted, if applicable) up to the 'Nyquist frequency,' which
is one-half of the sampling rate. Any positive number (integer or
floating point) may be given as an argument. If you enter a number higher
than the Nyquist frequency, it will have no effect (except during RePlot,
see below). If no number has been entered, the default high frequency--
the Nyquist frequency--is displayed if it can be computed.
Once you enter a new high frequency it will remain in effect for the
current Sample File and any additional files processed in the same GFFT
session. However, you may restore the default by deleting the number
shown in the High-Frequency gadget and pressing RETURN.
Note that a specified high frequency is handled differently by the RePlot
button than by the OK and ReOutput buttons. See the help for the RePlot
button for further details.
?Workbench Smoothing
Using the Smoothing gadget, you can specify that the output be 'smoothed'
or averaged over a certain number of 'smoothing segments.' To do this,
enter the number of segments you wish to used into the gadget. (This
works best if the number of segments is much smaller than the number of
bins used). The number of of segments you specify is used to span the
range from the lowest non-zero frequency to the Nyquist frequency. To
cancel smoothing, press the NO button immediately to the right of the
smoothing gadget, or delete the number in the Smoothing gadget.
Without smoothing, if you plot with a large number of bins, or with LogX
on, you may find that the left or right side of the scale 'blooms' with a
wide range of values. Rather than 'pixel averaging,' GNUPLOT shows the
effect of plotting a line to each and every data point--even if many such
points occur within one vertical line of pixels. SmoothingSegments can
be used to eliminate this 'blooming' effect, simulate 'pixel averaging,'
and give you a more easily interpretable curve (though some important
actual detail may be lost!).
If LogX is enabled, the mesh applied to the output will be logarithmically
scaled. The combination of using LogX, SmoothingSegments, and a extra
large number of Bins is especially recommended for analysis using random
noise (e.g. white or pink noise) and/or whenever LogX is used.
The smoothing technique is very simple. A mesh of smoothing segments is
laid on top of the FFT bins, and for each smoothing segment containing
one or more data points, the average Y (amplitude) and X (frequency) values
are computed, and these become the X and Y values that are written to the
output file. If there is only one data point within a smoothing segment,
it is unchanged by this procedure. If there is no data point within a
smoothing segment, no data point will be output.
(If LogX is enabled, it is very possible that there will not be as many
data points as the number of segments you have chosen. For example, given
4096 bins and 400 smoothing segments, only about 225 points will actually
be produced because the actual data points at the lower frequencies are
farther apart than the smoothing segments, even though there are many
data points per segment at the higher frequencies. This does not happen if
LogX is not enabled.)
If SquaredSmoothing button (Sq) is selected, the averaging of the Y values
is done by taking the positive root of average of the sum of the squared Y
values.
I am aware of much more sophisticated smoothing or 'convoluting'
procedures which may have greater theoretic validity (e.g., see S. P.
Lipschitz, T. C. Scott, and J. Vanderkooy, 'Increasing the Audio
Measurement Capability of Analyzers by Microcomputer Postprocessing,'
Journal of the Audio Engineering Society, Volume 33, Number 9, September
1985...their technique simulates 1/3 octave bandwidth digital filters
which is useful in that it supposedly approximates human auditory
limitations), but these are also much more complicated. The present
technique is workable and useful, though it may be somewhat lacking in
theoretic validity (though it is not without precedent), and the results
should be interpreted with some caution (you are probably not seeing all
the real features that are there--but then that is true with any
smoothing technique).
?Workbench Smoothing-NO
The 'Smoothing-NO' button cancels smoothing. When clicked, any number you
may have entered into the smoothing gadget is cleared. You can achieve
the same effect by deleting the number in the smoothing gadget. By
default when GFFT is started, smoothing is turned off, and the
Smoothing-NO button will be selected.
See help for the Smoothing gadget for more information about the smoothing
used by GFFT.
?Workbench Smoothing-Squared
The Smoothing-Squared button changes the operation of the Smoothing gadget
(see) slightly. It has no effect if smoothing segments are not being used.
This is a toggle button which can be clicked on or off, but it has no
effect unless a number of smoothing segments has been entered into the the
Smoothing gadget.
With Smoothing-Squared selected, the averaging of the Y values is done by
taking the positive root of the average of the sum of the squared Y
values.
I have found this to make a nearly negligible difference in practice, but
your experience may vary. I'm not sure which averaging approach is more
'valid' (I suspect it depends on whether you are plotting logarithmically
or not).
?Workbench Mean
The Mean button determines whether GFFT will write Mean (average) or
summed values. By default, GFFT will write Mean values. In other words,
by default, Root Mean Square (RMS) Amplitude or Mean Square (MS) Power
values will be written.
I do not recommend the use of the 'summed' values (as with Mean
deactivated) except for special debugging purposes.
?Workbench More-Help
Getting help for any button or string gadget in GFFT is easy...simply
click on that button or gadget while holding down the CTRL key.
(The CTRL key is normally found to the left of the Caps Lock key.)
There is one bug here. If a STRING GADGET has ALREADY been activated, you
must deactivate it first before requesting help for it. To do this,
simply click anywhere else on the window (such as on the window
background). Then, you may click on the string gadget while holding the
CTRL key, and the help message will be displayed. It is not necessary to
deselect ordinary buttons first. Help is not available for the message
indicator on the bottom of the GFFT Dialog Window (sorry; I tried).
If you would like more information about the author of GFFT, how you can
support GFFT development, your rights regarding the use and distribution
of GFFT, the disclaimer, and other related information, click on the
Version/Copyright button on the top of the main GFFT Dialog Window. (Of
course, you must exit from this HELP requester first by clicking on the
'...OK' button on the bottom right.
The HELP requester also provides two other 'canned' messages which you may
display by clicking on the 'Intro' and 'Topics' buttons on the bottom row.
The message for 'Topics' is a list of additional topics. You may enter
the name of any HELP topic into the string gadget and press RETURN.
Note that each message will be displayed in its own window and runs in its
own shell process, and, if you re-size or move the windows, you may display
more than one message at the same time. You may also use or even exit
from GFFT while still reading one or more help windows. Isn't
multitasking wonderful?
GFFT uses MORE to display help messages. MORE must be installed either
in the usual place (sys:utilities), C:, or in the same directory as
GFFT in order to be used by GFFT. Unfortunately, aliases for MORE
will not work. However, if you would prefer to use some text reader
other than MORE, you can either create a link or a copy of that reader
in any of these three locations. Links (made with the makelink) command
are preferable, as they take a minimum of storage, but they must be
on the same device or partition as the actual program itself. A link
in the directory C: to a reader named MORE2 would be created with the
following command:
makelink c:more c:more2
Running GFFT basically requires three steps: selecting a file, selecting
options (or just using the defaults), and then clicking the 'OK' button at
the bottom right of the GFFT dialog window.
?GFFT-Dialog-Window
Almost everything in the GFFT dialog window is a button or string gadget.
One notable exception is the Message Display at the bottom. This gives
information about the current GFFT operational status, and possibly
indicates what user action is currently most desireable. (If an FFT
analysis is being performed, the message 'Performing FFT analysis...'
will be displayed. This could take a considerable amount of time. During
this time, you will should not attempt to operate on any other GFFT Dialog
Window gadgets.)
When clicked, the Version/Copyright button at the top will bring up a
requester providing more information about the author of GFFT and the
copyright and disclaimer.
For further information on the Message Display, refer to help topic
>Workbench-Message-Display<.
?Workbench 3D-Time
The 3D-Time button brings up the 3D-Time requester which allows you to
set parameters associated with the display of how a spectrum varies over
time. Further information is available through the 'Help' button in that
requester.
?Workbench 3D-Time Help
The '3D-Time' facilities of GFFT are intended to enable you to show how a
spectrum varies with time. GFFT is very flexible in how it enables you to
do this. The results can also be plotted in 3 dimensions by GNUPLOT where
z is the axis of time.
If you would like to try it now, rather than reading about it first, just
click the 'Auto Set-Up 1' button, which will set up the 3D-Time parameters
to work for many, if not most, sample files. Then, click '...Done,' then
select a sample file to analyze (if you haven't done so already), and
click 'OK.' If it doesn't work, you'll just have to read more.
The basic model is as follows: The sample frames are divided into segments
called 'Time Segments,' and a spectrum analysis is performed on each Time
Segment. Time Segments can be overlapped, and the overlap can either be
specified as a fraction of the size of each Time Segment ('Time Segment
Overlap') or as the number of frames by which each Time Segment is ahead
of the previous one ('Time Segment Offset'). By default, the Time Segment
Overlap is set to 0.5 (i.e. 50%) and the 'Time Segment Offset' is computed
automatically. Then, either the number of time segments can be specified
(this is the 'Time Segment Count') or, their size can be specified (this
is the 'Time Segment Size') whichever is more convenient or useful to your
application.
One of the two parameters Time Segment Count and Time Segment Size must be
set. When either of these two parameters is set, any previous value of
the other one is cleared.
Time Segment Overlap has a default value of 0.5. If Time Segment Offset
is set, it supercedes Time Segment Overlap (whose value is then hidden).
If you set any of the above 3D-Time parameters, the toggle button 3D-Time
On is activated.
You may also adjust the X Rotation and Z Rotation factors used by GNUPLOT
in rendering the 3-d plot, and/or select Hidden3D display, which hides all
lines which are behind the 3D surface. (This feature may not work with
versions of GNUPLOT prior to 3.4.)
The Reset button clears Time Segment Count, Time Segment Size, Time
Segment Offset, and 3D-Time On, and Time Overlap, X Rotation, and Z
Rotation are set to their default values. Any of these values may also be
cleared or defaulted by deleting all characters in each string gadget and
pressing return.
You may advance to the next string gadget in this requester simply by
pressing RETURN.
Note that Time Segments are distinct from the FFT 'segments' used in a
flat spectral analysis and from the FFT analysis within each Time Segment.
If each Time Segment is large enough relative to the number of Bins, there
may be more than one FFT segment within each Time Segment, the results of
which are averaged to reduce the variance. Within each Time Segment, the
usual 'Bins,' 'Overlap,' 'Pad,' and window shape parameters still apply,
so the full flexibility of a flat GFFT is available (though the maximum
number of bins possible may be reduced). Only one parameter available to
a flat analysis is unavailable for analysis within each Time
Segment--StartFrame (a parameter which may only be set from the CLI).
StartFrame will apply to the input file as a whole and not to each Time
Segment.
In cases where 3D-Time analysis reduces the number of bins possible, the
use of high performance window shapes such as Hann or 74dB Blackman-Harris
is recommended.
Examples:
1. Suppose you just want a rough idea as to how the spectrum in a fairly
small sample file (such as an instrument) varies over time, and are
willing to use the default Time Segment Overlap, and would simply like
each segment to use the maximum Bins size possible (and with overlap, if
possible). You might figure 5 time segments would be adequate to get a
rough idea, yet would not be too many considering the number of frames.
(If you have a very small sample file, you might have to use only 2 or 3
Time Segments. Increasing the number of Time Segments will reduce the
maximum possible number of bins, so there is a trade-off here which is
critical for small sample files.)
Set the Time Segment Count to 5, and click 'Done.' In the main Workbench
Dialog Window click on 'Bins-MAX' and/or 'Overlap' if they had previously
been turned off.
2. Suppose you wish to divide the sample file into non-overlapping time
segments which could each be analyzed with 1024 bins (with no overlap or
padding within each time segment).
First set the Time Segment Size parameter to 2048, then set the Time
Overlap parameter to 0. (For non-complex data, there must be 2 sample
frames for each FFT bin.) This is sufficient to define this analysis, and
3D-Time On is selected automatically, so then you click 'Done.' If you
have not already set the number of Bins explicitly, you will notice that
it has been automatically set to 1024. Since exactly 2048 frames are
available for each FFT analysis, no overlap will be used regardless of
whether the Overlap button in the main GFFT Dialog is activated.
3. Suppose you wish to have each Time Segment to be ahead of the previous
one by exactly 1000 frames. (This might apply if you want the z axis to
have increments of 0.1 second, and the sampling rate was 10,000.) You
consider some Time Segment Overlap of approximately 0.5 to be acceptable,
but you would like an analysis with 1024 frequency bins.
Set the Time Segment Size to 2048 and the Time Segment Offset to 1000.
4. Suppose you have a VERY large sample file, and would rather not
analyze the whole thing, but would like a 'spot' analysis every 100,000
frames. You would like to have 1024 bins used in each analysis, but would
prefer to reduce the variance of each 'spot' spectrum by averaging 4
overlapped segments within each time segment.
Note that the overlap used for a flat spectral analysis and within each
Time Segment is fixed at 0.5 and cannot be changed (though it can be
turned off). Therefore, 2 overlapping FFT segments would occupy 1.5x the
space of one segment, 3 overlapping segments would occupy 2x, and 4
overlapping segments would occupy 2.5x if exactly these numbers of frames
are available.*
Set the Time Segment Offset to 100,000, and the Time Segment Size to 5120
(2.5 x (1024 x 2)). Click 'Done...' and set the Bins gadget (in the main
dialog window) to 1024.
(*Actually, 2 overlapping segments will be used for any number of frames
greater than 1 segment but less than 2 segments, 3 overlapping segments
will be used for exactly the number of frames in 2 segments, 4 overlapping
segments will be used for any number of frames greater than 2 segments but
less than 3 segments, and so on.)
?Workbench Ok
The OK button initiates an FFT according to all the specified parameters.
The selected Sample File will be read and transformed, the selected
Spectrum File file (if any) will be written to (otherwise, a temporary
file will be used), and a PLOT will be produced (if that option is
enabled).
This command is invalid if any parameters have been set incorrectly, if no
sample file has been selected, or if plot mode is disabled AND no named
(permanent) spectrum file has been selected.
Example:
1. select sample file using the requester that appears after pressing
SELECT in the Sample File row (requires 2.0+) or enter
filename directly in Sample File Gadget
2. plot is enabled by default in workbench mode; re-enable if disabled
by clicking on it
3. click the OK button
Note: depending on the size of the sample file, the number of bins and
other parameters you have set, as well as the CPU and/or FPU resources
available, an FFT analysis could take anywhere between a fraction of a
second to several weeks. So, if you don't get an immediate response, have
faith that GFFT is working, not hanging. If there is any error, GFFT
should let you know right away. If it is working away on your file, and
the number of bins is small compared with the size of your sample file,
you will see the disk light flickering occasionally.
While an FFT is being performed, DO NOT click on any other gadgets in the
GFFT Dialog Window.
?Workbench Cal-&-Mag
The 'Cal & Mag' button brings up the Calibration and Magnification
Requester which allows you to specify calibration files and values for
quantization, low Y, and high Y.
A help button is provided within the Calibration and Magnification
Requester which provides more information.
?Workbench Calibration Help
The Calibration and Magnification requester enables you to apply a
'calibration' to the output of GFFT. In this way, you can compensate for
the frequency response of your sampler, microphone, noise source, etc.
Any number of calibrations may be in effect at the same time. Each time a
filename is entered into the Calibration or DbCalibration gadgets, a new
calibration is linked into the current list of calibrations (even though
only the last one entered into each gadget is shown). The entire list is
canceled by clicking the Cancel All Calibrations button. A message window
shows the number of calibrations currently in effect, and indicates
whether a calibration file is currently being processed...which can take
some time.) (More about these gadgets follows...)
This requester also includes the Quantization gadget, into which a
quantization value can be entered. Quantization can be canceled by
clicking the Cancel button following the Quantization gadget, or by
erasing the value shown. (More about this gadget follows...)
This requester also includes the Low Y and High Y gadgets, which allow you
to adjust the Y range used in plotting. You may restore either or both of
these to the default (autoscaling) by deleting the value shown, or by
clicking the Cancel buttons which follow each one. It is best to set both
of these gadgets if setting either one. (More about these gadgets
follows...)
The Calibration gadget allows you to enter a calibration file to be
applied to the spectrum data before output. The DbCalibration gadget
allows you to calibrate using a file in which the amplitudes are scaled in
dB. Calibrations and DbCalibrations may be applied to spectrums in any
combination regardless of whether the final output is scaled in dB or not.
Each of these gadgets has a small 'S' button; when the S button is
clicked, a file requester comes up to allow you to select the file. (This
file requester requires Workbench 2.0 or higher; otherwise, you will have
to enter the name into the corresponding gadget yourself.)
The calibration file(s) should be in the same format as the spectrum files
produced by GFFT itself. Each line (terminated by newline) should have a
frequency value, any number of spaces, and an amplitude value (NOT a
'power' or squared amplitude value!). The frequencies must be in
increasing order, and the range of frequencies must be equal to or greater
than that to be output by GFFT (see warning below). Lines beginning with
one of the following characters are considered to be comments:
# ; !
If a spectrum is calibrated by itself, the result should be a straight
line at either 1.0 or 0.0 (for dB output). Actually, due to slight
rounding errors, the actual result will be close to, but not exactly these
ideal values (e.g. 0.9999998). Given that Gnuplot will always scale the
output to the maximum Y magnification, small differences between these
values will be shown from the top to the bottom of the Y scale. To
correct this effect, consider setting the LowY and/or HighY values
explicitly to increase the vertical range, which will make the spectral
line look much flatter. Quantization can also be used, but it has some
other disadvantages.
Calibration as used here is unrelated to true complex 'correlation,' which
is not currently available in GFFT. Calibration has somewhat limited
accuracy and validity, but is still probably a feature worth having for
its usefulness. Note that in between points specified in a calibration
file, simple linear interpolation will be used by GFFT. If a frequency
higher than the highest calibration frequency is output by GFFT, it will
be calibrated by the value for the highest calibration frequency, and any
frequency lower than the lowest calibration frequency will be calibrated
by the value for the lowest calibration frequency. In other words, GFFT
uses simple horizontal extension of the calibration curve rather than
extrapolation. (WARNING! This could be dangerous if interpreted
improperly! Remember to provide calibrations over a range equal to or
greater than the range to be output by GFFT.)
One way to use Calibration is to perform a GFFT analysis on your signal
source itself, and then apply that result as a 'calibration' to your test
measurements. Another way is to write frequency response data provided by
a calibration laboratory (such as for a microphone) into a suitable
calibration file. In fact, both kinds of calibration can be used at the
same time.
The High Y gadget allows you to set the lowest value to be shown on the
vertical axis used for plotting by GNUPLOT. Using this gadget, you can
'zoom in' or 'zoom out' vertically into the plot. This gadget has no
effect on the data file written by GFFT.
The Low Y gadget allows you to set the lowest value to be shown on the
vertical axis used for plotting by GNUPLOT. Using this gadget, you can
'zoom in' or 'zoom out' vertically into the plot. This gadget has no
effect on the data file written by GFFT.
Note that GNUPLOT might do strange things if you specify a HighY value
without also specifying a LowY value and vice-versa. It may, for example,
decide to run the Y axis upside down in order to show the widest range of
Y values. Or, if less than one Y unit would be plotted when autoscaling
one value, GNUPLOT may decide the Y range is invalid. So, it is safest to
specify both High Y and Low Y.
In 3D mode, the vertical axis (representing power or amplitude) is
actually the Z axis, so the High Y and Low Y values selected are applied
to the Z axis in that mode.
Quantization lets you set a quantization value for GFFT output. For
example, a quantization of 0.1 will cause all amplitude or power values to
be rounded off to the nearest 0.1.
Note that you could use any arbitrary value for quantization (e.g.
12.3456) though this might not be very useful. Typical values might be
0.1, 0.05, 0.001, etc.
Quantization only affects the amplitude or power values. It has no effect
on the FFT computation itself, and does not affect the output of frequency
values.
?Workbench Copyright
The 'Copyright' button at the top of the GFFT Dialog window displays the
version number of GFFT you are running and a copyright notice. When
clicked, it brings up a requester which can provide more information about
the author, the NO WARRANTY disclaimer, the GNU General Public License
agreement, information about services available from the author and how
you can support the development of this program, and other information
about the development of this program.
?Workbench Help
The 'help' button brings up a requester which displays instructions on how
to obtain help for any gadget displayed in the GFFT Dialog Window,
provides a button to display an introductory message, and provides a
string gadget to get help on other topics suggested by the introductory
message.
?Workbench Help Topics
To get help for any general topic documented in the help file for GFFT,
enter the topic name in the Help Topic gadget and press return. To get
a list of topics which you may request help for, press the 'Topics'
button.
?Workbench Sample-File
The Sample File gadget displays the currently selected sample file (if
any) and allows you to enter the name of any other sample file to read.
You may click in the text box and type the name. This action may be
completed by pressing the Return key, or by clicking on any other button.
(As soon as Return is pressed or any other button is clicked, the file you
named will be opened.)
Under Workbench 2.0 or greater, you may also select a file to read using
the adjacent 'Select' button which brings up an ASL file requester.
If GFFT was started by clicking on the GFFT icon, the Sample File gadget
will be activated by default so that you can just start typing the name of
the first sample file to analyze. If GFFT was started by clicking on a
sample file icon that has GFFT as its tooltype, or through the 'extended
selection' of GFFT and one or more sample files, the name of the first
sample file will appear in the Sample File gadget and the gadget will not
be activated by default. If more than one sample file was selected, you
may advance to the next one by clicking on the 'Next' gadget.
GFFT can also read data points entered from the keyboard. See help for
the 'con:' button for further information.
GFFT can read both formatted and unformatted files. If GFFT understands
the format of the file (it currently understands IFF 8SVX, AIFF, and AVR
formats), it will automatically set the sampling rate, and it will know
the number of frames so that the maximum number of bins can be determined
without scanning the entire file. (GFFT also recognizes but does not yet
understand RIFF and VOCH formats. See help for the IgnoreFormat command
for some advice on how to deal with those formats.)
If the file is unformatted, you will have to set the sampling rate
manually before beginning an analysis. You may also have to use the Bits
and Unsigned commands if your unformatted file does not use the default
for unformatted files (8 bits, signed). If the file is formatted using an
unrecognized format, you may still be able to read it using the command
'StartByte' (which allows you to skip over the file header) if you know
how long the file header is, and 'Frames' (which allows you to read a
specified number of frames, skipping any file segments following the
sample data). This is not recommended unless you are very familiar with
the inner workings of the file format you are working with.
?Workbench Sample-Select
When the Select button is clicked, a requester will appear to let you
select the sample file for GFFT to read. This feature requires Workbench
2.0 or higher. (If you do not have 2.0 or higher, you can enter the
filename into the Sample File gadget, or use the 'extended selection' of
GFFT and one or more sample files from the Workbench.)
?Workbench Sample-Con:
In addition to reading stored sample files, GFFT can accept data points
through the keyboard 'con:' device. You can select this option either by
clicking on the Sample File 'con:' button, or entering the name 'con:'
into the Sample File string gadget. Next, you should enter the sampling
rate into the 'S Rate' gadget. Then, you can adjust other parameters.
Finally, after you click 'OK,' you will be prompted to enter each data
point from a console window. You may enter each data point as an integer
or as a floating point number with optional exponent.
If you started GFFT from the Workbench using Workbench 2.0 or greater, a
new console window will appear for you to enter data points. If you
started GFFT from the CLI, and then activated the GFFT Dialog Window using
the WORKBENCH command, you will be prompted to enter data points in the
original CLI from which you started GFFT (which might now be hidden by the
GFFT Dialog Window). If you started GFFT from the Workbench using
Workbench 1.3, the GFFT console window will be present whether you use it
or not (due to limitations of that Workbench version).
This may be useful if you have a small number of manually recorded data
points, or wish to experiment with FFT spectrum analysis to gain a deeper
understanding of it. For example, if you entered the following points:
> 1
> 0
> -1
> 0
You would get a spectrum of 2 points (Nyquist Frequency/2, Nyquist
Frequency) or 3 points if you set the Low Frequency to 0 (as "zero
frequency," i.e. D.C., would be included). The center frequency of
Nyquist Frequency/2 would have amplitude 0.707 and the amplitude would be
0 at the other frequency(ies). This illustrates the default normalization
of GFFT, since 0.707... is also the RMS amplitude of the signal you have
entered, and the frequency is 1/2 of the Nyquist Frequency.
?Workbench Octave-Low
The 'Octave Low' button selects the lowest octave currently available in
a formatted file (such as 8SVX) which may have more than one octave. If
there is only one octave present, it is considered to match the lowest
octave. 'Low Octave' is the default octave.
?Workbench Octave-2
The 'Octave 2' button selects the second (from the lowest) octave
available in a file with a format (such as 8SVX) which supports more than
one octave. If the sample file does not have this octave, this button
should be ghosted.
?Workbench Octave-3
The 'Octave 3' button selects the third (from the lowest) octave available
in a file with a format (such as 8SVX) which supports more than one
octave. If the sample file does not have this octave, this button should
be ghosted.
?Workbench Octave-4
The 'Octave 4' button selects the fourth (from the lowest) octave
available in a file with a format (such as 8SVX) which supports more than
one octave. If the sample file does not have this octave, this button
should be ghosted.
?Workbench Octave-5
The 'Octave 5' button selects the fifth (from the lowest) octave available
in a file with a format (such as 8SVX) which supports more than one
octave. If the sample file does not have this octave, this button should
be ghosted.
?Workbench Octave-6
The 'Octave 6' button selects the second (from the lowest) octave
available in a file with a format (such as 8SVX) which supports more than
one octave. If the sample file does not have this octave, this button
should be ghosted.
?Workbench Octave-7
The 'Octave 7' button selects the second (from the lowest) octave
available in a file with a format (such as 8SVX) which supports more than
one octave. If the sample file does not have this octave, this button
should be ghosted.
?Workbench Octave-Hi
The 'octave hi' button selects the highest available octave in a file with
a format (such as 8SVX) which supports more than one octave. This choice
is always valid, regardless of how many octaves are in the file.
?Workbench One-Shot-Only
The One-Shot Only button causes GFFT to read only the one-shot portion of
a sample in a format (e.g. 8SVX) supporting this feature. Pressing the
One-Shot Only button a second time will disengage it and cause GFFT to
read the entire sample.
Pressing the One-Shot Only button once will also disengage the Repeat Only
button if it had previously been engaged.
?Workbench Repeat-Only
The Repeat Only button causes GFFT to read on the repeat portion of a
sample in a format (e.g. 8SVX) which supports this feature. Pressing the
Repeat Only button a second time will disengage it and cause GFFT to read
the entire sample.
Pressing the Repeat Only button once will also disengage the One-Shot Only
button if it had previously been engaged.
?Workbench Channel
The Channel gadget selects a particular channel for a file in a format
(e.g. AIFF) which supports this feature. After entering the channel
number in this gadget, you may press return to have it entered and checked
immediately. If the selected channel is unavailable, an error requester
will appear, however, the number you selected will not be changed; it will
be up to you to enter a valid number. You must have entered a valid
channel number before clicking OK. To select the default channel, delete
all characters and press RETURN. (The default channel is always Channel
1.)
?Workbench Rate
The S Rate gadget automatically displays the sampling rate defined by a
formatted file and allows you to specify a rate for any file. For an
unformatted file, you must enter a valid sampling rate before clicking OK.
(Any positive floating point number is acceptable.) You may also override
the sampling rate value for a formatted file by entering a different rate
AFTER selecting the file. When the next formatted file is read in, the
Sampling Rate gadget will be set to the sampling rate indicated by that
file.
?Workbench Bins
The Bins gadget displays the current bins value, and allows you to enter a
different bins value if desired. By default, GFFT chooses the maximum
number of bins which could be put to use (considering the number of sample
frames and other parameters in effect). If you have a very large sample
file, or desire to reduce the spectral variance by averaging successive
frame segments, you should choose a smaller number of bins.
1024 is a typical number of bins, though I usually use more. You should
enter a value which is a power of 2. If you do not, GFFT will choose the
next higher power of two for you. If you select a number of bins higher
than the maximum, GFFT will detect this problem after you click OK.
When you enter a number of bins, the MAX Bins button will disengage. The
value you specify will then continue to be used for subsequent files
regardless of their size. To return to the default (MAX) bins setting,
press the MAX bins button, or delete all digits from the Bins gadget.
For an unformatted file, the default number of bins will not be known
until the file is scanned, and normally this does not happen until the
OK button is pressed, so the Bins gadget will remain blank unless you
choose to specify a non-default number of bins.
?Workbench Bins-MAX
The Bins MAX button indicates whether GFFT is automatically determining
the number of bins based on the number of frames in the file (and other
settings), as it does by default. Also, by clicking the MAX Bins button,
you can re-engage this automatic default mode. If the MAX Bins button is
unselected, it indicates that a number of bins was entered into the Bins
gadget, dis-engaging the default MAX mode.
(The MAX Bins gadget will not automatically be selected if you happen to
enter the maximum number of bins into the Bins gadget, as that fixed value
would continue to be applied to subsequent files regardless of their
size.)
?Workbench Plot
The Plot button is a toggle button which selects or de-selects Plot mode.
In Plot mode, GNUPLOT is automatically invoked in a shell process to
display the result of each spectrum analysis performed. If you have not
explicitly selected a file to which to write spectral data, GFFT will
automatically write a temporary file (in t:) for GNUPLOT to read. All
such temporary files will be deleted on exit from GFFT if you have
terminated the plot display. You terminate the plot display by pressing
RETURN after it has been displayed. GFFT can only display one PLOT at a
time, but you can overlay or concatenate several spectra in one PLOT
clicking the Plot-Combine ('&' following Plot) or Open buttons (see).
If Plot mode is de-selected, a spectrum file must be explicitly
specified--otherwise there is no point in doing the analysis since the
data would only be written to a temporary file and then deleted. GFFT
will check to see that either a spectrum file has been specified and/or
Plot mode is engaged when you click OK.
If you wish to create a nicely labeled Plot, it is preferable to
explicitly name each spectrum file, since GNUPLOT will use each the name
of each spectrum file to label the corresponding spectrum. Read HELP for
the Write gadget for further details.
?Workbench Plot-Combine
The Plot-Combine button (the ampersand following the PLOT button)
activates CombinePlots mode. In this mode, successive spectra are shown
together in the same plot display. Each spectrum is plotted with a
different color (or linetype) by GNUPLOT and labeled with the name of the
specified spectrum file or temporary file. Using CombinePlots mode,
different data and/or parameter choices can be compared.
CombinePlots will have no effect unless Plot mode is also engaged.
The Plot-Combine button is a toggle button. To disengage CombinePlots
mode after having engaged it, click the button again.
When CombinePlots mode is first engaged, the previously completed spectrum
(if any) becomes the first data set for the plotter, the next completed
spectrum becomes the second data set, and so on. If you would rather not
include the previously completed spectrum, click the 'Plot-Cut' (X) button
(immediately to the right) after engaging CombinePlots.
To use this mode most easily, CANCEL any spectrum file name you have
specified and let GFFT create sequentially named temporary files for you.
If you would like to save each spectrum to a named file, then YOU MUST
remember to create a different named file for each spectrum computed.
Otherwise, each new spectrum will overwrite the previous one, and you will
get nothing but the same spectrum over and over. For use with RePlot, you
will have to Plot-Cut (X) the current file first, or it will be repeated
twice. Use of Plot-Combine with Write-Append can also be tricky.
When CombinePlots mode is disengaged, all previously combined spectra are
'cut' off, so that if CombinePlots is re-engaged immediately, a new plot
combination starts from scratch.
To 'cut' only the last spectrum, click the Plot-Cut button once. To cut
several spectra from the plot combination, click Plot-Cut button several
times. Each time Plot-Cut is clicked, one more spectra is cut from the
end until there are no more spectra to be cut. (This is a useful way to
cut spectra that didn't quite work out without starting over.)
CombinePlots mode is very useful for many things including comparing the
effect of different parameters (e.g. window type), or for comparing
alternate sets of data representing the same original source (to get a
feel for the variance caused by random fluctuations). (When you are
recording sample files for later analysis, remember to record two or more
sample files so that you can compare them and see which spectral features
are truly inherent in the source and not the result of random
fluctuations. If the variance is minimal, the spectral lines for each
sample file should lay on top of one another, or nearly so. Note that
very large sample files (> 1,000,000 frames) may be necessary to reduce
the variance of a pink noise source in the low frequency ranges to
acceptable levels.)
?Workbench Plot-Cut
The workbench Plot-Cut button cuts the previous spectrum when in
CombinePlots mode.
To 'cut' only the last spectrum, click the Plot-Cut button once. To cut
several spectra from the plot combination, click Plot-Cut button several
times. Each time Plot-Cut is clicked, one more spectra is cut from the
end until there are no more spectra to be cut. (This is a useful way to
cut spectra that didn't quite work out without starting over.)
See help for the Plot-Combine button (immediately to the left) for further
information about CombinePlots mode.
?Workbench Overlap
The Overlap button is a toggle button which engages or disengages overlap
mode.
Because it makes the best use of a limited amount of data, overlap mode is
engaged by default. It is also able to include all the data in the
analysis, regardless of whether the number of frames is exactly 2n times a
power of 2 (where n is a positive integer). If you are more concerned
with making the best use of processing time, and are not concerned about
ignoring a trailing remainder of the data, you may wish to disengage
overlap mode.
In overlap mode, the windows applied to the data are overlapped. By
overlapping the windows (as compared with just laying them end-to-end to
cover all frames present) better use is made of a fixed amount of data in
reducing the variance of the computed spectrum. This is true for all
window shapes, but especially true for the non-rectangular ones.
Overlapping may provide up to 9/11 of the variance reduction of having
twice as much data to work with (see Press, et. al.).
If overlap mode is disengaged, successive windows will still be applied to
the input data (if the number of frames is 4 times or more greater than
the number of bins) and the result from each window will be averaged to
reduce the variance, but windows will not be overlapped. Also, any
partial window of data at the end will not be analyzed (unless pad mode is
selected, which is strongly discouraged).
Normally, windows are overlapped by half their length (i.e., the fixed
overlap percentage for flat FFT analysis is 50%). However, in overlap
mode, the overlap of the last window is decreased or increased to
encompass the remainder of the data.
Given real (i.e. non-complex) sample data, 2 data points (frames) are
required for each Bin. Thus, 1024 bins would require 2048 frames. With
50% overlap, two overlapping windows would fit exactly into 3072 (2048 x
1.5) frames, three overlapping windows would fit exactly into 4096 (2048 x
2) frames, and four overlapping windows would fit exactly into 5120 (2048
x 2.5) frames. But GFFT varies the overlap of the last window to fit
whatever amount of additional data is present after the last whole window
of data has been read. So, two windows are used for any number of frames
F such that 2048 < F < 4096, three windows are used for F = 4096, four
windows are used for 4096 < F < 6144, and so on, with the overlap of the
last window somewhere between 0 and 100% (non-inclusive).
Though this scheme will ensure that all frames are included in at least
one segment, it may result in either over-representation or
under-representation of the last region of data. This is a fairly minor
detail (especially considering that the FFT is really only intended for
'continuous' sounds...) but if you are concerned with such things you may
want to specify exactly the number of frames to be used using the Frames
or StartFrame commands available in the CLI interface, and make sure you
have chosen an exact multiple (two or greater) of the bin size for an
exact overlap fit. For 3D-Time analysis, you should set the Time Segment
Size instead (this is discussed further in by the special help button in
the 3D-Time requester).
?Workbench Pad
[This button has been removed. I saw no real need for it, and it was
taking up critical screen real estate.]
The Pad button is a toggle which engages or disengages 'Pad' mode. In
'Pad' mode, the last (or only) partial window of data will be padded with
zeros prior to analysis. Pad mode is disengaged by default, and its use
is strongly discouraged.
Though it may sound innocuous, zero padding can produce serious artifacts
in a computed spectrum, and I strongly discourage it. The default
'Overlap' mode takes the best use of all the data without padding or
truncation. Even truncation, which might result if 'Overlap' mode is
disengaged, is superior to padding for most purposes. The only advantage
of padding is that it permits the use of a larger maximum number of bins
than the other techniques in some cases, but be forewarned that many of
those bins will be filled with spurious garbage.
See help for the Bins and Overlap buttons for further discussion.
?Workbench Rectangle
The Rectangle button selects windows of rectangular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins.
The Rectangle button is a 'radio' style button which disengages any other
window shape button. Likewise it is disengaged by the selection of any
other window shape button.
The 'Rectangle' window is the simplest window (effectively a series of
1's) and the fastest to compute and apply (i.e. no computation or
application is necessary). It also results in the sharpest initial
fall-off on either side of a spectral peak. However, it is also the most
susceptible to the presence of side-lobe artifacts. If you wish to remove
the influence of side-lobes, use a different window shape, such as 'B-H
74dB.'
Rectangle is currently the default window shape.
?Workbench Triangle
The Triangle button selects windows of triangular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins.
The Triangle button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The 'Triangle' window is the next simplest window, after the Rectangle
window. Its shape is that of a triangle peaking in the center of each
data segment. The 'Triangle' window is often called the 'Bartlett'
window, after a scientist who found it to be useful.
The triangle window is superior to the rectangle window in side-lobe
rejection. In turn, it is inferior to all other window shapes except
rectangle in side-lobe rejection.
?Workbench Parzen
The Parzen button selects windows of a particular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins.
The Parzen button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The Parzen window is based on the formula presented by Press, et al, in
their book 'Numerical Recipes.' It is not the same as the "Parzen Window"
identified by Harris. It is superior to the triangle and rectangle
windows in sidelobe rejection.
?Workbench Welch
The Welch button selects windows of particular shape. These windows will
be applied to the data in segments whose size is determined by the number
of bins.
The Welch button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The Welch window is based on the formula presented by Press, et al, in
their book 'Numerical Recipes.' It is superior to the triangle and
rectangle windows in sidelobe rejection.
?Workbench Hann
The Hann button selects windows of a particular shape. These windows will
be applied to the data in segments whose size is determined by the number
of bins.
The Hann button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The 'Hann Window' is frequently mis-named as the 'Hanning Window.'
Actually, Hann-ing (or Hann'd) is a kind of verb which attests to the
popularity of this window in instrumentation. It is superior to the
preceding windows in sidelobe rejection. The formula used here is from
Harris.
?Workbench Hamming
The Hamming button selects windows of a particular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins.
The Hamming button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The Hamming window is superior to the preceding windows in sidelobe
rejection. The formula used here is from Harris.
?Workbench 74dB-Blackman-Harris
The B-H 74dB button selects windows of a particular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins.
The B-H 74dB button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The Blackman-Harris 74dB window is a nearly optimal window according to
criteria developed by Harris. It is superior to all the preceding
windows in sidelobe rejection. The '74dB' refers to a 74dB minimum
sidelobe rejection. GFFT also provides the Blackman-Harris 92dB window
which has even greater sidelobe rejection, but also suffers considerably
from a loss of selectivity (actually, "processing loss") compared with
other window shapes.
?Workbench 92dB-Blackman-Harris
The B-H 92dB button selects windows of a particular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins.
The B-H 92dB button is a 'radio' style button which disengages any other
selected window shape button. Likewise it is disengaged by the selection
of any other window shape button.
The Blackman-Harris 92dB window has the highest sidelobe rejection of all
windows studied by Harris. In fact, the '92dB' refers to the impressive
92dB sidelobe rejection, so any spectral feature you see is that much more
likely to be a real spectral feature (provided data of sufficient quality
and quantity). Unfortunately, it also suffers considerably from a
corresponding "processing loss" in comparison with other windows included
in this program, so that many real features may be smeared and hidden.
Ultimately, each window has its own unique set of compromises.
?Workbench Spectrum-File
The Spectrum File gadget shows the name of the current non-temporary
spectrum file (if any), and allows you to enter a new one. The spectrum
file is an output file produced by GFFT which is read by GNUPLOT (if Plot
mode is enabled) and is also human-readable. It is not necessary to name
spectrum files if Plot mode is enabled because GFFT will automatically
create and manage temporary spectrum files for you. But, if you want to
save the spectrum file for later use, or give it a nice name (since the
spectrum file name is used by GNUPLOT as a label), you should name it
using this gadget or one of the following buttons.
If you would like GFFT to make up a permanent spectrum file name for you,
use the '*.fft' button. (It will take the sample file name and tack on
".fft").
You may enter a filename into the Spectrum File gadget using a file
requester if you click the Spectrum File Select ('S') button. When you
use that button and select a file, Open mode will be activated
automatically, but you may cancel Open mode and return to Write mode if
you do so right away. See help for the 'S' button for further details.
The Spectrum-File-Open to the left activates 'Open' mode, which changes
how the spectrum file will be used...
By default, GFFT starts in 'Write' mode in which every spectrum file
written by GFFT will be written from the beginning each time. When a name
is entered into the Spectrum File gadget, GFFT will look for an existing
file of that same name, and back it up first (to a file with the same name
and a trailing underscore), and then begin writing the file from the
beginning (overwriting all previous data). To warn you that this is
occurring, GFFT will display a warning requester. Note that GFFT only
performs one level of backup, so the second time you overwrite a spectrum
file, the original data will be lost.
In Open mode, GFFT will not overwrite pre-existing data in the spectrum
file, but may be used either to re-plot that data, or to append additional
"bands" of spectral data to it. See help for the 'Open' button for
further details.
New data will not actually be written to the spectrum file until you click
either 'OK' or 'ReOutput.'
If you had selected an explicitly named output file but wish to return to
using temporary files managed by GFFT, click the Write-Cancel ('CAN')
button. This is also a quick way to delete an existing spectrum file
name so you can start over.
You may also select the pseudo-file 'con:' to write data to. This will
cause the spectral data to be written to a console window (in the same way
that the Sample file 'con:' button causes data to be read from a console
window...see the help for that button for some discussion of how the
console window appears and/or may be hidden depending on how GFFT was
started and what Workbench revision you are using). If you select con: as
the spectrum file, you must cancel plot mode, as GNUPLOT cannot plot data
written to the console window.
?Workbench Spectrum-File-Select
The Spectrum-File-Select button (the 'S' following the Spectrum File
gadget) brings up a file requester to let you select a spectrum file to
open (or write). This feature requires Workbench 2.0 or higher. (If you
do not have 2.0 or higher, you can enter the filename into the Spectrum
File gadget.)
When you select a file in this manner, 'Open' mode is automatically
activated to prevent you from overwriting previous spectral data by
mistake, in case you wanted to RePlot the file or append new data bands to
it (see help for the Open button). However, if you really DID want to
overwrite the spectrum file from the beginning, you may then click on the
Open button to disengage Open mode immediately after selecting the file.
You must make this change before clicking on any other button, or GFFT
will cancel the spectrum file selection rather than allowing you to
overwrite a spectrum file that was 'Opened.'
?Workbench Spectrum-File-Open
The Spectrum File 'Open' button is a toggle button which activates
spectrum file 'Open' mode, or switches back to the default 'Write' mode.
After Open mode has been activated, any spectrum file selected is opened
at the end of existing data in the file, NOT overwritten from the
beginning (as would be the case in Write mode). This is useful either if
you want to RePlot previously stored spectrum files, or append data to a
spectrum file in bands. These two possibilities are discussed separately
below. In either case, you should activate Open mode BEFORE selecting the
file, or previous data will get truncated (i.e. clobbered). (Actually,
GFFT will save the previous file to a backup file, but there is only one
level of backup, and you shouldn't depend on this.) When you use the
Spectrum File Select ('S') button, Open mode is automatically activated.
If the spectrum file does not already exist when opened, a new blank one
is created, just as in Write mode. You may not Open 'con:'
Open for RePlot
----------------
To RePlot previously stored spectrum files, you first click the Open
button, then select or enter a spectrum file name into the Spectrum File
gadget.
(If you select a file by using the requester which comes up when you press
the 'S' button, 'Open' will automatically be activated, to prevent you
from accidentally overwriting a previously stored spectrum.)
Then, to replot the spectrum, simply click on the RePlot button. Do NOT
click OK or ReOutput, as those may write additional spectral data to the
opened file (as described in the following section).
When replotting a previously stored spectrum, you may adjust any of the
parameters allowed before using the RePlot button. For further
discussion, see the help message for the RePlot button.
You may also use the CombinePlots ('&') and CutCombinedPlot ('X')
functions when opening previously stored spectrum files to plot several
spectra on the same screen or page. For example:
Click on CombinePlots ('&')
Select piano-rect.fft (Open mode is automatically engaged)
Click on RePlot (piano-rect.fft is plotted)
Press Return (Plot screen is removed)
Select piano-hann.fft
Click on RePlot (both .fft's are plotted on the screen)
Press Return
Select piano-74db.fft
Click on RePlot (all 3 .fft's are plotted)
Now, suppose you wanted to remove piano-74db.fft from the multiple plot
display and add piano-92db.fft. You would continue as follows:
Click on CutCombinedPlot ('X')
Select piano-92db.fft (piano-rect.fft, piano-hann.fft and
piano-92db.fft are plotted)
CutCombinedPlot works in the above example as shown (removing
piano-74db.fft from the multiple plot display), but doesn't generally work
with RePlot in other contexts, such as if you are simply changing plot
parameters in between each RePlot using the same spectrum file. A
spectrum file must have a unique name in order to be "cut." (GFFT
will automatically give TEMPORARY files unique names in CombinePlots
mode, but that would not apply in this example in which we are replotting
previously stored files.)
In fact, Open, CombinePlots, RePlot, and/or CutCombinedPlot can sometimes
have unexpected consequences when used together. You should not have any
trouble, however, if you follow the underlying model of the example shown
here.
Open for Appending 'bands'
--------------------------
Once a particular file has been Opened, each subsequent OK will append
additional data to the same file (until another file is Opened or the GFFT
session is ended). Data may not be written to a file while a plot is
being performed or displayed, however.
This is particularly useful if you are composing a file of spectral data
in several frequency "bands." You may be using data sampled by different
methods in separate sample files, or simply analyzed with different
numbers of bins or smoothing points depending on the frequency range. The
best way to show this is with a batch mode example, but the same
operations could be performed through the dialog window. (Note:
the 'read' command is the counterpart of entering a name into the
Sample File gadget. Here, there is a sample file named 'white.iff')
gfft read white.iff write white.fft bins 8192 lowf 0 highf 200 psd
gfft read white.iff open white.fft bins 2048 lowf 200 highf 400 psd
gfft read white.iff open white.fft bins 1024 lowf 400 highf 800 psd
gfft read white.iff open white.fft bins 512 lowf 800 highf 1600 psd
gfft read white.iff open white.fft bins 256 lowf 1600 highf 3200 psd
gfft read white.iff open white.fft bins 128 lowf 3200 highf 6400 psd
gfft read white.iff open white.fft bins 64 lowf 6400 psd
(Actually, you wouldn't need to do all this if you merely wanted to have
the same number of spectral data points per octave. An easier way to
accomplish that would be by using a large number of bins (e.g. 8192) and a
smaller number of smoothing points (e.g. 200), with LogX selected.)
?Workbench Spectrum-File-Cancel
The Spectrum File Cancel button cancels the explicit filename you have
entered into the Spectrum File Gadget. This will cause GFFT to use
temporary files for the spectral data written by GFFT to be read by
GNUPLOT, which is the default before any explicit filename has been
entered. You may also use this button to "clear" out the old spectrum
file name before entering a new one.
?Workbench *.fft
The '*.fft' button will let GFFT make up a spectrum file name by tacking a
'.fft' extension on to the end of the sample file name.
In CLI mode, it is easy to make up such a name using command replay, so
this button was created to make explicit file naming just as easy (or
actually, easier) in Workbench Mode (so you don't have to copy the whole
Sample File name over into the Spectrum File gadget by hand).
This button will not do anything useful if you are reading from con:.
?Workbench ReOutput
The ReOutput button allows you to rewrite the results of the preceding
analysis subject to a number of changed parameters. The FFT analysis
itself will not be repeated, only the output processing, writing, and
plotting (if applicable). This is useful for making minor changes after a
long analysis without repeating the analysis itself.
Here are the parameters which may be changed before a ReOutput:
Spectrum File
Plot (on or off)
Smoothing Segments and Squared Smoothing
High Frequency
Low Frequency
Mean
Power
Amplitude
dB
LogX
LogY
Multiply (CLI only)
Sampling Rate
Pink
Quantization
LowY (see CAL requester)
HighY (see CAL requester)
Here are just a few parameters which may NOT be changed between OK and
ReOutput:
Sample File
Bins
Overlap
Window Shape (Rectangle, etc.)
Any 3D parameters...in fact, ReOutput is not at all possible with 3D
(Pad...from CLI)
[Currently, if you change these parameters and ReOutput, you will not get
any sort of warning that the changed values have no effect. They just
will not have any effect.]
There is also a RePlot button which has generally more limited
capabilities, but does allow changing the 3D parameters.
?Workbench RePlot
The Workbench RePlot button allows you to RePlot the previous analysis or
previously stored spectrum file with a few changed parameters. The
spectrum analysis itself, including the output phase, will not be
repeated. Instead, GNUPLOT will simply be launched with with new
parameters on the currently named (or temporary) spectrum file.
RePlot may be used in conjunction with Open mode to RePlot previously
stored spectral data files. See help for the Open button for further
details.
Here are the parameters which may be changed before doing a RePlot:
Plot (if previously off)
LogX (with no smoothing! LogX w/smoothing requires a ReOutput)
LogY
RotX
RotZ
LowFrequency (*see note below)
HighFrequency (*see note below)
LowY
HighY
[Currently, if you change any other parameters and RePlot, you will not
get any sort of warning that the changed values will have no effect.]
(ReOutput permits the modification of many more parameters than RePlot,
though it does not permit the repetition of a 3D analysis. Like RePlot,
ReOutput will also produce a new plot if Plot mode is on.)
*Note that RePlot does not effect the LowFrequency and HighFrequency in
exactly the same way as OK or ReOutput. OK and ReOutput 'filter' the data
written to the output data file so that no data outside the range
established by LowFrequency and HighFrequency is written. RePlot cannot
filter the data which has already been written, but instead sends
explicit 'set xrange' commands to GNUPLOT. If you wanted a plot with
artificially large left and right 'margins,' you could first do OK (with
the desired actual data range set or defaulted), then do a RePlot with
LowFrequency and HighFrequency values set outside the range of actual data
to the point(s) where you would like the margins to be. Thus, this
difference in the way LowFrequency and HighFrequency are used in RePlot
mode is actually a 'feature' which you can take advantage of to change
the presentation of a plot.
?Workbench Pink
* Warning! The results of this feature may not be entirely 'correct.' *
The Pink button engages pink mode, in which a particular sort of
frequency-dependent normalization is performed on the spectral output so
that pink noise will be shown as having nearly 'flat' response. The Pink
button is a toggle button which may be clicked on or off.
(Pink noise is random noise shaped so that there is an equal amount of
energy or amplitude in each octave or fractional-octave band. It is
frequently used in acoustic testing.)
Pink mode simply weights each output value by a corrective factor; it does
not do any grouping and/or averaging (so no resolution is lost). The
current formula does not seem entirely accurate at the lowest frequencies,
where the results may vary depending on how many bins are being used.
This makes it difficult (or impossible) to splice several curves of pink
noise with different numbers of bins together. In any case, the sum of
the squared output values will no longer reflect the sum of the squared
input values, in fact, the scale may be offset considerably. You may
choose to use the 'Multiply' command (available in CLI mode; see help for
the CLI button) to rescale the results conveniently.
(You may also wish to do Smoothing with LogX set when plotting pink noise,
and use extremely large sample files with 1,000,000 frames or more to
allow for the randomness in pink noise to average out.)
?Workbench LogX
The LogX button is a toggle button which selects whether the X axis will
be scaled logarithmically by GNUPLOT during plotting.
LogX has no effect on the spectral data output by GFFT itself, except that
when both Smoothing and LogX are engaged a logarithmic mesh will be used
during the smoothing phase.
?Workbench LogY
The LogY toggle button selects whether the vertical axis will be scaled
logarithmically by GNUPLOT during plotting. It has no effect on the
spectral data output by GFFT itself.
If a dB conversion is selected with the dB toggle button, LogY is probably
not desireable (as this would mean plotting logarithms on a logarithmic
scale).
LogY is intended to make the vertical axis (representing amplitude or
power) logarithmic. In 3D mode, it is actually the Z axis that is
vertical and that represents amplitude or power, so in that mode LogY
actually scales the Z axis logarithmically.
?Workbench dB
The dB toggle button selects whether GFFT will write output amplitude or
power values converted to the dB scale.
If a dB is selected, LogY is probably not desireable (because then you
would be plotting logarithms on a logarithmic scale).
?Workbench Power
?Workbench Amplitude
The Power and Amplitude button are mutually exclusive toggle buttons.
Selecting one automatically de-selects the other. They determine whether
GFFT will output Amplitude or "Power" (squared amplitude) values. By
default, GFFT will output Amplitude values.
?Workbench Next
The Next button will advance to the next sample file selected from the
Workbench by extended selection. If GFFT was invoked without selecting
any files by extended selection, or if only one sample file was selected
by extended selection, the Next button will be ghosted.
?Workbench CLI
The CLI button will continue the current session of GFFT from the CLI
interface, and will remove the GFFT Dialog Window. From the CLI
interface, you may then return to the GFFT Dialog Window by giving the
'Workbench' command.
If you started GFFT from the workbench by clicking on its icon, clicking
the CLI button will cause a new console window to be created below where
the GFFT Dialog Window was for you to work in. (Under AmigaDOS 1.3, this
console window is always there whether you need it or not.)
If you started the GFFT dialog from the CLI by giving the 'Workbench'
command, control will return to the console from which GFFT was started.
Using the WORKBENCH command and the CLI button, you can switch back and
forth between WORKBENCH and CLI interfaces. This might be useful if there
are a few commands having no corresponding gadgets in the GFFT Dialog
Window which are needed in your application, such as 'Frames' or
'StartByte.' You may also put CLI commands in your .gfft startup file.
?Workbench-Message-Display
The Message indicator shows an informational message concerning your GFFT
session. Usually, this gives an indication of what sort of user action is
expected or required next. Sometimes, it lets you know of some decision
that has been made for you (such as selecting the exact number of bins if
you entered a number which was not a power of 2), or how much time the
internal FFT loop required. (Note that the internal FFT loop DOES include
some file reading, but not the output file writing, which is handled after
the internal FFT loop. Also, the FFT loop may be repeated many times for
a 3D-Time analysis.)
If the message 'Performing FFT analysis...' is displayed, the analysis is
being performed. This could take some time. Additional time may also be
required after the FFT loop elapsed time indication appears (to write the
output file and invoke GNUPLOT). Meanwhile, do not attempt to operate on
any other gadgets in the GFFT Dialog Window.
?CLI
The CLI command argument is used to enter CLI-interactive mode when GFFT
is run from a shell or shell command. By default, GFFT now starts in
Workbench mode. For more information about the modes in which GFFT may be
run, see 'Help Introduction.'
CLI-interactive mode is very much like GNUPLOT. This type of operation
is convenient for some types of work, though it is discouraged by
Commodore interface standards.
The CLI must be the first and only command argument used. It may not
follow a series of other batch command (non-interactive) arguments. For
example, the following is correct:
shell> GFFT CLI
while the following is NOT correct:
shell> GFFT HANNING CLI
?Cli-Commands
?Syntax
The CLI commands for GFFT are either entered all in one line (for
batch mode) or one for each prompted line (for interactive mode).
The GFFT commands are not case sensitive. They may each be abbreviated
to the shortest unambiguous string.
You may enclose filenames in either single or double quotation marks.
This may help gfft distinguish it from the command itself. Though no
ambiguity could (currently) arise in CLI Interactive mode since only one
command is permitted per line, there might otherwise be an ambiguity in
CLI Batch mode.
Most commands actually set some parameter for later use. The OK or GO
commands actually initiate a spectrum analysis. That is when all
previously specified settings are actually used (and incompatibilities
might be detected).
In the syntax descriptions for some commands, square brackets like [this]
enclose optional arguments, and angle brackets like <this> enclose
arguments generally, while the un-enclosed words are the command(s)
themselves.
??
?help
The HELP and ? commands display a list of commands available in GFFT,
along with some hints and other helpful information. If an argument is
specified, help for that keyword or command is displayed.
Syntax:
?
help
help <command or keyword>
?About
The About command displays information about the author of GFFT and how
you can support its future development.
?Amplitude
?Power
The Amplitude and Power commands are mutually exclusive. Selecting one
automatically cancels the other. They determine whether GFFT will output
Amplitude or "Power" (squared amplitude) values. By default, GFFT will
output Amplitude values.
?Append
?Open
The Open and Append commands are identical (in this release, anyway).
Syntax:
append [<filename>]
open [<filename>]
The Open command is similar to the Write command (see) in that it will
open a spectrum file which may be read or plotted by GNUPLOT. However,
the Open command will cause any data written to this file to be appended
to the end of existing data, if any, while the Write command would cause
the file to be rewritten from the beginning. If the named file does not
already exist, the Open command will create one (just as the Write command
does).
Open may also be used to open a previously stored spectrum file so that it
may be plotted with the RePlot command. Once a file has been opened, it
may be plotted with RePlot, and parameters such as HighFrequency,
LowFrequency, LogX, and LogY may be adjusted. If you are using Open in
this way, be sure NOT to give the OK or ReOutput commands, or else GFFT
may write more data at the end of the opened file. See help for the
RePlot command for a discussion of which parameters may be adjusted.
The Open command is normally given with one argument: the filename (which
may include device and/or absolute or relative directory specifiers). If
the Open command is given without any arguments, GFFT will make a
temporary file to plot from (assuming plot mode is enabled). At the end
of the GFFT session, this temporary file will be deleted (if the plot is
no longer being displayed).
Once a particular file has been opened with Open, each subsequent OK
command will append additional data to the same file (until another Open
or WRITE command is given, or the GFFT session is ended). Note that data
may not be written to a file while a plot is being performed or displayed,
however.
Open is particularly useful if you are composing a file of spectral data
in several frequency "bands." You may be using data sampled by different
methods, or analyzed with different numbers of bins or smoothing points
depending on the frequency range.
Example:
gfft read white write white.fft bins 8192 lowf 0 highf 200 psd
gfft read white open white.fft bins 2048 lowf 200 highf 400 psd
gfft read white open white.fft bins 1024 lowf 400 highf 800 psd
gfft read white open white.fft bins 512 lowf 800 highf 1600 psd
gfft read white open white.fft bins 256 lowf 1600 highf 3200 psd
gfft read white open white.fft bins 128 lowf 3200 highf 6400 psd
gfft read white open white.fft bins 64 lowf 6400 psd
(Actually, you wouldn't need to do all this if you merely wanted to have
the same number of spectral data points per octave. An easier way to
accomplish that would be by using a large number of bins (e.g. 8192) and a
smaller number of smoothing points (e.g. 200), with LogX selected.)
If you want to comparatively plot several different spectra during the
plotting phase, use the CombinePlots command instead of the Open command,
or, in addition to it if you are replotting previously stored spectrum
files (see below). CombinePlots will cause each different spectrum to be
plotted with a different color (or linetype) with a legend identifying
each one.
While you are using Open to open previously written spectral data files
and RePlot to plot them, you may also use CombinePlots to overlay each of
these spectra into one plot.
Example:
sys> gfft
gfft> combineplots
gfft> open piano.fft.rect
gfft> RePlot
gfft> open piano.fft.hann
gfft> RePlot ;plots both ...rect and ...hann
gfft> open piano.fft.74dB
gfft> RePlot ;plots ...rect, ...hann, and ...74db
gfft> CutCombinedPlot
gfft> open piano.fft.92dB
gfft> RePlot ;plots ...rect, ...hann, and ...92db
CutCombinedPlot works in the above example as shown (replacing
piano.fft.74db with piano.fft.92db with an Open command), but doesn't
generally work with RePlot if you are only changing parameters (it works
best if you are changing the actual filename), nor does CombinePlots work
with Open and RePlot if you are only changing parameters (and not adding
files with different names) between each RePlot. The example shown here
works, but Open, CombinePlots, RePlot, and/or CutCombinedPlot can
sometimes have unexpected consequences when used together. You should not
have any trouble, however, if you follow the model of the example shown
here.
You may not Open 'con:'
?Banner
The Banner command displays the GFFT banner, which normally comes up when
you start GFFT in CLI-interactive mode. (This might be useful if you are
running GFFT in batch mode but nevertheless want to have the GFFT banner
displayed.)
?Bins
The Bins command lets you choose or default the number of bins to be used.
It is followed by an (optional) integer argument. By default, GFFT
chooses the maximum number of bins which could be put to use (considering
the number of sample frames, and the current Overlap, Pad, Interleave and
other settings). If you have a large sample file, or wish to reduce the
spectral variance by averaging successive frame segments, you should
choose a smaller number of bins than the maximum.
1024 is a typical number of bins, though I usually use more. You should
enter a value which is a power of 2. If you do not, however, GFFT will
choose the next power of two for you and indicate the actual value chosen.
Once set explicitly, the same number of bins will be used for the present
and all future sample files read in the same GFFT session.
If you enter the Bins command with no argument, the default (maximum) bins
mode will be re-engaged. In the default mode, you will be alerted as to
the actual number of bins used after the OK command is given for each file
analyzed.
By default, GFFT attempts to make use of all data present either by using
the largest number of bins and/or by by averaging the data segments (whose
length is 2*N where N is the number of bins) present to reduce the
spectral variance. If you wish GFFT to limit analysis to a smaller number
of data points within you file, you may use the Frames and/or StartFrames
commands.
By default, GFFT will also use Overlap to provide even more data segments,
resulting in a further reduction of variance. (See the Overlap command
for further information.) Overlap may be disengaged with the NoOverlap
command.
?Bits
The Bits command lets you set the number of bits used in the
representation of each input datum in an unformatted input sample file.
Normally, the number is either 8 or 16, but you may specify any number
between 1-16 inclusive. (The handling of numbers other than 8 and 16 is
as specified for the AIFF format--i.e., the least significant bits are
ignored first.)
Syntax:
Bits <number of bits: integer 1-16>
Note that the argument for this command is mandatory.
If a Bits command is given BEFORE the header of a formatted sample file is
read with a READ command, the number of bits specified in the sample file
header will supercede the number specified in the Bits command. If the
Bits command is given AFTER the READ command, the number in the Bits
command will supercede the number specified in the sample file header.
The default for unformatted sample files is 8 bit.
?74dB-Blackman-Harris
The 74db-Blackman-Harris command selects windows of a particular shape.
These windows will be applied to the sample data in segments whose size is
determined by the number of bins. This command cancels the effect of any
preceding window shape command.
The Blackman-Harris 74dB window is a nearly optimal window according to
criteria developed by Harris. It is superior to most other windows in
sidelobe rejection. The '74dB' refers to a 74dB minimum sidelobe
rejection. GFFT also provides the 92dB-Blackman-Harris window which has
even greater sidelobe rejection, but also suffers considerably from a loss
of selectivity (or, more precisely, 'processing loss.')
?92dB-Blackman-Harris
The 92db-Blackman-Harris command selects windows of a particular shape.
These windows will be applied to the sample data in segments whose size is
determined by the number of bins. This command cancels the effect of any
preceding window shape command.
The Blackman-Harris 92dB window has the highest sidelobe rejection of all
windows studied by Harris. In fact, the '92dB' refers to the impressive
92dB sidelobe rejection, so any spectral feature you see is that much more
likely to be a real spectral feature (provided data of sufficient quality
and quantity). Unfortunately, it also suffers considerably from a
corresponding "processing loss" in comparison with other windows included
in this program, so that many real features may be smeared and hidden.
Ultimately, each window has its own unique set of compromises.
?Calibration
?DbCalibration
?NoCalibration
Syntax:
Calibration <Calibration File Name>
DbCalibration <Calibration File Name>
NoCalibration
The Calibration command enables you to apply a 'calibration' to the output
of GFFT. In this way, you can compensate for the frequency response of
your sampler, microphone, noise source, etc. Any number of calibrations
may be in effect at the same time. Each time the Calibration (or
DbCalibration) command is given, a new calibration is linked into the
existing list of calibrations. The NoCalibration command cancels the
entire list of calibrations. The DbCalibration command allows you to use
a file in which the amplitudes are in dB (logarithmic) form. Calibrations
and DbCalibrations may be applied to spectrums in any combination
regardless of whether the final output is in dB form or not.
The calibration file(s) should be in the same format as the output files
produced by GFFT itself. Each line (terminated by newline) should have a
frequency value, any number of spaces, and an amplitude value (NOT a
'power' or squared amplitude value!). The frequencies must be in
increasing order, and the range of frequencies must be equal to or greater
than that to be output by GFFT (see warning below). Lines beginning with
one of the following characters are considered to be comments:
# ; !
If a spectrum is calibrated by itself, the result should be a straight
line at either 1.0 or 0.0 (for dB output). Actually, due to slight
rounding errors, the actual result will be close to, but not exactly these
ideal values (e.g. 0.9999998). Given that Gnuplot will always scale the Y
axis to the maximum magnification, these small differences may be
disconcerting. To minimize this effect, consider setting the LowY and/or
HighY values to fix the vertical range. You may also use the Quantization
command to apply a quantization to the output (but, that may cause other
problems).
Calibration as used here is unrelated to true complex 'correlation,' which
is not currently available in GFFT. Calibration has somewhat limited
accuracy and validity, but is still probably a feature worth having for
its usefulness. Note that in between points specified in a calibration
file, simple linear interpolation may be used. If a frequency higher than
the highest calibration frequency is output by GFFT, it will be calibrated
by the value for the highest calibration frequency, and likewise for any
frequency lower than the lowest calibration frequency. In other words,
GFFT extends the last calibration value rather than extrapolating.
(WARNING! This could be dangerous if interpreted improperly! Remember to
provide calibrations over a range equal to or greater than the range to be
output by GFFT.) GFFT does not truncate to the calibration range because
rounding errors may cause premature truncation.
One way to use the Calibration command is to perform a GFFT analysis on
your signal source itself, and then apply that result as a 'calibration'
to your test measurements. Another way is to write frequency response
data provided by a calibration laboratory into a suitable calibration
file. (Many microphones, for example, are provided with calibration
curves that could be used for this purpose.)
?Channel
The Channel command selects a particular channel for a file in a format
(e.g. AIFF) which supports multiple channels. The desired channel number
is entered as a digit. If the Channel command is given with no arguments,
the default (1) channel (which is valid for all files, whether they have
channels or not) is selected. You must select a valid channel number
before giving the OK command or no analysis will be performed.
?CombinePlots
?NoCombinePlots
?CutCombinedPlot
The CombinePlots command activates CombinePlots mode. In this mode,
successive spectra (i.e. 'plots') are overlaid on top of one another.
Each spectrum is plotted with a different color (or linetype, if plotting
on a black and white printer) by GNUPLOT. The x and y axis are
automatically scaled so as to include the largest x and y values of any
spectrum included, unless you have opted to fix the HighY and LowY values.
When the first CombinePlots command is given, the previously completed
spectrum (if any) is used as the first data set for the plotter, the next
completed spectrum becomes the second data set, and so on.
If a subsequent CombinePlots command is given when already in CombinePlots
mode, it is ignored.
To disable CombinePlots mode, enter the NoCombinePlots command. All
previously combined plots are 'cut' off, so that if another CombinePlots
command is given immediately, a new plot combination starts from scratch.
To 'cut' only the last plot, give the CutCombinedPlot command. To cut
several plots from the plot combination, enter CutCombinedPlot several
times. Each time CutCombinedPlot is entered, one more plot is cut from
the end until there are no more plots to be cut. This is a useful way to
cut plots that didn't quite work out without starting over.
(CutCombinedPlot used in conjunction with RePlot can have unexpected
consequences. See help for the Open command for a working example; many
other combinations of these commands won't work as might be intended.)
Combine plots mode is very useful for comparing the effect of different
parameters (e.g. window type), or for comparing alternate sets of data
representing the same source (e.g. to get a feel for the variance due to
sampling size limitations--this is extremely useful for seeing which
spectral features are truly inherent in the source and not the result
of an inadequately large sample file. Note that very large sample files
(e.g. > 1,000,000 frames) may be necessary to reduce the variance of
a pink noise source in the low frequency ranges.)
Example:
gfft>read pink1.iff
gfft>bins 4096
gfft>logx
gfft>db
gfft>smoothingsegments 300
gfft>pink
gfft>ok
gfft>combineplots
gfft>read pink2.iff
gfft>ok
In this example, pink1.iff and pink2.iff are two samples of pink noise.
If they are both large enough, their spectral lines will be overlaid
nearly on top of one another. In any case, the extent of their divergence
will give an approximate feel for the variance.
?Copying
The Copying command will display the GNU General Public License under
which this program is being distributed. This specifies your rights to
have the source code and to give out copies of this program.
(Note: This command requires that the file named COPYING was placed either
in the same directory as GFFT or in the S: directory, as specified in the
file named INSTALLATION. If this file has been lost, you may obtain
another copy from the Free Software Foundation, Inc., 675 Mass Ave,
Cambridge, MA 02139, USA. Please do not ask them any other questions
about this program.)
?dB
?NodB
The dB command instructs GFFT to write output amplitude or power values
converted to the dB scale. The NodB command cancels this.
If dB is engaged, LogY is probably not desireable, as then you would be
plotting logarithms on a logarithmic scale. (LogY causes GNUPLOT to use a
logarithmically scaled Y axis, but does not otherwise modify the data file
written by GFFT.)
You will get a warning if any spectral values are equal to zero. Such
values will not be output as they cannot be converted to the dB scale.
?Exit
?Quit
The Quit or Exit command is used to end an interactive session of GFFT.
As GFFT is terminating, it will delete all temporary files it has created
if they are no longer in use. The temporary files corresponding to
plots or help messages still being displayed will not be deleted.
In that case, be sure to remove all help message and plot displays before
beginning a second GFFT session.
Warning! GFFT will also delete your files, if they match the masks
it uses for its temporary files:
t:temp-#?.fft-#?
ram:cli.temp-gfft-#?
ram:gnuplot.temp-gfft-plot
ram:temp-gfft-more-#?
As you can see, however, this isn't very likely.
?FFT-Complex
The FFT-Complex command changes the operation of GFFT fundamentally.
Instead of producing a plottable 2d (or 3D-Time) spectrum analysis, GFFT
will simply output (not plot) a file containing the Complex FFT of the
input data provided. (It is complex in that for each frequency there are
'real' and 'imaginary' components). This will be done when the OK command
is given.
Beware that few of the parameters provided in GFFT are applicable to
FFT-Complex operation. Only one data segment (whose size based on the Bin
specification) will be analyzed.
?Frames
The Frames command determines how many frames from the sample file will be
read and used by GFFT. It accepts one argument--the number of frames. If
no argument is given, the default is restored. By default, the number of
frames read and used by GFFT is the total number of frames in the file (if
possible--of course, the number of frames actually used may be less than
that if the Overlap (see) mode is turned off).
(If you are unfamiliar with the 'frame' terminology, for the purposes of
GFFT one 'frame' is the same as one 'data point,' or 'number.' Some sample
file formats permit more than one channel, and frequently the data points
for all channels present are combined in each 'frame' which consists of
all the samples taken for all channels to represent one instant of time.
Currently, GFFT can only use the data for one channel at a time, but the
'frame' terminology has been adopted because it is the most general. The
term 'sample' is ambiguous because sometimes it may refer to an individual
data point, and other times it may refer to an entire file of data points.
I have tried to consistently use the term 'sample file' here when
referring to such a file.
?Go
?OK
The OK command initiates an FFT according to all the specified parameters.
The Go command is identical.
The selected sample file will be read and transformed, the spectrum file
(if any) which has been selected with a Write or Open command will be
written to, and a PLOT will be produced if the Plot option is enabled.
This command is invalid if any parameters have been set incorrectly, if no
sample file has been selected, or if no spectrum file has been explicitly
specified AND the PLOT option is not enabled (as there would be no point
in writing to a temporary spectrum file only to delete it).
It may not be necessary to give the OK command in Batch-CLI mode because
it may be implied by the commands given and the end of the command line.
Example:
sys> gfft
gfft> read piano.iff
gfft> plot
gfft> ok
Batch Examples:
gfft read piano.iff write piano.fft
gfft read piano.iff hann write piano.hann ok hamming write piano.hamm
In the first batch example, no OK command is necessary because sample and
spectrum files are specified for which no OK command is given. In the
second batch example, two output files are written, OK is necessary to
write the first, but not necessary for the second. (See help for 'Batch'
for further information about batch mode).
Note: depending on the size of the sample file, the number of bins and
other parameters you have set, as well as the CPU and/or FPU resources
available, an FFT analysis could take anywhere between a fraction of a
second to several weeks. So, if you don't get an immediate response, have
faith that GFFT is working, not hanging. If there is any error, GFFT
should let you know right away. If it is working away on your file, and
the number of bins is small compared with the size of your sample file,
you will see the disk light flickering occasionally as GFFT reads in each
additional data segment.
?Hamming
The Hamming button selects windows of a particular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins. The Hamming command cancels the effect of any preceding
window shape command.
The Hamming window is superior to the Rectangle, Triangle, Parzen, and
Hann windows in sidelobe rejection. The formula used here is from Harris.
?Hann
The Hann button selects windows of a particular shape. These windows will
be applied to the data in segments whose size is determined by the number
of bins. The Hann command cancels the effect of any preceding window
shape command.
The 'Hann Window' is frequently mis-named as the 'Hanning Window.'
Actually, Hann-ing (or Hann'd) is a kind of verb which attests to the
popularity of this window in instrumentation. It is superior to the
Rectangle, Triangle, and Parzen windows in sidelobe rejection. The
formula used here is from Harris.
?Hidden3D
?NoHidden3D
The Hidden3D command enables hidden line removal in 3D plot displays.
The NoHidden3D disables this feature. It is disabled by default.
I find the hidden line 3D display to be the most readable, though some
useful data may be hidden.
GNUPLOT has other 3D display features which are not yet supported by GFFT,
such as contour plots (with many contour parameters). If there are any
particular ones you would like to be able to control from GNUPLOT, please
let me know. (I'm probably just going to add a generic GNUPLOT option
control facility in a future release.)
?HighFrequency
The HighFrequency command allows you to select the highest frequency to be
output (and plotted, if applicable) up to the Nyquist frequency, which is
one-half of the sampling rate. Any positive number (integer or floating
point) may be given as an argument. If no argument is given, the default
is restored in which the highest frequency output and plotted is
automatically the Nyquist frequency.
Using the HighFrequency and LowFrequency commands, you can zoom in to see
a particular part of the spectrum more clearly.
If a HighFrequency is selected prior to a RePlot command, that value is
given in a range specification to GNUPLOT. Otherwise, the effect of a
selected HighFrequency is to filter the output file produced by GFFT, and
GNUPLOT is allow to autorange. (This may result in a slight difference in
how the axes are drawn by GNUPLOT, and may be used to your advantage
during RePlot as you can then increase or decrease the right margin if
desired.)
?HighY
The HighY command allows you to set the lowest value to be shown on the
vertical axis used for plotting by GNUPLOT. Using this command, you can
'zoom in' or 'zoom out' vertically into the plot. This command has no
effect on the data file written by GFFT. If the HighY command is given
without any arguments, the HighY value will be automatically determined by
GNUPLOT autoscaling.
Syntax:
HighY [<highest Y value: double>]
Note that GNUPLOT might do strange things if you specify a HighY value
without also specifying a LowY value. It may, for example, decide to run
the Y axis upside down in order to show the widest range of Y values. Or,
if less than one Y unit would be plotted when autoscaling one value,
GNUPLOT may decide the Y range is invalid. Be forewarned.
In 3D mode, the vertical axis (representing amplitude or power) is
actually the Z axis, so then the HighY value is applied to the Z axis.
?IgnoreFormat
?NoIgnoreFormat
The IgnoreFormat causes GFFT to ignore the format of a file which it
recognizes. Currently, GFFT recognizes IFF, AIFF, AIFF-C, AVR, RIFF, and
VOCH formats, though it is only capable of processing IFF-8SVX, AIFF,
AIFF-C, and AVR formats (and ONLY if UNCOMPRESSED). Thus, IgnoreFormat
may allow you to read files in RIFF, VOCH, and other IFF formats, though
you will be responsible for setting parameters such as StartByte, Frames,
and Rate yourself, and there is no guarantee that even after setting these
parameters that GFFT will read the data properly (not to imply that there
is any guarantee anyway).
This feature should be used with caution and only by those who are well
versed in the format of the files they are going to read.
If you would like GFFT to support some additional file formats, please
contact the author and considering hiring him to do this or making a
regular or contingent donation. See the README file for details.
RIFF and VOCH formats might be included in a future release.
The NoIgnoreFormat command cancels the effect of a previous IgnoreFormat
command.
?Key
The KEY command allows you to enter a "registration" key. With the
registration key, you will not be required to click away one or more
requesters when running GFFT on the workbench.
Normally, once you are given a key, you would add a key command to the
tooltypes of the GFFT icon, or, if you normally start GFFT from the CLI,
you would add the key command to the .gfft startup file. The key tooltype
or command would look like this:
key=1234567890
The README file and/or the requester(s) that come up will explain how to
register for GFFT so that you can obtain the key.
?Interleave
?NoInterleave
* Note: this command is EXPERIMENTAL (even more than the others). *
* The theoretic validity of this technique is not well understood. *
The Interleave command tells GFFT to average the results of FFT's
performed on alternate samples. For example, 'Interleave 2' tells GFFT to
perform two FFT's, one on the odd frames and one on the even frames, and
then to average the results. 'Interleave 3' would tell GFFT to perform 3
such FFT's, and so on. The NoInterleave command may be used to cancel
interleave mode. Interleave on any non-positive or non-integer number is
invalid, and interleave set to 1 would be meaningless (it would be the
same as NoInterleave).
Syntax:
Interleave <interleave-factor: integer in the range 2 - huge>
NoInterleave
This is a counterpart to the ordinary way of averaging the results of FFT
performed on successive segments (which may also be done at the same time
if possible). While dividing up a file into more than the minimum number
of segments (i.e., with less than the maximum number of bins) does not
reduce the highest frequency for which an FFT value is computed, it does
increase the lowest non-zero frequency for which an FFT value is computed
(i.e., the low frequency resolution is lost). Meanwhile, Interleave does
not increase the lowest non-zero frequency, but instead reduces the the
highest frequency (leaving the low frequency resolution intact).
Unfortunately, though the utility of this feature seemed compelling for
analyzing a spectrum in bands (using Interleave averaging for the low
frequencies and typical 'bin' averaging for the high frequencies) the
results indicate there is some theoretical error here which I still don't
fully understand, as I haven't been able to get the bands to meet. I
think I understand the reason for this, but I don't understand it well
enough to know how to compensate for it. Meanwhile, I have found no
discussion of this 'interleaving' or 'alternating' technique in the
literature.
?LogX
?NoLogX
The LogX command will cause GNUPLOT to scale the x-axis logarithmically
during plotting (if plot mode is set). It has no effect on the spectral
data output by GFFT itself, except when a number of smoothing segments are
being applied. When smoothing with LogX on, a logarithmic mesh will be
used during the smoothing phase.
The NoLogX command cancels the effect of the LogX command.
?LogY
?NoLogY
The LogY command will cause GNUPLOT to scale the vertical axis
logarithmically during plotting (if plot mode is set). It has no effect
on the spectral data output by GFFT itself. The NoLogY command cancels
the effect of the LogY command.
If a dB conversion is selected with the dB command, LogY is probably
not desireable (as this would mean plotting logarithms on a logarithmic
scale).
LogY is intended to make the vertical axis (representing amplitude or
power) logarithmic. In 3D mode, it is actually the Z axis that is
vertical and that represents amplitude or power, so in that mode LogY
actually scales the Z axis logarithmically.
?LowFrequency
The LowFrequency command allows you to select the lowest frequency to be
output (and plotted, if applicable). By default, GFFT outputs and plots
the lowest non-zero frequency. You may specify 0 or any other floating
point number as the argument to a LowFrequency command. If no argument is
specified, the LowFrequency command restores the default.
Although the FFT process yields a value for the 0 frequency (e.g. D.C.),
typical FFT analyzers do not display it because it may display a
considerable offset caused by the sampling hardware.
Once you specify a LowFrequency, it will remain in effect for the current
sample file and any additional files processed in the same GFFT session.
Note that the LowFrequency is handled differently by RePlot than by OK and
ReOut. See help for the RePlot command for further information.
?LowY
The LowY command allows you to set the lowest value to be shown on the
vertical axis used for plotting by GNUPLOT. Using this command, you can
'zoom in' or 'zoom out' vertically into the plot. This command has no
effect on the data file written by GFFT. If the LowY command is given
without any arguments, the LowY value will be automatically determined by
GNUPLOT autoscaling.
Syntax:
LowY [<lowest Y value: double>]
Note that GNUPLOT might do strange things if you specify a LowY value
without also specifying a HighY value. It may, for example, decide to run
the Y axis upside down in order to show the widest range of Y values. Or,
if less than one Y unit would be plotted when one value is autoscaled,
GNUPLOT may decide the Y range is invalid. Be forewarned.
In 3D mode, the vertical axis (representing amplitude or power) is
actually the Z axis, so the value selected for LowY is then applied to the
Z axis.
?Mean
?Sum
The Mean command instructs GFFT to write 'mean' (average) values, which
is what it does by default. The Sum command instructs GFFT to write
'summed' values, which are summed but not averaged (not divided by
the number of frames and segments).
Mean values are equivalent to Root Mean Square (RMS) Amplitude or Mean
Square Power (actually, squared amplitude) values. Note that by default
GFFT normalizes Mean outputs to the level of total actual amplitude
or power within each bin. There are two commands, PSDensity and Pink,
which alter this default normalization.
I do not recommend the use of the Sum command, except for debugging
purposes.
?Multiply
The Multiply command allows you to multiply all of the output values of an
FFT by some constant non-zero number for scaling purposes. (This only
affects the amplitude or power values, not the frequency values.) If no
argument is specified, the previous multiplication factor is canceled.
?NoWarranty
The NoWarranty command displays the nowarranty disclaimer of GFFT,
excerpted from the General Public License.
?Numerical
?NoNumerical
The Numerical command replaces the new FFT routines written originally for
GFFT with routines from the book 'Numerical Recipes In C,' by Press,
Flannery, Teukolsky, and Vetterling (Cambridge University Press: 1988).
The NoNumerical restores the original GFFT routines.
You will probably find only very small differences between using the
GFFT FFT routines and the Numerical ones, though there are significant
differences in how they have been implemented. But this command enables
you to compare for yourself (as it has for me). Note that it only
replaces the code performing the FFT itself, not the segment averaging and
output processing.
GFFT is not distributed with the source code for the 'Numerical' FFT
routines, nor is this code linked into the distributed binary image,
because the Numerical routines have a copyright which does not permit
this. To enable this command, you must acquire the code by either by
buying the book and entering the source code yourself, or by buying the
source code diskette, and making an image with it included (uncomment the
line(s) defining 'NUMERICAL_RECIPES_AVAILABLE' in the smakefile. The
functions needed are 'four1.c' and 'realft.c.' Be sure NOT to distribute
a binary image of GFFT with the numerical recipes code included, or to
distribute the Numerical Recipes code in any other fashion without
permission of its authors.
?Octave
The Octave command allows you to select a particular octave within a file
whose format permits more than one octave (e.g. 8SVX). By default, the
lowest octave is selected--this is present in all files. You may return
to the default by giving an octave command with no argument. To specify
another octave, use an argument which is a single digit between 0 and 7.
1 specifies the lowest octave, and 7 specifies the highest one. 0 is a
special case which specifies the highest octave available, regardless of
how many octaves there are (it may also be the lowest). If the octave
specified is not available, this problem may not be detected until the OK
command is given, but no analysis will be performed.
Syntax:
Octave [<number>]
Examples:
gfft>Octave 0
gfft>Octave 1
?OneShotOnly
?NoOneShotOnly
The OneShotOnly command causes GFFT to read only the one-shot portion of
a sample in a format (e.g. 8SVX) supporting this feature. By default,
GFFT will read the combined one-shot and repeat portions of the file.
The OneShotOnly command implicitly cancels the RepeatOnly command as they
are mutually exclusive.
The NoOneShotOnly command cancels the OneShotOnly command and restores the
default operation if OneShotOnly had been in effect.
?Overlap
?NoOverlap
The Overlap command engages overlap mode (which is the default). The
NoOverlap command disengages overlap mode.
Because it makes the best use of a limited amount of data, overlap mode is
engaged by default. It is also able to include all the data in the
analysis, regardless of whether the number of frames is exactly 2n times a
power of 2 (where n is a positive integer). If you are more concerned
with making the best use of processing time, and are not concerned about
ignoring a trailing remainder of the data, you may wish to disengage
overlap mode.
In overlap mode, the windows applied to the data are overlapped. By
overlapping the windows (as compared with just laying them end-to-end to
cover all frames present) better use is made of a fixed amount of data in
reducing the variance of the computed spectrum. This is true for all
window shapes, but especially true for the non-rectangular ones.
Overlapping may provide up to 9/11 of the variance reduction of having
twice as much data to work with (see Press, et. al.).
Normally, windows are overlapped by half their length (i.e., the fixed
overlap percentage for flat FFT analysis is 50%). However, in overlap
mode, the overlap of the last window is decreased or increased to
encompass the remainder of the data.
Given real (i.e. non-complex) sample data, 2 data points (frames) are
required for each Bin. Thus, 1024 bins would require 2048 frames. With
50% overlap, two overlapping windows would fit exactly into 3072 (2048 x
1.5) frames, three overlapping windows would fit exactly into 4096 (2048 x
2) frames, and four overlapping windows would fit exactly into 5120 (2048
x 2.5) frames. But GFFT varies the overlap of the last window to fit
whatever amount of additional data is present after the last whole window
of data has been read. So, two windows are used for any number of frames
F such that 2048 < F < 4096, three windows are used for F = 4096, four
windows are used for 4096 < F < 6144, and so on, with the overlap of the
last window somewhere between 0 and 100% (non-inclusive).
Though this scheme will ensure that all frames are included in at least
one segment, it may result in either over-representation or
under-representation of the last region of data. This is a fairly minor
detail (especially considering that the FFT is really only intended for
'continuous' sounds...) but if you are concerned with such things you may
want to specify exactly the number of frames to be used using the Frames
or StartFrame commands available in the CLI interface, and make sure you
have chosen an exact multiple (two or greater) of the bin size for an
exact overlap fit. For 3D-Time analysis, you should set the Time Segment
Size instead (this is discussed further in the help for TimeSegSize).
?Pad
?NoPad
The Pad command activates 'Pad' mode. The NoPad command cancels Pad mode.
Pad mode is not activated by default, and its use is strongly discouraged.
In 'Pad' mode, the last (or only) partial segment of data will be padded
with zeros prior to analysis.
Though it may sound innocuous, zero padding can produce serious artifacts
in a computed spectrum, and I strongly discourage it. The default
'Overlap' mode takes the best use of all the data without padding or
truncation. Even truncation, which might result if 'Overlap' is
disengaged and the number of frames is not 2 times a power of 2, is
superior to padding for most purposes. The only advantage of padding is
that it permits the use of a larger maximum number of bins than the other
techniques in some cases, but be forewarned that many of those bins will
be filled with garbage.
See help for the Bins and Overlap commands for further discussion.
?Parseval
?NoParseval
The Parseval command selects the Parseval normalization option. The
NoParseval command cancels the Parseval normalization option. Parseval
normalization is the default. This may be slightly slower, but is more
accurate. By selecting the NoParseval option, you may get a performance
improvement of about 2.5%, at the cost of a small error (I have seen
0-20%) in the overall spectrum level. The spectrum shape is unaffected.
Using Parseval normalization, the accuracy of the output normalization
(prior to PSDensity and/or Pink normalization, if also applied) is assured
by applying Parseval's theorem. According to Parseval's theorem, the sum
of the squared sample values should equal the sum of the (squared
amplitude) bin values. Otherwise, estimators are used (based on the
average window gain, etc.) which are fairly accurate.
Parseval normalization is particularly significant if non-rectangular data
windows are used, and is more significant for complex waveforms than
simple ones.
?Parzen
The Parzen command selects windows of a particular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins. The Parzen command cancels the effect of any preceding
window shape command.
The Parzen window is based on the formula presented by Press, et al, in
their book 'Numerical Recipes.' It is not the same as the "Parzen
Window" identified by Harris. It is superior to the triangle and
rectangle windows in sidelobe rejection.
?Pink
?NoPink
* Warning! The results of this command may not be entirely 'correct.' *
The Pink command engages pink mode, in which a particular sort of
frequency-dependent normalization is performed on the spectral output so
that pink noise will be shown as having nearly 'flat' response. The
NoPink command cancels pink mode.
(Pink noise is random noise shaped so that there is an equal amount of
energy or amplitude in each octave or fractional-octave band. It is
frequently used in acoustic testing.)
Pink mode simply weights each output value by a corrective factor; it does
not do any grouping and/or averaging (so no resolution is lost). The
current formula does not seem entirely accurate at the lowest frequencies,
where the results may vary depending on how many bins are being used.
This makes it difficult (or impossible) to splice several curves of pink
noise with different numbers of bins together. In any case, the sum of
the squared output values will no longer reflect the sum of the squared
input values, in fact, the scale may be offset considerably. You may
use the 'Multiply' command to rescale the results conveniently.
(You may also wish to do Smoothing with LogX set when plotting pink noise,
and use extremely large sample files with 1,000,000 frames or more to
allow for the randomness in pink noise to average out.)
?Plot
?NoPlot
The Plot command selects Plot mode. The NoPlot command cancels Plot mode.
Plot mode is the default for Workbench and CLI-Interactive modes; it is
not the default for CLI-batch mode.
In Plot mode, GNUPLOT is automatically invoked in a background process to
display the result of any spectrum analysis performed. If no spectrum
file has been explicitly specified, GFFT will create a temporary spectrum
file to use to send data to GNUPLOT. All such temporary files created by
GFFT will be deleted on exit from GFFT (if the plot display was canceled).
If plot mode is disengaged, a named output file must be explicitly
specified with the Write command--otherwise the analysis would simply
create and then delete a temporary file, which would be pointless. It is
not possible to plot data written to 'con:' (see help for the Write
command for further details on con:) so if con: is chosen as the write
file, Plot mode is invalid.
?PlotOutput
The PlotOutput command lets you set the output device or filename for
GNUPLOT. By default, plots are displayed on an amiga screen, and no
PlotOutput command is required. However, if the Terminal command is used
to produce a plot on an external plotter or printer or to a Postscript or
TeX file, the PlotOutput command may be required. (The argument to the
PlotOutput command will become an argument used in an Output command to
GNUPLOT.)
Syntax:
plotoutput <device or filename: char *>
plotoutput '<device or filename: char *>'
plotoutput "<device or filename: char *>"
plotoutput ''
plotoutput ""
plotoutput
If the terminal command is given without any arguments, or if the argument
is a null string enclosed in "" or '', GNUPLOT will use the default
output (i.e. it will plot to an Amiga screen).
Examples:
plotoutput ser:
plotoutput par:
plotoutput Plot1.PS
Note: Because GNUPLOT already formats the output for the particular
printer you have, use of the serial device (ser:) or parallel device
(par:), whichever your printer is actually attached to, is more
appropriate than the use of the printer device (prt:). GNUPLOT supports
many different printers and plotters, but does not support the Amiga
Intuition printer drivers.
Example:
terminal hp500c
plotoutput par:
?PSDensity
?NoPSDensity
The PSDensity command activates an output normalization in which each FFT
value is divided by the width of the bins used in Hz. The NoPSDensity
command restores the default (total amplitude/power) normalization.
By default, GFFT will output values which are normalized to show the total
amplitude or power (squared amplitude) present in each frequency range
centered on that bin's nominal frequency, as well as can be determined by
the FFT technique (which depends on the window shape used, the number of
segments which can be averaged, and other parameters, but does not feature
an extremely sharp cut-off from one bin to the next as compared with some
esoteric spectrum analysis techniques).
For some applications, it is preferable to have a 'density' normalization,
for which bin values are normalized by the bin width. This will permit
several FFT's of a random noise source using different numbers of bins to
be directly compared with one another or spliced together, even though the
wider bins (which result from using a smaller number of bins) will
naturally capture more amplitude or power. The Multiply command can then
be used to scale each FFT as required.
?Quantization
?NoQuantization
The Quantization command lets you set a quantization value for GFFT
output. For example, a quantization of 0.1 will cause all amplitude or
power values to be rounded off to the nearest 0.1. The quantization value
in effect can be canceled with the NoQuantization command, or by giving
the Quantization command with no argument.
Syntax:
Quantization [<quantization value: double>]
NoQuantization
Note that you could use any arbitrary value for quantization (e.g.
12.3456) though this might not be very useful. Typical values might be
0.1, 0.05, 0.001, etc.
This has no effect on the FFT computation itself, and does not affect the
output of frequency values.
[Unfortunately, quantization may cause 'quantum jumps' to occur back and
forth as a spectrum nears each quantum threshold. Thus, the quantization
feature is not quite as useful as originally intended. What needs to be
done here, I think, is to apply quantization BEFORE smoothing, though the
result would then not be quantized as such. If you have any useful ideas
here, please let me know. Meanwhile, consider the use of explicit HighY
and LowY values to make small Y variations appear less pronounced.]
?Rate
The Rate command allows you to enter the sampling rate for an unformatted
file. You must enter a rate for an unformatted file before giving the OK
command or no analysis will be performed. One you enter a rate, it
remains in effect for all further unformatted files until you select a new
rate or select a formatted file. The rate command expects one numeric
argument which may be in either integer or floating point format. The
rate must be greater than zero.
Syntax:
Rate [<sampling rate: number>]
gfft>rate 10000
gfft>rate 1.119e6
You may also override the rate indicated by a formatted file with the rate
command. (For example, you may wish to change the units from seconds to
microseconds.) To override the rate for a formatted file, you must give
the rate AFTER giving the Read command for the file. (When you give the
Read command the formatted information is read and it supercedes any Rate
command previously in effect.) You may return to the default rate
indicated by the file itself by giving a rate command with no argument.
?Read
The Read command selects a sample file for GFFT to read, or cancels
reading from the sample file currently in effect if no argument is given.
Once a sample file is selected, it remains in effect for one or more
analyses until another sample file is selected.
The argument following Read may be a complete file pathname or a relative
file pathname (relative to the current directory when GFFT was started).
If the filename contains spaces, you must enclose it in either apostrophes
(') or quotation marks (").
Syntax:
Read [<filename: string>]
Read '<filename: string>'
Read "<filename: string>"
Example:
gfft> read sample1
gfft> rate 10000
gfft> bins 1024
gfft> ok
gfft> smoothing 100
gfft> ok
gfft> read "ram disk:samples/my old piano"
gfft> ok
gfft> read /old/sample1
gfft> ok
GFFT can read both formatted and unformatted files. If GFFT understands
the format of the file (it currently understands IFF 8SVX, AIFF, and AVR
formats), it will automatically set the sampling rate. If the file is
unformatted, you will have to set the sampling rate manually before
beginning an analysis. You may also have to use the Bits and Unsigned
commands if your unformatted file uses does not use the default for
unformatted files (8 bits, signed).
If the file is formatted using an unrecognized format, you may still be
able to read it using the CLI command 'StartByte' (which allows you to
skip over the file header) if you know how long the file header is, and
'Frames' (which allows you to read a specified number of frames, skipping
any file segments following the sample data). This is not recommended
unless you are very familiar with the inner workings of the file format
you are working with. (GFFT recognizes but does not yet understand RIFF
and VOCH formats. See help for the IgnoreFormat command for further
advice on how to deal with those formats.)
A sample file must be selected before you can perform an analysis.
However, you may specify 'con:' as the sample file. This will cause GFFT
to prompt you to enter each data point from the keyboard after the OK
command is given. You may then enter each point as a floating point or
integer number. Note that for con: you must also enter the sampling rate
before giving the OK command, since con: has no 'formatted' information.
This may be useful if you have a small number of manually recorded data
points, or wish to experiment with FFT spectrum analysis to gain a deeper
understanding of it. For example, if you entered the following:
gfft> read con:
gfft> rate 10000
gfft> ok
Enter <value> (float OK) or <newline> to end input [0]: 1
Enter <value> (float OK) or <newline> to end input [0]: 0
Enter <value> (float OK) or <newline> to end input [0]: -1.0e0
Enter <value> (float OK) or <newline> to end input [0]: 0
Enter <value> (float OK) or <newline> to end input [0]:
You would get a spectrum of 2 points (Nyquist Frequency/2, Nyquist
Frequency) with amplitude 0.707... at the first frequency and amplitude 0
at the second frequency. This illustrates the default normalization of
GFFT, since 0.707... is also the RMS amplitude of the signal you have
entered, and it has a frequency of half of the Nyquist frequency.
Once con: has been specified as the sample file, it remains in effect
until another Read command is given. However, the con: data is stored
internally so you do not have to re-enter it for each analysis. If you
wish to read new data from con:, you may give the 'Read con:' command
again.
con: must be specified in lower case.
?Rectangle
The Rectangle command selects windows of rectangular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins. The Rectangle command cancels the previously selected
window shape.
The 'Rectangle' window is the simplest window (effectively a series of
1's) and the fastest to compute and apply (i.e. no computation or
application is necessary). It also results in the sharpest initial
fall-off on either side of a spectral peak. However, it is the most
susceptible to the presence of side-lobe artifacts. If you wish to remove
the influence of side-lobes, use a different window shape, such as
'74dbBlackmanHarris.'
Rectangle is currently the default window shape.
?ReOutput
The ReOutput command allows you to rewrite the results of the preceding
analysis subject to a number of changed parameters. The FFT analysis
itself will not be repeated, only the output processing (and plotting
phase--if Plot is selected). This is useful for making minor changes
after a long analysis without repeating the analysis itself.
Here are the parameters which may be changed before a ReOutput:
Spectrum File ('Write,' 'Open,' or 'Append' commands)
Plot (or NoPlot)
Smoothing Segments and Squared Smoothing
High Frequency
Low Frequency
Mean
Power
Amplitude
dB
LogX
LogY
Multiply
Sampling Rate
Pink
Parseval
Quantization
LowY
HighY
Here are just a few parameters WHICH SHOULD NOT BE CHANGED between OK and
ReOutput:
Sample File (Read command)
Bins
Overlap
Pad
Window Shape (Rectangle, 74dB, etc.)
Any 3d parameters...in fact, ReOutput is not at all possible with 3d...
see help for the RePlot command.
Warning! Currently, if you change these parameters and ReOut, you will
not get any sort of warning that the changed values have no effect.
There is also a RePlot command, with different capabilities (generally
more limited) which skips the output stage (but allows change of 3d
parameters).
?RepeatOnly
?NoRepeatOnly
The RepeatOnly command causes GFFT to read only the repeat portion of a
sample in a format (e.g. 8SVX) which supports this feature. By default,
GFFT will read the combined one-shot and repeat portions of the file. The
RepeatOnly command implicitly cancels the OneShotOnly command as they are
mutually exclusive. The NoRepeatOnly command cancels the RepeatOnly
command and restores the default operation if RepeatOnly had been in
effect.
?RePlot
The RePlot command allows you to plot the previous analysis with a few
changed parameters. The analysis itself, including the output phase, will
not be repeated. Instead, GNUPLOT will be re-invoked with with new
parameters.
Here are the parameters which may be changed between OK and RePlot:
Plot (if previously off)
LogX (with no smoothing! LogX smoothing requires output phase)
LogY
RotX
RotZ
LowFrequency (*see note below)
HighFrequency (*see note below)
Warning! Currently, if you change other parameters and RePlot, you will
not get any sort of warning that the changed values have no effect.
Note that the ReOutput command permits the modification of many more
parameters than RePlot, though it might take slightly longer, and it does
not permit the repetition of a 3D analysis. (ReOutput will also produce a
plot if Plot mode is activated.)
RePlot may also be used in conjunction with the Open command to RePlot
previously stored spectral data files. See help for the Open command
for further details.
*Note that RePlot does not effect the LowFrequency and HighFrequency in
exactly the same way as OK or ReOutput. OK and ReOutput 'filter' the data
written to the output data file so that no data outside the range
established by LowFrequency and HighFrequency is written. RePlot cannot
filter the data which has already been written, but instead sends an
explicit 'set xrange' command to GNUPLOT. OK and ReOutput simply let
GNUPLOT do autoranging for the x coordinate. If you wanted a plot with
artificially large left and right 'margins,' you could first do OK (with
the desired actual data range set or defaulted), then do a RePlot with
LowFrequency and HighFrequency values set outside the range of actual data
to the point(s) where you would like the margins to be. Thus, this
difference in the way LowFrequency and HighFrequency are used in RePlot
mode is actually a 'feature.'
?RotX
The RotX command changes the X Rotation factor used by GNUPLOT in
rendering a three-dimensional plot (as would be produced using the Time3D
command(s).) Giving RotX without any arguments restores the default
value, which is 60 degrees.
Syntax:
RotX [<x rotation: degrees 0-180>]
Example:
gfft>RotX 10
?RotZ
The RotZ command changes the Z Rotation factor used by GNUPLOT in
rendering a three-dimensional plot (as would be produced using the Time3D
command(s).) Giving RotZ without any arguments restores the default
value, which is 30 degrees.
Syntax:
RotZ [<x rotation: degrees 0-360>]
Example:
gfft>RotZ 90
?Set
Most commands in GFFT are 'set' commands, i.e., they adjust some particular
setting which takes effect later when the OK command is given. It is not
necessary to preface these command with the verb 'Set,' as it is implied.
However, for those whose fingers have been trained (by GNUPLOT and/or
other programs) to type SET without thinking, an explicit SET command is
also provided in GFFT. It is essentially a dummy command, or, more
precisely, it simply executes its arguments as if they are a complete
command string in themselves.
For example, the two following commands are equivalent:
set logx
logx
Set does not discriminate between commands that are parameter setting
commands and those that are not. So, you could type 'set ok' which would
perform the OK command.
?SaveMemory
?NoSaveMemory
The SaveMemory option indicates to GFFT that you need to save memory
space, possibly at the expense of processing time. The NoSaveMemory
command cancels this. By default, GFFT will use extra memory if it can be
used to save estimated processing time, even if the effect on processing
time is fairly small.
Currently, the only effect this has in on whether the trigonometric values
used in the primary FFT function are saved for re-use. By default, these
values are saved, so if more than one segment is processed, they will not
have to be recomputed. This saves time at the expense of a considerable
amount of memory (which increases as the number of bins increases). If
you are using a very large number of bins with a limited amount of memory,
you may need the SaveMemory option. I have found that even with a large
number of segments, the effect of saving these trigonometric values is
fairly small, about 6% on overall performance at most. With some cached
processors having very high internal floating point throughput (e.g.
68040), the 'savememory' option might actually result in increased
performance under some unusual circumstances, though the difference is
likely to be quite small.
?SaveSettings
?SaveParameters
The SaveSettings and SaveParameters commands save the current non-default
settings to the named file. The filename is required as an argument.
An existing file with the same name will be backed up once.
Syntax:
SaveSettings <filename>
SaveParameters <filename>
SaveSettings will save the name of the current input and output files
to the settings file, while SaveParameters will not.
A settings or parameters file can be loaded with the 'LoadSettings'
command. If renamed to ".gfft," and placed in the S: directory or in
the directory from which GFFT is executed, it will be loaded automatically
at startup.
Action commands such as OK, ReOutput, RePlot, Workbench, or SaveSettings
will not be written to a settings file. However, such commands can be
added to the settings file after it has been written with a text editor.
?ShowSettings
The ShowSettings command displays some of the settings (such as input
filename, output filename, number of bins, sampling rate, and window
shape) which are currently in effect.
?Signed
?Unsigned
The Signed command specifies that the input data file will have samples in
'signed' format. The UnSigned command will specify that the input data
file will have samples in 'unsigned' format. These commands are not
necessary for formatted files, as the property is determined by the file
type and/or header. However, if you give the Signed or Unsigned command
after the Read command, the Signed or Unsigned command will override the
file type and/or header.
Signed is the default and most usual type.
?SmoothingSegments
Using the SmoothingSegments command, you can specify that the output be
'smoothed' or averaged over a certain number of segments. (This works
best if the number of segments is much smaller than the number of bins
used). The argument to SmoothingSegments is the number of segments to
span the range from the lowest non-zero frequency to the Nyquist
frequency. If the SmoothingSegments command is given without any
arguments, smoothing is canceled.
Syntax:
SmoothingSegments [<segments: integer>]
Example:
gfft> smooth 200
If you plot with a large number of bins, or with LogX on, you may find
that the left or right side of the plot line 'blooms' vertically with a
wide range of values. Rather than 'pixel averaging,' GNUPLOT shows the
effect of plotting a line to each and every data point (even if many such
points occur within one vertical line of pixels). SmoothingSegments can
be used to eliminate this 'blooming' effect, simulate 'pixel averaging,'
and give you a more easily interpretable curve (though some important
actual detail may be lost).
If LogX is enabled, the mesh applied to the output will be logarithmically
scaled. The combination of using LogX, SmoothingSegments, and a extra
large number of Bins is especially recommended for random noise analysis
and/or whenever LogX is used.
The smoothing technique is very simple. A mesh of smoothing segments is
laid on top of the FFT bins, and for each smoothing segment containing
one or more bins, the average Y (amplitude) and X (frequency) values are
computed, and these become the X and Y values that are written to the
output file. If there is only one data point within a smoothing segment,
it is unchanged by this procedure. If there is no data point within a
smoothing segment, no data point will be output. (Because of this, if LogX
is enabled, it is very possible that there will not be as many data points
as the number of segments you have chosen. For example, given 4096 bins
and 400 smoothing segments, only about 225 points will actually be
produced because the actual data points in the beginning are farther apart
than the smoothing segments.)
If SquaredSmoothing selected, the averaging of the Y values is done by
taking the positive root of average of the sum of the squared Y values.
I am aware of much more sophisticated smoothing or 'convoluting'
procedures which may have greater theoretic validity (e.g., see S. P.
Lipschitz, T. C. Scott, and J. Vanderkooy, 'Increasing the Audio
Measurement Capability of Analyzers by Microcomputer Postprocessing,'
Journal of the Audio Engineering Society, Volume 33, Number 9, September
1985...their technique simulates 1/3 octave bandwidth digital filters
which is useful in that it supposedly approximates human auditory
limitations), but these are also much more complicated. The present
technique is workable and useful, though it may be somewhat lacking in
theoretic validity (though it is not entirely without precedent), and the
results should be interpreted with some caution (you are probably not
seeing all the real features that are there--but then that is true with
any technique).
?SquaredSmoothing
?NoSquaredSmoothing
The SquaredSmoothing command changes the operation of SmoothingSegments
(see) slightly. It has no effect if SmoothingSegments are not being used.
The NoSquaredSmoothing cancels SquaredSmoothing.
With SquaredSmoothing selected, the averaging of the Y values is done by
taking the positive root of the average of the sum of the squared Y
values.
I have found this to make a nearly negligible difference in practice, but
your experience may vary.
?StartByte
The StartByte command allows you to set a byte offset into a file at which
GFFT will start reading samples. StartByte should only be used with
unformatted files, those whose format is not recognized by GFFT, or whose
format is being ignored with the IgnoreFormat command, and only by those
who understand the file format. If the StartByte command is given without
an argument, the StartByte feature is canceled.
See also the StartFrame command, which is intended for more general usage.
?StartFrame
The StartFrame command allows you to set an offset into the sampled data
at which GFFT will begin reading. This is intended for use with formatted
files which GFFT understands or unformatted files. Use this command if
you wish to ignore an early portion of the data.
Syntax:
StartFrame [<frame number: non-negative integer>]
If Time3D processing is being performed, the StartFrame will apply to the
data as a whole, and not to each Time3D segment.
?Terminal
The terminal command allows you to set the terminal type to be used by
Gnuplot. Ordinarily, GNUPLOT will default to using the 'amiga' terminal.
Thus, your plot will be displayed on an amiga screen. Using the
'terminal' command, you can set it to use a printer, plotter, or anything
else supported by GNUPLOT.
Syntax:
terminal
terminal <terminal name: name>
terminal '<terminal specification: character string>'
terminal "<terminal specification: character string>"
terminal ""
terminal ''
If the terminal command is given without any arguments, or if the argument
is a null string enclosed in "" or '', GNUPLOT will use the default
terminal type. If the argument given to the terminal command consists of
more than one word separated by spaces, it should be enclosed in "" or ''
(whichever is not used in the actual string).
Examples:
terminal amiga
terminal hp500c
terminal dumb
terminal 'postscript landscape color "Courier" 14'
terminal
Note that if you specify a printer terminal, you should also use the
PlotOutput command to specify the output device (ser: or par:, NOT prt:)
or filename.
For further information about the many GNUPLOT terminal types, refer to
the GNUPLOT documentation.
Note: the version of GNUPLOT supplied with WinGnuPlot defaults to using a
terminal 'amigawindow' which requires MUI. For use with GFFT, this
must be changed to terminal 'amigascreen,' which is done by renaming the
file .gfft-WinGnuPlot to .gfft as discussed in the INSTALLATION file.
?Time3D
?NoTime3D
?TimeOffset
?TimeOverlap
?TimeSegments
?TimeSegSize
Syntax:
Time3D
NoTime3D
TimeOffset [<Time Offset: integer>]
TimeOverlap [<Time Overlap: floating point number>]
TimeSegments [<Time Segment Count: integer>]
TimeSegSize [<Time Segment Size: integer>]
The '3D-Time' facilities of GFFT are intended to enable you to show how a
spectrum varies with time. GFFT is very flexible in how it enables you to
do this. The results can also be plotted in 3 dimensions by GNUPLOT where
Z is the axis of time.
The basic model is as follows: The sample frames are divided into segments
called 'Time Segments,' and a spectrum analysis is performed on each Time
Segment. Time Segments can be overlapped, and the overlap can either be
specified as a fraction of the size of each Time Segment ('Time Segment
Overlap') or as the number of frames by which each Time Segment is ahead
of the previous one ('Time Segment Offset'). By default, the Time Segment
Overlap is set to 0.5 (i.e. 50%) and the 'Time Segment Offset' is computed
automatically. Then, either the number of time segments can be specified
(this is the 'Time Segment Count') or, their size can be specified (this
is the 'Time Segment Size') whichever is more convenient or useful to your
application.
One of the two parameters Time Segment Count and Time Segment Size must be
set. When either of these two parameters is set, any previous value of
the other one will then be determined automatically.
Time Segment Overlap has a default value of 0.5. If Time Segment Offset
is set, it supercedes Time Segment Overlap.
If you set any of the above 3D-Time parameters, Time3D mode is activated
automatically. You may deactivate it by giving the NoTime3D command, and
subsequently reactivate it by giving the Time3D command.
You may also adjust the X Rotation and Z Rotation factors used by GNUPLOT
in rendering the 3-d plot using the RotX and RotZ commands.
Note that Time Segments are distinct from the FFT 'segments' used in a
flat spectral analysis--and in the FFT analysis within each Time Segment.
If each Time Segment is large enough relative to the number of Bins, there
may be more than one FFT segment within each Time Segment, the results of
which are averaged to reduce the variance. Within each Time Segment, the
usual 'Bins,' 'Overlap,' 'Pad,' and window shape parameters still apply,
so the full flexibility of a flat GFFT is available (though the maximum
number of bins possible may be reduced). Only one parameter available to
a flat analysis is unavailable for analysis within each Time
Segment--StartFrame. StartFrame will apply to the input file as a whole
and not to each Time Segment.
In cases where 3D-Time analysis reduces the number of bins possible, the
use of high performance window shapes such as Hann or 74dB Blackman-Harris
is recommended.
Examples:
1. Suppose you just want a rough idea as to how the spectrum in a fairly
small sample file (such as an instrument) varies over time, and are
willing to use the default Time Segment Overlap (50%), and would simply
like each segment to use the maximum Bins size possible (with overlap, if
possible). You might figure 5 time segments would be adequate to get a
rough idea, yet would not be too many considering the number of frames.
(If you have a very small sample file, you might have to use only 2 or 3
Time Segments. Increasing the number of Time Segments will reduce the
maximum possible number of bins, so there is a trade-off here which is
critical for small sample files.)
gfft>read piano.iff
gfft>TimeSegments 5
gfft>74dB-Blackman-Harris
gfft>OK
If the Bins value had previously been set to a specific value, or if a
NoOverlap command had previously been given, you would also include one of
the following commands prior to OK:
gfft>Bins
gfft>Overlap
2. Suppose you wish to divide the sample file into non-overlapping time
segments which could each be analyzed with 1024 bins (with no overlap or
padding within each time segment).
First set the Time Segment Size parameter to 2048, then set the Time
Overlap parameter to 0. (For non-complex data, there must be 2 sample
frames for each FFT bin.) You may either specify 1024 bins or use the
maximum (default) setting, which is re-established by giving a Bins
command with no argument. Since exactly 2048 frames are available in each
Time Segment, and this corresponds exactly to what would be required for
1024 bins, no overlap will be used within each Time Segment regardless of
whether the Overlap mode is engaged, so it is not necessary to give the
NoOverlap command in this case.
gfft>Read manysamples.aiff
gfft>TimeSegSize 2048
gfft>TimeOverlap 0
gfft>Bins
gfft>OK
3. Suppose you wish to have each Time Segment to be ahead of the previous
one by exactly 1000 frames. (This might apply if you want the z axis to
have increments of 0.1 second, and the sampling rate was 10,000.) You
consider some Time Segment overlap of approximately 0.5 to be acceptable,
but you would like an analysis with 1024 bins.
gfft>Read myrate10000
gfft>TimeSegSize 2048
gfft>TimeOffset 10000
gfft>OK
4. Suppose you have a VERY large sample file, and would rather not
analyze the whole thing, but would like a 'spot' analysis every 100,000
frames. You would like to have 1024 bins used in each analysis, but would
prefer to reduce the variance of each 'spot' spectrum by averaging 4
overlapped segments within each time segment.
Note that the overlap used for a flat spectral analysis and within each
Time Segment is fixed at 0.5 and cannot be changed (though it can be
turned off). Therefore, 2 overlapping FFT segments would occupy 1.5x the
space of one segment, 3 overlapping segments would occupy 2x, and 4
overlapping segments would occupy 2.5x if exactly these numbers of frames
are available.
So, to get 4 overlapped FFT segments within each Time Segment, we would
specify the TimeSegSize to 2.5 x (1024 x 2) which is 5120. In this case
we would have to specify the Bins too, otherwise they would default to
the maximum possible, 2048.
gfft>Read hugefile.aiff
gfft>TimeOffset 100000
gfft>TimeSegSize 5120
gfft>Bins 1024
gfft>OK
(Actually, 2 overlapping segments will be used for any number of frames
greater than 1 segment but less than 2 segments, 3 overlapping segments
will be used for exactly the number of frames in 2 segments, 4 overlapping
segments will be used for any number of frames greater than 2 segments but
less than 3 segments, and so on.)
?Topaz
The Topaz command forces the use of the font TOPAZ 8 in the GFFT Dialog
Window and associated requesters. It has no effect during CLI mode, nor
on GNUPLOT rendering. It must be specified before the Dialog Window is
opened. The easiest way to do this is to include it in a GFFT startup
file or as a tooltype (see HELP INTRODUCTION).
If, for some unforeseen reason, your system default font does not work well
in the GFFT Dialog Box, you may force TOPAZ 8 to be used by giving the
TOPAZ command (probably in your setup file or as a tooltype).
GFFT will attempt to use your system default font (the monospaced one) in
the Dialog Window if you have Amiga OS 2.0 or later. If your screen is
not large enough to display a 80x24 grid of characters, or if the Topaz
command has been given, GFFT will use the TOPAZ 8 font which should
provide a tolerable display on all systems.
?Triangle
The Triangle command selects windows of triangular shape. These windows
will be applied to the data in segments whose size is determined by the
number of bins. The Triangle command cancels the effect of any preceding
window shape command.
The 'Triangle' window is the next simplest window, after the Rectangle
window. Its shape is that of a triangle peaking in the center of each
data segment. The 'Triangle' window is often called the 'Bartlett'
window, after a scientist who found it to be useful.
The triangle window is superior to the rectangle window in side-lobe
rejection. In turn, it is inferior to all remaining window shapes in
side-lobe rejection.
?Welch
The Welch button selects windows of particular shape. These windows will
be applied to the data in segments whose size is determined by the number
of bins. The Welch command cancels the effect of any preceding window
shape command.
The Welch window is based on the formula presented by Press, et al, in
their book 'Numerical Recipes.' It is superior to the triangle and
rectangle windows in sidelobe rejection.
?Workbench
The Workbench command will open a 'GFFT Dialog Window' on the workbench
(or the default public screen) to continue the current GFFT session. If
you have already selected file(s) and/or options, these will continue in
effect and may be shown in the Dialog Window display. From the GFFT
Dialog Window, you may perform any operations ordinarily available in that
display, the same as if you had clicked on the GFFT icon to begin with.
While the GFFT Dialog Window is active, no more commands will be accepted
from the console, but you may be prompted to enter data points from the
console if 'con:' is specified as the sample file.
To resume entering commands from the console, click the 'CLI' button on
the lower left hand of the GFFT Dialog Window display. At that point,
the GFFT Dialog Window will be removed and GFFT will prompt for the
next command.
You may go back and forth between graphical and command modes as often as
you wish.
?Write
The Write command enables you to explicitly name and save the file of
spectral data written by GFFT (and read by GNUPLOT). By default, if plot
mode is activated (which is the default except for CLI-Batch mode),
temporary spectrum file(s) are created automatically by GFFT for GNUPLOT
and deleted when GFFT exits, so it is not necessary to give a Write
command. But if you would like to save the spectrum file, or if plot mode
is not activated, you must specify an explicit spectrum file name before
giving the OK command. To return to the default (using automatically
named temporary files), give the Write command without an argument.
Note that spectral data will only be written after an OK command is given.
Syntax:
Write [<filename>]
Write con:
There are several reasons why you would use a Write command:
(1) GNUPLOT uses the filename in the legend it creates to
identify plotted lines. You may wish to use a nicer name
than the one automatically created for the temporary file.
(2) You want to save spectral data files for later plotting or
or other uses.
(3) You wish to display the output data points on the console.
Note that if you specify the device 'con:' as the spectral
output data will be written to the console. In this mode,
it will not be possible to plot the data.
Note that if you perform more than one FFT without changing the Write
name, the later data will, by default, overwrite the earlier data from the
beginning. If you would rather accumulate data in the same file (such as
if you are computing a particular spectrum in bands), use the Open command
(see) instead of the Write command. If you would like to view several
spectra in the same plot, use the CombinePlots command (see).
Example:
sys> gfft
gfft> read whales.iff
gfft> hann
gfft> write whales-hann
gfft> ok
gfft> combineplots
gfft> 74db
gfft> write whales-74dB
gfft> ok ;both whales-hann and whales-74db are plotted
?Appendices
The following appendices are present: code contributors, idea
contributors, and financial contributors.
?code contributors
Code has been submitted by and accepted from...
[See your name here...please contribute code, GOOD code.]
[Please see README file for further details.]
?Idea Contributors
?References
Just a few of the multitude who have developed the ideas behind this
program can be listed here...
Jean Baptiste Joseph Fourier...developer of the Fourier Series
Danielson and C. Lanczos...FFT pioneers of the 1940's
J.W. Cooley, J.W. Tukey, and R.L. Garwin of IBM...first to make the
decimation-in-time FFT public, and in the public domain (YES!)
N. Brenner of Lincoln Laboratories...refined the 'in-place' algorithm
Julius Von Hann...developer of the Hann[ing] window
Fredric J. Harris, window expert and refiner of the 'Blackman-Harris'
window functions
(Very much was learned from Press, et. al, below, listed in references)
Jay Miner and the other creators and developers of the Amiga computer
Guido van Rossum for SOX and 'FAQ: Audio File Formats' (from which much
was learned)
David Champion for OmniPlay (from which some was learned)
Malcolm Slaney and Ken Turkowski for ConvertFromIeeeExtended (from which
some was learned)
Richard M. Stallman and the Free Software Foundation, for GNU Emacs
(which was used in the creation of this program), the GNU General
Public License, and the GNU Manifesto
Dennis M. Ritchie, for the C programming language (see references)
The SAS Institute, Inc., for the SAS/C compiler (A quality product)
Thomas Williams, Colin Kelley, and innumerable contributors for
Gnuplot
Adrian Aylward and Robert Poole for POST version 1.86enh
All the others whose work and vision has made this possible
REFERENCES:
Commodore Amiga, Inc., 1992. 'Amiga ROM Kernel Reference Manual:
Libraries, Third Edition' and 'Amiga ROM Kernel Reference Manual: Includes
And Autodocs, Third Edition.' (Reading, Massachusetts: Addison-Wesley
Publishing Company)
Fredric J. Harris, 1978. "On the Use of Windows for Harmonic Analysis
with the Discrete Fourier Transform," Proceedings of the IEEE, vol. 66
pp. 51-83.
Brian W. Kernighan and Dennis M. Ritchie, 1988. 'The C Programming
Language, Second Edition.' (Englewood Cliffs, New Jersey: Prentice Hall)
Press, Flannery, Teukolsky, and Vetterling, 1988. 'Numerical Recipes in
C' (Cambridge UK and New York: Cambridge University Press), pp. 398- 470.
SAS Institute, Inc., 1993. SAS/C Development System User's Guide, Volumes
1-3, Version 6.50. (Cary, NC: SAS Institute, Inc.)
?financial contributors
Only a limited number of financial contributors, and ONLY those who give
their EXPRESS permission will be listed here, and identifications may be
limited in length (1-2 lines maximum) and/or edited. Presence on this
list DOES NOT constitute any form of endorsement either to the parties
listed or from them to GFFT. For the purposes of this list, purchasing
services at minimum donations does not qualify.
?Installation
Installation instructions are included in a file named 'INSTALLATION.'
