MB-System Unix Manual Page: mbfilter

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

##

    mbfilter
    Section:  MB-System 5.0  (1)
    Updated:  6 June 2010
    Index

    NAME

    mbfilter - Apply some simple filter functions to sidescan or beam
    amplitude data from swath sonar data files.

    VERSION

    Version 5.0

    SYNOPSIS

    mbfilter [-Akind
    -Byr/mo/da/hr/mn/sc
    -Cmode/xdim/ldim/iteration
    -Dmode/xdim/ldim/iteration[/offset]
    -Eyr/mo/da/hr/mn/sc
    -Fformat -Iinfile -Nbuffersize
    -Rwest/east/south/north
    -Smode/xdim/ldim/iteration[/threshold_lo/threshold_hi]
    -V -H]

    DESCRIPTION

    mbfilter applies one or more simple filters to the specified
    sidescan or beam amplitude data. The filters
    include:

      -S1: boxcar mean for low-pass filtering

      -S2: gaussian mean for low-pass filtering

      -S3: boxcar median for low-pass filtering

      -S4: inverse gradient for low-pass filtering

      -D1: boxcar mean subtraction for high-pass filtering

      -D2: gaussian mean subtraction for high-pass filtering

      -D3: boxcar median subtraction for high-pass filtering

      -C1: edge detection for contrast enhancement

      -C2: gradient magnitude subtraction for contrast enhancement

    These filters are mostly intended for use with sidescan
    data. In particular, the low-pass or smoothing filters
    can be used for first-order speckle reduction in sidescan
    data, and the high-pass filters can be used to emphasize
    fine scale structure in the data. A combination of
    low-pass and high-pass filtering can effectively perform
    band-pass filtering. The contrast enhancing
    filters can, under certain circumstances, sharpen sidescan
    images of the seafloor. The low-pass and contrast
    enhancement filters are described
    in the paper by Sauter and Parson (1994) listed below.

    The filtering used here is designed and applied in the
    same manner as spatial filters are applied to images.
    The swath data is treated as an image, with the x and
    y coordinates corresponding to pixel (or beam) number and
    ping number, respectively. The filters consist of M x N
    matrices which are convolved with the swath data image
    (M is the filter dimension in the acrosstrack direction
    and N is the filter dimension in the alongtrack direction).
    Missing or flagged data are ignored in the filtering
    process.

    Low-pass filters are specified with the -S option,
    high-pass filters with the -D option, and contrast
    enhancement with the -C option. Users can apply up
    to ten filters in any order; the filters are applied
    in the order in which they are specified on the command line.
    Users can apply as many iterations of each filter as
    desired. The user specifies the window size
    used by the filters (3x3 or 5x5 are typical for using smoothing
    filters iteratively to reduce speckle; larger windows like 3x20
    are typical for high-pass filtering).

    The boxcar mean, gaussian mean, and median filter all
    achieve similar results in uniformly smoothing the data;
    the boxcar mean is faster to apply, the gaussian mean preserves
    the frequency content of the data better, and the median filter
    is least sensitive to spikes in the data. The inverse
    gradient filter applies averaging weights which depend on the
    inverse gradient of the data. This approach causes the filter
    to smooth regions without distinct edges much more than regions
    with edges, thus tending to preserve the sharpness of features
    more than the simpler smoothing filters.

    The median smoothing filter can be set by the -T
    option to operate with low and high
    ratio thresholds (the value is changed only if the original
    value divided by the median value is less than the low
    threshold or greater than the high threshold). This allows the
    filter to preferentially despike the data. In particular, this
    approach is useful for suppressing "stripes" or "bad"
    pings which have amplitude or sidescan values differing significantly
    from surrounding pings.

    The high-pass filters are constructed by calculating a low-pass
    filtered version of the data and then subtracting that from
    the original data. An offset value is added to the high-passed
    data so that it is positive (negative values are considered
    flagged as bad in some formats and not allowed in others).
    The high-pass filters can be used to remove
    long-wavelength variations in seafloor reflectivity in order
    to emphasize fine-scale structure.

    The contrast enhancement filters are generally only successful
    when applied after smoothing because of their tendency to
    amplify noise. The edge detection filter enhances contrast by
    tending to shift values on either side of a boundary away
    from the average value across the boundary. A 5 X 5 filter or
    larger is generally required for success with the edge detection
    algorithm. The gradient filter increases contrast by subtracting
    twice the local gradient magnitude from each value.

    The filtered amplitude or sidescan data are written to ancilliary
    files located parallel to the input swath data files. Filtered
    amplitude data will be in files named by adding ".ffa" to the input
    file name, and sidescan data will be in files with an ".ffs" suffix.
    Filtered amplitude or sidescan data can be plotted with mbm_plot by
    appending "F" to that macro's mode argument (e.g. -G4F for filtered
    amplitude data, and  -G5F for filtered sidescan data).
    If accessing mbswath directly rather than through mbm_plot,
    plot the filtered data by appending "F" to the program's mode argument
    (e.g. -Z4F for filtered
    amplitude data, and  -Z5F for filtered sidescan data).
    When using mbmosaic to generate mosaics of amplitude or sidescan data,
    the filtered data can be accessed by appending "F" to the data kind argument
    (e.g. -A3F for amplitude and  -A4F for sidescan data.

    AUTHORSHIP

    David W. Caress (caress@mbari.org)

      Monterey Bay Aquarium Research Institute

    Dale N. Chayes (dale@ldeo.columbia.edu)

      Lamont-Doherty Earth Observatory

    OPTIONS

    -A

    kind

    Determines whether beam amplitude (kind = 1),
    or sidescan (kind = 2) data will be processed.
    Default: kind = 2.
    -B

    yr/mo/da/hr/mn/sc

    This option sets the starting time for data allowed in the input data.
    The -E option sets the ending time for data. If the
    starting time is before the ending time, then any data
    with a time stamp before the starting time or after the
    ending time is ignored. If instead the starting time is
    after the ending time, then any data between the ending
    and starting time will be ignored. This scheme allows time
    windowing both inside and outside a specified interval.
    Default: yr/mo/da/hr/mn/sc = 1962/2/21/10/30/0.
    -C

    mode/xdim/ldim/iteration

    Turns on contrast enhancement filtering and sets the
    filter parameters to be
    used. Here mode specifies the filter type:

            mode = 1 : Edge Detection Filter

            mode = 2 : Gradient Magnitude Subtraction Filter

    The dimensions of the data window used are set using xdim
    (acrosstrack dimension) and ldim (alongtrack dimension).
    Values of xdim = 5 and ldim = 5 are typical, but
    larger or smaller dimensions can be used.
    The iteration value specifies
    the number of times the filter is applied; there is no limit to
    this value.
    Default: contrast enhancement off, xdim = 5, ldim = 5,
    iteration = 1.
    -D

    mode/xdim/ldim/iteration/offset

    Turns on high-pass filtering and sets the filter parameters to be
    used. Here mode specifies the filter type:

            mode = 1 : Boxcar Mean Subtraction Filter

            mode = 2 : Gaussian Mean Subtraction Filter

            mode = 3 : Boxcar Median Subtraction Filter

    The dimensions of the data window used are set using xdim
    (acrosstrack dimension) and ldim (alongtrack dimension).
    Values of xdim = 3 and ldim = 3 are typical, but
    larger dimensions can be used. The iteration value specifies
    the number of times the filter is applied; there is no limit to
    this value, but high-pass filters are generally only applied
    once. The offset value is added to each high-pass filtered
    value to force the results to be positive; this value should be
    chosen according to the range of values allowed in the
    data type and data formats being used (e.g. for SeaBeam 2100
    sidescan as represented in format 41, the sidescan values
    can range from 1 to 65535, so an offset = 1000 is appropriate).
    Default: high-pass filtering off, xdim = 3, ldim = 10,
    iteration = 1, offset = 1000.
    -E

    yr/mo/da/hr/mn/sc

    This option sets the ending time for data allowed in the input data.
    The -B option sets the starting time for data. If the
    starting time is before the ending time, then any data
    with a time stamp before the starting time or after the
    ending time is ignored. If instead the starting time is
    after the ending time, then any data between the ending
    and starting time will be ignored. This scheme allows time
    windowing both inside and outside a specified interval.
    Default: yr/mo/da/hr/mn/sc = 2062/2/21/10/30/0.
    -F

    format

    Sets the MBIO integer format identifier for the input file  specified  with
    the  -I option. By default, mbfilter derives the format id from the mbpro-
    cess parameter file associated with the input file (-I option) or, if  nec-
    essary, infers the format from the "*.mbXX" MB-System suffix convention.
    -H

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

    infile

    Swath data file from which the input data will be read, or a datalist  file
    containing a list of input swath data files and/or other datalist files. If
    infile is a datalist file, then mbprocess will attempt to process all  data
    files identified by recursively reading infile.
    Default: infile = "datalist.mb-1"
    -N

    buffersize

    Sets the maximum number of data records which can be
    read into the buffer. In general, data records may be
    of several different types (e.g. parameter, position,
    comment) in addition to survey data records. Many data
    formats include many more position data records than
    survey data records. Thus, a large buffer may be required
    to access a reasonable number of survey data records.
    However, on memory limited machines large buffer sizes
    can lead to poor performance due to memory swapping.
    The default value of buffersize = 500 is appropriate
    for most cases, but users can set the buffer size as required.
    The absolute maximum buffer size is 5000.
    Default: buffersize = 500.
    -R

    west/east/south/north

    Sets the longitude and latitude bounds within which swath sonar
    data will be read. Only the data which lies within these bounds will
    be copied.
    Default: west=-360, east=360, south=-90, north=90.
    -S

    mode/xdim/ldim/iteration

    Turns on low-pass smoothing filtering and sets the filter
    parameters to be used to
    smooth the data. Here mode specifies the filter type:

            mode = 1 : Boxcar Mean Filter

            mode = 2 : Gaussian Mean Filter

            mode = 3 : Boxcar Median Filter

            mode = 4 : Boxcar Inverse Gradient Filter

    The dimensions of the data window used are set using xdim
    (acrosstrack dimension) and ldim (alongtrack dimension).
    Values of xdim = 3 and ldim = 3 are typical, but
    larger dimensions can be used. The iteration value specifies
    the number of times the filter is applied; there is no limit to
    this value.
    Default: mode = 1, xdim = 3, ldim = 3,
    iteration = 1.
    -T

    threshold_lo/threshold_hi

    This option causes the boxcar median smoothing filter to
    operate with low and high
    ratio thresholds (the value is changed only if the original
    value divided by the median value is less than threshold_lo
    or greater than threshold_hi). This allows the
    filter to preferentially despike the data. In particular, this
    approach is useful for suppressing "stripes" or "bad"
    pings which have amplitude or sidescan values differing significantly
    from surrounding pings. This option only works with the median
    smoothing filter.
    -V

    Normally, mbfilter works "silently" without outputting
    anything to the stderr stream.  If the
    -V flag is given, then mbfilter works in a "verbose"
    mode and outputs the program version being used, the values
    of some important control parameters, and
    all error status messages.

    EXAMPLES

    Suppose one has a SeaBeam 2100 data file called test.mb41
    which contains bathymetry (121 beams in a 120 degree swath),
    beam amplitude (121 beams coincident with bathymetry),
    and sidescan data (2000 pixels, roughly a 150 degree swath)
    which has been corrected for the amplitude vs grazing angle
    variation using the program mbanglecorrect.
    Plots of the corrected sidescan often show a large amount
    of speckle that was suppressed in plots of the raw data
    by the large contrast between the specular and non-specular
    regions of the swath. To reduce the speckle and make coherent
    features of the data clearer, the user can apply any of
    the smoothing filters available in mbfilter. One iteration
    of the boxcar mean filter can be applied as follows:

            mbfilter -F41 -Itest.mb41 -Otest_mean.mb41              -S1/3/3/1

    Five iterations of the inverse gradient filter can be applied as follows:

            mbfilter -F41 -Itest.mb41 -Otest_igrad.mb41             -S4/3/3/5

    To remove large scale variations in seafloor reflectivity, one can
    apply a high-pass filter to the data:

            mbfilter -F41 -Itest.mb41 -Otest_hipass.mb41            -D1/3/10/1/10000

    To first apply a high-pass filter to emphasize fine-scale structure
    and then apply a low-pass filter to reduce speckle:

            mbfilter -F41 -Itest.mb41 -Otest_hipass.mb41            -D1/3/10/1/10000 -S4/3/3/5

    To first reduce speckle by smoothing the data with Gaussian
    mean filter and apply an edge detection contrast enhancement
    filter:

            mbfilter -F41 -Itest.mb41 -Otest_hipass.mb41            -S3/7/7/1 -C1/5/5/1

    SEE ALSO

    mbsystem(l), mbmosaic(l), mbm_plot(l), mbbackangle(l), mbanglecorrect(l)

    REFERENCES

    Sauter, D., and L. Parson, Spatial filtering for speckle reduction,
    contrast enchancement, and texture analysis of GLORIA images,
    IEEE J. Ocean. Eng., 19, 563-576, 1994.

    BUGS

    All the filtering in the world won't make bad data good.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    EXAMPLES
    SEE ALSO
    REFERENCES
    BUGS

Last Updated: 6 June 2010

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

Back to MB-System Home Page...