/*--------------------------------------------------------------------
 *    The MB-system:	README	6/1/2002
 *
 *    Copyright (c) 2002 by
 *    David W. Caress (caress@mbari.org)
 *      Monterey Bay Aquarium Research Institute
 *      Moss Landing, CA 95039
 *    and Dale N. Chayes (dale@ldeo.columbia.edu)
 *      Lamont-Doherty Earth Observatory
 *      Palisades, NY 10964
 *
 *--------------------------------------------------------------------*/

This directory (mbsystem/src/surf) contains source code for 
reading and writing the SURF format developed by 
ATLAS Hydrographics GmbH of Bremen, Germany. This source 
code was developed by ATLAS Hydrographics and has been
released by ATLAS Hydrographics for open source distribution
under the GNU Public License (GPL).

The original ATLAS Hydrographics distribution also included
data samples and example programs that use the SURF API or
sapi library. This original distribution is available
separately from the MB-System ftp site.

The text from the original ATLAS README file is below, including
references to the example data and programs included in the
separate SAPI distribution.

/*--------------------------------------------------------------------*/

SURF Application Programming Interface (SURF API)
-------------------------------------------------
Version: 3.1.4

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 transferred 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. 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.
