MB-System: Mapping the Seafloor

Integrating Third-Party Bathymetry Editors With MB-System
David W. Caress (1) and Dale N. Chayes (2)
1. Monterey Bay Aquarium Research Institute
2. Lamont-Doherty Earth Observatory
of Columbia University

Version 4

Originated September 3, 2004
Modified December 31, 2009
Modified May 16, 2012
Modified July 23, 2014



Purpose

MB-System [Caress and Chayes, 1996] is an open source software package for the processing and display of swath mapping sonar data. One of the most common and important swath data processing tasks is bathymetry editing. This document addresses the issue of integrating a third-party bathymetry editor with the MB-System processing environment. Since some editors, most likely commercial, may have proprietary source licensing that is inconsistent with the GNU Public License (GPL) applied to MB-System, the suggestions presented here do not involve direct use of GPL licensed MB-System source code. For the most part, this can be accomplished using executable programs that are part of the MB-System distribution, and therefore freely available to be installed by users independent of proprietary packages. However, we also include some code derived from the MB-System distribution that we will separately release under the Lessor GNU Public License (LGPL), allowing those particular functions to be linked with proprietary software without imposing "open sourceness" on the proprietary package.

Note that while this suggested scheme allows proprietary software vendors to serve users that independently install and use MB-System, the GPL requirement that code touching GPL'd open source becomes GPL'd open source still requires that a proprietary package that includes MB-System in a distribution becomes subject to the GPL in its entirety. Thus, we envision that proprietary software developers are most likely to build and distribute editors that integrate with the MB-System environment without redistributing MB-System with their package.

We first present an abbreviated overview of the MB-System processing environment, with an emphasis on the ancillary files that form much of the underlying structure. We then present the use of some of these ancillary files by the MB-System bathymetry editor MBedit in detail; this is the behavior which much be mimiced by a third-party editor. Finally, we give suggestions on how to structure such an editor to integrate it into the MB-System environment. Several appendices are included presenting relevant data formats and LGPL-released code./p>


History of this Document

This document, and the edit save file scheme it documents, originated in 2004 with the early 5.0 releases, and remained unchanged from 2004 through release 5.1.1beta11.

Both the scheme, and this document, were augmented in December 2009 with release 5.1.1beta12 in order to handle data from multiple head sonars that produce more than one ping with identical timestamps.

The fbt file format (corresponding to format mbf_ldeoih, or format 71) was changed for release 5.3.1906 (September 2011) by subtracting the sonar depth from the stored bathymetry values. This allowed depth resolution to 0.001 m in data from submerged platforms in the deep ocean.

The fbt file format was changed again for release 5.3.1955 (May 2012) by improving the resolution of the navigation stored in fbt files to 1e-9 degrees longitude and latitude, equivalent to about 0.0001 m. Similar changes were made to the navigation stored in or reported by fnv and inf files (as produced by mblist and mbinfo, respectively).



Overview of the MB-System Processing Environment

The MB-System processing environment is documented in the distribution MB-System web pages (Caress and Chayes, 2004) and in the MB-System Cookbook (Schmidt et al., 2004). Some of the more critical aspects of the MB-System approach are briefly presented in this section; see the regular documentation for comprehensive discussions of the processing methods and the underlying structure.

The distinguishing characteristics of the MB-System approach include:
MB-System processing is format independent in the sense that all of the processing tools are applied in the same fashion, regardless of format. MB-System supports a large number of swath data formats, most of which are appropriate for processing. The output, or "processed" data files are written is the same format as the input, or "raw" data.

In the few cases where the initial data format is not entirely suitable for processing because it lacks space for required information, the data must first be translated to a related processing format using the program mbcopy. This translation must occur prior to the start of processing. For example, the Simrad multibeam vendor format (56) has no place to store bathymetry beam flags, and therefore cannot be used in conjunction with a bathymetry editor such as MBedit. In order to process Simrad multibeam data with MB-System, users must first use mbcopy to translate the data to format 57, a format that is the same as 56 except that it includes some extended data record types allowing storage of processing parameters such as beam flags.

