MB-System Unix Manual Page

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

 

MB-SYSTEM AUTHORSHIP

David W. Caress

  Monterey Bay Aquarium Research Institute
Dale N. Chayes

  Center for Coastal and Ocean Mapping

  University of New Hampshire
Christian do Santos Ferreira

  MARUM - Center for Marine Environmental Sciences

  University of Bremen

 

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$

        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$

        ## 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
MB-SYSTEM AUTHORSHIP
OPTIONS
EXAMPLE
SEE ALSO
BUGS


Last Updated: