mbclean(1)

NAME
mbclean - Tool to automatically flag bad beams in swath sonar bathymetry data.

VERSION
Version 5.0

SYNOPSIS
mbclean [-Amax -Blow/high -Cslope/units -Dmin/max -Fformat -Gfraction_low/fraction_high -Iinfile -Krange_min -Llonflip -Mmode -Ooutfile -Pmin_speed/max_speed -Qbackup -Rmaxheadingrate -Sslope/mode/units -Ttolerance -Unmin -Wwest/east/south/north -Xbeamsleft/beamsright -Ydistanceleft/distanceright -Z -V -H]

DESCRIPTION
mbclean identifies and flags artifacts in swath sonar bathymetry data. Several algorithms are available for identifying artifacts; multiple algorithms can be applied in a single pass. The most commonly used approach is to identify artifacts based on excessive bathymetric slopes. Spikes where an excessive slope occurs before and reverses after a beam can also be removed. If desired, mbclean will also flag beams associated with "rails" where outer beams have smaller acrosstrack distances than more inner beams (-Q option). Low and high bounds on acceptable depth values can be set; depth values outside the acceptable range will be flagged. The acceptable depth ranges can either be absolute (-B option), relative to the local median depth (-A option) or defined by low and high fractions of the local median depth (-G option). A set number of outer beams can also be flagged. The order in which the flagging algorithms are applied is as follows:
     1. Flag specified numbers of outer beams
         (-X option).
     2. Flag outer beams by acrosstrack distance
         (-Y option).
    3. Flag all beams in pings outside specified
        acceptable speed range (-P option).
    4. Flag all beams in pings outside specified
        acceptable position bounds (-W option).
    5. Flag all beams in pings with zero
        longitude and latitude values (-Z option).
     6. Flag soundings outside specified acceptable
         depth range (-B option).
     7. Flag soundings with ranges less than
         specified minimum value (-B option).
     8. Flag pings with excessive heading change rate
            (-R option).
     9. Zap "rails" (-Q option).
     10. Flag soundings with acrosstrack distances
         greater than specified maximum value
         (-B option).
     11. Flag soundings outside acceptable depth range
         using fractions of local median depth
         (-G option).
     12. Flag soundings outside acceptable depth range
         using deviation from local median depth
         (-A option).
     13. Flag soundings associated with spikes (-S option).
     14. Flag soundings associated with excessive slopes
         (-C option or default).
     15. Flag all soundings in pings with too few
         good soundings (-U option). This program flags beams by outputting the flags as edit events to an "edit save file", like that produced by mbedit. If an "edit save file" (named by adding a ".esf" suffix to the input swath filename) already exists, the edits are read in and applied before the mbclean flagging algorithms are used. Once generated, the edit events can be applied to the data using the program mbprocess, which outputs a processed swath data file. The mbprocess program is also used to merge edited navigation, recalculate bathymetry, and apply other corrections to swath bathymetry data.

AUTHORSHIP
David W. Caress (caress@mbari.org)
  Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)
  Lamont-Doherty Earth Observatory
Alberto Malinverno
  Schlumberger-Doll

OPTIONS

-A  max
    This option sets the range of acceptable depth values relative to the local median depth. The median depth is obtained from the current ping and the pings immediately before and after that ping. If a depth value deviates from the median depth by more than max, then it will be flagged. No deviation from the median depth checking is done if the -A option is not used.

-B  low/high
    This option sets the range of acceptable depth values. If a depth value is less than low or more than high then it will be flagged. No depth range checking is done if the -B option is not used.

-C  slope/unit
    The value slope is the maximum acceptable slope. Beams associated with excessive slopes will be flagged or removed according to the operational mode specified using the -M option. This method will be used if no other algorithms are specified; if other algorithms are specified but -C is not used then no slope checking will occur. unit is optional and specifies the unit of slope, 0 (default) indicates the slope is in tangents, 1 slope is in radians, 2 slope is in degrees. Default: slope = 1.0

-D  min/max
    Sets the minimum and maximum allowed distances between beams used for some of the flagging algorithms. Both values are expressed in terms of fractions of the local median depth. Thus, -D0.01/0.25 will translate, if the local median depth is 1000 meters, to a minimum distance of 10 meters and a maximum distance of 250 meters. The min value sets the minimum distance between beams required for an excessive slope to be used to flag bad beams. The navigation and heading of the ship are used to calculate the locations of beams. Ship turns often cause beams of adjacent pings to overlap, causing the distances between these beams to become quite small. This can, in turn, magnify noise in the bathymetry data to produce slope estimates which are excessively large. The max value sets the maximum distance between the current beam and other beams for those beams to be used in evaluating the current beam. For instance, only beams within the maximum distance are used to calculate the local median depth, and only beams within the maximum distance are used to check for excessive slopes. Default: min/max = 0.01/0.25.

-F  format
    Sets the data format used if the input is read from stdin or from a file. If format < 0, then the input file specified with the -I option will actually contain a list of input swath sonar data files. This program uses the MBIO library and will read or write any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. Default: format = 11.

-G  fraction_low/fraction_high
    This option sets the range of acceptable depth values relative to low and high fractions of the local median depth. The median depth is obtained from the current ping and the pings immediately before and after that ping. If a depth value is less than fraction_low times the median depth (e.g. fraction_low = 0.5 means one half the median depth) or more than fraction_high times the median depth then it will be flagged. No fractional depth range checking is done if the -G option is not used.

-H  This "help" flag cause the program to print out a description of its operation and then exit immediately.

-I  infile
    Sets the input filename. If format > 0 (set with the -F option) then the swath sonar data contained in infile is read and processed. If format < 0, then infile is assumed to be an ascii file containing a list of the input swath sonar data files to be processed and their formats. The program will read and process the data in each one of these files. Each input file will have an associated output file with either the ".sga" or ".aga" suffix. In the infile file, each data file should be followed by a data format identifier, e.g.:
         datafile1 11
         datafile2 24
    This program uses the MBIO library and will read or write any swath sonar format supported by MBIO. A list of the swath sonar data formats currently supported by MBIO and their identifier values is given in the MBIO manual page. Default: infile = "datalist.mb-1".

-K  range_min
    This option causes all unflagged beams with ranges less than range_min to be flagged as bad. The value range_min is specified in meters.

-L  lonflip
    Sets the range of the longitude values used. If lonflip=-1 then the longitude values will be in the range from -360 to 0 degrees. If lonflip=0 then the longitude values will be in the range from -180 to 180 degrees. If lonflip=1 then the longitude values will be in the range from 0 to 360 degrees. Default: lonflip = 0.

-M  mode
    Sets the manner in which bad beams identified by excessive slope are handled.
         mode = 1:    Flags one beam associated with each outlier slope.
                 The flagged beam is the one furthest from the local
                 median depth.
         mode = 2:    Flags both beams associated with each outlier slope.
         mode = 3:    Zeros one beam associated with each outlier slope.
                 The zeroed beam is the one furthest from the local
                 median depth.
         mode = 4:    Zeros both beams associated with each outlier slope.
    If the data format of the input file prohibits storage of negative depths, an error message will be output and the program will exit. Default: mode = 1.

-P  speed_low/speed_high
    This option causes mbclean to flag as bad all beams in pings associated with platform speed outside the acceptable range from speed_low to speed_high. The speed values are specified in km/hour.

-Q  backup
    This flag causes mbclean to search for bad "rails" in the swath sonar swath; the "rails" refer to groups of outer beams which have crosstrack distances (and depths) much less than they should have. These are identified when one or more outer beams lies more than backup meters inboard of a more inner beam; all beams meeting this criteria are flagged.

-R  maxheadingrate
    The value maxheadingrate is the maximum acceptable rate of change in heading in degrees/second. All soundings associated with pings for which the heading was changing at a greater rate will be flagged.

-S  slope/mode/unit
    The value slope is the maximum acceptable spike slope. If the slope from the preceding beam to this beam exceeds this value, and the slope from this beam to subsequent beam exceeds this value but with an opposite sign this beam is considered a spike and will be flagged or removed according to the operational mode specified using the -M option. Acrosstrack slopes are determined by the preceding and subsequent beams in the same ping. Alongtrack slopes are determined from the same beam in the previous and subsequent pings. Alongtrack are fairly sensitive to the minimum distance -D option, which will normally need to be set less to a very small value for alongtrack slopes to be detected. There is no test that alongtrack distances are all in the same direction. If mode is 1 (default) only acrosstrack spikes are detected. If mode is 2 only alongtrack spikes are detected. If mode is 3 both along track and across track slopes are checked. unit is optional and specifies the unit of slope, 0 (default) indicates the slope is in tangents, 1 slope is in radians, 2 slope is in degrees. A beam is not considered a spike if either the preceding or subsequent beam has already been flagged. Default: slope = 1.0

-T  tolerance
    If requested this option will reset the timestamps of edit events from an existing esf file to exactly match the timestamps of the survey pings. The /fItolerance/fP value sets how close timestamps must be in seconds to be considered a match. This option handles the case where survey data have been processed using non-MB-System software and a user is extracting the edits from one set of files with mbgetesf and then applying them to another using mbprocess.

-U  nmin
    This flag causes mbclean to search for port or starboard halves of pings which contain fewer than nmin good bathymetry values. All bathymetry values in the affected half-pings are flagged.

-V  Normally, mbclean works "silently" without outputting anything to the stderr stream. If the -V flag is given, then mbclean works in a "verbose" mode and outputs the program version being used, all error status messages, and the number of beams flagged as bad.

-W  west/east/south/north
    This option causes mbclean to flag as bad all beams in pings with navigation outside the specified acceptable bounds.

-X  zap_beams
    If this option is used, the outermost zap_beams at both ends of the swath are flagged as bad; this is useful if the outer beams are known to be unreliable. Default: zap_beams = 0.