MB-System processing is "parallel" in the sense that the order in which processing tools are applied does not matter. One can choose to edit navigation first, last, or not at all. One can edit bathymetry as many times as desired, and work on other aspects of the data in between editing sessions. This works because each input, or "raw" data file has an associated parameter file containing settings for all MB-System processing parameters. The parameter files are named by simply adding a ".par" suffix to the "raw" filename. Each tool changes settings in the parameter files, and, in many cases, generates an ancilliary data file containing data to be used in correcting or reprocessing the swath data. Examples include navigation to be merged (*.nve files generated by MBnavedit), sound velocity profile files (*.svp files generated by MBsvplist and MBvelocitytool), and bathymetry edit files (*.esf files generated by MBedit, MBclean, and MBareaclean). When MBprocess is invoked for a particular swath file, the parameter file is parsed, and then all of the specified processing actions are performed, and a processed swath file is output.

The datalist, or list of data files, is an important construct in the MB-System processing scheme because it allows tools to operate on many data files simultaneously. Datalists can also be recursive (entries can point to other datalists), allowing one to manage all the files in a single survey, many surveys, and even very large databases using multiple datalists. Often swath data will be stored in a directory tree structure, with datalists located in each directory to reference lower levels in the structure. One benefit to using datalists is that a single call to MBprocess with a datalist as input will cause all swath files referenced (directly or recursively) through that datalist to be reprocessed. Moreover, the default behavior is for MBprocess to only reprocess files that are out of date because the parameter file or one of the ancilliary data files has been modified since the processed file was last generated.



How MBedit Works

In order to integrate a third-party bathymetry editor into MB-System, one essentially has to duplicate the function of the interactive editor supplied with the package, MBedit. What follows is a full description of the input and output behavior of MBedit during an editing session, and the use of the resulting edit save file by the processing program MBprocess.

1) MBedit determines which data file to read

When an MBedit user specifies a swath data file to open, MBedit first checks that the file exists. The program then checks to see if an ancillary file containing only bathymetry also exists; this is the fbt file, which is named by appending ".fbt" onto the original swath file name (if the swath file is named "exampledata.mb57", then the fbt file with be named "exampledata.mb57.fbt").  MBedit will open and read the fbt file if it exists; otherwise MBedit will open and read the original swath data file.

The fbt files are created by MBdatalist to improve performance of applications that need to access simple swath bathymetry data and do not make use of other information. Indeed, "fbt" stands for "fast bathymetry". The fbt files are generated in the MBLDEOIH format (format id 71), which is one of the simpler swath data formats supported by MB-System (see Appendix 1 for the data format specification).

Whether the data are read from directly from a swath file or from the shorter and simpler fbt file, the information that is stored internally includes the following:
The entire file is read, and all of the bathymetry records, with the information given above, are stored in memory.

The beam flags, one of which exists for each sounding, indicate the status of the soundings and control whether the soundings are used for listing, plotting, or gridding applications by various MB-System tools. A beam flag will indicate if a sounding is "good" (to be used), "bad" (to be ignored), or "null" (nonexistant). In the case that a sounding is flagged as "bad", the beam flag can also indicate if that flag was applied by the sonar originally or applied during post processing by an interactive tool or by an automated, non-interactive program. See Appendix 2 for the format specification of beam flags. MBedit keeps two sets of beam flags in memory, the original beam flags loaded from the swath file (or the fbt file), and a second, active set that can be modified. Regardless of what happens during an editing session, comparison of an active beam flag with the corresponding original beam flag value will always indicate if a sounding's status is changed relative to the original swath file.

2) MBedit reads existing edit events from an edit save file (if available and requested)

Next, MBedit checks to see if an "edit save file" or esf file exists for the specified swath file. Like the fbt files, esf files are located in the same directory as the swath file, and are named by appending a simple suffix (".esf") to the original file name (e.g. "exampledata.mb57.esf"). The edit save files contain a record of the beam edit events that have been generated previously for the swath bathymetry, in the order that those edits occurred. The individual edit events contain the following information:

The multiplicity value relates to sonars with multiple heads that produce multiple pings with identical timestamps. The first ping has a multiplicity of 0, the second 1, and so on. Most mapping sonars produce a single ping at a time.

The edit action will be one of the following:

