Gold Fish 2/goldfish_vol2_cd1.bin/files/misc/sci/gfft/gfft.help

Text File | 1994-08-29 | 168.1 KB | 3,890 lines

?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., it has a GFFT tooltype).

 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.


 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 in the command line invoking GFFT, interactive mode
 is assumed.  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.

    sys> gfft ?

    OR

    sys> gfft

    gfft> help

 If you desire, a Workbench session can be started from the CLI.  To do
 this, give GFFT the 'Workbench' command.  From the Workbench, you can then
 go back to the CLI session (if it was interactive) by clicking the CLI
 button.

 sys> gfft workbench

 [workbench session]

 OR

 sys> gfft

 gfft> workbench

 [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
 to your CLI prompt.  (This assumes that you have installed GFFT to a
 directory in your path, or have the current directory set to the directory
 or device where GFFT resides.)  If you specify any additional arguments in
 the GFFT command line, GFFT will start in 'batch' mode instead.

 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.  Aren't you glad I don't require you
 to click away a Version/Copyright requester each time you start GFFT?

 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 chose<n 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-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.


?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.


?ShowSettings

 The ShowSettings command displays a number of settings (such as input
 filename, output filename, number of bins, sampling rate, and window
 shape) which are currently in effect.

 ShowSettings has not kept up with the enormous growth of parameters and
 options in this program.  I figure most people will be using the
 workbench interface anyway, or switching between CLI and workbench.
 Let me know if you are a CLI user so you can be counted.


?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.)


?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.'