                 WAVE: Waveform Analyzer, Viewer, and Editor

	                       George B. Moody
                    Massachusetts Institute of Technology

	WAVE version WAVEVERSION was installed WHEN

-------------------------------------------------------------------------------
WAVE: Waveform analyzer, viewer, and editor
Copyright (C) 2000 George B. Moody

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.

You may contact the author by e-mail (george@mit.edu) or postal mail
(MIT Room E25-505A, Cambridge, MA 02139 USA).  If you are submitting a bug
report, please include your name and address, and the version number and date
shown above.  Thanks!

For updates to this software, please visit PhysioNet
(http://www.physionet.org/).

_______________________________________________________________________________

For a copy of this document, print `HELPDIR/wave/wave.pro' (or click
`Print' at the top of the window if you are viewing this from within WAVE).
For a copy of the on-line help for WAVE, print `HELPDIR/wave/wave.hlp'.

For a copy of the WAVE User's Guide (a tutorial introduction and reference
manual for WAVE), use your web browser to open HELPDIR/html/wug/wug.htm
(or http://www.physionet.org/physiotools/wug/wug.htm), or print
HELPDIR/html/wug/wug.ps on a PostScript printer.

Summary of changes from version 5.0
-----------------------------------
- WAVE User's Guide in hypertext
- Coordination of multiple WAVE processes
- Remote control of and by Netscape
- `Level' window
- Signals may be rearranged in the signal window
- Fine and coarse grid options
- Automatic selection of time scale
- New controls in the `Analyze' window
- New WAVE menu features
- Enhanced log functions
- Enhanced scope functions
- New help topic: frequently asked questions
- New versions of WAVE for 386 Linux and Sparc Solaris 2.x are available
- New command-line options for specifying the first screen to view
- New X11 resources and command-line options for setting display preferences
- New controls in the `View' window (annotation, signal, time display options)
- Keypad annotation editing and display commands
- Multi-edit mode
- Signal selection using the mouse
- Fewer restrictions on WAVE menu files
- Timed autosave
- WFDB environment editing
- Support for remote file access via web (HTTP) and FTP servers
- WAVE sources now available freely under the GPL
- All previously reported bugs fixed

New features
------------
- If you have a web browser such as Netscape, you can read the WAVE User's
  Guide on-line.  WAVE's Help Topics window contains a `User's Guide' button
  that opens the guide using Netscape or the browser of your choice.  (If
  you don't use Netscape, you will need to customize the `url_view' script
  provided with the WAVE distribution.)  Some topics in WAVE's spot help
  have `More' buttons that link in this way to the User's Guide for an
  in-depth discussion.

- You may open two or more records at once if you start WAVE with a command
  such as
	wave -r 100+101+102
  (which opens records 100, 101, and 102 in separate main windows).  Each
  main window is a separate WAVE process, and may be controlled independently
  of the others.  The `master WAVE process', corresponding to the last named
  record, has an extra button (labelled `Sync') in the control panel;  clicking
  on this button causes all of the other windows in the process group to become
  synchronized with the master WAVE process.  It is also possible to open the
  same record in two or more windows, and to select different displays for each
  one, by a command such as
	wave -r 100+100 +0/-display +0/some.other.cpu:0
  (which opens record 100 in a window on `some.other.cpu', and also in a
  master WAVE window on the local display;  for this to be done successfully,
  it is usually necessary to run `xhost' on the remote system to permit the
  WAVE host to open a window on it).  For further details on teleconferencing
  via WAVE, and other applications of this feature, see the WAVE User's Guide.

- A new LINK annotation type (mnemonic `@') has been added to the WFDB library.
  The aux field of a LINK annotation contains a URL and an optional comment.
  WAVE displays the comment, underlined and distinctively colored, in the
  manner of a Web browser;  if you select a LINK annotation, WAVE uses the
  `url_view' script included in the WAVE distribution to cause your web browser
  to open the specified URL.  Going in the opposite direction, the `wavescript'
  application included in the WAVE distribution can be used as a helper by
  a web browser;  `wavescript' starts WAVE if necessary and causes it to
  display a segment of a record as specified by the file named on its command
  line.  It is therefore possible to use a browser such as Netscape to control
  WAVE, and vice versa.  For details, see `WAVE and the Web' in the WAVE User's
  Guide.

- If you have enabled `levels' in the `View' window, WAVE now opens a `Level'
  window if you press a mouse button while the pointer is in the signal window.
  The `Level' window shows the time and amplitudes of the samples at the
  pointer location;  this information is updated continuously whenever a mouse
  button is depressed.  Using the `Show' menu at the top of the `Level' window,
  you may choose to view the time and amplitudes in physical units (seconds,
  mV, etc.) or database units (sample intervals and analog-to-digital converter
  units);  you may also choose to view absolute time and levels, or time
  interval and levels relative to a reference marker.  The reference marker
  (there may be at most one defined in any record) may be inserted, moved, or
  deleted in the same way as any other marker;  its mnemonic is `;'.

- If you choose to draw `listed signals only' using the Draw menu in the `View'
  window, signals shown in the signal window are now arranged as they appear in
  the signal list.

- A new fine grid option (0.04 s x 0.1 mV) has been added to the `Grid' menu
  in the `View' window.  If this option is selected, every fifth grid line is
  emphasized.  At standard display scales (25 mm/s, 10 mm/mV), this option
  specifies a 1 mm grid.  Two more new grid options are for use at condensed
  time scales.  These offer grid lines at 1 minute intervals, with every fifth
  grid line emphasized;  these may be used with 0.5 mV horizontal grid lines,
  or without horizontal grid lines.

- Records sampled at very low frequencies (10 Hz and under) are automatically
  displayed at a condensed time scale, and with a coarse time grid.  You may
  choose any desired time scale and grid mode for such records if the default
  is not satisfactory, and you may change the default by saving the desired
  settings in the `View' window while a low-rate record is open.  Doing so does
  not affect the default time scale or grid mode for high-rate records.

- In the `Analyze' window, the standard controls (i.e., those not defined in
  the menu file) are now all at the top of the window (several appeared at the
  bottom of the window in previous versions), and six new standard controls
  (`<', `>', `From', `To', `Signal list' and `Reload') have been added.  The
  `<' and `>' buttons allow you to shift the analysis interval (the interval
  between the `Start' and `End' markers) in either direction without changing
  the length of the interval.  The `From' and `To' controls show the date and
  time of day corresponding to `Start' and `End', if the header file for the
  record contains a start time and date.  You can adjust the analysis interval
  by changing either `Start' and `End' or `From' and `To', as you wish.
  `Signal list' is a string, initially set to the list of available signal
  numbers in the current record.  The signal list may be edited directly, or
  the current signal may be appended to or deleted from the signal list using
  the mouse (point to the desired signal, press and hold down the <control>
  key, and click the left mouse button to add the signal to the signal list;
  follow the same procedure using the <meta> key instead of the <control> key
  to delete the first occurrence of a specified signal from the signal list).

  If you click on `Reload', WAVE waits until any pending foreground commands
  issued from the Analysis command window are complete, and then WAVE reloads
  the current record.   If a pending command is rewriting the annotations or
  signals being viewed, using this button allows you to view the revised files
  as soon as they are complete.  You can also use this button to load
  `snapshots' of files being written by commands running in the background,
  but do not attempt to edit such `snapshots'.

- Several additional variables can now be used within WAVE menu files to
  control external programs.  If the WAVE menu contains the string `$SIGNALS'
  in a command, the signal list will be inserted at that position in the
  command.  (Note that the meaning of the current $SIGNAL variable is
  unchanged.)  The current display scales used by WAVE are available in the
  WAVE menu as $VSCALE (the amplitude scale, in mm/mV) and $TSCALE (the time
  scale, in mm/sec), and other WAVE display options are available in $DISPMODE.
  See the default WAVE menu file for details on $DISPMODE and for examples of
  all of these variables in use.

- New controls have been added to the log window.  The `Load' button forces
  WAVE to load or reload the current log file;  this feature is useful if
  another process (such as a WAVE analysis menu button) has been used to
  create or modify the current log file.  The `Edit' button now allows you
  to edit a log file using your favorite text editor (set the EDITOR
  environment variable or the Wave.TextEditor resource;  the default is
  the standard Open Windows `textedit' utility).  New buttons labelled `|<'
  and `>|' allow you to jump directly to the first or last entry in the log.
  Finally, the `Delay' slider allows you to change the update frequency
  (from once per second up to once per ten seconds) while using review mode.

- New mouse and keyboard controls have been implemented in the scope window.
  Click left or right within the scope window to single-step the scope display
  backward or forward respectively.  Click the middle mouse button to pause
  the continuous mode display and to recenter the main window on the current
  waveform in the scope window.  Press and hold down the <control> key while
  clicking left or right to resume the continuous mode display.  Press
  <control> while clicking the middle button to adjust the delay time (the
  interval from the left edge of the scope window to the trigger point).  The
  left, up, and right arrow keys emulate the mouse buttons within the scope
  window (but you must click at least once using the mouse to move the keyboard
  focus into the scope window before these keys work).

- Frequently asked questions and answers have been gathered in a new help
  topic.  Select `Frequently asked questions' from the Help window to review
  this topic.  Please submit additional questions, answers, and suggestions
  to the author at the address above.

- At last, there is a version of WAVE that runs on a PC!  WAVE has been ported
  to Linux, a freely available UNIX clone for 386/486/Pentium PCs.  See file
  `LINUX', in the WAVE distribution, for further information.  There is also a
  version of WAVE that has been recompiled for Sparc Solaris 2.x.  The standard
  version for SunOS 4.x will also run in SunOS binary compatibility mode under
  Solaris 2.3 and later versions, but the native version for Solaris is a
  better (i.e., faster and more robust) choice for such environments.

- You can now specify the starting time of the first screen shown by WAVE
  using the `-f' command-line option.  For example,
	wave -r 100 -a atruth -f 25:14
  opens record 100 at 25 minutes and 14 seconds from the beginning of the
  record.  You may also set the initial value of the signal list (see below)
  using the `-s' option.  For example,
	wave -r slp60 -a ecg -s 0 2 3 -f 1:30
  opens record slp60 at 1 minute and 30 seconds from the beginning, and
  initializes the signal list to contain signals 0, 2, and 3.  If the option
  `-VS 1' is also used (see next item), WAVE displays only the signals in the
  signal list.

  Note that the meaning of `-s' has been changed from previous versions, to
  conform with the convention used by many other WFDB applications for
  specifying signal lists.  To force WAVE to use a shared colormap, use the
  new `-S' option.  The new `-O' option forces WAVE to use overlays instead,
  if the display supports them (this is the default behavior unless the
  resource Wave.GraphicsMode has been set to a value other than 0 or 8). 

- WAVE now allows you to specify initial values for the settings controlled
  from the `View' window using either X11 resources or command-line options.
  In addition, you may save the current settings as defaults for the next time
  you run WAVE.  The following command-line options and X11 resources may be
  used to initialize the `View' settings:
       Option   	X11 resource
	-Vs		Wave.View.Subtype
	-Vc		Wave.View.Chan
	-Vn		Wave.View.Num
	-Va		Wave.View.Aux
	-Vm		Wave.View.Markers
	-VN		Wave.View.SignalNames
	-Vb		Wave.View.Baselines
	-Vl		Wave.View.Level

	-Vt CHOICE	Wave.View.TimeScale
	-Vv CHOICE	Wave.View.AmplitudeScale
	-VS CHOICE	Wave.View.SignalMode
	-VA CHOICE	Wave.View.AnnotationMode
	-VT CHOICE	Wave.View.TimeMode
	-VG CHOICE	Wave.View.GridMode

  The options and resources in the first group correspond to the like-named
  `Show:' options at the top of the `View' window.  By default, all of these
  options are off (false);  set any of the X11 resources to `true' to enable
  these options, or use the command-line options to do so.  For example, to
  enable initial display of markers, either use `-Vm' on the command line, or
  `Wave.View.Markers:true' in the X11 resource database (for example, in your
  `.Xdefaults' file).

  The options and resources in the second group correspond to the menu buttons
  that appear in the remainder of the `View' window.  The CHOICE argument, or
  the value of the X11 resource, should match the position of the desired
  menu choice in the corresponding `View' menu, where the top item on the menu
  is in position 0, the one below it is in position 1, etc.  For example, to
  set the initial time scale to 50 mm/sec (the item at position 6 in the `Time
  Scale' menu), add `-Vt 6' to the command line, or `Wave.View.TimeScale:6' to
  the X11 resource database.

  Click left on `Save as new defaults' in the `View' window to retain WAVE's
  current settings as defaults for future WAVE sessions.  In addition to the
  options on the `View' window, this action also records the screen resolution
  (which you may specify on the command line using the `-dpi' option), the
  signal window size (which you may change by dragging the resize handles on
  the signal window), and the graphics mode (which you may specify on the
  command line using the `-g', `-m', `-O', or `-S' options).  Note that WAVE's
  current settings, and those that are saved as defaults, are those reflected
  in the signal window.  If you have modified `View' window options since the
  last time the signal window was redrawn, these modifications have not been
  applied, and are not saved.

- Three controls have been added to the `View' window.  Using the `Draw:' menu
  button, you may instruct WAVE to draw all available signals (the default)
  or those in the signal list (see below) only.  Using the `Show annotations:'
  menu button, you may view annotations centered in the signal window (the
  default), attached to the signal specified by the `chan' field of each
  annotation, or as a signal.  This last option replaces the standard
  annotation display with a signal (drawn in the annotation color, in the
  center of the signal window) derived from the `num' fields of any annotations
  in the window.  Turn off this selection to restore the normal display.
  Finally, the `Time display:' menu button allows you to choose to display and
  enter elapsed times (the default), absolute times (if the header
  file for the record contains the absolute time of the beginning of the
  record), or (elapsed) times in sample intervals.  WAVE shows elapsed times
  in the corners of the signal window in the signal color;  absolute times are
  drawn in the annotation color.

- Whenever the pointer is in the signal window (as indicated by a crosshair
  cursor replacing the normal arrow pointer), the numeric keypad and several of
  the function keys may be used for many annotation editing and display
  operations.  `Num Lock' must be off if you wish to use the keypad for these
  operations.  The keypad commands are:
    <1> (End):		moves the display window to the end of the record
    <2> (down-arrow):   moves the selected annotation down one signal (see
			 next item)
    <3> (PgDn):		moves the display window back half a screenful (or
			 a full screenful if <control> is depressed)
    <4> (left-arrow):	behaves like the left mouse button (*)
    <5>:		behaves like the middle mouse button (*)
    <6> (right-arrow):	behaves like the right mouse button (*)
    <7> (Home):		moves the display window to the beginning of the record
    <8> (up-arrow):	moves the selected annotation up one signal (see next
			 item)
    <9> (PgUp):		moves the display window forward half a screenful (or
			 a full screenful if <control> is depressed)
    <=>:		moves the pointer left (with acceleration while the key
			 is held down)
    <*>:		moves the pointer right (with acceleration while the
			 key is held down)
  Function key commands are:
    <Copy> (or F6):	copies the selected annotation into the template
    <Find> (or F9):	simulates clicking on `Search >' in the main window;
			 if <control> is depressed, simulates `< Search'
  (*) Note that the <control> and <meta> keys may be used in combination with
  the numeric keypad keys <4>, <5>, and <6>, and that these combinations work
  just as when using the mouse buttons.  <Shift> does not work with the numeric
  keypad, however.  See the section on PC keyboard equivalents (below) if you
  are not using a Sun keyboard.

- `Multi-edit mode' is enabled when you open a record with two or more signals,
  enable annotation editing, and show annotations attached to signals (see the
  previous item).  In multi-edit mode, annotation editing operations are
  slightly different from the usual ones.  The most important difference is
  that you must always point to the desired signal when inserting or moving
  annotations.  In this mode, the `chan' field in the Annotation Template
  window does not determine the `chan' field of an inserted annotation; rather,
  the signal to which you point determines the `chan' field, and the `chan'
  field in the Annotation Template window is updated accordingly after each
  insertion.  To move an annotation to a different signal, simply select it
  and drag the pointer to the desired time and signal.  If you wish to change
  the `chan' field of an annotation without changing its time, select the
  annotation and use the up-arrow and down-arrow keys (keys <2> and <8> on the
  numeric keypad; `Num Lock' must be off) to move it to the desired signal.
  Hold down the <control> key during these operations to copy the annotation,
  rather than to move it (simultaneous annotations are permitted if their
  `chan' fields differ).

- Signals may be selected using the mouse.  Point to the desired signal, press
  and hold down the <shift> key, and click the left mouse button.  The selected
  signal remains highlighted until the signal window is redrawn.  The value
  in the `Signal' field of the `Analyze' window changes to match the selection.

- Command strings in the WAVE menu can now be much longer (up to 1024
  characters each, including the button label).  There is no longer any limit
  (other than those imposed by the X server and by total available memory) on
  the number of menu entries (buttons) in the `Analyze' window.  If the
  environment variable WAVEMENU is not set, but a file named `wavemenu' exists
  in the current directory, WAVE uses that file as its menu file;  otherwise,
  WAVE uses the system default menu file.  As always, WAVE offers to create
  `wavemenu' if you attempt to edit the system default menu file.

- WAVE now saves your edits at one-minute intervals.  Note that this operation
  is postponed until you perform an edit.

- The `Load' window now allows you to change the WFDB environment (WFDB path
  and WFDB calibration file) without exiting from WAVE as was necessary
  previously.  Note that any changes you make are local to the current WAVE
  process, although you can export these values to processes running in the
  Analyze window using the symbols $WFDB and $WFDBCAL in the WAVE menu file.

- WAVE (and all other applications based on the WFDB library) can now read
  input files from web sites and FTP servers, provided that the WFDB library
  has been compiled together with libwww (see http://www.w3.org/Library/).  To
  do so, simply add the appropriate http:// or ftp:// base URL to the WFDB
  path, and use WAVE in the usual way.

- Sources for WAVE are now available on the web at http://www.physionet.org/.
  WAVE has been released under the GNU Public License (GPL), which permits
  it to be copied and redistributed without cost.

Bug fixes
---------

- Several bugs that caused WAVE to crash or behave oddly when searching beyond
  the end or before the beginning of an annotation file have been fixed.

- WAVE now contains a work-around for an X server-related problem that
  sometimes caused annotations to be moved inappropriately when clicking the
  left or right mouse button rapidly.

- In previous versions of WAVE, if the record name was changed while there are
  unsaved edits, an inappropriate error message appeared (asserting that
  write permission must be obtained in the current directory before continuing)
  and it was then impossible to save the edits or to continue.  (There may have
  been other ways of triggering the same bug.)  This bug has been fixed.

- WAVE now contains a work-around for an XView library bug that occasionally
  caused earlier versions to dump core after the WAVE menu file was reread.
  This problem occurred if menu items were added more than once in a single
  session;  there may have been other ways of triggering the same bug.  A side
  effect of the work-around is that the `Analyze' window may reappear in a
  different location after the menu file has been reread (this depends on
  the window manager).  There is no way to keep the window position fixed and
  avoid crashes at the same time, short of fixing the bug in the XView library.

- WAVE (and other WFDB applications) crashed in some cases after closing a
  record and reopening it or another record;  the cause of this problem was
  a WFDB library bug, which was fixed in WFDB library version 9.7.

- WAVE version 6.0 contained a bug that caused crashes when attempting to
  change all annotations within a specified range;  this has been fixed.

PC keyboard equivalents for Sun function and numeric keypad keys
----------------------------------------------------------------

WAVE can be controlled using the mouse and the normal alphanumeric keys only,
but there are a few alternate controls that use function keys and the numeric
keypad.  The on-line help for WAVE generally describes how to use these
functions on a Sun keyboard.  On a PC keyboard, some substitutions must be
made:

 Action					PC key			Sun key

 Open spot help				<F1>			<Help>
 Simulate middle mouse button click	<F2>			keypad <5>
 Move editing cursor left		<F3>			keypad <=>
 Move editing cursor right		<F4>			keypad <*>
 Copy selected annotation to template	<F6>			<Copy>
 Search forward				<F9>			<Find>
 Advance to the end of the record	<shift><F9>		<End>
 Search backward			<ctrl><F9>		<ctrl><Find>
 Move to the beginning of the record	<ctrl><shift><F9>	<Home>
 Advance half a screen			<F10>			<PgDn>
 Advance a full screen			<ctrl><F10>		<ctrl><PgDn>
 Move back half a screen		<shift><F10>		<PgUp>
 Move back a full screen		<ctrl><shift><F10>	<ctrl><PgUp>

These PC equivalents are also usable on Sun keyboards.  In addition, all of the
actions that can be performed using the Sun arrow keys can also be performed
using the PC arrow keys.

Cautions
--------

Whenever the annotator name appears within parentheses in WAVE's title bar,
there are unsaved edits.  Unsaved edits may be saved by selecting `Save' from
WAVE's `File' menu, by changing to another record or existing annotation file,
or by exiting from WAVE via the `Quit' button (but not via `Quit' from the
system menu, see below).  There are still three known ways to lose your edits
in WAVE:

- If you are running WAVE in the foreground under SunOS, and you have opened
  the `Analyze' window or have selected `Print' from the `File' menu, do not
  attempt to suspend WAVE (for example, by typing control-Z in the terminal
  window from which WAVE was started).  Under these circumstances, WAVE may be
  killed immediately (without quit confirmation) and any unsaved edits are
  lost.  To avoid this problem, always run WAVE in the background (use `&' at
  the end of the WAVE command line).

  Note that it doesn't matter if the `Analysis commands' window is open, only
  that it has been opened at some time in the current WAVE session.  Using the
  `Print' command invisibly opens the `Analysis commands' window, and thus has
  the same effect.

  This problem is the result of a bug in the XView `termsw' package used
  for the `Analysis commands' window.  The Solaris 2.x and Linux versions of
  the XView library do not have this bug, and this problem does not occur
  except when running WAVE under SunOS 4.x.

- If another process sends any of several termination signals to WAVE, WAVE
  is killed immediately (without exit confirmation).  This may be regarded
  as a feature rather than as a bug.  A system crash has the same effect.

- If you select `Quit' from the system menu, WAVE pops up a quit confirmation
  notice box;  if you confirm that you wish to quit, WAVE quits immediately,
  and any unsaved edits are lost.  To avoid this, always use WAVE's `Quit'
  button on the main control window;  when you select it, WAVE pops up a
  quit confirmation notice box, but saves edits first if you confirm that you
  wish to quit.

To limit the amount of damage resulting from loss of unsaved edits, WAVE
autosaves your edits frequently (at one-minute intervals, or after every 20
edits).

On some 24-bit displays, an X server bug causes WAVE to start with an empty
signal window.  Using any of the navigation controls, or resizing the window,
should make the signals visible.  On some of these displays, text in the
signal window may be invisible using overlay graphics mode; if this happens,
use the `-S' option.

A bug in network file handling can sometimes interfere with correct display
of waveforms in the scope window when reading records via HTTP.  For now,
the only workarounds are to restart WAVE, or to copy the record to local
disk files (this can be done easily using `xform', `snip', or a web browser).
Check http://www.physionet.org/ for updates to WAVE or to the WFDB library
that may correct this bug.
