mbbackangle
Section:  MB-System 5.0  (1)
Updated:  3 June 2013 
Index


 
NAME

mbbackangle - Generates tables of the average amplitude or
sidescan values in swath sonar data as a function of
the grazing angle with the seafloor.

 
VERSION

Version 5.0

 
SYNOPSIS

mbbackangle [-Akind
-C -D -Fformat
-Gkind/angle/max/nx/ny
-Ifile
-Nnangle/anglemax -Ppings -Q
-Rrefangle -Ttopogridfile -Zaltitude -V -H]

 
DESCRIPTION

The program mbbackangle reads a swath sonar data file
containing beam amplitude and/or sidescan data and generates tables
of the average amplitude and/or sidescan values as a function of
the grazing angle with the seafloor. These tables can be used
by the program mbprocess to correct the sidescan or
amplitude data for the variation with grazing angle. No assumption
is made about the nature of the data or the sonar used to
collect it.

The user specifies the angular width
of the swath considered and the number of angular bins in that
swath; the average amplitude or sidescan value within each bin
form the output data. By default, the grazing angle is calculated simply using the
acrosstrack distance and depth at the beam or pixel location.
If bathymetry is not available, the seafloor is assumed to be flat
with a sonar altitude specified by the -Z option.
If the -Q option is used, then the acrosstrack bottom slope
at the beam or pixel location is factored into the grazing angle
values. For bins outside the nadir region (angles > 15.0 degrees
from vertical), the averaging extends over the neighboring bins (three bins
averaged for each value). The user also specifies the number of pings
to be read to generate each table; the default is 50 pings.

The results are written to a file named by
adding a ".sga" suffix to the swath filename for sidescan and
".aga" for amplitude. These files contain a series of amplitude vs.
grazing angle tables, each time tagged according to the average time
of the pings used to generate that table. The swath file's
mbprocess parameter file is also modified (or created if necessary)
so that sidescan or amplitude correction is enabled.

The correction tables are read and interpolated according to ping time
by mbprocess. The correction value for each amplitude or sidescan
sample is also interpolated using the samples apparent grazing angle.
The grazing angle is calculated using a flat bottom assumption
by default but, if the -Q option is used, will instead be
calculated using the acrosstrack slope in the bathymetry (if available) .
If the -T option is used to specify a topography grid of the area
of interest, then the grazing angle is calculated using that grid rather
than any bathymetry data within the file being processed.

If the values are in dB, and therefore log scaled, then the corrections
are subtracted from the raw values and then the value of the correction
table at the reference angle (specified with the -R option) is
added back in. In the case of linear data, the correction operation is
to divide by the correction value and then multiply by the reference
value. At present, only SeaBeam 2100 sidescan values are linear; all
other amplitude and sidescan data supported by MB-System are
in dB.

If the -G option is used, then mbbackangle also generates
gridded histograms of the amplitude versus grazing angle values for
each swath data file processed. The user specifies the bounds and dimensions
of the grids; the -G option must be given twice to produce grids
of both amplitude and sidescan histograms. In addition to outputting the
grids, mbbackangle uses mbm_grdplot to generate GMT
shellscripts that, when executed, will generate plots of the gridded
histograms overlain with the amplitude versus grazing angle tables in
the ".aga" and ".sga" files.

 
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 if beam amplitude (kind = 1)
and/or sidescan (kind = 2) data will be processed.
Default: both amplitude and sidescan data are processed.
-C


Normally, mbbackangle produces a table of amplitude vs
grazing angle values which is asymmetric about the vertical
(zero angle) axis. If -C is specified, the amplitude
vs grazing angle function will be forced to be symmetric.
Generally, it is better to not use this option in mbbackangle,
and to instead use mbset to set symmetric or asymmetric
sidescan correction in the mbprocess parameter file.
-D


This option causes mbbackangle to dump the output to
stdout rather than to ".sga" or ".aga" files..
-F


format



Sets the MBIO integer format identifier
for the input file specified with the
-I option. By default, mbbackangle
infers the format from the "*.mbXX" MB-System suffix
convention.
-G


kind/angle/max/nx/ny



This option causes mbbackangle to output gridded histograms
of the amplitude versus grazing angle data for each swath file
processed. The program also generates a shellscript to produce a
first-cut GMT postscript plot of the histogram overlain by
the amplitude versus grazing angle tables used by mbprocess.
The kind parameter indicates whether an amplitude (kind = 1)
or sidescan (kind = 2) histogram is desired; the -G command
must be given twice (once with kind = 1 and once with kind = 2)
to generate both amplitude and sidescan histograms. The histogram grid
consists of nx bins extending from -angle to +angle degrees in the
x-dimension, and ny bins extending from 0.0 to max in the
y-dimension. The values of the histogram are normalized so that they sum
to 1000.0 within each angle bin.
-H


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