-Y  distanceleft/distanceright
    This option causes mbclean to flag as bad all beams with acrosstrack distances more to port than distanceleft and more to starboard than distanceright. The distances are defined in meters, and distances to port of nadir are negative.

-Z
    This option causes mbclean to flag as bad all beams in pings with zero longitude and latitude values.

EXAMPLES
Suppose one wishes to do a first pass edit of six Simrad EM300 files in the processing format (format 57). A datalist referencing these six files exists as the file datalist.mb-1 and has the contents:
     0001_20020424_212920.mb57 57
     0002_20020425_011607.mb57 57
     0003_20020425_022926.mb57 57
     0004_20020425_024336.mb57 57
     0005_20020425_034057.mb57 57
     0006_20020425_045013.mb57 57
Use the following to flag any beams which deviate by more than 20% from the local median depth or which produce a slope greater than 3.5 (74 degrees):
     mbclean -Idatalist.mb-1 \
         -M1 -C3.5 -D0.01/0.20 \
         -G0.80/1.20 The program will output flagging statistics for each file and give totals at the end. If the -V option is specified, mbclean will also output information for each beam that is flagged. Here is an example of the nonverbose output:
     Processing 0001_20020424_212920.mb57
     908 bathymetry data records processed
     0 outer beams zapped
     0 beams zapped for too few good beams in ping
     0 beams out of acceptable depth range
     64 beams out of acceptable fractional depth range
     0 beams exceed acceptable deviation from median depth
     0 bad rail beams identified
     1601 excessive slopes identified
    0 excessive spikes identified
     1665 beams flagged
     0 beams unflagged
     0 beams zeroed
     Processing 0002_20020425_011607.mb57
     259 bathymetry data records processed
     0 outer beams zapped
     0 beams zapped for too few good beams in ping
     0 beams out of acceptable depth range
     0 beams out of acceptable fractional depth range
     0 beams exceed acceptable deviation from median depth
     0 bad rail beams identified
     242 excessive slopes identified
    0 excessive spikes identified
     242 beams flagged
     0 beams unflagged
     0 beams zeroed
     Processing 0003_20020425_022926.mb57
     65 bathymetry data records processed
     0 outer beams zapped
     0 beams zapped for too few good beams in ping
     0 beams out of acceptable depth range
     9 beams out of acceptable fractional depth range
     0 beams exceed acceptable deviation from median depth
     0 bad rail beams identified
     497 excessive slopes identified
    0 excessive spikes identified
     506 beams flagged
     0 beams unflagged
     0 beams zeroed
     Processing 0004_20020425_024336.mb57
     410 bathymetry data records processed
     0 outer beams zapped
     0 beams zapped for too few good beams in ping
     0 beams out of acceptable depth range
     0 beams out of acceptable fractional depth range
     0 beams exceed acceptable deviation from median depth
     0 bad rail beams identified
     148 excessive slopes identified
    0 excessive spikes identified
     148 beams flagged
     0 beams unflagged
     0 beams zeroed
     Processing 0005_20020425_034057.mb57
     252 bathymetry data records processed
     0 outer beams zapped
     0 beams zapped for too few good beams in ping
     0 beams out of acceptable depth range
     0 beams out of acceptable fractional depth range
     0 beams exceed acceptable deviation from median depth
     0 bad rail beams identified
     100 excessive slopes identified
    0 excessive spikes identified
     100 beams flagged
     0 beams unflagged
     0 beams zeroed
     Processing 0006_20020425_045013.mb57
     562 bathymetry data records processed
     0 outer beams zapped
     0 beams zapped for too few good beams in ping
     0 beams out of acceptable depth range
     0 beams out of acceptable fractional depth range
     0 beams exceed acceptable deviation from median depth
     0 bad rail beams identified
     41 excessive slopes identified
    0 excessive spikes identified
     41 beams flagged
     0 beams unflagged
     0 beams zeroed
     MBclean Processing Totals:
     -------------------------
     6 total swath data files processed
     2456 total bathymetry data records processed
     0 total beams flagged in old esf files
     0 total beams unflagged in old esf files
     0 total beams zeroed in old esf files
     0 total outer beams zapped
     0 total beams zapped for too few good beams in ping
     0 total beams out of acceptable depth range
     73 total beams out of acceptable fractional depth range
     0 total beams exceed acceptable deviation from median depth
     0 total bad rail beams identified
     2629 total excessive slopes identified
    0 total excessive spikes identified
     2702 total beams flagged
     0 total beams unflagged
     0 total beams zeroed

SEE ALSO
mbsystem(1), mbedit(1), mbinfo(1) mbprocess(1),

BUGS
The algorithms implemented in mbclean simply don't detect all bathymetric artifacts that are obvious to the eye on contour charts. Although mbclean often does a credible first pass at flagging obvious artifacts, we strongly recommend that any swath bathymetry processing stream include interactive editing of the bathymetry data (e.g. mbedit).