See Appendix 3 for the details of the esf file format. Note that edit events have a different format and definition than beam flags. Edit events are not beam flags, but are used to modify beam flags. It is possible for a particular beam of a particular ping to be referenced by multiple edit events in an esf file. For example, an MBedit user might choose to flag a sounding as bad, and later choose to unflag it, returning the sounding's beam flag to its original state, but in the process generating two edit events.

If an esf file exists, MBedit opens a dialog allowing the user to indicate whether the existing edit events are to be read and applied to the data before the editing session begins. If so, as is usually the case, MBedit first copies the existing esf file to two secondary storage files. The first storage file is named by appending ".tmp" to the esf file name (e.g. "exampledata.mb57.esf.tmp"). This allows recovery of the pre-existing edit events in the event that MBedit crashes or is killed during a session. The second storage file is named by appending ".stream" to the esf file name (e.g. "exampledata.mb57.esf.stream"). This stream file will be appended with each of the edit events generated by MBedit as an editing session proceeds. In contrast to the first storage file that saves the edits from previous sessions, the second storage file provides a means to recover the edits generated during a session in the event that MBedit crashes or is killed.  Finally, MBedit reads all of the edit events into memory, and opens a new, empty esf file (again with the name "exampledata.mb57.esf").

3) MBedit applies the edit events from the esf file to the swath bathymetry in memory

Once the edit events have been read, MBedit determines if any preprocessing is required. Normally the edit events will already be in the order of the pings and soundings in the bathymetry, and there will be at most one edit event for each sounding. If either condition is not true, MBedit sorts the edit events. The program then applies the edits to the active swath bathymetry beam flags in memory. In the case where multiple edit events refer to a particular sounding, that sounding's beam flag will reflect the edit event generated last. This may, or may not, leave that beam flag in a state identical to that of the original beam flag.

4) MBedit displays the swath bathymetry during an interactive editing session

During an editing session, MBedit displays groups of bathymetry across-track profiles, allowing the user to step forward and backward through the swath file. Unflagged soundings are shown as small filled black squares, and flagged soundings are shown as small unfilled squares. Soundings flagged interactively are shown in red, and those flagged by automatic algorithms are shown in green. Several interactive mouse modes allow the user to flag and unflag soundings. Each time a sounding is flagged, or unflagged, the display of the sounding is modified, the active beam flag in memory is modified and the corresponding edit event is appended to the stream storage file.

5) MBedit outputs the edit events to the edit save file when the session is completed

When an editing session is completed, MBedit sequentially examines the beam flag state of each sounding. Edit events are output to the esf file for each sounding that has an active beam flag differing from the corresponding original beam flag. The  output edit events are those required to produce the active beam flag. Since the flags are not output during the editing session, no sounding is referenced by more than one edit event (unlike the stream storage file). Also, the edit events are in the order of the pings and soundings in the swath file, making sorting unnecessary when the esf file is read later by MBedit or MBprocess.

6) MBedit sets values in the parameter file

Once the edit save file has been completed, the final step is for MBedit is to set flags so that MBprocess will read and apply the edit events as part of processing "exampledata.mb57". All of the processing flags and control values are set in the parameter file, a text file that is named by appending ".par" onto the original swath file name (if the swath file is named "exampledata.mb57", then the parameter file with be named "exampledata.mb57.par"). The parameter file contains parameter names and associated values controlling all aspects of swath data processing as performed by MBprocess. MBedit modifies the parameter file if it exists; otherwise MBedit will create a new parameter file. The two parameters relating to bathymetry editing that are set by MBedit (and MBclean and MBareaclean) are:

EDITSAVEMODE    1
EDITSAVEFILE   exampledata.mb57.esf

where EDITSAVEMODE is set to 1 if edits should be applied to the bathymetry (0 turns used of any edits off) and EDITSAVEFILE specifies the name of the edit save file.



Suggestions for Integrating a Bathymetry Editor with
MB-System

In order to function as a part of MB-System, a bathymetry editor needs to perform the same underlying tasks as MBedit, as described above. This section lists the essential elements of that integration, and provides suggestions on how to accomplish these tasks without linking to MB-System libraries.

1) Read the swath bathymetry data

