SURF Application Programming Interface (SURF API) ------------------------------------------------- Program Version: 3.1.5 Document Version: 1.1 1. GENERAL ---------------------------------------- SURF ("Sensor-Unabhaengiges Rohdaten-Format") is a widely used ATLAS format for exchange of hydroacoustic data. The SURF format contains data of one specific hydroacoustic sensor accompanied by assigned data of all other sensors that are relevant for hydrographic data processing. SURF is used as a transfer format from the ATLAS HYDROMAP ONLINE to hydrographic data processing systems like the ATLAS HYDROMAP OFFLINE. SURF data are generated by the ATLAS HYDROMAP ONLINE or by the SURF API using the system independent LAN transfer format XDR. The SURF format supports parallel data access (for fast memory access) and serial data transfer. SURF data are transfered via LAN or data exchange media to data processing tools or user-dependent application programs for interpretation and transformation into other data output formats. The SURF format is the same for all sensors of the same sounder type (multibeam echosounder or singlebeam echosounder). SURF includes sensor data information of relevant sensors like position sensors, gyros and motion sensors. The sensor data information is assigned to the hydroacoustic data of the sounding sensor. The sensor data information is interpolated for each sounding according to time (for transmit time and receive time of the acoustic pulse). The SURF format contains other data necessary for data processing as well (e.g. water sound velocity profiles, tide measurements). Data which are valid for a number of soundings are stored only once. SURF data are accessible from external side via the SURF API leading to the following customer benefit: Changes in the SURF format do not require changes in customer application software; they only require the inclusion of an updated version of the SURF API. The SURF API is a function library written in ANSI C. The provided SURF API source code is compatible with Unix and Windows platforms and was tested on HP-UX, Sun-OS, Dec-Unix, Sgi-Irix, Linux, Windows 9x, Windows NT and Windows 2000. Over the years, the SURF Format has been extended twice: - The original SURF format was SURF 1. - The extension to the SURF 2 format includes backscatter information. - The extension to the SURF 3 format includes TPE information. ( TPE = Total Propagated Error ) The current SURF API is able to read all types of SURF files (SURF 1, SURF 2 and SURF 3) and writes SURF 3 files. 2. SURF - FORMAT Details ------------------------ Sounding depend data sets ------------------------- Sounding accompanying data sets are stored in different tables and referenced by time or index: - Angle data sets ( SurfDataInfo ,SurfMultiBeamAngleTable ) - Transducer parameter ( SurfDataInfo ,SurfTransducerParameterTable ) - Sound velocity profiles ( SurfDataInfo , SurfCProfileTable ) - Manual and cyclic events ( SurfDataInfo , SurfEvents ) The indices for the transducer, sound velocity and angle tables are located in the area "SurfDataInfo, SdaInfo, SurfSoundingData". There are additional elements for each sounding: - the motion values and heading at transmission time - the mean sound velocity and the velocity at the transducer face - the tide value - the time and way relative to the profil start Depth and offset calculation ---------------------------- The echosounder provides roll and sound velocity at the transducer face corrected traveltimes for each beam. ( traveltimes from ATLAS HYDROSWEEP DS/DS2 are pitch corrected too ). The angle table is not modified by roll, pitch and sound velocity. The function "depthFromTT", stored in library/pb_math.c, will give an example how to calculate the depth from the traveltime. The depth is already heave and draught corrected. 3. HOW TO USE THE SURF API ----------------------------------------- The SURF API is a library enabling easy access to SURF data. One of the source code files is the header file sapi.h describing the contents of the different SURF modules and declaring the SURF API function prototypes. The directory 'libsrc' includes the source code of the SURF API library. In the directory 'examples', you find two example source files (sapitest1.c, sapitest2.c) showing how to read data and using most of the SURF API functions. There are three additional examples which show how to build your own SURF data files (sapitest3.c, sapitest4.c, sapitest5.c). In the directory 'data', you find two different SURF files for testing the examples or testing your own application. In the directory 'doc', you find a description of the API functions. For compilation of the SURF API, an ANSI C compiler is required. Two additional system libraries must be linked to your application: - the math-lib 'libm.a' - the library with the xdr-routines In order to build the library and the example programms on a specific Unix system, please adapt the Makefiles in the directory 'libsrc' and in the directory 'examples' first: uncomment the compile and link options for the used Unix system and use make or gmake (on DEC-Unix) from the main directory. For Windows systems, you can find the project definition files for Visual Studio 6.0 in the following directories: example/win_sapitest1 example/win_sapitest2 example/win_sapitest4 libsrc/libsapi 3. COPYRIGHT AND LICENSING ----------------------------------------- SURF API Copyright (C) 1993-2001 by ATLAS Hydrographics GmbH D-28211 Bremen, Kurfuerstenallee 130 All Rights Reserved This SURF API source code is distributed under the GNU General Public License (GNU GPL) as formulated by the GNU Project. The GNU GPL prohibits the distribution of proprietary executables linked with this SURF API library unless the source code is also distributed. (see: http://www.gnu.org/copyleft/gpl.html) This SURF API does not come with any warranties, nor is it guaranteed to work on your computer or to do anything useful. The user assumes full responsibility for the use of this library.