mbio
Section: MB-System 5.0 (l)
Updated: 21 August 2003
Index
NAME
mbio - Format independent input/output library for swath mapping sonar data.VERSION
Version 5.0DESCRIPTION
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 ObservatoryDATA 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: 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: 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: 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.
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 se