Although the MB-System library MBIO includes function calls to easily read all supported swath formats, any software product which links with MBIO is required by the GPL to be open source in its entirety; this consequency may not be desireable for proprietary source developers. Fortunately, the structure of the MB-System processing environment includes the generation of fbt files located in parallel to all swath files. Identifying the fbt files is simple since they are named by simply adding the suffix ".fbt" to the original swath data filename. Thus, a third-party program can access all of the basic swath bathymetry information by supporting and reading the single format used for fbt files (Appendix 1). Some example code for reading ".fbt" files is provided in Appendix 4 with LGPL licensing; proprietary source developers are welcome to use this code, but should be aware that it has not been tested and is primarily provided as an example.

We also recommend that bathymetry editors be capable of opening groups of swath files referenced through datalist files. Since datalists may be recursive, the process of parsing through a datalist structure and resolving all of the full pathnames is somewhat complicated. However, the command line program MBdatalist provides this capability. So, when asked to open a datalist named "datalist.mb-1", a program can obtain a list of all the swath files referenced through that datalist by executing:

mbdatalist -I datalist.mb-1

If the editor internally uses a different beam flagging scheme than MB-System (as is likely), the beam flags will need to be converted to that internal format. The beam flag definitions used in MB-System are listed in Appendix 2.

2) Read pre-existing edit save files

An editor must also be capable of identifying and reading the edit save files (when they already exist). The format for the edit save files is quite simple, and is listed in Appendix 3.

2) Process and apply pre-existing edit events

An editor must apply any pre-existing edit events to the swath bathymetry before displaying it for interactive editing. Note that the edit events must be applied in the order they are read to insure that a sounding affected by multiple events reflects the last of those edit events.

3) Output new edit event list to the edit save file

The editor's primary output will be a new list of edit events in an MB-System format edit save, or esf, file. Two approaches to generating the esf file are possible.

The simplest scheme is to simply append any new edit events to the existing esf file, or to a newly created esf file, if none existed before. The consequence of the sequential or stream esf construction is that programs using the edit events later will have to sort those events before applying them, a process which can be time-consuming.

A more desirable scheme is to save the swath bathymetry's initial beam flag state internally, and then apply both pre-existing and new edit events to an active set of beam flags through the editing session. Then, on completion of editing, a set of edit events can be output that captures the final set of changes relative to the original swath file. This is, of course, the approach used for MBedit, and it saves time during both later editing sessions and during processing with MBedit.

We also recommend that a third-party editor implement the use of storage esf files in a fashion similar to that of MBedit. The purpose of these files is to provide a backup of the user's work in the case that the editor crashes or is killed during a session. Our experience is that users appreciate a means to recover apparently lost work.

4) Set the bathymetry edit values in the parameter file

Finally, the successful generation of a proper edit save file will matter little if those edits cannot be applied to the swath bathymetry in the production of a processed data file. The editor must modify, or create if necessary, a parameter file that causes MBprocess to read and apply the new edit events. Although MBedit accomplishes this task using MBIO library calls, modifying parameter files can also be accomplished using the program MBset. Given a swath file "exampledata.mb57", the following command will suffice:

mbset -I exampledata.mb57 -P EDITSAVEMODE:1 -P EDITSAVEFILE:exampledata.mb57.esf



Conclusions

Although the MB-System processing environment is complicated, the integration of a third-party bathymetry editor can be accomplished without undue pain. In particular, integration can be accomplished by supporting the reading of a single swath format, the reading and writing of fairly simple edit save files, and the use of the command line MB-System programs MBdatalist and MBset.



References

 Caress, David.W., and Dale N. Chayes, "Improved processing of Hydrosweep DS Multibeam Data on the R/V Maurice Ewing", Marine Geophysical Researches, 18, 631-650, 1996.

 Caress, D.W., and D.N. Chayes, "MB-System", Version 5, Open source software distributed from http://www.ldeo.columbia.edu/MB-System/ and http://www.mbari.org/data/mbsystem/, 2003-2004.

 Schmidt, V., D.N. Chayes, D.W. Caress, "The MB-System Cookbook", http://www.mbari.org/data/mbsystem/mb-cookbook and http://www.ldeo.columbia.edu/MB-System/mb-cookbook, Version 1.1, 2004.


