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 5

Originated September 3, 2004
Modified December 31, 2009
Modified May 16, 2012
Modified July 23, 2014
Modified December 1, 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>

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

The fbt file format was extended for release 5.4.2215 to allow represention of data records containing more than 32768 bathymetry values, a situation possible for lidar sensors and for dense photogrammetry from photographic stereo pairs. This extension consists for data record headers in which the numbers of bathymetry beams, amplitude beams, and sidescan pixels are represented by four-byte integer values rather than two-byte short values. The extended record headers are used only when required. For most data, including all sonar data at present, there is no change to the structure of fbt files.

---

Overview of the MB-System Processing Environment

The MB-System processing environment is documented in the distribution MB-System web pages (Caress and Chayes, 2014) 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.

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.

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:

• time stamp
• sonar longitude
• sonar latitude
• heading
• speed
• sonar altitude
• sonar depth
• roll
• pitch
• heave
• number of bathymetry soundings
• array of depths
• array acrosstrack distances
• array of beam flags

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.

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").

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.

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.

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:

---

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:

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.

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.

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.

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.

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

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

Old Survey Data Record:                       28270   "nn"
Current Survey Data Record:                 22068   "V4"
Current Extended Survey Data Record:  22069   "V5"
Comment Record:                                  25443   "cc"

Comment Record (130 bytes):

Current (V4) Survey Data Record (90 + 7 * beams_bath + 2 * beams_amp + 6 * pixels_ss bytes):

Extended (V5) Survey Data Record (98 + 7 * beams_bath + 2 * beams_amp + 6 * pixels_ss bytes):

Old Survey Data Record (44 + 7 * beams_bath + 2 * beams_amp + 6 * pixels_ss bytes):

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:

Flagging modes of MB-System beam flag values:

Beam Flag Value Definitions for Flagging Beams as Bad:

Definitions for MB-System Macros Applying and Testing Beam Flags:

Appendix 3: MB-System Edit Save File Format

Edit event (16 bytes):

Edit action definitions:

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

Last modified November 30, 2014