MB-System Unix Manual Page: mbio

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

##

    mbio
    Section:  MB-System 5.0  (3)
    Updated:  3 June 2013
    Index

    NAME

    mbio - Format independent input/output library for swath mapping sonar data.

    VERSION

    Version 5.0

    DESCRIPTION

    MBIO (MultiBeam Input/Output) is a library
    of functions used for reading and writing swath mapping sonar
    data files.  MBIO supports a large number of data
    formats associated with different institutions and different sonar systems.
    The purpose of MBIO is to allow users to write processing and display
    programs which are independent of particular data formats and to provide
    a standard approach to swath mapping sonar data i/o.

    AUTHORSHIP

    David W. Caress (caress@mbari.org)

      Monterey Bay Aquarium Research Institute

    Dale N. Chayes (dale@ldeo.columbia.edu)

      Lamont-Doherty Earth Observatory

    DATA TERMINOLOGY

    MBIO handles three types of swath mapping data:  beam bathymetry,
    beam amplitude, and sidescan.  Both amplitude and sidescan represent
    measures of backscatter strength. Beam amplitudes are backscatter
    values associated with the same preformed beams used to
    obtain bathymetry; MBIO assumes that a bathymetry value
    exists for each amplitude value and uses the bathymetry beam
    location for the amplitude.  Sidescan is generally constructed with
    a higher spatial resolution than bathymetry, and carries its
    own location parameters.  In the context of MB-System documentation,
    the discrete values of bathymetry and amplitude are referred
    to as "beams", and the discrete values of sidescan are referred to
    as "pixels". An additional difference between "beam" and "pixel"
    data involves data flagging. An array of "beamflags" is carried by
    MBIO functions which allows the bathymetry (and by extension
    the amplitude) data to be flagged as bad. The details of the
    beamflagging scheme are presented below.

    VERSION 5 CHANGES

    This document describes version 5 releases of MBIO.
    The source code structure used in version 4 MBIO had grown
    complex and difficult to support. In particular, the addition
    of new i/o modules had become excessively time consuming.
    Consequently, we have restructured and rewritten much of the library.
    Most of the changes are internal, but two  function calls have
    disappeared (mb_put() and mb_write()), and a
    number of new functions have been added.

    A further significant architectural change was implemented for
    release 5.0.8 in order to support data formats that have no
    explicit maximum number of beams or pixels. The memory management
    of arrays used to hold bathymetry, amplitude, and sidescan data
    has been made dynamic. Now, when data records are encountered that
    include larger numbers of beams or pixels than will fit in the
    arrays previously allocated, those arrays are reallocated to
    the required size. This is handled automatically for all of the
    internal arrays used by MBIO functions. Of course,
    applications using MBIO must allocate arrays that are
    passed into functions like mb_read, mb_get_all, and
    mb_get to be populated by the desired data. In order for
    these arrays to be managed dynamically, the application must
    first register each array by passing the location of the array
    pointer to a new function called mb_register_array.

    OVERVIEW

    MBIO opens and initializes sonar data files for reading
    and writing using the functions mb_read_init and mb_write_init,
    respectively.  These functions return a pointer to a data structure
    including all relevent information about the opened file, the
    control parameters which determine how data is read or written,
    and the arrays used for processing the data as it is read or written.
    This pointer is then passed to the functions used for reading or
    writing.  There is no limit on the number of files which may be
    opened for reading or writing at any given time in a program.

    The mb_read_init and mb_write_init functions also return
    initial maximum numbers of bathymetry beams, amplitude beams,
    and sidescan pixels that can be used to allocate data storage
    arrays of the appropriate sizes. However, for some data formats
    there are no specified maximum numbers of beams and pixels, and
    so in general the required dimensions may increase as data are
    read. Applications must pass appropriately dimensioned arrays
    into data extraction routines such as mb_read, mb_get,
    and mb_get_all. In order to enable dynamic memory management
    of thse application arrays, the application must first register
    each array by passing the array pointer location to the function
    mb_register_array.

    Data files are closed using the function mb_close. All
    internal and registered arrays are deallocated as part of closing
    the file.

    When it comes to actually reading and writing swath mapping
    sonar data, MBIO has three levels of i/o functionality:

            1:      Simple reading of swath data files. The primary

                    functions are:

                            mb_read()

                            mb_get()

                    The positions of individual beams and pixels are

                    returned in longitude and latitude by

                    mb_read() and in acrosstrack and alongtrack

                    distances by mb_get(). Only a limited set

                    of navigation information is returned. Comments

                    are also returned. These functions can be used

                    without any special include  files or any

                    knowledge of the actual data structures used

                    by the data formats or MBIO.

            2:      Complete reading and writing of data structures

                    containing all of the available information.

                    Data records may be read or written without

                    extracting any of the information, or the

                    swath data may be passed with the data structure.

                    Several functions exist to extract information

                    from or insert information into the data

                    structures; otherwise, special include files

                    are required to make sense of the sonar-specific

                    data structures passed by level 2 i/o functions.

                    The basic read and write functions that only pass

                    pointers to internal data structures are:

                            mb_read_ping()

                            mb_write_ping()

                    The read and write routines which also extract

                    or insert information are:

                            mb_get_all()

                            mb_put_all()

                            mb_put_comment()

                    The information extraction and insertion

                    functions are:

                            mb_insert()

                            mb_extract()

                            mb_extract_nav()

                            mb_insert_nav()

                            mb_extract_altitude()

                            mb_insert_altitude()

                            mb_ttimes()

                            mb_copyrecord()

            3:      Buffered reading and writing of data structures

                    containing all of the available information.

                    The primary functions are:

                            mb_buffer_init()

                            mb_buffer_close()

                            mb_buffer_load()

                            mb_buffer_dump()

                            mb_buffer_info()

                            mb_buffer_get_next_data()

                            mb_buffer_extract()

                            mb_buffer_insert()

                            mb_buffer_get_next_nav()

                            mb_buffer_extract_nav()

                            mb_buffer_insert_nav()

    The level 1 MBIO functions allow users to read
    sonar data independent of format, with the limitation that
    only a limited set of navigation information is passed.  Thus, some of the
    information contained in certain data formats (e.g. the "heave" value
    in Hydrosweep DS data) is not passed by mb_read() or mb_get().
    In general, the level 1 functions are useful for applications
    such as graphics which require only the navigation and the depth
    and/or backscatter values.

    The level 2 functions (mb_get_all() and
    mb_put_all()) read and write the complete data
    structures, translate the data to internal data structures
    associated with each of the supported sonar systems, and
    pass pointers to these internal data structures. Additional
    functions allow a variety of information to be extracted
    from or inserted into the data structures (e.g. mb_extract()
    and mb_insert()). Additional information may be accessed
    using special include files to  decode the data structures.
    The great majority of processing programs use level 2 functions.

    The level 3 functions provide buffered reading and
    writing which is useful for applications that generate
    output files and need access to multiple pings at a time.  In addition to reading
    (mb_buffer_load()) and writing (mb_buffer_dump()), functions
    exist for extracting information from the buffer (mb_buffer_extract())
    and inserting information into the buffer (mb_buffer_insert()).

    MBIO supports swath data in a number of different formats,
    each specified by a unique id number. The function mb_format()
    determines if a format id is valid. A set of similar functions
    returns information about the specified format
    (e.g. mb_format_description(), mb_format_system(),
    mb_format_description(), mb_format_dimensions(),
    mb_format_flags(), mb_format_source(),
    mb_format_beamwidth()).

    Some MB-System programs can process multiple data
    files specified in "datalist" files. Each line of a datalist
    file contains a file path and the corresponding MBIO
    format id. Datalist files can be recursive and can contain
    comments. The functions used to extract input swath data
    file paths from datalist files
    includes mb_datalist_open(), mb_datalist_read(),
    and mb_datalist_close().

    A number of other MBIO functions dealing with default values for
    important parameters, error messages, memory management, and time conversions
    also exist and are discussed below.

    SUPPORTED SWATH SONAR SYSTEMS

    Each swath mapping sonar system outputs a data stream which includes some values
    or parameters unique to that system.  In general, a number of different data
    formats have come into use for data from each of the sonar systems; many of
    these formats include only a subset of the original data stream.  Internally,
    MBIO recognizes which sonar system each data format is associated
    with and uses a data structure including the complete data stream for that
    sonar.  Consequently, it is possible to read and write the complete
    data stream when using the level 2 or 3 MBIO functions.
    At present, formats associated with the following sonars are
    supported:

            SeaBeam "classic" 16 beam multibeam sonar

            Hydrosweep DS 59 beam multibeam sonar

            Hydrosweep MD 40 beam mid-depth multibeam

                    sonar

            SeaBeam 2000 multibeam sonar

            SeaBeam 2112, 2120, and 2130 multibeam

                    sonars

            Simrad EM12, EM121, EM950, and EM1000

                    multibeam sonars

            Simrad EM120, EM300, EM1002, and EM3000

                    multibeam sonars

            Hawaii MR-1 shallow tow interferometric

                    sonar

            ELAC Bottomchart 1180 and 1050 multibeam

                    sonars

            ELAC/SeaBeam Bottomchart Mk2 1180 and

                    1050 multibeam sonars

            Reson Seabat 9001/9002 multibeam sonars

            Reson Seabat 8101 multibeam sonars

            Simrad/Mesotech SM2000 multibeam sonars

            WHOI DSL AMS-120 deep tow interferometric

                    sonar

            AMS-60 interferometric sonar

    SUPPORTED FORMATS

    The following swath mapping sonar data formats are supported in this version of
    MBIO:

        MBIO Data Format ID:  11

        Format name:          MBF_SBSIOMRG

        Informal Description: SIO merge Sea Beam

        Attributes:           Sea Beam, bathymetry, 16 beams,

                              binary, uncentered, SIO.

        MBIO Data Format ID:  12

        Format name:          MBF_SBSIOCEN

        Informal Description: SIO centered Sea Beam

        Attributes:           Sea Beam, bathymetry, 19 beams,

                              binary, centered, SIO.

        MBIO Data Format ID:  13

        Format name:          MBF_SBSIOLSI

        Informal Description: SIO LSI Sea Beam

        Attributes:           Sea Beam, bathymetry, 19 beams,

                              binary, centered, obsolete, SIO.

        MBIO Data Format ID:  14

        Format name:          MBF_SBURICEN

        Informal Description: URI Sea Beam

        Attributes:           Sea Beam, bathymetry, 19 beams,

                              binary, centered, URI.

        MBIO Data Format ID:  15

        Format name:          MBF_SBURIVAX

        Informal Description: URI Sea Beam from VAX

        Attributes:           Sea Beam, bathymetry, 19 beams,

                              binary, centered,

                              VAX byte order, URI.

        MBIO Data Format ID:  16

        Format name:          MBF_SBSIOSWB

        Informal Description: SIO Swath-bathy SeaBeam

        Attributes:           Sea Beam, bathymetry, 19 beams,

                              binary, centered, SIO.

        MBIO Data Format ID:  17

        Format name:          MBF_SBIFREMR

        Informal Description: IFREMER Archive SeaBeam

        Attributes:           Sea Beam, bathymetry, 19 beams,

                              ascii, centered, IFREMER.

        MBIO Data Format ID:  21

        Format name:          MBF_HSATLRAW

        Informal Description: Raw Hydrosweep

        Attributes:           Hydrosweep DS, bathymetry and

                              amplitude, 59 beams, ascii,

                              Atlas Electronik.

        MBIO Data Format ID:  22

        Format name:          MBF_HSLDEDMB

        Informal Description: EDMB Hydrosweep

        Attributes:           Hydrosweep DS, bathymetry,

                              59 beams, binary, NRL.

        MBIO Data Format ID:  23

        Format name:          MBF_HSURICEN

        Informal Description: URI Hydrosweep

        Attributes:           Hydrosweep DS, 59 beams,

                              bathymetry, binary, URI.

        MBIO Data Format ID:  24

        Format name:          MBF_HSLDEOIH

        Informal Description: L-DEO in-house binary Hydrosweep

        Attributes:           Hydrosweep DS, 59 beams,

                              bathymetry and amplitude,

                              binary, centered, L-DEO.

        MBIO Data Format ID:  25

        Format name:          MBF_HSURIVAX

        Informal Description: URI Hydrosweep from VAX

        Attributes:           Hydrosweep DS, 59 beams,

                              bathymetry, binary, VAX byte

                              order, URI.

        MBIO Data Format ID:  32

        Format name:          MBF_SB2000SB

        Informal Description: SIO Swath-bathy SeaBeam 2000

        Attributes:           SeaBeam 2000, bathymetry, 121

                              beams, binary,  SIO.

        MBIO Data Format ID:  33

        Format name:          MBF_SB2000SS

        Informal Description: SIO Swath-bathy SeaBeam 2000

        Attributes:           SeaBeam 2000, sidescan,

                              1000 pixels for 4-bit

                              sidescan, 2000 pixels for

                              12+-bit sidescan, binary,

                              SIO.

        MBIO Data Format ID:  41

        Format name:          MBF_SB2100RW

        Informal Description: SeaBeam 2100 series vender format

        Attributes:           SeaBeam 2100, bathymetry,

                              amplitude and sidescan,

                              151 beams and 2000 pixels,

                              ascii with binary sidescan,

                              SeaBeam Instruments.

        MBIO Data Format ID:  42

        Format name:          MBF_SB2100B1

        Informal Description: SeaBeam 2100 series vender format

        Attributes:           SeaBeam 2100, bathymetry,

                              amplitude and sidescan,

                              151 beams bathymetry,

                              2000 pixels sidescan, binary,

                              SeaBeam Instruments and L-DEO.

        MBIO Data Format ID:  43

        Format name:          MBF_SB2100B2

        Informal Description: SeaBeam 2100 series vender format

        Attributes:           SeaBeam 2100, bathymetry and

                              amplitude, 151 beams bathymetry,

                              binary, SeaBeam Instruments

                              and L-DEO.

        MBIO Data Format ID:  51

        Format name:          MBF_EMOLDRAW

        Informal Description: Old Simrad vendor multibeam format

        Attributes:           Simrad EM1000, EM12S, EM12D,

                              and EM121 multibeam sonars,

                              bathymetry, amplitude, and

                              sidescan, 60 beams for EM1000,

                              81 beams for EM12S/D, 121 beams

                              for EM121, variable pixels,

                              ascii + binary, Simrad.

        MBIO Data Format ID:  53

        Format name:          MBF_EM12IFRM

        Informal Description: IFREMER TRISMUS format for

                              Simrad EM12

        Attributes:           Simrad EM12S and EM12D,

                              bathymetry, amplitude, and

                              sidescan 81 beams, variable

                              pixels, binary, IFREMER.

        MBIO Data Format ID:  54

        Format name:          MBF_EM12DARW

        Informal Description: Simrad EM12S RRS Darwin

                              processed format

        Attributes:           Simrad EM12S, bathymetry

                              and amplitude, 81 beams,

                              binary, Oxford University.

        MBIO Data Format ID:  56

        Format name:          MBF_EM300RAW

        Informal Description: Simrad current multibeam

                              vendor format

        Attributes:           Simrad EM120, EM300, EM1002,

                              EM3000, bathymetry, amplitude,

                              and sidescan, up to 254 beams,

                              variable pixels, ascii + binary,

                              Simrad.

        MBIO Data Format ID:  57

        Format name:          MBF_EM300MBA

        Informal Description: Simrad multibeam processing format

        Attributes:           Old and new Simrad multibeams,

                              EM12S, EM12D, EM121, EM120,

                              EM300, EM100, EM1000, EM950,

                              EM1002, EM3000, bathymetry,

                              amplitude, and sidescan,

                              up to 254 beams, variable pixels,

                              ascii + binary, MBARI.

        MBIO Data Format ID:  58

        Format name:          MBF_EM710RAW

        Informal Description: Simrad current multibeam vendor format

        Attributes:           Simrad EM710,

                              bathymetry, amplitude, and sidescan,

                              up to 400 beams, variable pixels,

                              binary, Simrad.

        MBIO Data Format ID:  59

        Format name:          MBF_EM710MBA

        Informal Description: Simrad current multibeam vendor format

        Attributes:           Simrad EM710,

                              bathymetry, amplitude, and sidescan,

                              up to 400 beams, variable pixels,

                              binary, Simrad.

        MBIO Data Format ID:  61

        Format name:          MBF_MR1PRHIG

        Informal Description: SOEST MR1 post processed format

        Attributes:           SOEST MR1, bathymetry and

                              sidescan, variable beams and

                              pixels, xdr binary, SOEST,

                              University of Hawaii.

        MBIO Data Format ID:  62

        Format name:          MBF_MR1ALDEO

        Informal Description: L-DEO MR1 post processed

                              format with travel times

        Attributes:           L-DEO MR1, bathymetry and

                              sidescan, variable beams

                              and pixels, xdr binary, L-DEO.

        MBIO Data Format ID:  63

        Format name:          MBF_MR1BLDEO

        Informal Description: L-DEO small MR1 post processed

                              format with travel times

        Attributes:           L-DEO MR1, bathymetry and sidescan,

                              variable beams and pixels,

                              xdr binary, L-DEO.

        MBIO Data Format ID:  64

        Format name:          MBF_MR1PRVR2

        Informal Description: SOEST MR1 post processed format

        Attributes:           SOEST MR1, bathymetry and sidescan,

                              variable beams and pixels, xdr binary,

                              SOEST, University of Hawaii.

        MBIO Data Format ID:  71

        Format name:          MBF_MBLDEOIH

        Informal Description: L-DEO in-house generic multibeam

        Attributes:           Data from all sonar systems,

                              bathymetry, amplitude and

                              sidescan, variable beams and

                              pixels, binary, centered, L-DEO.

        MBIO Data Format ID:  75

        Format name:          MBF_MBNETCDF

        Informal Description: CARAIBES CDF multibeam

        Attributes:           Data from all sonar systems,

                              bathymetry only, variable

                              beams, netCDF, IFREMER.

        MBIO Data Format ID:  81

        Format name:          MBF_CBAT9001

        Informal Description: Reson SeaBat 9001 shallow

                              water multibeam

        Attributes:           60 beam bathymetry and

                              amplitude, binary, University

                              of New Brunswick.

        MBIO Data Format ID:  82

        Format name:          MBF_CBAT8101

        Informal Description: Reson SeaBat 8101 shallow

                              water multibeam

        Attributes:           101 beam bathymetry and

                              amplitude, binary, SeaBeam

                              Instruments.

        MBIO Data Format ID:  83

        Format name:          MBF_HYPC8101

        Informal Description: Reson SeaBat 8101 shallow

                              water multibeam

        Attributes:           101 beam bathymetry,

                              ASCII, read-only, Coastal

                              Oceanographics.

        MBIO Data Format ID:  84

        Format name:          MBF_XTFR8101

        Informal Description: XTF format Reson SeaBat 81XX

        Attributes:           240 beam bathymetry and amplitude,

                              1024 pixel sidescan

                              binary, read-only,

                              Triton-Elics.

        MBIO Data Format ID:  88

        Format name:          MBF_RESON7KR

        Informal Description: Reson 7K multibeam vendor format

        Attributes:           Reson 7K series multibeam sonars,

                              bathymetry, amplitude, three

                              channels sidescan, and subbottom

                              up to 254 beams, variable pixels,

                              binary, Reson.

        MBIO Data Format ID:  91

        Format name:          MBF_BCHRTUNB

        Informal Description: Elac BottomChart shallow

                              water multibeam

        Attributes:           56 beam bathymetry and

                              amplitude, binary, University

                              of New Brunswick.

        MBIO Data Format ID:  92

        Format name:          MBF_ELMK2UNB

        Informal Description: Elac BottomChart MkII shallow

                              water multibeam

        Attributes:           126 beam bathymetry and

                              amplitude, binary, University

                              of New Brunswick.

        MBIO Data Format ID:  93

        Format name:          MBF_BCHRXUNB

        Informal Description: Elac BottomChart shallow

                              water multibeam

        Attributes:           56 beam bathymetry and

                              amplitude, binary, University

                              of New Brunswick.

        MBIO Data Format ID:  94

        Format name:          MBF_L3XSERAW

        Informal Description: ELAC/SeaBeam XSE vendor format

        Attributes:           Bottomchart MkII 50 kHz and

                              180 kHz multibeam, SeaBeam 2120

                              20 KHz multibeam, bathymetry,

                              amplitude and sidescan, variable

                              beams and pixels, binary, L3

                              Communications (Elac Nautik

                              and SeaBeam Instruments).

        MBIO Data Format ID:  101

        Format name:          MBF_HSMDARAW

        Informal Description: Atlas HSMD medium depth

                              multibeam raw format

        Attributes:           40 beam bathymetry, 160 pixel

                              sidescan, XDR (binary),

                              STN Atlas Elektronik.

        MBIO Data Format ID:  102

        Format name:          MBF_HSMDLDIH

        Informal Description: Atlas HSMD medium depth

                              multibeam processed format

        Attributes:           40 beam bathymetry, 160 pixel

                              sidescan, XDR (binary), L-DEO.

        MBIO Data Format ID:  111

        Format name:          MBF_DSL120SF

        Informal Description: WHOI DSL AMS-120 processed format

        Attributes:           2048 beam bathymetry,

                              8192 pixel sidescan,

                              binary, single files, WHOI DSL.

        MBIO Data Format ID:  112

        Format name:          MBF_DSL120PF

        Informal Description: WHOI DSL AMS-120 processed

                              format

        Attributes:           2048 beam bathymetry,

                              8192 pixel sidescan,

                              binary, parallel bathymetry

                              and amplitude files, WHOI DSL.

        MBIO Data Format ID:  121

        Format name:          MBF_GSFGENMB

        Informal Description: SAIC Generic Sensor Format (GSF)

        Attributes:           variable beams,  bathymetry

                              and amplitude, binary,

                              single files, SAIC.

        MBIO Data Format ID:  131

        Format name:          MBF_MSTIFFSS

        Informal Description: MSTIFF sidescan format

        Attributes:           variable pixels,  sidescan,

                              binary TIFF variant,

                              single files, Sea Scan.

        MBIO Data Format ID:  132

        Format name:          MBF_EDGJSTAR

        Informal Description: Edgetech Jstar format

        Attributes:           variable pixels, dual frequency

                              sidescan and subbottom,

                              binary SEGY variant, single files,

                              low frequency sidescan returned as

                              survey data, Edgetech.

        MBIO Data Format ID:  133

        Format name:          MBF_EDGJSTR2

        Informal Description: Edgetech Jstar format

        Attributes:           variable pixels, dual frequency

                              sidescan and subbottom,

                              binary SEGY variant, single files,

                              high frequency sidescan returned as

                              survey data, Edgetech.

        MBIO Data Format ID:  141

        Format name:          MBF_OICGEODA

        Informal Description: OIC swath sonar format

        Attributes:           variable beam bathymetry and

                              amplitude, variable pixel

                              sidescan, binary,

                              Oceanic Imaging Consultants

        MBIO Data Format ID:  142

        Format name:          MBF_OICMBARI

        Informal Description: OIC-style extended swath

                              sonar format

        Attributes:           variable beam bathymetry and

                              amplitude, variable pixel

                              sidescan, binary, MBARI

        MBIO Data Format ID:  151

        Format name:          MBF_OMGHDCSJ

        Informal Description: UNB OMG HDCS format

                              (the John Hughes Clarke format)

        Attributes:           variable beam bathymetry and

                              amplitude, variable pixel

                              sidescan, binary, UNB

        MBIO Data Format ID:  160

        Format name:          MBF_SEGYSEGY

        Informal Description: SEGY seismic data format

        Attributes:           seismic or subbottom trace data,

                              single beam bathymetry, nav,

                              binary, SEG (SIOSEIS variant)

        MBIO Data Format ID:  161

        Format name:          MBF_MGD77DAT

        Informal Description: NGDC MGD77 underway geophysics

                              format

        Attributes:           single beam bathymetry, nav,

                              magnetics, gravity, ascii,

                              NOAA NGDC

        MBIO Data Format ID:  162

        Format name:          MBF_ASCIIXYZ

        Informal Description: Generic XYZ sounding format

        Attributes:           XYZ (lon lat depth) ASCII

                              soundings, generic

        MBIO Data Format ID:  163

        Format name:          MBF_ASCIIYXZ

        Informal Description: Generic YXZ sounding format

        Attributes:           YXZ (lat lon depth) ASCII

                              soundings, generic

        MBIO Data Format ID:  164

        Format name:         MBF_HYDROB93

        Informal Description: NGDC binary hydrographic

                              sounding format

        Attributes:           XYZ (lon lat depth) binary

                              soundings

        MBIO Data Format ID:  165

        Format name:          MBF_MBARIROV

        Informal Description: MBARI ROV navigation format

        Attributes:           ROV navigation, MBARI

        MBIO Data Format ID:  166

        Format name:          MBF_MBPRONAV

        Informal Description: MB-System simple navigation

                              format

        Attributes:           navigation, MBARI

        MBIO Data Format ID:  167

        Format name:          MBF_MBNETCDF

        Informal Description: CARAIBES CDF navigation

        Attributes:           netCDF, IFREMER.

        MBIO Data Format ID:  168

        Format name:          MBF_ASCIIXYT

        Informal Description: Generic XYT sounding format

        Attributes:           XYT (lon lat topography) ASCII

                              soundings, generic

        MBIO Data Format ID:  169

        Format name:          MBF_ASCIIYXT

        Informal Description: Generic YXT sounding format

        Attributes:           YXT (lat lon topograpy) ASCII

                              soundings, generic

        MBIO Data Format ID:  170

        Format name:          MBF_MBARROV2

        Informal Description: MBARI ROV navigation format

        Attributes:           ROV navigation, MBARI

        MBIO Data Format ID:  171

        Format name:          MBF_HS10JAMS

        Informal Description: Furuno HS-10 multibeam format,

        Attributes:           45 beams bathymetry and amplitude,

                              ascii, JAMSTEC

        MBIO Data Format ID:  181

        Format name:          MBF_SAMESURF

        Informal Description: SAM Electronics SURF format.

        Attributes:           variable beams,  bathymetry,

                              amplitude,  and sidescan,

                              binary, single files, SAM Electronics
                              (formerly Krupp-Atlas Electronik).

        MBIO Data Format ID:  182

        Format name:          MBF_HSDS2RAW

        Informal Description: STN Atlas raw multibeam format

        Attributes:           STN Atlas multibeam sonars,

                              Hydrosweep DS2, Hydrosweep MD,

                              Fansweep 10, Fansweep 20,

                              bathymetry, amplitude, and sidescan,

                              up to 1440 beams and 4096 pixels,

                              XDR binary, STN Atlas.

        MBIO Data Format ID:  183

        Format name:          MBF_HSDS2LAM

        Informal Description: L-DEO HSDS2 processing format

        Attributes:           STN Atlas multibeam sonars,

                              Hydrosweep DS2, Hydrosweep MD,

                              Fansweep 10, Fansweep 20,

                              bathymetry, amplitude, and sidescan,

                              up to 1440 beams and 4096 pixels,

                              XDR binary, L-DEO.

        MBIO Data Format ID:  222

        Format name:          MBF_SWPLSSXP

        Informal Description: SEA interferometric processed data format

        Attributes:           Submetrix Interferometers,

                      SWATHplus-L, SWATHplus-M, SWATHplus-H,

                      Bathyswath-1, Bathyswath-2,

                      bathymetry and amplitude, SXP binary.

    The institutional acronyms used above have the following meanings:

            L-DEO   Lamont-Doherty Earth Observatory

            MBARI   Monterey Bay Aquarium Research Institute

            SIO     Scripps Institution of Oceanography

            WHOI    Woods Hole Oceanographic Institution

            URI     University of Rhode Island

            NRL     Naval Research Laboratory

            UNB     University of New Brunswick

            UH      University of Hawaii

            NOAA    National Oceans and Atmospheres Agency

            NGDC    National Geophysical Data Center

            USGS    United States Geological Survey

            IFREMER French government agency responsible

                    for operation of French oceanographic

                    research fleet.

    FUNCTION STATUS AND ERROR CODES

    All of the MBIO functions return an integer status value with the
    convention that:

            status = 1:     success

            status = 0:     failure

    All MBIO functions also pass an error value argument which gives
    somewhat more information about problems than the status value.  The
    full suite of possible error values and the associated error messages are:

            error = 0:      "No error",

            error = -1:     "Time gap in data",

            error = -2:     "Data outside specified location

                            bounds",

            error = -3:     "Data outside specified time interval",

            error = -4:     "Ship speed too small",

            error = -5:     "Comment record",

            error = -6:     "Neither a data record nor a comment

                            record",

            error = -7:     "Unintelligible data record",

            error = -8:     "Ignore this data",

            error = -9:     "No data requested for buffer load",

            error = -10:    "Data buffer is full",

            error = -11:    "No data was loaded into the buffer",

            error = -12:    "Data buffer is empty",

            error = -13:    "No data was dumped from the buffer"

            error = -14:    "No more survey data records in buffer"

            error = -15:    "Data inconsistencies prevented

                            inserting data into storage structure"

            error = 1:      "Unable to allocate memory,

                            initialization failed",

            error = 2:      "Unable to open file,

                            initialization failed",

            error = 3:      "Illegal format identifier,

                            initialization failed",

            error = 4:      "Read error, probably end-of-file",

            error = 5:      "Write error",

            error = 6:      "No data in specified location bounds",

            error = 7:      "No data in specified time interval",

            error = 8:      "Invalid MBIO descriptor",

            error = 9:      "Inconsistent usage of MBIO descriptor",

            error = 10:     "No pings binned but no fatal error

                            - this should not happen!",

            error = 11:     "Invalid data record type specified

                            for writing",

            error = 12:     "Invalid control parameter specified

                            by user",

            error = 13:     "Invalid buffer id",

            error = 14:     "Invalid system id - this should

                            not happen!"

            error = 15:     "This data file is not in the specified format!"

    In general, programs should treat negative error values as non-fatal
    (reading and writing can continue) and positive error values as fatal (the data
    files should be closed and the program terminated).

    FUNCTION VERBOSITY

    All of the MBIO functions are passed a verbose parameter which
    controls how much debugging information is output to standard error.  If
    verbose is 0 or 1, the MBIO functions will be silent.  If
    verbose is 2, then each function will output information as it is
    entered and as it returns, along with the parameter values passed into and
    returned out of the function.  Greater values of verbose will cause
    additional information to be output, including values at various stages
    of data processing during read and write operations.  In general, programs
    using MBIO functions should adopt the following verbosity conventions:

            verbose = 0:    "silent" or near-"silent" execution

            verbose = 1:    simple output including

                                    program name, version

                                    and simple progress updates

            verbose >= 2:   debug mode with copious output

                                    including every function call

                                    and status listings

    INITIALIZATION AND CLOSING FUNCTIONS

    int mb_read_init(

                    int verbose,

                    char *file,

                    int format,

                    int pings,

                    int lonflip,

                    double bounds[4],

                    int btime_i[7],

                    int etime_i[7],

                    double speedmin,

                    double timegap,

                    char **mbio_ptr,

                    double *btime_d,

                    double *etime_d,

                    int *beams_bath,

                    int *beams_amp,

                    int *pixels_ss,

                    int *error);

    The function mb_read_init initializes the data file to be read
    and the data structures required for reading the data. The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            file:           input filename

            format:         input MBIO data format id

            pings:          ping averaging

            lonflip:                longitude flipping

            bounds:         location bounds of acceptable data

            btime_i:                beginning time of acceptable data

            etime_i:                ending time of acceptable data

            speedmin:               minimum ship speed of acceptable data

            timegap:                maximum time allowed before data gap

    The format identifier format specifies which of the supported
    data formats is being read or written; the currently supported formats
    are listed in the "SUPPORTED FORMATS" section.

    The pings parameter determines whether and how pings are averaged as part
    of data input.  This parameter is used only by the functions mb_read
    and mb_get; mb_get_all and mb_buffer_load do not average
    pings.  If pings = 1, then no ping averaging will be done and
    each ping read will be returned unaltered by the reading function.  If
    pings > 1, then the navigation and beam data for pings pings
    will be read, averaged, and returned as the data for a single ping.  If
    pings = 0, then the ping averaging will be varied so that the
    along-track distance between averaged pings is as close as possible to the
    across-track distance between beams.

    The lonflip paramenter determines the range in which longitude values
    are returned:

            lonflip = -1 : -360 to   0

            lonflip =  0 : -180 to 180

            lonflip =  1 :    0 to 360

    The bounds array sets the area within which data are desired.
    Data which lie outside the area specified by bounds will
    be returned with an error by the reading function.
    The functions mb_read,
    mb_get and mb_get_all use the bounds array; the
    function mb_buffer_load does no location checking.

            bounds[0] : minimum longitude

            bounds[1] : maximum longitude

            bounds[2] : minimum latitude

            bounds[3] : maximum latitude

    The btime_i array sets the desired beginning time for the data
    and the etime_i array sets the desired ending time.
    If the beginning time is earlier than the ending time, then any
    data with a time stamp before the beginning time or
    after the ending time will be returned with an
    MB_ERROR_OUT_TIME error by the reading function.
    If the beginning time is after the ending time, then
    data with time stamps between the ending and beginning
    time are returned with an error. This scheme allows time
    windowing outside or inside a specified interval.
    The functions mb_read,
    mb_get and mb_get_all use the
    btime_i and btime_i arrays; the
    function mb_buffer_load does no time checking.

            btime[0] : year

            btime[1] : month

            btime[2] : day

            btime[3] : hour

            btime[4] : minute

            btime[5] : second

            btime[6] : microsecond

            etime[0] : year

            etime[1] : month

            etime[2] : day

            etime[3] : hour

            etime[4] : minute

            etime[5] : second

            etime[6] : microsecond

    The speedmin parameter sets the minimum acceptable ship speed for
    the data.  If the ship speed associated with any ping is less than
    speedmin, then that data will be returned with an error
    by the reading function.
    This is used to eliminate data collected while a ship is on station is
    a simple way. The functions mb_read,
    mb_get and mb_get_all use the speedmin value; the
    function mb_buffer_load does no speed checking.

    The timegap parameter sets the minimum time gap allowed before a
    gap in the data is declared.  Ping averaging is not done across
    data gaps; an error is returned when time gaps are encountered.
    The functions mb_read and
    mb_get use the timegap value; the
    functions mb_get_all and mb_buffer_load do no ping averaging
    and thus have no need to check for time gaps.

    The returned values are:

            mbio_ptr:       pointer to an MBIO descriptor structure

            btime_d:                desired beginning time in seconds

                                            since 1/1/70 00:00:0

            etime_d:                desired ending time in seconds

                                            since 1/1/70 00:00:0

            beams_bath:     maximum number of bathymetry beams

            beams_amp:      maximum number of amplitude beams

            pixels_ss:      maximum number of sidescan pixels

            error:          error value

    The structure pointed to by
    mbio_ptr holds the file descriptor and all of the control parameters
    which govern how the data is read; this pointer must be provided to
    the functions mb_read, mb_get, mb_get_all,
    or mb_buffer_load to read data. The values beams_bath,
    beams_amp, and pixels_ss return initial estimates of the maximum number
    of bathymetry and amplitude beams and sidescan pixels, respectively,
    that the specified data format may contain. In general, beams_amp
    will either be zero or equal to beams_bath. The values btime_d
    and etime_d give the desired beginning and end times of the data
    converted to seconds since 00:00:00 on January 1, 1970;
    MBIO uses these units to calculate time internally.

    For most data formats, the initial maximum beam and pixel dimensions will not change.
    However, a few formats support both variable and arbitrarily large numbers
    of beams and/or pixels, and so applications must be capable of handling
    dynamic changes in the numbers of beams and pixels. The arrays allocated
    internally in the mbio_ptr structure are automatically increased
    when necessary. However, in order to successfully extract
    swath data using mb_get, mb_get_all, mb_read, or
    mb_extract, an application must also
    provide pointers to arrays large enough to hold the current maximum numbers
    of bathymetry beams, amplitude beams, and sidescan pixels. The function
    mb_register_ioarray allows applications to register array pointers
    so that these arrays are also dynamically allocated by MBIO. Registered
    arrays will be managed as data are read and then freed when mb_close
    is called.

    A status value indicating success or failure is returned; an error value
    argument passes more detailed information about initialization failures.

    ---------------------------------------------------------

    int mb_write_init(

                    int verbose,

                    char *file,

                    int format,

                    char **mbio_ptr,

                    int *beams_bath,

                    int *beams_amp,

                    int *pixels_ss,

                    int *error);

    The function mb_write_init initializes the data file to be written
    and the data structures required for writing the data. The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            file:           output filename

            format:         output MBIO data format id

    The returned values are:

            mbio_ptr:       pointer to a structure describing

                                            the output file

            beams_bath:     maximum number of bathymetry beams

            beams_back:     maximum number of backscatter beams

            error:          error value

    The structure pointed to by
    mbio_ptr holds the output file descriptor; this pointer must be
    provided to
    the functions mb_write, mb_put, mb_put_all,
    or mb_buffer_dump to write data. The values beams_bath,
    beams_amp, and pixels_ss return the maximum number
    of bathymetry and amplitude beams and sidescan pixels, respectively,
    that the specified data format may contain.  In general, beams_amp
    will either be zero or equal to beams_bath.  In order to successfully
    write data, the calling program must
    provide pointers to arrays large enough to hold beams_bath bathymetry
    values, beams_amp amplitude values, and pixels_ss sidescan
    values.

    For most data formats, the initial maximum beam and pixel dimensions will not change.
    However, a few formats support both variable and arbitrarily large numbers
    of beams and/or pixels, and so applications must be capable of handling
    dynamic changes in the numbers of beams and pixels. The arrays allocated
    internally in the mbio_ptr structure are automatically increased
    when necessary. However, in order to successfully insert modified
    swath data using mb_put, mb_put_all, or
    mb_insert, an application must also
    provide pointers to arrays large enough to hold the current maximum numbers
    of bathymetry beams, amplitude beams, and sidescan pixels. The function
    mb_register_ioarray allows applications to register array pointers
    so that these arrays are also dynamically allocated by MBIO. Registered
    arrays will be managed as data are read and written and then freed when mb_close
    is called.

    A status value indicating success or failure is returned; an error value
    argument passes more detailed information about initialization failures.

    ---------------------------------------------------------

    int mb_register_array(

                    int verbose,

                    void *mbio_ptr,

                    int type,

                    int size,

                    void **handle,

                    int *error)

    Registers an array pointer *handle so that the size of
    the allocated array can be managed dynamically by MBIO.
    Note that the location **handle of the array
    pointer must be supplied, not the pointer value *handle.
    The pointer value *handle should initially be NULL.
    The type value indicates whether this
    array is to be dimensioned according to the maximum number of
    bathymetry beams (type = 1), amplitude beams (type = 2),
    or sidescan pixels (type = 3). The size
    value indicates the size of each element array in bytes (e.g. a char
    array has size = 1, a short array has size = 2, an
    int array or a float array have size = 4, and a double array
    has size = 8). The array is associated with the MBIO
    descriptor mbio_ptr, and is freed when mb_close is
    called for this particular mbio_ptr.

    ---------------------------------------------------------

    int mb_close(

                    int verbose,

                    char *mbio_ptr,

                    int *error)

    Closes the data file listed in the MBIO descriptor pointed to
    by mbio_ptr and releases all specially allocated memory,
    including all application arrays registered using mb_register_array..
    The verbose value controls the standard error output verbosity
    of the function. A status value indicating success or failure is
    returned; an error value argument passes more detailed information
    about failures.

    LEVEL 1 FUNCTIONS

    ---------------------------------------------------------

    int mb_read(

                    int verbose,

                    char *mbio_ptr,

                    int *kind,

                    int *pings,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    double *distance,

                    double *altitude,

                    double *sonardepth,

                    int *nbath,

                    int *namp,

                    int *nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathlon,

                    double *bathlat,

                    double *ss,

                    double *sslon,

                    double *sslat,

                    char *comment,

                    int *error);

    The function mb_read reads, processes, and returns sonar
    data according to the MBIO descriptor pointed to by mbio_ptr.
    The verbose
    value controls the standard error output verbosity of the function. A number
    of different data record types are recognized by MB-System, but
    mb_read() only returns survey and comment data records. The
    kind value indicates which type of record has been read.
    The data is in the form of bathymetry, amplitude, and sidescan values combined
    with the longitude and latitude locations of the bathymetry and
    sidescan measurements (amplitudes are coincident with the bathymetry).

    The return values are:

            kind:           kind of data record read

                                            1       survey data

                                            2       comment

                                            >=3     other data that cannot

                                                    be passed by mb_read

            pings:          number of pings averaged to give current data

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            distance:               distance along shiptrack since last

                            ping in km

            altitude:               altitude of sonar above seafloor

                            in m

            sonardepth:     depth of sonar in m

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathlon:                array of of longitude values corresponding

                            to bathymetry

            bathlat:                array of of latitude values corresponding

                            to bathymetry

            ss:             array of sidescan values in unknown units

            sslon:          array of of longitude values corresponding

                            to sidescan

            sslat:          array of of latitude values corresponding

                            to sidescan

            comment:        comment string

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    read failures.

    ---------------------------------------------------------

    int mb_get(

                    int verbose,

                    char *mbio_ptr,

                    int *kind,

                    int *pings,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    double *distance,

                    double *altitude,

                    double *sonardepth,

                    int *nbath,

                    int *namp,

                    int *nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_get reads, processes, and returns sonar
    data according to the MBIO descriptor pointed to by mbio_ptr.
    The verbose
    value controls the standard error output verbosity of the function. A number
    of different data record types are recognized by MB-System, but
    mb_get() only returns survey and comment data records. The
    kind value indicates which type of record has been read.
    The data is in the form of bathymetry, amplitude, and sidescan values combined
    with the acrosstrack and alongtrack distances relative to the navigation
    of the bathymetry and sidescan
    measurements (amplitudes are coincident with the bathymetry values).

    The return values are:

            kind:           kind of data record read

                                            1       survey data

                                            2       comment

                                            >=3     other data that cannot

                                                    be passed by mb_get

            pings:          number of pings averaged to give current data

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            distance:       distance along shiptrack since last

                            ping in km

            altitude:               altitude of sonar above seafloor

                            in m

            sonardepth:     depth of sonar in m

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:                comment string

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    read failures.

    LEVEL 2 FUNCTIONS

    int mb_read_ping(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    int *error);

    The function mb_read_ping reads and returns sonar
    data according to the MBIO descriptor pointed to by mbio_ptr.
    The verbose
    value controls the standard error output verbosity of the function.
    The data is returned one record at a time; no averaging is performed.
    A pointer to a data structure containing all of the data read is returned
    as store_ptr; the form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of record has been read.

    The return values are:

            store_ptr:      pointer to complete data structure

            kind:           kind of data record read

                                            1       survey data

                                            2       comment

                                            3       header

                                            4       calibrate

                                            5       mean sound speed

                                            6       SVP

                                            7       standby

                                            8       nav source

                                            9       parameter

                                            10      start

                                            11      stop

                                            12      nav

                                            13      run parameter

                                            14      clock

                                            15      tide

                                            16      height

                                            17      heading

                                            18      attitude

                                            19      ssv

                                            20      angle

                                            21      event

                                            22      history

                                            23      summary

                                            24      processing parameters

                                            25      sensor parameters

                                            26      navigation error

                                            27      uninterpretable line

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    read failures.

    ---------------------------------------------------------

    int mb_write_ping(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *error);

    The function mb_write_ping writes sonar data to the file listed
    in the MBIO descriptor pointed to by MBIO_ptr.
    The verbose
    value controls the standard error output verbosity of the function.
    A pointer to a data structure containing all of the data read is passed
    as store_ptr; the form of the data structure is determined by the
    sonar system associated with the format of the data being written.
    The values to be output are:

            store_ptr:      pointer to complete data structure

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    write failures.

    ---------------------------------------------------------

    int mb_get_store(

                    int verbose,

                    char *mbio_ptr,

                    char **store_ptr,

                    int *error);

    The function mb_get_store() returns a pointer *store_ptr
    to the data storage structure associated with a particular MBIO
    descriptor mbio_ptr. The mb_read_init() and
    mb_write_init() functions
    both allocate one of these internal storage structures. The
    form of the data structure is determined by the
    sonar system associated with the format of the data being written.
    Storage structure pointers must be passed to level two MBIO
    functions such as mb_write_ping() and mb_insert().
    The verbose value controls the standard error
    output verbosity of the function.

    The return values are:

            store_ptr:      pointer to complete data structure

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_get_all(

                    int verbose,

                    char *mbio_ptr,

                    char **store_ptr,

                    int *kind,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    double *distance,

                    double *altitude,

                    double *sonardepth,

                    int *nbath,

                    int *namp,

                    int *nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_get_all reads and returns sonar
    data according to the MBIO descriptor pointed to by mbio_ptr.
    The verbose
    value controls the standard error output verbosity of the function.
    The data is returned one record at a time; no averaging is performed.
    A pointer to a data structure containing all of the data read is returned
    as store_ptr; the form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of record has been read. Additional
    data is returned if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan), navigation data (navigation only), or
    comment data (comment only).

    The return values are:

            store_ptr:      pointer to complete data structure

            kind:           kind of data record read

                                            1       survey data

                                            2       comment

                                            3       header

                                            4       calibrate

                                            5       mean sound speed

                                            6       SVP

                                            7       standby

                                            8       nav source

                                            9       parameter

                                            10      start

                                            11      stop

                                            12      nav

                                            13      run parameter

                                            14      clock

                                            15      tide

                                            16      height

                                            17      heading

                                            18      attitude

                                            19      ssv

                                            20      angle

                                            21      event

                                            22      history

                                            23      summary

                                            24      processing parameters

                                            25      sensor parameters

                                            26      navigation error

                                            27      uninterpretable line

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            distance:       distance along shiptrack since last

                            ping in km

            altitude:               altitude of sonar above seafloor

                            in m

            sonardepth:     depth of sonar in m

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:        comment string

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    read failures.

    ---------------------------------------------------------

    int mb_put_all(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int usevalues,

                    int kind,

                    int time_i[7],

                    double time_d,

                    double navlon,

                    double navlat,

                    double speed,

                    double heading,

                    int nbath,

                    int namp,

                    int nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_put_all writes sonar data to the file listed
    in the MBIO descriptor pointed to by MBIO_ptr.
    The verbose
    value controls the standard error output verbosity of the function.
    A pointer to a data structure containing all of the data read is passed
    as store_ptr; the form of the data structure is determined by the
    sonar system associated with the format of the data being written.
    Additional data is passed if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan), navigation data (navigation only), or
    comment data (comment only).
    If the usevalues flag is set to 1,
    then the passed values will be inserted in the data structure
    pointed to by store_ptr before
    the data is written.  If the usevalues flag is set to 0, the data
    structure pointed to by store_ptr will be written without modification.
    The values to be output are:

            store_ptr:      pointer to complete data structure

            usevalues:      flag controlling use of data passed by value

                                            0       do not insert into data

                                                    structure before writing

                                                    the data

                                            1       insert into data structure

                                                    before writing the data

            kind:           kind of data record to be written

                                            1       survey data

                                            2       comment

                                            3       header

                                            4       calibrate

                                            5       mean sound speed

                                            6       SVP

                                            7       standby

                                            8       nav source

                                            9       parameter

                                            10      start

                                            11      stop

                                            12      nav

                                            13      run parameter

                                            14      clock

                                            15      tide

                                            16      height

                                            17      heading

                                            18      attitude

                                            19      ssv

                                            20      angle

                                            21      event

                                            22      history

                                            23      summary

                                            24      processing parameters

                                            25      sensor parameters

                                            26      navigation error

                                            27      uninterpretable line

            time_i:         time of current ping (used if time_i[0] != 0)

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds since

                                    1/1/70 00:00:00 (used if time_i[0] = 0)

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:        comment string

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    write failures.

    ---------------------------------------------------------

    int mb_put_comment(

                    int verbose,

                    char *mbio_ptr,

                    char *comment,

                    int *error);

    The function mb_put_comment writes a comment to the file listed
    in the MBIO descriptor pointed to by MBIO_ptr.
    The verbose
    value controls the standard error output verbosity of the function.
    The data is in the form of a null terminated string. The maximum
    length of comments varies with different data formats. In
    general individual comments should be less than 80 characters
    long to insure compatibility with all formats.
    The values to be output are:

            comment:                comment string

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    write failures.

    ---------------------------------------------------------

    int mb_extract(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    int *nbath,

                    int *namp,

                    int *nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_extract extracts sonar data from the
    structure pointed to by *store_ptr according to the
    MBIO descriptor pointed to by mbio_ptr.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of record is stored in *store_ptr.
    Additional
    data is returned if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan), navigation data (navigation only), or
    comment data (comment only).

    The return values are:

            kind:           kind of data record read

                                            1       survey data

                                            2       comment

                                            12      navigation

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            distance:               distance along shiptrack since last

                            ping in km

            altitude:               altitude of sonar above seafloor

                            in m

            sonardepth:     depth of sonar in m

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:        comment string

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    extract failures.

    ---------------------------------------------------------

    int mb_insert(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int kind,

                    int time_i[7],

                    double time_d,

                    double navlon,

                    double navlat,

                    double speed,

                    double heading,

                    int nbath,

                    int namp,

                    int nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_insert inserts sonar data into the
    structure pointed to by *store_ptr according to the
    MBIO descriptor pointed to by mbio_ptr.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of
    record is to be stored in *store_ptr.
    Data will be inserted only if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan), navigation data (navigation only), or
    comment data (comment only).
    The values to be inserted are:

            kind:           kind of data record inserted

                                            1       survey data

                                            2       comment

                                            12      navigation

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            distance:               distance along shiptrack since last

                            ping in km

            altitude:               altitude of sonar above seafloor

                            in m

            sonardepth:     depth of sonar in m

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:        comment string

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    insert failures.

    ---------------------------------------------------------

    int mb_extract_nav(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    double *draft,

                    double *roll,

                    double *pitch,

                    double *heave,

                    int *error);

    The function mb_extract_nav extracts navigation data from the
    structure pointed to by *store_ptr according to the
    MBIO descriptor pointed to by mbio_ptr.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of record is stored in *store_ptr.
    Navigation
    data is returned if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan) or navigation data (navigation only).

    The return values are:

            kind:           kind of data record read

                                    1       survey data

                                    12      navigation

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            draft:          sonar depth in meters

            roll:           sonar roll in degrees

            pitch:          sonar pitch in degrees

            heave:          sonar heave in meters

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    extract failures.

    ---------------------------------------------------------

    int mb_insert_nav(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int time_i[7],

                    double time_d,

                    double navlon,

                    double navlat,

                    double speed,

                    double heading,

                    double draft,

                    double roll,

                    double pitch,

                    double heave,

                    int *error);

    The function mb_insert_nav inserts navigation data into the
    structure pointed to by *store_ptr according to the
    MBIO descriptor pointed to by mbio_ptr.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of
    record is to be stored in *store_ptr.
    Data will be inserted only if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan), or navigation data (navigation only).
    The values to be inserted are:

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            draft:          sonar depth in meters

            roll:           sonar roll in degrees

            pitch:          sonar pitch in degrees

            heave:          sonar heave in meters

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    insert failures.

    ---------------------------------------------------------

    int mb_extract_altitude(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    double *transducer_depth,

                    double *altitude,

                    int *error);

    The function mb_extract_altitude extracts the sonar transducer
    depth (transducer_depth) below the sea surface
    and the the sonar transducer altitude above the seafloor
    according to the
    MBIO descriptor pointed to by mbio_ptr.
    This function is not defined for all data formats.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of record is stored in *store_ptr.
    These data are returned only if the data record is survey data.
    These values are useful for
    sidescan processing applications. Both transducer depths and
    altitudes are reported in meters.

    The return values are:

            kind:           kind of data record read (error

                                    if not survey data):

                                            1       survey data

            transducer_depth:       depth of sonar in meters

            altitude:               altitude of sonar above seafloor

                            in meters.

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data extraction failures.

    ---------------------------------------------------------

    int mb_insert_altitude(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    double transducer_depth,

                    double altitude,

                    int *error);

    The function mb_insert_altitude inserts
    sonar depth and altitude data into the
    structure pointed to by *store_ptr according to the
    MBIO descriptor pointed to by mbio_ptr.
    This function is not defined for all data formats.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System.
    Data will be inserted only if the data record is survey data (navigation,
    bathymetry, amplitude, and sidescan).
    The values to be inserted are:

            transducer_depth:       depth of sonar in meters

            altitude:               altitude of sonar in meters

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    insert failures.

    ---------------------------------------------------------

    int mb_extract_svp(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    int *nsvp,

                    double *depth,

                    double *velocity,

                    int *error);

    The function mb_extract_svp extracts a water sound
    velocity profile according to the
    MBIO descriptor pointed to by mbio_ptr.
    This function is not defined for all data formats.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System; the
    kind value indicates which type of record is stored in *store_ptr.
    These data are returned only if the data record is a sound
    velocity profile record. These values are useful for
    calculating bathymetry from travel times and beam angles.

    The return values are:

            kind:           kind of data record read (error

                                    if not SVP data):

                                            6       SVP data

            nsvp:           number of depth and sound speed

                                    data in the profile

            depth:          array of depths in meters

            velocity:               array of sound speeds in m/sec

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data extraction failures.

    ---------------------------------------------------------

    int mb_insert_svp(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int nsvp,

                    double *depth,

                    double *velocity,

                    int *error);

    The function mb_insert_svp inserts a water sound
    velocity profile according to the
    MBIO descriptor pointed to by mbio_ptr.
    This function is not defined for all data formats.
    The verbose value controls the standard
    error output verbosity of the function.
    The form of the data structure is determined by the
    sonar system associated with the format of the data being read. A number
    of different data record types are recognized by MB-System.
    These data are inserted only if the data record is a sound
    velocity profile record. These values are useful for
    calculating bathymetry from travel times and beam angles.
    The inserted values are:

            nsvp:           number of depth and sound speed

                                    data in the profile

            depth:          array of depths in meters

            velocity:               array of sound speeds in m/sec

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data insertion failures.

    ---------------------------------------------------------

    int mb_ttimes(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    int *nbeams,

                    double *ttimes,

                    double  *angles,

                    double *angles_forward,

                    double *angles_null,

                    double *heave,

                    double *alongtrack_offset,

                    double *draft,

                    double *ssv,

                    int *error);

    The function mb_ttimes extracts travel times and beam
    angles from a sonar-specific data structure pointed to by
    store_ptr. These values are used for calculating
    swath bathymetry. The verbose value controls
    the standard error output verbosity of the function.
    The coordinates of the beam angles can be a bit confusing.
    The angles are returned in "takeoff angle coordinates"
    appropriate for raytracing. The array angles contains the
    angle from vertical and the array angles_forward
    contains the angle from acrosstrack. This
    coordinate system is distinct from the roll-pitch coordinates
    appropriate for correcting roll and pitch values. A description
    of these relevent coordinate systems is given below.
    The angles_null array
    contains the effective sonar array orientation for each beam. The
    angles_null array may be used to correct
    beam angles using Snell's law if the ssv is changed.
    The angles_null values reflect the sonar configuration.
    For example, some multibeam sonars have a flat transducer array, and
    so the angles_null array consists of nbeams zero values.
    Other multibeams have circular arrays so that the angles_null
    values equal the angles values. The alongtrack_offset array
    accommodates sonars which report multiple pings in a single
    survey record; each ping occurs at a different position along the
    shiptrack, producing alongtrack offsets relative to the navigation
    for some beam values. The sum of the draft value
    and the heave array values gives the depth
    of the sonar for each beam. For hull mounted installations the
    draft value is generally static but the heave values
    vary with time. For towed sonars the draft varies with time
    and the heave values are typically zero. The ssv value
    gives the water sound velocity at the sonar array.

    The return values are:

            kind:           kind of data record read (error

                                    if not survey data):

                                            1       survey data

            nbeams:         number of beams

            ttimes:         array of two-way travel times in seconds

            angles:         array of angles from vertical in degrees

            angles_forward: array of angles from acrosstrack in degrees

            angles_null:    array of sonar array orientation in degrees

            heave:          array of heave values for each beam in meters

            alongtrack_offset:array of alongtrack distance offsets for

                                    each beam in meters

            draft:          draft of sonar in meters

            ssv:            water sound velocity at sonar in m/seconds

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data extraction failures.

    ---------------------------------------------------------

    int mb_detects(

                    int verbose,

                    void *mbio_ptr,

                    void *store_ptr,

                    int *kind,

                    int *nbeams,

                    int *detects,

                    int *error);

    The function mb_detects extracts beam bottom detect
    types from a sonar-specific data structure pointed to by
    store_ptr. These values indicate whether the depth
    value associated with a particular beam i derived from an
    amplitude detect (e.g. detects[i] = 1), a phase detect
    (e.g. detects[i] = 2), or the algorithm is unknown
    (e.g. detects[i] = 0). The verbose value controls
    the standard error output verbosity of the function.

    The return values are:

            kind:           kind of data record read (error

                                    if not survey data):

                                            1       survey data

            nbeams:         number of beams

            detects:                array of nbeams bottom detect algorithm flags

                                            0 = unknown

                                            1 = amplitude detect

                                            2 = phase detect

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data extraction failures. This functionality is available for
    only a subset of the supported sonars. If the corresponding low
    level routine is undefined, *error will be set to
    MB_ERROR_BAD_SYSTEM (14).

    ---------------------------------------------------------

    int mb_gains(

                    int verbose,

                    void *mbio_ptr,

                    void *store_ptr,

                    int *kind,

                    double *transmit_gain,

                    double *pulse_length,

                    double *receive_gain,

                    int *error);

    The function mb_gains extracts the most basic gain
    settings from a sonar-specific data structure pointed to by
    store_ptr. In many cases, sonars have more complicated
    gain functions, particularly with respect to the receiver
    TVG function. In those cases, the receive gain returned here
    refers to the constant gain setting and does not include any
    TVG parameters. The verbose value controls
    the standard error output verbosity of the function.

    The return values are:

            kind:           kind of data record read (error

                                    if not survey data):

                                            1       survey data

            transmit_gain:  transmit gain (dB)

            pulse_length:   transmit pulse length (sec)

            receive_gain:   receive gain (dB)

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data extraction failures.  This functionality is available for
    only a subset of the supported sonars. If the corresponding low
    level routine is undefined, *error will be set to
    MB_ERROR_BAD_SYSTEM (14).

    ---------------------------------------------------------

    int mb_extract_rawss(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int *kind,

                    int *nrawss,

                    double *rawss,

                    double *rawssacrosstrack,

                    double *rawssalongtrack,

                    int *error);

    This function has not yet been implemented for any data format.
    The notion is that since some formats carry both "raw" and
    "processed" sidescan imagery, there should be functions to
    extract and insert the "raw" sidescan. Given that the meaning of "raw"
    sidescan varies greatly among sonars, the processing one might apply to
    the data will depend on the sonar source. The definition of
    mb_extract_rawss may well change when we actually implement it.

    ---------------------------------------------------------

    int mb_insert_rawss(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    int nrawss,

                    double *rawss,

                    double *rawssacrosstrack,

                    double *rawssalongtrack,

                    int *error);

    This function has not yet been implemented for any data format.
    The notion is that since some formats carry both "raw" and
    "processed" sidescan imagery, there should be functions to
    extract and insert the "raw" sidescan. Given that the meaning of "raw"
    sidescan varies greatly among sonars, the processing one might apply to
    the data will depend on the sonar source. The definition of
    mb_insert_rawss may well change when we actually implement it.

    ---------------------------------------------------------

    int mb_copyrecord(

                    int verbose,

                    char *mbio_ptr,

                    char *store_ptr,

                    char *copy_ptr,

                    int *error);

    The function mb_copyrecord copies the sonar-specific
    data structure pointed to by
    store_ptr into the data structure pointed to by *copy_ptr.
    The data structures must already have been allocated.

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    data copy failures.

    LEVEL 3 FUNCTIONS

    int mb_buffer_init(

                    int verbose,

                    char **buff_ptr,

                    int *error);

    The function mb_buffer_init initializes the data structures
    required for buffered i/0. A pointer to the buffer data structure
    is returned as *buff_ptr.
    The verbose
    value controls the standard error output verbosity of the function.

    The return values are:

            *buff_ptr:      pointer to buffer structure

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer initialization failures.

    ---------------------------------------------------------

    int mb_buffer_close(

                    int verbose,

                    char **buff_ptr,

                    char *mbio_ptr,

                    int *error);

    The function mb_buffer_close releases all memory allocated
    for buffered i/0, including the structure pointed to by *buff_ptr.
    The verbose
    value controls the standard error output verbosity of the function.

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer deallocation failures.

    ---------------------------------------------------------

    int mb_buffer_load(

                    int verbose,

                    char *buff_ptr,char *mbio_ptr,

                    int nwant,

                    int *nload,

                    int *nbuff,

                    int *error);

    The function mb_buffer_load loads data into the buffer pointed
    to by buff_ptr from the input file initialized in the
    MBIO descriptor pointed to by mbio_ptr.
    The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            nwant:          The number of data records desired

                                    in the buffer.

    The returned values are:

            nload:          The number of data records loaded into the buffer.

            nbuff:          The total number of data records in the buffer after loading.

            error:          error value

    The buffer may already contain data records when the mb_buffer_load
    call is made; if the number of previously loaded records is less than
    nwant, the function will attempt to read and load records
    until a total of nwant records are loaded. The nload
    value is the number of data records loaded during the current
    function call, and the nbuff value is the number of data
    records in the buffer at the completion of the mb_buffer_load
    call.
    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer deallocation failures.

    ---------------------------------------------------------

    int mb_buffer_dump(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    char *ombio_ptr,

                    int nhold,

                    int *ndump,

                    int *nbuff,

                    int *error);

    The function mb_buffer_dump dumps data from the buffer pointed
    to by *buff_ptr into the output file initialized in the
    MBIO descriptor pointed to by ombio_ptr. The data in the
    buffer were read from the input file initialized in the MBIO
    descriptor pointed to by mbio_ptr.
    The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            nhold:          The number of data records desired to be held

                                    in the buffer.

    The returned values are:

            nload:          The number of data records dumped from the buffer.

            nbuff:          The total number of data records in the buffer after dumping.

            error:          error value

    If the number of loaded records is more than
    nhold, the function will attempt to write out records
    from the beginning of the buffer until nhold records
    are left in the buffer. The ndump
    value is the number of data records dumped during the current
    function call, and the nbuff value is the number of data
    records in the buffer at the completion of the mb_buffer_dump
    call.
    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer deallocation failures.

    ---------------------------------------------------------

    int mb_buffer_clear(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int nhold,

                    int *ndump,

                    int *nbuff,

                    int *error);

    The function mb_buffer_clear removes data from the buffer pointed
    to by *buff_ptr without writing those data records to an
    output file. An MBIO descriptor pointed to by mbio_ptr
    is still required, and generally represents the MBIO descriptor
    used to read and load the data originally.
    The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            nwant:          The number of data records desired to be held

                                    in the buffer.

    The returned values are:

            nload:          The number of data records cleared from the buffer.

            nbuff:          The total number of data records in the buffer after dumping.

            error:          error value

    If the number of loaded records is more than
    nhold, the function will attempt to clear out records
    from the beginning of the buffer until nhold records
    are left in the buffer. The ndump
    value is the number of data records cleared during the current
    function call, and the nbuff value is the number of data
    records in the buffer at the completion of the mb_buffer_dump
    call.
    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer deallocation failures.

    ---------------------------------------------------------

    int mb_buffer_info(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int id,

                    int *system,

                    int *kind,

                    int *error);

    The function mb_buffer_clear removes data from the buffer pointed
    to by *buff_ptr without writing those data records to an
    output file. An MBIO descriptor pointed to by mbio_ptr
    is still required, and generally represents the MBIO descriptor
    used to read and load the data originally.
    The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            nwant:          The number of data records desired to be held

                                    in the buffer.

    The returned values are:

            nload:          The number of data records cleared from the buffer.

            nbuff:          The total number of data records in the buffer after dumping.

            error:          error value

    If the number of loaded records is more than
    nhold, the function will attempt to clear out records
    from the beginning of the buffer until nhold records
    are left in the buffer. The ndump
    value is the number of data records cleared during the current
    function call, and the nbuff value is the number of data
    records in the buffer at the completion of the mb_buffer_dump
    call.
    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer deallocation failures.

    ---------------------------------------------------------

    int mb_buffer_get_next_data(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int start,

                    int *id,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    int *nbath,

                    int *namp,

                    int *nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    int *error);

    The function mb_buffer_get_next_data searches for the
    next survey data record in the buffer, beginning at buffer
    index start. Since buffer indexes begin at 0, the first
    call to mb_buffer_get_next_data should have start = 0.
    If a survey data record is found at or beyond start,
    mb_buffer_get_next_data returns the buffer index of that
    record in id. Data is also returned in the forms of bathymetry,
    amplitude, and sidescan survey data. No comments or other
    non-survey data records are returned.
    The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            start:          The buffer index at which to start

                            searching for a survey data record.

    The returned values are:

            id:             The buffer index of the first survey

                            data record at or after start.

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    failures. The most common error occurs when no more survey data
    records remain to be found in the buffer; in this case,
    error = -14.

    ---------------------------------------------------------

    int mb_buffer_extract(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int id,

                    int *kind,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    int *nbath,

                    int *namp,

                    int *nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_buffer_extract extracts and returns
    a subset of the data in a buffer record.
    The verbose
    value controls the standard error output verbosity of the function.
    The buffer record is specified with the
    buffer index id. The data is either
    in the form of bathymetry,
    amplitude, and sidescan survey data or a comment string.

    The input control parameters have the following significance:

            id:             The buffer index of the data

                            record to extract.

    The returned values are:

            kind:           kind of data record extracted

                                            1       survey data

                                            2       comment

                                            >=3     other data that cannot

                                                    be passed by mb_buffer_extract

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:                comment string

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    extract failures.

    ---------------------------------------------------------

    int mb_buffer_insert(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int id,

                    int time_i[7],

                    double time_d,

                    double navlon,

                    double navlat,

                    double speed,

                    double heading,

                    int nbath,

                    int namp,

                    int nss,

                    char *beamflag,

                    double *bath,

                    double *amp,

                    double *bathacrosstrack,

                    double *bathalongtrack,

                    double *ss,

                    double *ssacrosstrack,

                    double *ssalongtrack,

                    char *comment,

                    int *error);

    The function mb_buffer_insert inserts data into a
    buffer record, replacing a subset of the original values.
    The verbose
    value controls the standard error output verbosity of the function.
    The buffer record is specified with the
    buffer index id. The data is either
    in the form of bathymetry,
    amplitude, and sidescan survey data or a comment string.

    The input control parameters have the following significance:

            id:             The buffer index of the data

                            record to insert.

    The returned values are:

            kind:           kind of data record inserted

                                            1       survey data

                                            2       comment

                                            >=3     other data that cannot

                                                    be passed by mb_buffer_insert

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            nbath:          number of bathymetry values

            namp:           number of amplitude values

            nss:            number of sidescan values

            beamflag:               array of bathymetry flags

            bath:           array of bathymetry values in meters

            amp:            array of amplitude values in unknown units

            bathacrosstrack:        array of of acrosstrack distances

                            in meters corresponding to bathymetry

            bathalongtrack: array of of alongtrack distances

                            in meters corresponding to bathymetry

            ss:             array of sidescan values in unknown units

            ssacrosstrack:  array of of acrosstrack distances

                            in meters corresponding to sidescan

            ssacrosstrack:  array of of alongtrack distances

                            in meters corresponding to sidescan

            comment:                comment string

    The returned values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    insert failures.

    ---------------------------------------------------------

    int mb_buffer_get_next_nav(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int start,

                    int *id,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    double *draft,

                    double *roll,

                    double *pitch,

                    double *heave,

                    int *error);

    The function mb_buffer_get_next_nav searches for the
    next survey data record in the buffer, beginning at buffer
    index start. Since buffer indexes begin at 0, the first
    call to mb_buffer_get_next_nav should have start = 0.
    If a survey data record is found at or beyond start,
    mb_buffer_get_next_nav returns the buffer index of that
    record in id. Navigation and vertical reference sensor
    data is also returned. No comments or other
    non-survey data records are returned.
    The verbose
    value controls the standard error output verbosity of the function.

    The input control parameters have the following significance:

            start:          The buffer index at which to start

                            searching for a survey data record.

    The returned values are:

            id:             The buffer index of the first survey data record at or after start.

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            roll:           ship roll in degrees

            pitch:          ship pitch in degrees

            heave:          ship heave in meters

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    failures. The most common error occurs when no more survey data
    records remain to be found in the buffer; in this case,
    error = -14.

    ---------------------------------------------------------

    int mb_buffer_extract_nav(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int id,

                    int *kind,

                    int time_i[7],

                    double *time_d,

                    double *navlon,

                    double *navlat,

                    double *speed,

                    double *heading,

                    double *draft,

                    double *roll,

                    double *pitch,

                    double *heave,

                    int *error);

    The function mb_buffer_extract_nav extracts and returns
    a subset of the data in a buffer record.
    The verbose
    value controls the standard error output verbosity of the function.
    The buffer record is specified with the
    buffer index id. The data returned consists of navigation
    and vertical reference sensor data.

    The input control parameters have the following significance:

            id:             The buffer index of the data

                            record to extract.

    The returned values are:

            kind:           kind of data record extracted

                                            1       survey data

                                            2       comment

                                            >=3     other data that cannot

                                                    be passed by mb_buffer_extract_nav

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            roll:           ship roll in degrees

            pitch:          ship pitch in degrees

            heave:          ship heave in meters

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    extract failures.

    ---------------------------------------------------------

    int mb_buffer_insert_nav(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int id,

                    int time_i[7],

                    double time_d,

                    double navlon,

                    double navlat,

                    double speed,

                    double heading,

                    double draft,

                    double roll,

                    double pitch,

                    double heave,

                    int *error);

    The function mb_buffer_insert_nav inserts navigation
    and vertical reference sensor data into a
    buffer record, replacing a subset of the original values.
    The verbose
    value controls the standard error output verbosity of the function.
    The buffer record is specified with the
    buffer index id.

    The input control parameters have the following significance:

            id:             The buffer index of the data

                            record to insert.

    The returned values are:

            kind:           kind of data record inserted

                                            1       survey data

                                            2       comment

                                            >=3     other data that cannot

                                                    be passed by mb_buffer_insert_nav

            time_i:         time of current ping

                            time_i[0]: year

                            time_i[1]: month

                            time_i[2]: day

                            time_i[3]: hour

                            time_i[4]: minute

                            time_i[5]: second

                            time_i[6]: microsecond

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            navlon:         longitude

            navlat:         latitude

            speed:          ship speed in km/s

            heading:                ship heading in degrees

            roll:           ship roll in degrees

            pitch:          ship pitch in degrees

            heave:          ship heave in meters

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    insert failures.

    ---------------------------------------------------------

    int mb_buffer_get_ptr(

                    int verbose,

                    char *buff_ptr,

                    char *mbio_ptr,

                    int id,

                    char **store_ptr,

                    int *error);

    The function mb_buffer_get_ptr returns
    a pointer to the data structure in a buffer record.
    The verbose
    value controls the standard error output verbosity of the function.
    The buffer record is specified with the
    buffer index id. The data returned consists of a pointer
    to the data structure stored in the specified buffer record.

    The input control parameters have the following significance:

            id:             The buffer index of the data

                                    record to locate.

    The return values are:

            *store_ptr:     pointer to data in specified

                                    buffer record

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about
    buffer failures.

    MISCELLANEOUS FUNCTIONS

    int mb_defaults(

                    int verbose,

                    int *format,

                    int *pings,

                    int *lonflip,

                    double bounds[4],

                    int *btime_i,

                    int *etime_i,

                    double *speedmin,

                    double *timegap);

    The function mb_defaults provides default values of control
    parameters used by some of the MBIO functions. The verbose
    value controls the standard error output verbosity of the function.
    The other parameters
    are set by the function; the meaning of these parameters is discussed
    in the listings of the functions
    mb_read_init and mb_write_init.
    If an .mbio_defaults file exists in the user's home directory,
    the lonflip and timegap defaults are read from this file.
    Otherwise, the values are set as:

            *lonflip = 0

            *timegap = 1

    The other values are simply set as:

            *format = 0

            *pings = 1

            bounds[0] = -360.

            bounds[1] = 360.

            bounds[2] = -90.

            bounds[3] = 90.

            btime_i[0] = 1962;

            btime_i[1] = 2;

            btime_i[2] = 21;

            btime_i[3] = 10;

            btime_i[4] = 30;

            btime_i[5] = 0;

            btime_i[6] = 0;

            etime_i[0] = 2062;

            etime_i[1] = 2;

            etime_i[2] = 21;

            etime_i[3] = 10;

            etime_i[4] = 30;

            etime_i[5] = 0;

            etime_i[6] = 0;

            *speedmin = 0.0

    A status value is returned to
    indicate success or failure.

    ---------------------------------------------------------

    int mb_env(

                    int verbose,

                    char *psdisplay,

                    char *imgdisplay,

                    char *mbproject);

    The function mb_env provides default values of Postscript
    and image display programs invoked by some MB-System
    programs and macros, and a default value for a working project
    name that will be used by future applications. The verbose
    value controls the standard error output verbosity of the function.
    If an .mbio_defaults file exists in the user's home directory,
    the *psdisplay, *imgdisplay, *mbproject
    defaults are read from this file.
    Otherwise, the values are set as:

            psdisplay =  "xpsview" (IRIX OS)

                               "pageview" (Solaris OS)

                               "gv" (other OS)

                               "ghostview" (other OS)

            imgdisplay = "gimp" (Linux OS)

                               "xv" (other than Linux OS)

            mbproject =  "none"

    ---------------------------------------------------------

    int mb_format(

                    int verbose,

                    int *format,

                    int *error);

    Given the format identifier format, mb_format checks if the
    format is valid.  If the format id corresponds to a value used in
    previous (<4.00) versions of MB-System, then the format value
    will be aliased to the current corresponding value.

    The return values are:

            format:         MBIO format id

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_register(

                    int verbose,

                    int *format,

                    char *mbio_ptr,

                    int *error);

    The function mb_format_register is called by mb_read_init
    and mb_write_init and serves to load format specific
    parameters and function parameters into the MBIO
    control structure pointed to by *error. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values.

    The input values are:

            *format:                MBIO format id

            *mbio_ptr:      pointer to data in specified

                                    buffer record

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_info(

                    int verbose,

                    int *format,

                    int *system,

                    int *beams_bath_max,

                    int *beams_amp_max,

                    int *pixels_ss_max,

                    char *format_name,

                    char *system_name,

                    char *format_description,

                    int *numfile,

                    int *filetype,

                    int *variable_beams,

                    int *traveltime,

                    int *beam_flagging,

                    int *nav_source,

                    int *heading_source,

                    int *vru_source,

                    double *beamwidth_xtrack,

                    double *beamwidth_ltrack,

                    int *error);

    The function mb_format_info returns a variety of
    data format specific parameters. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values.

    The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *system:                MBIO sonar system id

            *beams_bath_max:        maximum number of bathymetry beams

            *beams_amp_max: maximum number of amplitude beams

            *pixels_ss_max: maximum number of sidescan pixels

            *format_name:   MBIO format name

            *system_name:   MBIO sonar system name

            *format_description:    MBIO format description

            *numfile:               number of parallel data files used in format

            *filetype:      type of data files

            *variable_beams:        number of beams can vary [boolean]

            *traveltime:    travel time data available [boolean]

            *beam_flagging: beam flagging supported [boolean]

            *nav_source:    kind of data records containing navigation

            *heading_source:        kind of data records containing

                                    heading

            *vru_source:    kind of data records containing

                                    attitude

            *beamwidth_xtrack:      typical athwartships beam

                                            width [degrees]

            *beamwidth_ltrack:      typical alongtrack beam

                                            width [degrees]

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_system(

                    int verbose,

                    int *format,

                    int *system,

                    int *error);

    The function mb_format_system returns
    the MBIO sonar system id. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now oattintbsolete format id values are mapped
    to current values. The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *system:                MBIO sonar system id

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_description(

                    int verbose,

                    int *format,

                    char *description,

                    int *error);

    The function mb_format_description returns
    a short description of the format in the string
    *description. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values. The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *format_description:    MBIO format description

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_dimensions(

                    int verbose,

                    int *format,

                    int *beams_bath_max,

                    int *beams_amp_max,

                    int *pixels_ss_max,

                    int *error);

    The function mb_format_dimensions returns
    the maximum numbers of beams and pixels associated
    with a particular data format. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values. The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *beams_bath_max:        maximum number of bathymetry beams

            *beams_amp_max: maximum number of amplitude beams

            *pixels_ss_max: maximum number of sidescan pixels

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_flags(

                    int verbose,

                    int *format,

                    int *variable_beams,

                    int *traveltime,

                    int *beam_flagging,

                    int *error);

    The function mb_format_flags returns
    flags indicating certain characteristics of the
    specified data format. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values. The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *variable_beams:        number of beams can vary [boolean]

            *traveltime:    travel time data available [boolean]

            *beam_flagging: beam flagging supported [boolean]

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_source(

                    int verbose,

                    int *format,

                    int *nav_source,

                    int *heading_source,

                    int *vru_source,

                    int *error);

    The function mb_format_source returns
    flags indicating what kinds of data records contain
    navigation, heading, and attitude values in the
    specified data format. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values. The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *nav_source:    kind of data records containing

                                    navigation

            *heading_source:        kind of data records containing

                                    heading

            *vru_source:    kind of data records containing

                                    attitude

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_format_beamwidth(

                    int verbose,

                    int *format,

                    double *beamwidth_xtrack,

                    double *beamwidth_ltrack,

                    int *error);

    The function mb_format_beamwidth returns
    typical, upper bound values for athwartships and alongtrack
    beam widths. The format id
    *format is first checked for validity. In some cases,
    formerly valid but now obsolete format id values are mapped
    to current values. The input values are:

            *format:                MBIO format id

    The return values are:

            *format:                MBIO format id

            *beamwidth_xtrack:      typical athwartships beam

                                            width [degrees]

            *beamwidth_ltrack:      typical alongtrack beam

                                            width [degrees]

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_datalist_open(

                    int verbose,

                    char **datalist,

                    char *path,

                    int look_processed,

                    int *error);

    The function mb_datalist_open initializes reading
    from a datalist tree. The string *path is the
    path to the top level datalist file to be opened.
    The value look_processed indicates whether the datalist
    parsing should look for or ignore processed data files
    (see the mbprocess and mbdatalist manual pages).
    The input values are:

            *path:          datalist file to be opened

            look_processed: processed file behavior

                                            0 : unset

                                            1 : ignore processed files

                                            2 : return processed files

    The return values are:

            **datalist:     pointer to datalist

                                    structure

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_datalist_read(

                    int verbose,

                    char *datalist,

                    char *path,

                    int *format,

                    double *weight,

                    int *error);

    The function mb_datalist_read reads
    from a datalist tree, attempting to return the path
    to the next valid swath data file, the corresponding data
    format id, and a gridding weight
    (see the mbprocess and mbdatalist manual pages).
    Information about the
    datalist tree is embedded in a data structure pointed to
    by *datalist. The input values are:

            *datalist:      pointer to datalist

                                    structure

    The return values are:

            *path:          swath data file

            *format:                MBIO format id

            *weight:                mbgrid gridding weight

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_datalist_close(

                    int verbose,

                    char **datalist,

                    int *error);

    The function mb_datalist_close closes an
    open datalist tree, and deallocates the data structure pointed to
    by *datalist. The input values are:

            *datalist:      pointer to datalist

                                    structure

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_alloc(

                    int verbose,

                    char *mbio_ptr,

                    char **store_ptr,

                    int *error);

    The function mb_alloc allocates a data structure
    for internal storage of swath sonar data
    and returns a pointer to this structure in *store_ptr.
    The data structure is specific to the data format identified
    in the MBIO data structure pointed to by *mbio_ptr.
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

    The return values are:

            **store_ptr:    pointer to storage data

                                    structure

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_deall(

                    int verbose,

                    char *mbio_ptr,

                    char **store_ptr,

                    int *error);

    The function mb_deall deallocates a format specific
    swath sonar data structure pointed to by *store_ptr.
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            *store_ptr:     pointer to storage data

                                    structure

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_error(

                    int error,

                    int error,

                    char **message);

    Given the error value error, mb_format_inf returns a
    short error message in the string **message. The verbose
    value controls the standard error output verbosity of the function.  The return
    status value signals success if format is valid and failure otherwise.

    ---------------------------------------------------------

    int mb_navint_add(

                    int verbose,

                    char *mbio_ptr,

                    double time_d,

                    double lon,

                    double lat,

                    int *error);

    The function mb_navint_add adds a navigation fix
    to a circular buffer of navigation values maintained in
    the MBIO data structure pointed to by *mbio_ptr.
    This buffer is used to interpolate navigation for data
    formats where the navigation is asynchronous (where navigation
    and survey pings come in different data records).
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            time_d:         time of navigation fix in seconds

                            since 1/1/70 00:00:00

            lon:            longitude (degrees)

            lat:            latitude (degrees)

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_navint_interp(

                    int verbose,

                    char *mbio_ptr,

                    double time_d,

                    double heading,

                    double rawspeed,

                    double *lon,

                    double *lat,

                    double *speed,

                    int *error);

    The function mb_navint_interp interpolates navigation to
    the time time_d using
    a circular buffer of navigation values maintained in
    the MBIO data structure pointed to by *mbio_ptr.
    This buffer is used to interpolate navigation for data
    formats where the navigation is asynchronous (where navigation
    and survey pings come in different data records).
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

            heading:                heading in degrees

            rawspeed:               speed in km/hr

                                    (zero if not known)

    The return values are:

            *lon:           longitude (degrees)

            *lat:           latitude (degrees)

            *speed:         speed made good in km/hr

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_attint_add(

                    int verbose,

                    char *mbio_ptr,

                    double time_d,

                    double heave,

                    double roll,

                    double pitch,

                    int *error);

    The function mb_attint_add adds an attitude
    (heave, roll, pitch) data point
    to a circular buffer of attitude values maintained in
    the MBIO data structure pointed to by *mbio_ptr.
    This buffer is used to interpolate attitude for data
    formats where the attitude is asynchronous (where attitude
    and survey pings come in different data records).
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            time_d:         time of attitude in seconds

                            since 1/1/70 00:00:00

            heave:          heave (meters, up +)

            roll:           roll (degrees, starboard up +)

            pitch:          pitch (degrees, forward up +)

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_attint_interp(

                    int verbose,

                    char *mbio_ptr,

                    double time_d,

                    double *heave,

                    double *roll,

                    double *pitch,

                    int *error);

    The function mb_attint_interp interpolates attitude
    (heave, roll, pitch) data to
    the time time_d using
    a circular buffer of attitude values maintained in
    the MBIO data structure pointed to by *mbio_ptr.
    This buffer is used to interpolate attitude for data
    formats where the attitude is asynchronous (where attitude
    and survey pings come in different data records).
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

    The return values are:

            *heave:         heave (meters, up +)

            *roll:          roll (degrees, starboard up +)

            *pitch:         pitch (degrees, forward up +)

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_hedint_add(

                    int verbose,

                    char *mbio_ptr,

                    double time_d,

                    double heading,

                    int *error);

    The function mb_hedint_add adds a heading point
    to a circular buffer of heading values maintained in
    the MBIO data structure pointed to by *mbio_ptr.
    This buffer is used to interpolate heading for data
    formats where the heading is asynchronous (where heading
    and survey pings come in different data records).
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            time_d:         time of heading value in seconds

                            since 1/1/70 00:00:00

            heading:                heading (degrees)

    The return values are:

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_hedint_interp(

                    int verbose,

                    char *mbio_ptr,

                    double time_d,

                    double *heading,

                    int *error);

    The function mb_hedint_interp interpolates heading to
    the time time_d using
    a circular buffer of heading values maintained in
    the MBIO data structure pointed to by *mbio_ptr.
    This buffer is used to interpolate heading for data
    formats where the heading is asynchronous (where heading
    and survey pings come in different data records).
    The input values are:

            *mbio_ptr:      pointer to MBIO structure

            time_d:         time of current ping in seconds

                            since 1/1/70 00:00:00

    The return values are:

            *heading:               heading in degrees

            error:          error value

    A status value indicating success or failure is returned; the error value
    argument error passes more detailed information about failures.

    ---------------------------------------------------------

    int mb_get_double(

                    double *value,

                    char *str,

                    int nchar);

    The function mb_get_double parses the
    first nchar characters of the string
    *str for a floating point value, storing
    this value as a double in *value.

    ---------------------------------------------------------

    int mb_get_int(

                    int *value,

                    char *str,

                    int nchar);

    The function mb_get_int parses the
    first nchar characters of the string
    *str for an integer value, storing
    this value as a int in *value.

    ---------------------------------------------------------

    int mb_get_binary_short(

                    int swapped,

                    void *buffer,

                    short *value);

    The function mb_get_binary_short extracts
    a short int value from the first two bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of *value is swapped.

    ---------------------------------------------------------

    int mb_get_binary_int(

                    int swapped,

                    void *buffer,

                    int *value);

    The function mb_get_binary_int extracts
    an int value from the first four bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of *value is swapped.

    ---------------------------------------------------------

    int mb_get_binary_float(

                    int swapped,

                    void *buffer,

                    float *value);

    The function mb_get_binary_float extracts
    a float value from the first four bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of *value is swapped.

    ---------------------------------------------------------

    int mb_get_binary_double(

                    int swapped,

                    void *buffer,

                    double *value);

    The function mb_get_binary_double extracts
    a double value from the first eight bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of *value is swapped.

    ---------------------------------------------------------

    int mb_put_binary_short(

                    int swapped,

                    short value,

                    void *buffer);

    The function mb_put_binary_short inserts
    a short int value into the first two bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of value is swapped.

    ---------------------------------------------------------

    int mb_put_binary_int(

                    int swapped,

                    int value,

                    void *buffer);

    The function mb_put_binary_int inserts
    an int value into the first four bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of value is swapped.

    ---------------------------------------------------------

    int mb_put_binary_float(

                    int swapped,

                    float value,

                    void *buffer);

    The function mb_put_binary_float inserts
    a float value into the first four bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of value is swapped.

    ---------------------------------------------------------

    int mb_put_binary_double(

                    int swapped,

                    double value,

                    void *buffer);

    The function mb_put_binary_double inserts
    a double value into the first eight bytes pointed to
    by *buffer. If the boolean swapped is true,
    the byte order of value is swapped.

    ---------------------------------------------------------

    int mb_get_bounds(

                    char *text,

                    double *bounds);

    The function mb_get_bounds parses the string
    *text and extracts geographic bounds of a
    rectangular region in the form:

                    bounds[0]: minimum longitude

                    bounds[1]: maximum longitude

                    bounds[2]: minimum latitude

                    bounds[3]: maximum latitude

    where *text is in the standard GMT bounds form.
    The longitude and latitude values in *text
    should separated by a '/' character, and individual
    values may be represented in decimal degrees or in
    "dd:mm:ss" form (dd=degrees, mm=minutes, ss=seconds).

    double mb_ddmmss_to_degree(

                    char *text);

    The function mb_ddmmss_to_degree parses the string
    *text and extracts a decimal longitude or latitude
    value from a "dd:mm:ss" (dd=degrees, mm=minutes, ss=seconds)
    value.

    ---------------------------------------------------------

    int mb_takeoff_to_rollpitch(

                    int verbose,

                    double theta,

                    double phi,

                    double *alpha,

                    double *beta,

                    int *error);

    The function mb_takeoff_to_rollpitch
    translates angles from the "takeoff" coordinate
    reference frame to the "rollpitch" coordinate system.
    See the discussion of coordinate systems below.

    ---------------------------------------------------------

    int mb_rollpitch_to_takeoff(

                    int verbose,

                    double alpha,

                    double beta,

                    double *theta,

                    double *phi,

                    int *error);

    The function mb_rollpitch_to_takeoff
    translates angles from the "rollpitch" coordinate
    reference frame to the "takeoff" coordinate system.
    See the discussion of coordinate systems below.

    ---------------------------------------------------------

    int mb_double_compare(double *a,

                    double *b);

    The function mb_double_compare
    is used with the qsort function.
    This function returns 1 if a > b and -1 if a <= b.

    ---------------------------------------------------------

    int mb_int_compare(

                    int *a,

                    int *b);

    The function mb_int_compare
    is used with the qsort function.
    This function returns 1 if a > b and -1 if a <= b.

    COORDINATE SYSTEMS USED IN MB-SYSTEM

    I. Introduction

    The coordinate systems described below are used
    within MB-System for calculations involving
    the location in space of depth, amplitude, or
    sidescan data. In all cases the origin of the
    coordinate system is at the center of the sonar
    transducers.

    II. Cartesian Coordinates

    The cartesian coordinate system used in MB-System
    is a bit odd because it is left-handed, as opposed
    to the right-handed x-y-z space conventionally
    used in most circumstances. With respect to the
    sonar (or the ship on which the sonar is mounted),
    the x-axis is athwartships with positive to starboard
    (to the right if facing forward), the y-axis is
    fore-aft with positive forward, and the z-axis is
    positive down.

    III. Spherical Coordinates

    There are two non-traditional spherical coordinate
    systems used in MB-System. The first, referred to here
    as takeoff angle coordinates, is useful for raytracing.
    The second, referred to here as roll-pitch
    coordinates, is useful for taking account of
    corrections to roll and pitch angles.

    III.1. Takeoff Angle Coordinates

    The three parameters are r, theta, and phi, where
    r is the distance from the origin, theta is the
    angle from vertical down (that is, from the
    positive z-axis), and phi is the angle from
    acrosstrack (the positive x-axis) in the x-y plane.
    Note that theta is always positive; the direction
    in the x-y plane is given by phi.
    Raytracing is simple in these coordinates because
    the ray takeoff angle is just theta. However,
    applying roll or pitch corrections is complicated because
    roll and pitch have components in both theta and phi.

            0 <= theta <= PI/2

            -PI/2 <= phi <= 3*PI/2

            x = rSIN(theta)COS(phi)

            y = rSIN(theta)SIN(phi)

            z = rCOS(theta)

            theta = 0    ---> vertical, along positive z-axis

            theta = PI/2 ---> horizontal, in x-y plane

            phi = -PI/2  ---> aft, in y-z plane with y negative

            phi = 0      ---> port, in x-z plane with x positive

            phi = PI/2   ---> forward, in y-z plane with y positive

            phi = PI     ---> starboard, in x-z plane with x negative

            phi = 3*PI/2 ---> aft, in y-z plane with y negative

    III.2. Roll-Pitch Coordinates

    The three parameters are r, alpha, and beta, where
    r is the distance from the origin, alpha is the angle
    forward (effectively pitch angle), and beta is the
    angle from horizontal in the x-z plane (effectively
    roll angle). Applying a roll or pitch correction is
    simple in these coordinates because pitch is just alpha
    and roll is just beta. However, raytracing is complicated
    because deflection from vertical has components in both
    alpha and beta.

            -PI/2 <= alpha <= PI/2

            0 <= beta <= PI

            x = rCOS(alpha)COS(beta)

            y = rSIN(alpha)

            z = rCOS(alpha)SIN(beta)

            alpha = -PI/2 ---> horizontal, in x-y plane with y negative

            alpha = 0     ---> ship level, zero pitch, in x-z plane

            alpha = PI/2  ---> horizontal, in x-y plane with y positive

            beta = 0      ---> starboard, along positive x-axis

            beta = PI/2   ---> in y-z plane rotated by alpha

            beta = PI     ---> port, along negative x-axis

    IV. SeaBeam Coordinates

    The per-beam parameters in the SB2100 data format include
    angle-from-vertical and angle-forward. Angle-from-vertical
    is the same as theta except that it is signed based on
    the acrosstrack direction (positive to starboard, negative
    to port). The angle-forward values are also defined
    slightly differently from phi, in that angle-forward is
    signed differently on the port and starboard sides. The
    SeaBeam 2100 External Interface Specifications document
    includes both discussion and figures illustrating the
    angle-forward value. To summarize:

        Port:

            theta = absolute value of angle-from-vertical

            -PI/2 <= phi <= PI/2

            is equivalent to

            -PI/2 <= angle-forward <= PI/2

            phi = -PI/2 ---> angle-forward = -PI/2 (aft)

            phi = 0     ---> angle-forward = 0     (starboard)

            phi = PI/2  ---> angle-forward = PI/2  (forward)

        Starboard:

            theta = angle-from-vertical

            PI/2 <= phi <= 3*PI/2

            is equivalent to

            -PI/2 <= angle-forward <= PI/2

            phi = PI/2   ---> angle-forward = -PI/2 (forward)

            phi = PI     ---> angle-forward = 0     (port)

            phi = 3*PI/2 ---> angle-forward = PI/2  (aft)

    V. Usage of Coordinate Systems in MB-System

    Some sonar data formats provide angle values along with
    travel times. The angles are converted to takoff-angle
    coordinates regardless of the  storage form of the
    particular data format. Currently, most data formats
    do not contain an alongtrack component to the position
    values; in these cases the conversion is trivial since
    phi = beta = 0 and theta = alpha. The angle and travel time
    values can be accessed using the MBIO function mb_ttimes.
    All angle values passed by MB-System functions are in
    degrees rather than radians.

    The programs mbbath and mbvelocitytool use angles in
    take-off angle coordinates to do the raytracing. If roll
    and/or pitch corrections are to be made, the angles are
    converted to roll-pitch coordinates, corrected, and then
    converted back prior to raytracing.

    BEAM FLAGS USED IN MB-SYSTEM

    MB-System uses arrays of 1-byte "beamflag" values to indicate
    beam data quality. Each beamflag value is actually an eight bit mask
    allowing fairly complicated information to be stored regarding
    each bathymetry value. In particular, beams may be flagged as
    bad, they may be selected as being of special interest, and
    one or more reasons for flagging or selection may be indicated.
    This scheme is very similar to the convention used in the HMPS
    hydrographic data processing package and the SAIC Hydrobat
    package. The beam selection mechanism is not currently used by
    any MB-System programs.

    The flag and select bits:

      xxxxxx00 => This beam is neither flagged nor selected.

      xxxxxx01 => This beam is flagged as bad and should be ignored.

      xxxxxx10 => This beam has been selected.

    Flagging modes:

      00000001 => Flagged because no detection was made by the sonar.

      xxxxx101 => Flagged by manual editing.

      xxxx1x01 => Flagged by automatic filter.

      xxx1xx01 => Flagged because uncertainty exceeds 1 X IHO standard.

      xx1xxx01 => Flagged because uncertainty exceeds 2 X IHO standard.

      x1xxxx01 => Flagged because footprint is too large

      1xxxxx01 => Flagged by sonar as unreliable.

    Selection modes:

      00000010 => Selected, no reason specified.

      xxxxx110 => Selected as least depth.

      xxxx1x10 => Selected as average depth.

      xxx1xx10 => Selected as maximum depth.

      xx1xxx10 => Selected as location of sidescan contact.

      x1xxxx10 => Selected, spare.

      1xxxxx10 => Selected, spare.

    SEE ALSO

    mbsystem(l), mbformat(l)

    BUGS

    What could go wrong in a mere 204,289 lines of code?

    Let us know...

     Index

    NAME
    VERSION
    DESCRIPTION
    AUTHORSHIP
    DATA TERMINOLOGY
    VERSION 5 CHANGES
    OVERVIEW
    SUPPORTED SWATH SONAR SYSTEMS
    SUPPORTED FORMATS
    FUNCTION STATUS AND ERROR CODES
    FUNCTION VERBOSITY
    INITIALIZATION AND CLOSING FUNCTIONS
    LEVEL 1 FUNCTIONS
    LEVEL 2 FUNCTIONS
    LEVEL 3 FUNCTIONS
    MISCELLANEOUS FUNCTIONS
    COORDINATE SYSTEMS USED IN MB-SYSTEM
    BEAM FLAGS USED IN MB-SYSTEM
    SEE ALSO
    BUGS

Last Updated: 3 June 2013

Return to list of MB-System manual pages...

Back to MB-System Home Page...