Appendix 1: Current and Past Format Specifications for MB-System "fbt" Files

The MBLDEOIH format (MB-System format identifier 71) is used to store swath bathymetry, amplitude, and sidescan data with arbitrary numbers of bathymetry/amplitude beams and sidescan pixels.This format was created by the  Lamont-Doherty Earth Observatory and the Monterey Bay Aquarium Research Institute to serve as general purpose archive formats for processed swath data. There have been four iterations of the MBLDEOIH; MB-System version 5 reads both old and current files transparently but writes only the current version.

In general, MBLDEOIH files are generated by using MBcopy to translate swath data from some other format into MBLDEOIH. A special MBcopy argument, -D, causes that program to copy only the swath bathymetry information. This is how MBdatalist generates the ".fbt" files, ancillary swath bathymery-only files used in the MB-System processing structure. The fbt stands for "fast bathymetry" because the MBLDEOIH are quite spare in content, storing only the most basic elements of swath data in a very simple structure. Since ".fbt" files came into use after the data format was revised, only the current version of the MBLDEOIH format is documented here.

The original MBLDEOIH format was constructed only of one-byte integers, two-byte integers in big-endian order, and one-byte chars. The current format incorporates four-byte-float and eight-byte-double floating point values as well, again in big-endian form. There are two types of records, survey data records and comment records. The comment records store text strings, such as those commonly inserted by MBprocess at the start of processed swath files. The beginning of each record is a two-byte record type identifier, which in big-endian order has one of two values:

Old Survey Data Record:        28270   "nn"
Current Survey Data Record:  13398   "V4"
Comment Record:                  25443   "cc"

In the case of a comment record, the two-byte identifier is the entire record header. The rest of the comment record is a 128 byte long array of char comprising a null terminated string. This array may hold a comment up to 127 characters long. Thus, comment records are always 130 bytes long.

In the case of a current survey data record, the record header is 90 bytes long, including the starting two-byte identifier. The survey data record header includes basic swath data parameters, including time stamp, navigation, heading, speed, sonar depth, sonar altitude, beam widths, numbers of bathymetry beams, amplitude beams, and sidescan pixels, and scale factors for depth and distance values. Following the header are arrays of beam and pixel values, including alongtrack and acrosstrack distances as well as beam flags, depths, amplitude and sidescan values. The dimensions of these arrays are determined by the numbers of beams and pixels found in the header; the size of survey data records can thus vary within a data file as well as between different data files.

In the case of an old survey data record, the record header is 44 bytes long, including the starting two-byte identifier. The survey data record header includes basic swath data parameters, including time stamp, navigation, heading, speed, sonar depth, sonar altitude, beam widths, numbers of bathymetry beams, amplitude beams, and sidescan pixels, and scale factors for depth and distance values. Following the header are arrays of beam and pixel values, including alongtrack and acrosstrack distances as well as beam flags, depths, amplitude and sidescan values. The dimensions of these arrays are determined by the numbers of beams and pixels found in the header; the size of survey data records can thus vary within a data file as well as between different data files.

Appendix 4 contains example source code that reads ".fbt" files; these source files are released under the LGPL so that they can be used in commercial applications without violating the license.

Comment Record (130 bytes):
Value Size (bytes) Format
Value
Units
Description
recordtype
2
unsigned short
28270
N/A
Comment record identifier
comment
128
char[128]

null terminated string
Comment string

Current Survey Data Record (90 + 7 * beams_bath + 2 * beams_amp + 6 * pixels_ss bytes):
Value
Size (bytes)
Format
Value
Units
Description
recordtype
2
unsigned short
25443
N/A
Survey data record identifier
time_d
8
double
seconds since 00:00:00 01/01/1970
Time tag: unix seconds
longitude 8 double 0.0 - 359.9999 degrees east of prime meridian
Longitude
latitude
8 double -90.0 - 90.0
degrees from the equator Latitude
sonardepth
8 double
meters
Sonar depth
altitude
8 double
meters
Sonar altitude
heading
4 float 0.0 - 359.9999
degrees
Heading
speed
4 float >= 0.0
km/hr
Speed
roll
4 float -90.0 - 90.0
degrees
Roll
pitch
4 float -90.0 - 90.0
degrees
Pitch
heave
4 float
m
Heave
beam_xwidth
4 float
degrees
Acrosstrack beam width
beam_lwidth
4 float
degrees
Alongtrack beam width
beams_bath
2 short >= 0
N/A Number of bathymetry beams
beams_amp
2 short >= 0
(0 for fbt files)
N/A Number of amplitude beams
pixels_ss
2 short >= 0
(0 for fbt files)
N/A Number of sidescan beams
spare1
2 short