filename



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


nangle/angle



The amplitude vs grazing angle table is calculated by binning the
amplitude values according to their grazing angles and averaging
the amplitudes within each bin. This option sets the number of
grazing angle bins (nangle) and the maximum angle considered
(angle). The grazing angle function will be defined at
nangle points spaced equally from -angle to
+angle. The nangle value should be an odd integer
so that the middle bin is centered on the angle 0.0.
Default: nangle = 81, angle = 80.0.
-P


pings



Sets the number of pings to be read and averaged for each
amplitude vs grazing angle table. The output "*.sga" or ".aga" files
will generally contain many tables, each with a timestamp
corresponding to the average of the ping times used for
each table. A table may be output averaged over a lesser number
of beams if a time gap is encountered in the data, and also at
the end of the file. Default: pings = 50.
-Q


By default, mbbackangle does not use seafloor slopes in
calculating the grazing angles for each amplitude beam and sidescan
pixel. This option causes the program to calculate acrosstrack slopes
from swath bathymetry, if available, and to factor these slopes
into the grazing angle calculation for each data point.
-R


refangle
Sets the reference angle that will be used by mbprocess in
applying the amplitude and/or sidescan correction tables generated
by mbbackangle. Default: refangle = 30.0 degrees.
-T


topogridfile
By default, mbbackangle does not use seafloor slopes in
calculating the grazing angles for each amplitude beam and sidescan
pixel. This option causes the program to calculate acrosstrack slopes
using the topography grid topogridfile, and to factor these slopes
into the grazing angle calculation for each data point.
-V


Normally, mbbackangle works "silently" without outputting
anything to the stderr stream.  If the
-V flag is given, then mbmask works in a "verbose" mode and
outputs the program version being used and all error status messages.
-Z


depth



This option specifies a default sonar altitude value in meters to be
used whenever bathymetry values are unavailable. A flat seafloor
(zero slope) will be assumed wherever the default depth needs
to be used (e.g. data files with sidescan but no bathymetry, or
the outer parts of swaths where the sidescan may extend further
than the bathymetry). If this option is not specified, any
amplitude or sidescan values without associated bathymetry
information will not be used in calculating the amplitude
vs grazing angle table.


 
EXAMPLE

Suppose one has a Simrad EM300 data file called

       0003_20020425_022926.mb57
which contains 131 pings. In order to correct the beam amplitude and sidescan
with mbprocess, first use mbbackangle to generate the
amplitude vs grazing angle tables:

        mbbackangle -I mbari_1998_988_msn.mb57 \


                        -N81/80.0 -P50 \


                        -G1/80/60/81/121 \


                        -G2/80/60/81/121 \


                        -V




Here the angle bins will be 2.0 degree wide, the table
will extend from -80.0 degees (port) to +80.0 (starboard),
and each table will represent the averages over up to 50
pings. The output looks like:


        Program mbbackangle


        Version $Id: mbbackangle.1 2096 2013-06-04 08:17:22Z caress $


        MB-system Version 5.0.4



        Pings to average:    50


        Number of angle bins: 81


        Maximum angle:         80.000000


        Default altitude:      0.000000


        Working on beam amplitude data...


        Working on sidescan data...


        Using flat bottom assumption in calculating correction tables...


        Outputting gridded histograms of beam amplitude vs grazing angle...


        Outputting gridded histograms of sidescan amplitude vs grazing angle...



        processing swath file: mbari_1998_988_msn.mb57 57



        7274 records processed


        805564 amplitude data processed


        146 tables written to mbari_1998_988_msn.mb57.aga


        5371412 sidescan data processed


        146 tables written to mbari_1998_988_msn.mb57.sga



        Plot generation shellscript <mbari_1998_988_msn.mb57_aga.grd.cmd> created.


        Plot generation shellscript <mbari_1998_988_msn.mb57_sga.grd.cmd> created.



        7274 total records processed


        805564 total amplitude data processed


        146 total aga tables written


        5371412 total sidescan data processed


        146 total sga tables written


