BRAT - Basic Radar Altimetry Toolbox ------------------------------------ Contents ======== 1- Overview 2- Change Log 3- BRAT Graphical User Interface (GUI) 3.1- Overview 3.2- Visualisation interface 4- Using BRAT as commands 5- BRAT Application Programming Interfaces (APIs) 6- How to install BRAT 6.1- Windows binaries 6.2- Linux binaries 6.3- From source 7- How to uninstall BRAT 7.1- When installed from Windows binaries 7.2- When installed from Linux binaries 7.3- When installed from source 8- Description of some files 8.1- Executable files (commands) 8.2- Libraries 9- Linking with and using the Application Programming Interface (API) 9.1- Linux 9.2- Windows 10- Further information ================================================================================ 1- Overview =========== The Basic Radar Altimetry Toolbox is made of several parts: - a data dictionary, - several Applications Programming Interfaces, with data reading, date and cycle/pass conversion functions - executable files - a Graphical User Interface (GUI), which calls the executable files. For a beginner, we recommend using the GUI. 2- Change Log ============= 1.1.1 - June 2008 ---------------------- - Bug fixed : In Brat Gui, Loess filter is never applied. Bug appears in version 1.1.0. 1.1.0 - December 2007 ---------------------- - Bug fixed : sometimes the toolbox (GUI) crashes when you delete an operation. - Add Jason-2 data processing. - Add 'General' NetCdf data processing. - Built under linux with GCC 4.2.2 (new warnings) 1.0.2 - March 2007 ------------------ - Bug fixed : In X/Y plot display, sometimes the toolbox crashes when moving the graph after having modified the font size. - Disable 'barn' unit. 1.0.1 - December 2006 --------------------- - Add high-resolution fields processing. - Installation process and package creation enhanced 1.0.0 ----- - First released version 3- BRAT Graphical User Interface (GUI) ====================================== 3.1- Overview ------------- BRAT Graphical User Interface (GUI) is a windowed interface to the BRAT Tools. Note that everything possible with the tools is not included in the GUI (some options are only available using directly the command files) The GUI manipulates objects called 'workspaces'. A workspace contains · Datasets, collection of files of the same kind, · Operations, to read and/or compute, and/or select data within a dataset. An operation produces an intermediate file (NetCDF), and a command file · Formulas, that enables to use pre-defined combinations of data fields, or to define them yourself, and re-used them afterwards. · Views, that use results of one or more operations and plot them. A "view" produces a command file, and open the visualisation tool (see chapter 6) It can be saved and recalled. Some or all elements of a workspace can be imported into another workspace. The "Logs" tab displays the state of the programmes being run. Code 0 at the end of the execution of a command means the output is OK. When launched, the GUI recalls the last used Workspace, or asks for a new one if none exists or is valid. There is no specific tab for the Workspace, only the leftmost menu. 3.2- Visualisation interface ---------------------------- The visualisation interface is called by executing a command file from the "views" tab of the GUI. It can also be used with a command file. The visualisation options are quite different for an "Y=f(X)" (curve) than for a "Z=F(lon,lat)" 4- Using BRAT as commands ========================= The GUI is there to ease the use of BRAT. However, everything made with the GUI can be made directly by writing command files and execute them and more than what can be done with the GUI is possible with command files. 5- BRAT Application Programming Interfaces (APIs) ================================================= Some functions of BRAT are not available through the GUI, but through C++, C, Fortran, IDL, Matlab APIs : - Data reading function - Cycle/date conversion functions - Date conversion/computation functions Commands introduced above are some kind of example of how to use the C++ API. ---------------------------------------------- ----- For more details on using BRAT, ----- ----- please refer to the user's manual. ----- ---------------------------------------------- 6- How to install BRAT ====================== BRAT binaries are available for Windows 2000/XP and Linux (Redhat EL 4). The software is delivered two way: a single binary installation package file (for windows or for linux), and a source package. The names of the installation packages have the format: brat-VERSION-PLATFORM-installer.extension, where VERSION is the version of brat, PLATFORM is the destination platform (windows or linux) and extension is a more or less platform specific extension (exe for windows, bin for linux). The name of the source package has the format: brat-VERSION.tar.gz, with the same convention as above. 6.1- Windows binaries --------------------- Double-click on the installation package or installation program and follow the installer instructions. By default, the software will be put in C:\Program Files\brat-VERSION\ if you have write access to this directory or in your user profile (normally C:\Documents and settings\ACCOUNT\brat-VERSION). You can choose another directory, if you wish to. 6.2- Linux binaries ------------------- Execute the installation package or installation program from your file navigator or a console window and follow the installer instructions. If you have got the installation package by a network it may not be set as executable so you can issue the command "chmod +x brat-VERSION-linux-installer.bin" in order to make it runable. By default, the software will be put in /usr/local if you have root permissions or in $HOME/brat-VERSION. You can choose another directory, if you wish to. 6.3- From source ---------------- If you want or need to rebuild BRAT, you may install only the source files. Get the source package and expand it where you prefer. - Windows: use winzip/winrar or a similar tool able to expand gzipped tar file. - Unices: gunzip -c brat-VERSION.tar.gz | tar xvf - It will expand in a directory named brat-VERSION Then have a look at this directory and read the files README (this file) and INSTALL. The last one gives you information about the dependencies (what must be installed before) and the specific options which may be used. If you have got the package from a delivered DVD, you may find more informations in the README.txt file of the 'source' directory (which is the INSTALL file in the top directory of the source installation package). NOTE: All README.txt files in the DVD have DOS/Windows convention for end of lines ( followed by character) while all text files in the expanded source tree have unix convention ( character). 7- How to uninstall BRAT ======================== While BRAT is installed the whole installation process is registered and everything created can be removed (not what may be created after that). 7.1- When installed from Windows binaries ----------------------------------------- Like any other windows program, go to the control panel the click on "Add/Remove programs" and select the Brat entry. Everything created during installation will be removed. Note that a shortcut is also in the installation directory which you can click to do the same thing. 7.2- When installed from Linux binaries --------------------------------------- In the installation directory (the default one or the one chosen), there is a script called uninstall-brat-VERSION-linux which can be executed to remove everything created during installation. There is also a shortcut, called "Uninstall Basic Radar Altimetry Toolbox.desktop", which can be used from within your desktop manager (KDE, GNOME) and do the same thing. 7.3- When installed from source ------------------------------- If you have built BRAT from source, you may have to remove everything by hand. The directory containing the source files may be removed entirely 8- Description of some files ============================ 8.1- Executable files (commands) -------------------------------- Windows: BratGui.exe Linux: BratGui ==> BRAT Graphical User Interface (GUI) Windows: BratDisplay.exe Linux: BratDisplay ==> BRAT Visualisation Interface (GUI) Windows: BratCreateYFX.exe Linux: BratCreateYFX ==> BRAT Data Export to NetCDF Tools for an 'Y=f(X)' (curve) Windows: BratCreateZFXY.exe Linux: BratCreateZFXY ==> BRAT Data Export to NetCDF Tools for a 'Z=f(X,Y)' Windows: BratExportAscii.exe Linux: BratExportAscii==> BRAT Data Export to Ascii Tools (Dump Tools) For a quick help about how use these files in command line, type 'executable_name' --help. You can also refer to the BRAT user's manual. 8.2- Libraries -------------- When you have chosen the "Development files" option (unchecked by default), 2 more directories are installed: 'include' and 'lib'. They give the necessary files to use the C/C++ API. The 'lib' directory also contains (.a files are for linux, .lib for windows): libbrathl.a brathl.lib: library which contains all routines made available by .h files. libbrat.a brat.lib: low level file access library used by brathl. libnetcdf.a netcdf.lib: library used by brathl to access netcdf files. libudunits.a udunits.lib: used by brathl to handle formal units (as text strings) and compute conversions. IMPORTANT: These are libraries provided by BRAT but there might be some missing ones, like HDF4, for example. See the prerequisites of the source distribution for more details. NOTE: For MS-Windows, there is a subdirectory 'release' under the 'lib' directory. This is used to indicate that these libraries have been compiled in 'release mode' and not in 'debug mode': compilers and windows don't allow mixing objects compiled both modes. If you want the debug mode libraries install brat from source. For others systems (like Linux) this does not matter. 9- Linking with and using the Application Programming Interface (API) ===================================================================== 9.1- Linux ---------- Compile your source files with the "-Iinstalldir/include" option where 'installdir' is the base directory where you installed BRAT. If you did install BRAT with root privileges this option can normally be avoided since the compiler already knows it have to check this directory. Link your programs with the option "-Linstalldir/lib" option where 'installdir' is the base directory where you installed BRAT. If you did install BRAT with root privileges this option can normally be avoided since the compiler already knows it have to check this directory. Then add a "-llibrary" for each needed library where 'library' is the name of the library file without 'lib' and '-a'. So, normally, compiling and linking a new program written as a single source file can look like with gcc (command lines are cut for readability but it must reside on the same line): Compiling the source file: c++ -O3 -DNDEBUG -I/installation/directory/include -DSTL_USING_ALL -Wall -Werror -Werror -o BratCreateYFX.o -c BratCreateYFX.cpp Linking the program: c++ -O3 -DNDEBUG -fPIC BratCreateYXF.o -o BratCreateYFX -L/installation/directory/lib -lbrathlProcessUtilities -lbrathl -lbrat -ldf -lmfhdf -lz -ljpeg -lnetcdf -ludunits -lm 9.2- Windows ------------ Compiling and linking under windows is a bit more complicated because compilers and windows don't allow mixing objects and libraries built different way (see note above). At the date of June 2007 (it may change), the delivered libraries have been build with Visual C++ 6.0 (for C and C++) and Compaq Visual Fortran 6.1 (for fortran) with multithreaded mode. Here are the options used when compiling a program (BratCreateYFX, for example) with nmake makefiles generated with cmake (command lines are cut for readability but it must reside on the same line). If you want to compile within the Visual Studio IDE you have to set the appropriate options (look at VS user manual). If you compile with something else (like mingw) you have to use the equivalent options (or recompile all from source since we do not garantee it works with other compilers). Compiling the source file: CL.exe /nologo /DWIN32 /D_WINDOWS /W3 /Zm1000 /GX /GR /MD /O2 /Ob2 /D NDEBUG -IC:\installation\directory\include -DSTL_USING_ALL /TP /FoBratCreateYFX.obj /FdBratCreateYFX.pdb -c BratCreateYFX.cpp Linking the program: CL.exe /nologo /DWIN32 /D_WINDOWS /W3 /Zm1000 /GX /GR /MD /O2 /Ob2 /D NDEBUG BratCreateYFX.obj /FeBratCreateYFX.exe /FdBratCreateYFX.pdb -link /version:0.0 /STACK:10000000 /machine:I386 /INCREMENTAL:NO /subsystem:console -LIBPATH:c:\installation\directory\lib\Release -LIBPATH:C:\HDF42r1\release\lib -LIBPATH:C:\zlib123\release\lib -LIBPATH:C:\jpeg-6b\Release\lib brathlProcessUtilities.lib brathl.lib brat.lib ws2_32.lib hd421m.lib hm421m.lib zlib.lib libjpeg.lib netcdf.lib udunits.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib 10- Further information ======================= For software updgrades, documentation updates and the on line tutorial, including use cases go to http://earth.esa.int/brat or http://www.altimetry.info BRAT has been developed under contract with ESA and CNES.