depth_scale
4 float > 0.0
meters
Scale factor for depth values
distance_scale
4 float >0.0
meters
Scale factor for distance values
ss_type
2 short

0 = logarithmic units (dB)

1 = linear units



Sidescan pixel values in dB or in linear units
spare2
2 short


beamflag
beams_bath
unsigned char

MB-System beam flags
(Appendix 2)
Bathymetry beam flags
bath
2 * beams_bath
short
depth_scale
Bathymetry
bath_acrosstrack
2 * beams_bath short
distance_scale
Bathymetry across-track distance
bath_alongtrack
2 * beams_bath short
distance_scale Bathymetry along-track distance
amp
2 * beams_amp
short
variable
Amplitude
ss
2 * pixels_ss short
variable
Sidescan
ss_acrosstrack
2 * pixels_ss short
distance_scale Sidescan across-track distance
ss_alongtrack
2 * pixels_ss short
distance_scale Sidescan along-track distance

Old Survey Data Record (44 + 7 * beams_bath + 2 * beams_amp + 6 * pixels_ss bytes):
Value
Size (bytes)
Format
Value
Units
Description
recordtype
2
unsigned short
25443
N/A
Survey data record identifier
year
2
short
year
Time tag: year
day
2
short 1 - 366
day
Time tag: julian day
min
2
short 0 - 1439
minute
Time tag: minute from beginning of day
sec
2
short 0 - 59
second
Time tag: second
msec
2 short 0 - 999
millisecond
Time tag: millisecond
lon2u
2 unsigned short
arc minute
Longitude:
minutes east of prime meridian
lon2b
2 unsigned short
0.0001 * arc minute Longitude:
fraction of minute times 10000
lat2u
2 unsigned short
arc minute Latitude:
number of minutes north of 90S
lat2b
2 unsigned short
0.0001 * arc minute
Latitude:
fraction of minute times 10000
heading
2 unsigned short 0 - 65535
(360 / 65536) degree
Heading
speed
2 unsigned short
0.01 km/hr
Speed
beams_bath
2 short >= 0
N/A Number of bathymetry beams
beams_amp
2 short >= 0
(0 for fbt files)
N/A Number of amplitude beams
pixels_ss
2 short >= 0
(0 for fbt files)
N/A Number of sidescan beams
depth_scale
2 short >=1
0.001 meters
Scale factor for depth values
distance_scale
2 short >=1
0.001 meters
Scale factor for distance values
transducer_depth
2 short
depth_scale
Sonar transducer depth
altitude
2 short
depth_scale
Sonar transducer altitude
beam_xwidth
2 short
0.01 degrees
Beam acrosstrack width
beam_lwidth
2 short
0.01 degrees
Beam alongtrack width
spare
2 short


beamflag
beams_bath
unsigned char

MB-System beam flags
(Appendix 2)
Bathymetry beam flags
bath
2 * beams_bath
short
depth_scale
Bathymetry
bath_acrosstrack
2 * beams_bath short
distance_scale
Bathymetry across-track distance
bath_alongtrack
2 * beams_bath short
distance_scale Bathymetry along-track distance
amp
2 * beams_amp
short
variable
Amplitude
ss
2 * pixels_ss short
variable
Sidescan
ss_acrosstrack
2 * pixels_ss short
distance_scale Sidescan across-track distance
ss_alongtrack
2 * pixels_ss short
distance_scale Sidescan along-track distance


Appendix 2: MB-System Beam Flags

