MB-System Unix Manual Page: mbclean

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

    mbclean
    Section:  MB-System 5.0  (1)
    Updated:  1 December 2014
    Index

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

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    EXAMPLES
    SEE ALSO
    BUGS

Last Updated: 1 December 2014

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

Back to MB-System Home Page...