file: 00README G. Moody and G. Clifford 30 November 2003 Last revised: 1 December 2007 WFDB_tools quick start This package of software was written by Jonas Carlson, who has contributed it to PhysioNet for free use and redistribution. The WFDB_tools package allows Matlab R13 users to use the WFDB library to read and write digitized signals and annotations such as those available from PhysioNet. Version 0.5.3.1 differs from 0.5.3 only in that a missing 'n' that caused a compilation error in example4.m has been added to that file, and additional instructions have been added to those in step 4b for Linux, MacOS X, and Unix users below; thanks to David Linker for both of these changes. If you have previously installed version 0.5.3 successfully, it is not necessary to update your installation to 0.5.3.1. These notes provide a highly condensed set of instructions for installing WFDB_tools under MS-Windows, Linux, MacOS X, and other versions of Unix. (Installation has been tested under Linux, MacOS X 10.4.10, and MS-Windows XP only.) Please see http://www.physionet.org/physiotools/matlab/wfdb_tools/ for further information about this software. Under MS-Windows: 1. Install the Cygwin software package, following the instructions at http://cygwin.com/ Install Cygwin in a location that does not have any spaces in its pathname. The default and preferred location is c:\cygwin. Do not use locations under "Program Files", "Documents and Settings", or any other directory containing a space in its name. Be sure to select and install the gcc, binutils, make, and perl packages from the Devel category (these are not installed by default in a minimal Cygwin installation). (This procedure has been tested using Cygwin 1.5.5; if you have an older version previously installed, we recommend updating it to 1.5.5 or later.) 2. Install the WFDB software package, version 10.4.1 or later, following the instructions at http://www.physionet.org/physiotools/wfdb-windows-quick-start.shtml If you will be using Matlab R14 or later, install the standard (Cygwin) version first, then install a set of native Windows binaries as described near the end of the Windows quick start guide. 3. Install Matlab R13 or later if you have not already done so. These wrappers will not work with older versions of Matlab. 4. If you have not already done so, download http://www.physionet.org/physiotools/matlab/WFDB_tools.tar.gz In a Cygwin window, navigate to the directory containing WFDB_tools.tar.gz and unpack it by running the command tar xfvz WFDB_tools.tar.gz This command creates a new directory named WFDB_tools-X.Y.Z, where X, Y, and Z depend on the version number of the package you have downloaded. For example, the name is WFDB_tools-0.5.3 for version 0.5.3. Enter this directory by typing cd WFDB_tools-0.5.3 (or whatever version is correct). In the following steps, "this directory" means your local copy of the WFDB_tools-X.Y.Z directory (which is the current directory if you have followed these instructions). You can use the precompiled .dll files provided in the "windows" directory, or you can recompile them from the .c sources provided in the "src" directory. Choose only one of steps 5a and 5b: 5a. [To use the precompiled .dll files] Copy all of the files from the "windows" and "help" directories into this directory. 5b. [To recompile the .dll files from the .c sources] Copy all of the files from the "src" and "help" directories into this directory. Install gnumex following the instructions at http://gnumex.sourceforge.net/ Be sure to start Matlab from within a Cygwin terminal emulator to ensure that the environment variables are set appropriately before running the gnumex configuration script from the Matlab prompt. Accept the defaults offered by gnumex (Cygwin linking, generate mex dll, use C/C++ for compilation, safe compile) to create mexopts.bat. Copy mexopts.bat into the directory containing the WFDB_tools files (where this README is located). Edit the copy of mexopts.bat, changing the line that sets GM_ADD_LIBS (below "Added libraries for linking") so that it reads: set GM_ADD_LIBS=wfdb-10.4.dll At the Matlab prompt, add paths corresponding to cygwin, gnumex and wfdb: addpath C:\cygwin addpath C:\gnumex addpath C:\cygwin\opt\wfdb\bin (substituting the locations where these packages are installed on your system). Finally, ensure that your current directory is the one that contains this README file, and run: make_WFDB_dlls within Matlab to compile the WFDB_tools dlls. 6. To be able to use the WFDB_tools from any directory, add the directory containing the WFDB_tools dlls to your path, by typing at the Matlab prompt: addpath C:\WFDB_tools (substituting the name of the directory containing the .dll files). 7. Test the WFDB_tools by running "example.m" (in the "examples" directory) from the Matlab prompt. Under Linux, MacOS X, or Unix: Unix users, please note: We believe that the following procedure should work for you, but it has been tested only under GNU/Linux and MacOS X. Please let us know if you try it on another platform. We would appreciate success reports as well as problem reports; please be sure to tell us what versions of your OS, the WFDB software package, and the WFDB_tools package you have used. 1. Install the WFDB software package, version 10.4.1 or later, following the instructions at http://www.physionet.org/physiotools/wfdb-linux-quick-start.shtml (look in http://www.physionet.org/physiotools/wfdb.shtml for pointers if your platform is not GNU/Linux). 2. Install Matlab R13 or later if you have not already done so. These wrappers will not work with older versions of Matlab. 3. If you have not already done so, download http://www.physionet.org/physiotools/matlab/WFDB_tools.tar.gz In a terminal window, navigate to the directory containing WFDB_tools.tar.gz and unpack it by running the command tar xfvz WFDB_tools.tar.gz This command creates a new directory named WFDB_tools-X.Y.Z, where X, Y, and Z depend on the version number of the package you have downloaded. For example, the name is WFDB_tools-0.5.3.1 for version 0.5.3.1. Enter this directory by typing cd WFDB_tools-0.5.3.1 (or whatever version is correct). In the following steps, "this directory" means your local copy of the WFDB_tools-X.Y.Z directory (which is the current directory if you have followed these instructions). You may be able to use the precompiled .mexglx files provided in the "linux" directory (compiled under Red Hat Linux 9 for the x86 platform, using gcc version 3.2.2). If you have a different platform, you will need to compile .mexglx files for your platform from the .c sources provided in the "src" directory. Choose only one of steps 3a and 3b: 4a. [To use the precompiled .mexglx files] Copy all of the files from the "linux" and "help" directories into this directory. 4b. [To recompile the .mexglx files from the .c sources] Copy all of the files from the "src" and "help" directories into this directory. Find the location of the "mex" compiler and add it to your PATH; for example, on Mac OS X 10.4.10, the "mex" compiler for Matlab R2007b will probably be in /Applications/MATLAB_R2007b/bin, so (in a terminal window) type PATH=/Applications/MATLAB_R2007b/bin:$PATH The location will vary, depending on your installation, so substitute the actual location of your "mex" in the command above before running it. Then, in the same window, type these commands from within this directory: make clean make 5. To be able to use the WFDB_tools from any directory, add the directory containing the compiled WFDB_tools files to your path, by typing at the Matlab prompt: addpath /home/fred/WFDB_tools (substituting the name of the directory containing the .mexglx files). 6. Test the WFDB_tools by running "example.m" (in the "examples" directory) from the Matlab prompt. If you are successful in compiling and using these wrappers under any platform other than GNU/Linux, Mac OS X, or MS-Windows, please let us know about it!