The beam flagging scheme used by MB-System is very similar to the convention used in the HMPS hydrographic data processing package and the SAIC Hydrobat package (at least as these packages existed circa 1997). In particular, the beam flag values are defined to support both flagging soundings as "bad" and selecting soundings as being of particular interest. However, no MB-System programs currently make use of the "sounding selection" definitions of the beam flags. Many beam flag values and macro definitions are listed below, the few actually used by MB-System programs are noted.

The beam flag values are declared as single "char", one-byte integers. The beam flags are used as an eight-bit bitmask, and so macros to test and set the flags are easily constructed. Bit 0 is used to flag a sounding as bad, and bit 1 is used to select a sounding. The reason for flagging or selection can be encoded in bits 2-7. A beam cannot be both flagged and selected, but more than one "reason bit" can be set for either flagging or selection.

Flag and select bits of MB-System beam flag values:
Beam Flag Bit Values Meaning
Used by MB-System
xxxxxx00 This beam is neither flagged nor selected. X
xxxxxx01 This beam is flagged as bad and should be ignored. X
xxxxxx10 This beam has been selected.

Flagging modes of MB-System beam flag values:
Beam Flag Bit Values Meaning Used by MB-System
00000001 Flagged because no detection was made by the sonar (null beam). X
xxxxx101 Flagged by manual editing. X
xxxx1x01 Flagged by automatic filter. X
xxx1xx01 Flagged by automatic filter 2. X
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. X

Selection modes modes of MB-System beam flag values:
Beam Flag Bit Values Meaning
Used by MB-System
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.

Beam Flag Value Definitions for Flagging Beams as Bad:
Beam Flag Value Name
Value
Used by MB-System
MB_FLAG_NONE 0x00 X
MB_FLAG_FLAG 0x01 X
MB_FLAG_NULL 0x01 X
MB_FLAG_MANUAL 0x04 X
MB_FLAG_FILTER 0x08 X
MB_FLAG_FILTER2 0x10 X
MB_FLAG_GT_1X_IHO 0x10
MB_FLAG_GT_2X_IHO 0x20
MB_FLAG_FOOTPRINT 0x40
MB_FLAG_SONAR 0x80 X

Beam Flag Value Definitions for Selecting Beams (Not Used in MB-System):
Beam Flag Value Name Value Used by MB-System
MB_SELECT_SELECT 0x02
MB_SELECT_LEAST 0x04
MB_SELECT_MAXIMUM 0x08
MB_SELECT_AVERAGE 0x10
MB_SELECT_CONTACT 0x20
MB_SELECT_SPARE_1 0x40
MB_SELECT_SPARE_2 0x80

