.TH SHOW 1carl CARL
.SH NAME
show, fshow, yshow \- CRT waveform display hack
.SH SYNOPSIS
.B show 
[ 
.B flags 
] < 
.B floatsams 
> 
.B text mode graph
.SH DESCRIPTION
Input must be a file or pipe.
flags:
.TP
.B -l
set lower bound of display to N (-1)
.TP
.B -u
set upper bound of display to N (+1)
.TP
.B -m
set upper and lower bounds to + and - N ([-1,+1])
.TP
.B -R
show time instead of sample number using sampling rate N
(not available in yshow)
.TP
.B -a
display average of N seconds of samples.
.TP
.B -e
display mean squared energy of N seconds of samples
.TP
.B -s
skip output by N seconds worth of samples of input
.TP
.B -Cc
show sample value as character c ('*')
.TP
.B -Hc
histogram mode using character c ('-')
.TP
.B -S
set window jump size to N (yshow only).
All durations are in seconds.  Use postop 'S' for sample times.
Arguments may be expressions.
.PP
The 
.B show 
program will crudely plot a waveform on a CRT terminal.  If no
range arguments are given, samples are expected to lie in the
signed unit interval, [-1,+1].  The -m flag will set the
lower bound to -(upper bound).
.PP
.B fshow
is exactly like show, but it uses the 
.B curses(3) 
cursor optimization
package to make it fast (it's even fast enough on 300 
baud terminals!).
.B yshow
is also like show, but it scrolls the waveform horizontally instead of
vertically (for those who don't like to lie down on their sides
to view waveforms).  It also uses 
.B curses,
but, since it must do software scrolling it is pretty slow.
.PP
Ordinarily, 
.B show 
displays every sample point given it.  This is tedious
at best for large quantities of input.  You can condense the number of
points to be displayed by several methods.  The -s flag skips over so
many samples of data for each one displayed.  It takes an argument
specifying time in seconds to skip by.  e.g., -s.001 skips by over
millisecond's worth of input points for every output point.  You can
take the average of a window of time with -aN, where again N is time in
seconds.  Lastly, you can take the mean squared of a window size of
time N with the flag -eN.  Averaging is good to compress waveforms of
very long wavelength.  Mean squared is good to view the overall
envelope.  You have to play with the value of N for each situation.
.PP
The number of samples in a window is determined by the sampling rate.
The default rate is DHISR samples/second.  The default window
size is 2.6 milliseconds.  Change the sampling rate with -RN, where N
is the new sampling rate, e.g., -R16K.  Change it first before setting
any other time variables.
.PP
Window size can also be set as samples duration rather than time by the
use of the 'S' postoperator.  e.g., -e32S  tells 
\fBshow\fR to use an
averaging window of 32 samples.  (Without the 'S' postop, it would be
32*DHISR samples in size!)  All arguments may be expressions.  In particular,
operators + - * /, and postoperators S (samples), K (times 1024),
k (times 1000), s (seconds, default) and dB are supported.
.PP
The -bN, -eN and -dN flags specify the time to start displaying, stop
displaying and duration to display, respectively.  N is in seconds, at
the prevailing sampling rate.
.PP
Histogram output can be obtained with -Hc  where the character  c
immediately following the H will be the character used for the bars in
the graph.    If none is specified, it chooses one.
Similarly, you can change the
character that indicates sample values by supplying the one you want
as an argument to -C.
.PP
.B yshow
has an additional flag: -SN, which sets the number of samples
to skip over when scrolling.
.PP
Don't forget to express lower bound as a minus number if that's what
you really intend.
.SH AUTHOR
F. R. Moore (show), 
Gareth Loy (fshow, yshow).
.SH SEE ALSO
cmpsig(1carl)
