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