The output files include the amplitude versus grazing angle tables in
mbari_1998_988_msn.mb57.aga and mbari_1998_988_msn.mb57.sga, the
gridded histogram files mbari_1998_988_msn.mb57_aga.grd and
mbari_1998_988_msn.mb57_sga.grd, and the plotting shellscripts
mbari_1998_988_msn.mb57_aga.grd.cmd and
mbari_1998_988_msn.mb57_sga.grd.cmd. The mbprocess parameter file
mbari_1998_988_msn.mb57.par has also been either
created (if necessary) or modified to enable sidescan
correction using the ".sga" tables. The first of the six tables
in mbari_1998_988_msn.mb57.sga looks like:

        ## Sidescan correction table files generated by program mbbackangle


        ## Version $Id: mbbackangle.1 2096 2013-06-04 08:17:22Z caress $


        ## MB-system Version 5.0.4


        ## Table file format: 1.0.0


        ## Run by user <caress> on cpu <hess> at <Fri Oct  1 11:18:30 2004>


        ## Input swath file:      mbari_1998_988_msn.mb57


        ## Input swath format:    57


        ## Output table file:     mbari_1998_988_msn.mb57.sga


        ## Pings to average:      50


        ## Number of angle bins:  81


        ## Maximum angle:         80.000000


        ## Default altitude:      0.000000


        ## Data type:             sidescan


        # table: 0


        # nping: 50


        # time:  1998/06/10 14:55:24.979779    897490524.979780


        # nangles: 81


        -80.0000       0.0000       0.0000


        -78.0000       0.0000       0.0000


        -76.0000       0.0000       0.0000


        -74.0000       0.0000       0.0000


        -72.0000       0.0000       0.0000


        -70.0000       0.0000       0.0000


        -68.0000       0.0000       0.0000


        -66.0000       0.0000       0.0000


        -64.0000      33.4828       7.5915


        -62.0000      32.4068       5.4016


        -60.0000      31.9667       5.3320


        -58.0000      31.7880       5.1880


        -56.0000      31.6249       5.0681


        -54.0000      31.6362       4.9521


        -52.0000      31.5590       5.0482


        -50.0000      31.3955       5.1242


        -48.0000      31.0372       5.2364


        -46.0000      30.9569       5.1092


        -44.0000      30.8126       4.9848


        -42.0000      30.3497       4.9611


        -40.0000      29.7660       4.9479


        -38.0000      29.2746       4.9727


        -36.0000      29.1929       4.9734


        -34.0000      29.1729       4.9893


        -32.0000      28.7375       5.0295


        -30.0000      28.6560       5.0031


        -28.0000      28.0609       5.1757


        -26.0000      27.3652       5.2692


        -24.0000      26.2536       5.1193


        -22.0000      25.2113       4.8437


        -20.0000      24.9033       4.5717


        -18.0000      24.4118       4.5952


        -16.0000      24.4341       4.5824


        -14.0000      24.3251       4.7864


        -12.0000      23.6965       4.1409


        -10.0000      24.1326       3.7653


        -8.0000      26.1912       4.2246


        -6.0000      27.9516       4.5724


        -4.0000      31.1992       5.6401


        -2.0000      29.2624       5.8076


         0.0000      27.4466       4.3310


         2.0000      24.9780       4.1345


         4.0000      24.2328       4.0980


         6.0000      23.3917       4.6856


         8.0000      24.0867       4.5882


        10.0000      23.2293       4.6383


        12.0000      24.1375       4.5005


        14.0000      25.1402       4.6843


        16.0000      25.1948       4.9131


        18.0000      25.0986       5.0503


        20.0000      25.0798       5.0769


        22.0000      25.0582       5.1801


        24.0000      25.6108       5.1108


        26.0000      25.8393       5.0068


        28.0000      26.3232       4.9469


        30.0000      26.4346       5.0686


        32.0000      26.6474       5.1690


        34.0000      27.0092       5.2098


        36.0000      27.1987       5.1664


        38.0000      27.3710       5.2504


        40.0000      27.1160       5.1788


        42.0000      27.0691       5.1418


        44.0000      27.2547       4.8907


        46.0000      27.7406       4.9654


        48.0000      28.1568       4.9277


        50.0000      28.4015       4.9687


        52.0000      28.4042       4.9034


        54.0000      28.3741       4.9500


        56.0000      28.5195       4.9799


        58.0000      28.6455       5.0142


        60.0000      28.9284       4.9876


        62.0000      28.9028       5.0380


        64.0000       0.0000       0.0000


        66.0000       0.0000       0.0000


        68.0000       0.0000       0.0000


        70.0000       0.0000       0.0000


        72.0000       0.0000       0.0000


        74.0000       0.0000       0.0000


        76.0000       0.0000       0.0000


        78.0000       0.0000       0.0000


        80.0000       0.0000       0.0000


        #


        #


 
SEE ALSO

mbsystem(1), mbprocess(1), mbset(1), mbfilter(1)

 
BUGS

None worth bragging about.



 
Index

NAME

VERSION

SYNOPSIS

DESCRIPTION

AUTHORSHIP

OPTIONS

EXAMPLE

SEE ALSO

BUGS

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

Back to MB-System Home Page...