Thank you for installing the GTKWave Beta Release for MS-Windows. ** PLEASE READ THIS FILE CAREFULLY ** ** GTKWave IS BETA SOFTWARE ** This release is intended for users familiar with both Wave for Unix and MS-Windows. Most functions of Wave for Unix are available, but some functions may not work on some versions of Windows. It is strongly recommended that you install the free Cygwin "Unix-like" environment from www.cygwin.com (see section 2.2 below). GTKWave is designed for 32-bit MS-Windows operating systems (e.g. Windows 9x/ME/NT4/2000). GTKWave will not work with Windows 3.x or Windows NT3. GTKWave should work with the upcoming Windows XP, but has not been tested. GTKWave also works under Linux and is readily portable to other versions of Unix. See README-UNIX.TXT if you wish to use GTKWave under any version of Linux or Unix. Please write to Isaac Henry (ihenry@physionet.org) for further information or to report bugs. 1. Important Information for Users 1.1 Running GTKWave GTKWave can be started from the Start menu, Programs>Wave>Wave, or from the MS-DOS prompt (by typing 'gtkwave'). If started from the command line, GTKWave will accept the switches (command-line arguments) outlined in the Wave User's Guide (see section 1.6). If run with no switches, GTKWave will start with no record loaded, which is the default behavior if started from the start menu. If you start GTKWave from the MS-DOS prompt, GTKWave's current directory is the same as MS-DOS's current directory (normally shown in the MS-DOS prompt). If you start GTKWave from the Start menu or by clicking on its icon, its current directory is the directory specified by its 'Start in' property (right-click on the icon to view the property list). The current directory is significant since any files created by GTKWave (edited annotations, results of analyses) will generally be written there. 1.2 Viewing Records Please remember that record names are NOT file names! (See http://www.physionet.org/faq.shtml#record-names if the difference is not clear to you.) To view a record, the WFDB path must include the location(s) of the files belonging to the record. By default, the WFDB path includes the current directory (see section 1.1), then WAVEROOT (see section 2.1), and finally PhysioBank (http://www.physionet.org/physiobank/database). If you wish to use GTKWave to read local files, either put them into one of these directories, or add the names of the directories where they are located to the WFDB path. If you wish to read records directly from PhysioBank, simply prefix the database directory name, followed by a forward slash (/), to the record name (e.g., 'mitdb/100'). If you need to change the WFDB path, see section 2.1. ** IMPORTANT ** Even though Windows ignores character case in local file and directory names, you must be careful to use the proper case (usually lower case) in all record and annotator names and in remote directory names (those beginning with http: or ftp:). 1.3 Editing Annotations Editing annotations should be possible on most systems. A three button trackball or mouse is strongly recommended; if you are using special mouse software (like Logitech MouseWare(tm)) you must disable special functions on the middle button. If you have a two button mouse, the action of the middle button can be achieved by pressing . Note, however, that does not work on some Windows 2000 systems, and in such cases you must use a three button trackball or mouse. Many users who use Wave heavily for annotation editing prefer trackballs, since the act of clicking the button (used to insert or move an annotation) is less likely to disturb the position of the cursor when using a trackball than when using a mouse. Your edits are written to a copy of the annotation file that you opened; they do not replace those annotations. Your edits are normally written to the current directory (see section 1.1); if the original annotation file was also read from that directory, a tilde (~) is appended to its name. If a file with that name already exists, it will be overwritten. If you want to keep more than one level of backup, you must do so manually. An important exception to the rule that annotations are written to the current directory occurs if you have used a directory name as part of the record name, as suggested in the previous section. In this case, be sure that the current directory contains a subdirectory with the same name before beginning; your edits will then be written into this subdirectory. For example, if you wish to edit the 'st' annotations for record 'slpdb/slp60', create a directory 'slpdb' in the current directory before starting. Your edits will then be written to 'slp60.st' in the 'slpdb' directory you have created. (In the next release of the WFDB library, if the subdirectory doesn't exist, the library will try to create it, so that you won't have to do this manually.) 1.4 Analysis Menu Analysis functions are possible on most systems, but there is no native (Windows-like) interface to these functions at this point, and most of them will not work within an MS-DOS shell. In order to use the existing analysis menu (defined in wavemenu.def and taken directly from the original Wave for Unix), install Cygwin (see section 2.2), to get the proper environment for the scripts to run. You may also write your own analysis menu using MS batch commands. The analysis scripts are based on command-line tools from PhysioToolkit. A set of PhysioToolkit binaries is provided with GTKWave. If you already have PhysioToolkit binaries installed elsewhere, you may remove the duplicates from the Wave directory, but be sure to set your PATH accordingly. External graphing functions (such as heart rate plots) are currently dependent on plot2d, a shell script (batch file) provided with GTKWave that invokes gnuplot, which is available for Windows but not included in the GTKWave package (get it from http://www.gnuplot.org/). gnuplot has not been tested for use with GTKWave. If you would like to set up gnuplot, please contact Isaac Henry (ihenry@physionet.org), for more information. Alternatively, plot2d can be replaced by plt, which is available from http://www.physionet.org/physiotools/plt/. If you would like to set up plt for use with GTKWave, please contact George Moody (george@mit.edu). Under Windows 9x/ME, GTKWave uses the Win95Cmd.exe program as a shell. This program is necessary because Windows 9x does not come with a "real" shell. If you wish to use the analysis functions, however, you should install Cygwin (see section 2.2), and use Cygwin's bash shell (bash.exe) rather than Win95Cmd.exe. 1.5 Printing At this time printing is not supported. Future versions of GTKWave will support the creation of PostScript files and PostScript printing. 1.6 The Wave User's Guide GTKWave is based on George Moody's original Wave, for Unix systems. You can find George's manual, the Wave User's Guide, at http://www.physionet.org/physiotools/wug/wug.htm (where you can read it online or download a ready-to-print PostScript version). In most cases, the manual applies to GTKWave, although the illustrations show the original Unix version. If you find a difference between GTKWave and what is described in the Wave User's Guide (other than a cosmetic difference in the user interface elements), please check in the GTKWave Beta Notes (http://www.physionet.org/physiotools/beta/gtkwave/notes.shtml) to see if this difference has already been reported. If not, please send George a note (george@mit.edu), citing the page number in the printed Wave User's Guide, or the exact URL in the online version. Indicate what is different in GTKWave, and which version of Windows you are using. 2. Notes 2.1 Environment Variables To use GTKWave as intended, these environment variables must be set appropriately: WAVEROOT the name of the directory that contains GTKWave's initialization files WFDB A list of locations where GTKWave's input files are kept WFDBCAL The name of GTKWave's calibration file These variables are set to reasonable defaults during installation. Usually, the value of WAVEROOT will be the name of the directory in which GTKWave itself is installed, by default 'C:\Progra~1\Wave'. GTKWave searches the list of locations specified by the value of WFDB (the "database path") in order when you ask it to open a new record or annotation file. The first component of the path should usually be '.' (i.e., the current directory); since output files (such as edited annotation files) are normally written to the current directory, it is necessary to include '.' explicitly if GTKWave is to be able to find and read these files subsequently. Usually, WAVEROOT should be the second component of WFDB, so that the calibration file (see below) can be located when needed. Other components can include the names of local directories (these should usually include drive specifiers, as in 'c:/data/ecg') as well as directories on remote web or FTP servers (such as 'http://www.physionet.org/physiobank/database'). Use forward slashes (/) rather than backslashes (\) within WFDB, as within record names. The value of WFDB is simply the list of locations, separated by semicolons or spaces; for this reason, components of WFDB may not include embedded semicolons or spaces (e.g., use 'C:/Progra~1/Wave' rather than 'C:\Program Files\Wave'). GTKWave uses the calibration file named by WFDBCAL to determine the relative display scales for signals of different types. By default, WFDBCAL specifies a standard calibration file, named 'wfdbcal', which is installed in WAVEROOT when you install GTKWave. The values of WFDB and WFDBCAL can be set temporarily within GTKWave from the File:Load dialog; be sure to hit the Enter key after you finish (this is behavior inherited from Wave for Unix, and will be fixed in the next release). Changes made in this way are not saved between sessions. Setting environment variables in Windows: Note: In Windows 9x long file names should be shortened in variables. For example, "C:\Program Files\Wave" becomes "C:\Progra~1\Wave" (use the first six letters of the directory or file name and append "~1"). In WinNT/2000, long file names are OK, but embedded spaces cannot be used within WFDBCAL or within components of WFDB, as noted above. Please also heed the warning about character case in section 1.2 above. The following examples assume that you have allowed the installer to use the default GTKWave directory, "C:\Program Files\Wave". ** Windows NT ** Under NT, environment variables are set in "system properties". Login as Administrator (or as a user with administrator privileges), right click on "My Computer", select "Properties" and go to the "Environment" tab. Look for PATH in the list of "System variables", append ";C:\Program Files\Wave" to the end, and "set" the variable. To add WAVEROOT, WFDB, and WFDBCAL, select any variable from the "System variables" list, rename the variable to WAVEROOT (or WFDB, etc.), edit the value, and "set" (the variable you had originally selected will be unchanged). ** Windows 2000 ** As under NT, environment variables are set in "system properties". Login as Administrator (or as a user with administrator privileges), right click on "My Computer", select "Properties", go to the "Advanced" tab, and click on "Environment Variables...". Look for PATH in the list of "system variables", append ";C:\Program Files\Wave" to the end, and "set" the variable. To add WAVEROOT, WFDB, and WFDBCAL, use the "New..." button under "System variables" to create settings for WAVEROOT, etc. ** Windows ME ** From the Start menu, select "Run", enter "msconfig", and click "OK". Environment variables are set under the "Environment" tab. Long filenames seem to be OK, but use short filenames to be safe. ** Win95/98 (but not Win ME) ** Under Win95/98, environment variables are set in C:\autoexec.bat. For example, you might add these lines to your autoexec.bat: SET WAVEROOT=C:\PROGRA~1\WAVE SET WFDB=;C:/PROGRA~1/WAVE;http://www.physionet.org/physiobank/database SET WFDBCAL=wfdbcal (These values are the defaults, so you don't actually need to put these lines in your autoexec.bat unless you wish to use different values.) 2.2 Cygwin Cygwin is the popular Unix-like environment for Windows. GTKWave does not require Cygwin for basic functions (like signal viewing or annotation editing), but some more advanced analysis features must use Cygwin tools. Cygwin is free and available at www.cygwin.com. If you wish to use Cygwin with GTKWave, you must edit the "Defaults" file in your Wave installation directory (normally C:\Program Files\Wave). Open Defaults with Windows Notepad, and add the following line: Shell: C:\Cygwin\bin\bash.exe (where "C:\Cygwin" is the location of the Cygwin root directory). Wave should now use bash as your shell. Be sure to add the Wave directory to your PATH. 3. Technical Information 3.1 MS-Windows versions tested with GTKWave: Windows 3.x - Will not work (GTKWave is 32-bit) Windows 95 - OK Windows 95 OSR2 - OK Windows 98 - OK Windows 98se - Untested, should work Windows ME - OK Windows NT 3 - Will not work (it may be possible to port) Windows NT 4 - OK (Recommended platform) Windows 2000 - OK (some issues, see section 1.3) Windows XP - Untested, may work If you run GTKWave on Windows 98se or XP, please report your findings to Isaac Henry (ihenry@physionet.org) 3.2 Development Environment GTKWave is being developed with the GNU tool chain available in the current Cygwin installation. Specifically, mingw gcc is being used to produce binaries that are not dependent on the Cygwin runtime; this is due to requirements of the current GTK+. The goal is to integrate the build tools for Unix and Windows, but for now GTKWave for Windows uses a custom Makefile. If you are interested in building GTKWave yourself, please contact Isaac Henry (ihenry@physionet.org) for more instructions. 3.2 GTK+ Wave was originally developed using the XView toolkit for Unix systems running X. GTKWave is a port of Wave to the GTK+ toolkit (www.gtk.org), which is the base toolkit of the Gnome desktop system for Unix. GTK+ has been ported to Windows, and it appears that the next major release of GTK+ will have official Windows support. Using GTK+ for the user interface components allows us to compile GTKWave for MS-Windows or for Linux or Unix from a single set of sources. The current Windows version is based on the unofficial GTK+ port, however, and may contain significant bugs and other problems. It is expected that GTKWave for Windows performance and stability will improve as GTK+ matures. 3.3 Libwww Most PhysioToolkit applications, including GTKWave, use libwww (www.w3c.org) to access remote network records. GTKWave for Windows comes with a custom build of libwww which is compatible with mingw gcc and GTK+, and therefore can access remote records. --- Isaac C. Henry ihenry@physionet.org George B. Moody george@mit.edu 20 July 2001