************************************************************************

CSPECT - REAL-TIME OSCILLOSCOPE / SPECTRUM ANALYSER 

************************************************************************

INTRODUCTION

Cspect is a real-time signal analysis program for SGI computers. I hate
writing documentation so I'm afraid this isn't going to be very
comprehensive.

On launch, the "time display" window is displayed and the program starts
reading in data from the microphone input (this can be changed to a
line input or an aiff/aiffc soundfile) and displays the RMS level of
the input in a rolling display.

************************************************************************

BASIC CONTROLS

<SPACE BAR> **Pressing the space bar pauses/unpauses the input.

<AXIS BUTTONS> **The buttons to the left of the level axis change
the axis range. The upper two buttons expand and contract the scale
while the lower two buttons shift the scae up and down.

The buttons to the left of the frequency axis on the spectrogram
display change the axis range by incrementing and decrementing the
frequency values at the beginning and end of the axis. The two upper
buttons increment and decrement the end of the axis and the two upper
buttons increment and decrement the beginning of the axis.

The buttons at the bottom right of the time and frequency axes
shift the display left or right. If a duration or frequency range has
been selected then the step size is equal to the selected
duration/frequency range. If spectra are being calculated during
shifting, the step size is divided by the FFT Overlap value. If Play
has just been performed on the selected duration, the selected duration
is played for each shift. Likewise, if Spectrum has been requested, the
spectrum is calculated for each successive position of the selected
duration.

<LEFT MOUSE> **When the input is paused, dragging the left mouse button
across the display selects a range of the input to zoom in to, play, or
compute the spectrum of. The selected area is colored blue and the
selected time/frequency is displayed above.

<MIDDLE MOUSE> **Clicking the middle mouse button within the display
produces a cursor with the time/frequency and level corresponding to
the cursor position displayed above.

<RIGHT MOUSE> **The right mouse button produces a pop-up menu. The
various components of the menu for the different displays are described
below.

************************************************************************

TIME DISPLAY POP-UP MENU

Zoom In         zoom in to selected duration or decrease time axis range by
		a factor of 2.

Zoom Out        undo previous zoom in.

Play		plays selected duration over headphones or speaker.

Spectrum        if input is paused, calculates spectrum of selected
		time using FFT. The size of the FFT depends on the
		selected duration. A four second selection will take
		some time but give frequency resolution down to 0.25
		Hz! The spectrum is displayed in the "spectral display"
		window.

Trigger 	if selected, then the input will keep running until the
		input level exceeds the value on the right of the
		display, after which 3/4 of the display will be filled
		then the input will be paused.

Input Source 	Microphone, Line, or Soundfile. If the latter, then a
		Motif FileSelectionBox is displayed. An input file can
		also be put on the command line, i.e. "cspect
		<filename>".

Input Channel 	Left or Right.

Ordinate Units  Volts: linear amplitude (this probably isn't
		calibrated right - I guessed). If Envelope is selected
		then two lines are displayed joining max and min
		amplitude values. A middle mouse click above 0 V puts
		the cursor on the upper envelope, a middle mouse click
		below 0 V puts the cursor on the lower envelope.
		RMS dB: a running RMS level in dB is displayed.

Sample Rate 	input sample rate.

DC Correction 	Default: uses values defined in main.c to remove DC -
		may need to be modified according to input source etc.
		Auto: removes DC on the fly using IIR filter. May slow
		things up a bit and can filter out very low frequencies.
		Keep: uses last calculated DC correction value.
		Off: no DC correction.

		hint: use Auto to get DC correction then Keep for speed
		and to avoid removing low frequency components.

Display         can have all or any of Time Waveform, Spectrum,
		Spectrogram, or Waterfall.

Save As ASCII   save x,y coordinates of plot to text file (time
		normalised to start at zero). In Envelope mode, max and
		min curves are listed consecutively.

************************************************************************

SPECTRUM DISPLAY POP-UP MENU

Zoom In         zoom in to selected range or decrease frequency axis
		range by a factor of 2.

Zoom Out        undo previous zoom in.	

Average         if selected, perform running spectral average of
		incoming waveform. Stopped by pausing input with the
		<SPACE BAR>.

Excitation      if selected, display cochlear excitation pattern
		(shows vibration of basilar membrane as a function
		of centre frequency).

Pre-emphasis 	6-dB/Octave spectral pre-emphasis.

Ordinate Units  Spectral Envelope or Spectrum Level (= power per Hz).

FFT Size 	number of points in FFT for real-time spectrum.	

FFT Overlap 	FFTs are spaced (FFT Size)/(FFT Overlap) samples apart.

Window Type     windowing performed on input prior to FFT. Can have:
		Rectangular (no windowing), Hamming, Hanning, Bartlett,
		Blackman, or Blackman-Harris.

Display 	same as time display popup.

Save As ASCII   save x,y coordinates of plot to text file.

************************************************************************

SPECTROGRAM DISPLAY POP-UP MENU

Boost 	 	increase intensity.

Unboost 	decrease intensity.

Excitation	same as spectral display popup.

Pre-emphasis 	same as spectral display popup.

Color           nauseating colors. In decreasing intensity - white >
		yellow > red > blue.

Invert Colors	inverted grey scale or even more nauseating colors.

Plot Mode 	Scroll: left to right overwriting previous.
		Roll: right to left moving display. 

FFT Size 	same as spectral display popup.

FFT Overlap 	same as spectral display popup.

Window Type 	same as spectral display popup.

Display 	same as time display popup.

************************************************************************

WATERFALL DISPLAY POP-UPS

Click with the right hand mouse to the left of the display to get the
time display popup, click to the right of the display to get the
spectrum display popup. These control the time and frequency aspects of
the display respectively.

Save As ASCII saves all the data as time,frequency,level.

************************************************************************

Notes:

The spectrogram and waterfall displays work by moving great chunks of
the screen pixel data around. To avoid messy graphic effects they
always try to pop themselves to the top of the window stack when
plotting data. The only way to disable this is to turn the display off
using the Display option in the popup menu.

************************************************************************

ACKNOWLEDGEMENTS

I owe thanks to whoever wrote the fft routine in power.c. 

************************************************************************

Er... that's it. More or less. I've probably forgotten several crucial
features but I'm sure you'll tell me about any omissions. Feel free to
dabble in the source code which is an horrendous mess. My only fee is
to receive any improved versions as a matter of course. If anyone feels
like rewritting the whole thing in tidy C++ they'll have my eternal
gratitude.

There are a few definitions regarding calibration in main.c that you may
want to have a look at.

Comments PLEASE to chrisp@epunix.susx.ac.uk.

Chris Plack

Experimental Psychology
University of Sussex
Brighton
BN1 9QG
UK

Tel: (1273) 678434
 