Definitions for MB-System Macros Applying and Testing Beam Flags:
Macro Name
Definition
Used by MB-System
mb_beam_ok(F) ((int)(!(F & MB_FLAG_FLAG))) X
mb_beam_check_flag(F) ((int)(F & MB_FLAG_FLAG)) X
mb_beam_check_flag_null(F) ((int)(F == MB_FLAG_NULL)) X
mb_beam_check_flag_manual(F) ((int)((F & MB_FLAG_MANUAL ) && (F & MB_FLAG_FLAG))) X
mb_beam_check_flag_filter(F) ((int)((F & MB_FLAG_FILTER ) && (F & MB_FLAG_FLAG))) X
mb_beam_check_flag_filter2(F) ((int)((F & MB_FLAG_FILTER2 ) && (F & MB_FLAG_FLAG)))
mb_beam_check_flag_gt_1x_iho(F) ((int)((F & MB_FLAG_GT_1X_IHO) && (F & MB_FLAG_FLAG)))
mb_beam_check_flag_gt_2x_iho(F) ((int)((F & MB_FLAG_GT_2X_IHO) && (F & MB_FLAG_FLAG)))
mb_beam_check_flag_footprint(F) ((int)((F & MB_FLAG_FOOTPRINT) && (F & MB_FLAG_FLAG)))
mb_beam_check_flag_sonar(F) ((int)((F & MB_FLAG_SONAR ) && (F & MB_FLAG_FLAG))) X
mb_beam_set_flag_null(F) (MB_FLAG_NULL) X
mb_beam_set_flag_manual(F) (F | 0x05) X
mb_beam_set_flag_filter(F) (F | 0x09) X
mb_beam_set_flag_filter2(F) (F | 0x11) X
mb_beam_set_flag_gt_1x_iho(F) (F | 0x11)
mb_beam_set_flag_gt_2x_iho(F) (F | 0x21)
mb_beam_set_flag_footprint(F) (F | 0x41) X
mb_beam_check_select(F) ((int)(F & MB_SELECT_SELECT))
mb_beam_check_select_least(F) ((int)((F & MB_SELECT_LEAST ) && (F & MB_SELECT_SELECT)))
mb_beam_check_select_maximum(F) ((int)((F & MB_SELECT_MAXIMUM) && (F & MB_SELECT_SELECT)))
mb_beam_check_select_average(F) ((int)((F & MB_SELECT_AVERAGE) && (F & MB_SELECT_SELECT)))
mb_beam_check_select_contact(F) ((int)((F & MB_SELECT_CONTACT) && (F & MB_SELECT_SELECT)))
mb_beam_check_select_spare_1(F) ((int)((F & MB_SELECT_SPARE_1) && (F & MB_SELECT_SELECT)))
mb_beam_check_select_spare_2(F) ((int)((F & MB_SELECT_SPARE_2) && (F & MB_SELECT_SELECT)))
mb_beam_set_select(F) (F | 0x02)
mb_beam_set_select_least(F) (F | 0x06)
mb_beam_set_select_maximum(F) (F | 0x0a)
mb_beam_set_select_average(F) (F | 0x12)
mb_beam_set_select_contact(F) (F | 0x22)
mb_beam_set_select_spare_1(F) (F | 0x42)
mb_beam_set_select_spare_2(F) (F | 0x82)



Appendix 3: MB-System Edit Save File Format

MB-System edit save files are quite simple in structure. Each file consists of a stream of edit events, each requiring 16 bytes as follows:

Edit event (16 bytes):
Value
Size (bytes)
Format
Value
Units
Description
time_d
8
double
 
Unix epoch seconds
(seconds since 00:00:00 1/1/1970)
Time stamp of ping
beam
4
int
>= 0
beam number (counted from 0) + multiplicity * 1000000
Beam number plus offset of 1000000 for each ping multiplicity
action
4
int
1 >= action <= 4

Edit event


where all values are stored in big-endian byte order. Here time_d is the time tag of the affected sonar ping in Unix epoch seconds (decimal seconds since 1/1/1970 00:00:00.000), beam is the affected beam number (counting from 0) plus an offset of 1000000 times the ping multiplicity, and action defines the actual edit event. The multiplicity value refers to data from multiple head sonars that produce multiple pings with identical time stamps (most commonly sonars like the EM3002 that can produce left and right pings simultaneously). The first reported ping will have a multiplicity of 0, the second 1, and so on.

Edit action definitions:
Name
Value
Description
MBP_EDIT_FLAG 1 flag the beam as bad - identified interactively
MBP_EDIT_UNFLAG 2 unflag the beam - making it good
MBP_EDIT_ZERO 3 null the beam
MBP_EDIT_FILTER 4 flag the beam as bad - identified automatically

There is no file header or minimum or maximum number of edit events in an esf file. There is also no requirement that edit events appear in the order of time and/or beam number, and any particular beam may be affected by multiple edit events, providing these appear in the esf file in the order in which they were generated.


Appendix 4: LGPL Licensed Code Available for Third-Party Use

This section contains links to three source files written in C: mblgpl_fbt.c, mblgpl_fbt.h, and fbtinfo.c. The file mblgpl_fbt.c includes functions that read swath bathymetry data from ".fbt" files, the file mblgpl_fbt.h is the corresponding header file to be included in any application code calling the ".fbt" read functions, and the file fbtinfo.c is a sample application that will read an fbt file and output statistics of the data.

These source files are packaged together with a simple makefile and a test fbt file in the tarball: mblgpl.tar.gz. This code has been successfully tested on Mac OS X 10.9.4

These source files are licensed using the Lesser GNU Public License, or LGPL. Consequently this code can be used in the development of proprietary software products.


Last modified July 23, 2014

Back to MB-System Website...Back to MB-System Website...