DESCRIPTION

mbm_grid is a macro to generate a shellscript of MB-System commands
which, when executed, will generate a grid or mosaic of the
specified swath sonar data. The grid or mosaic may be of
bathymetry (positive down, -A1),
topography (positive up, -A2),
amplitude (-A3), or sidescan data (-A4).
The primary purpose of this
macro is to allow the simple, semi-automated production of
grids and mosaics with a few command line arguments. The macro
can determine the area covered by the swath data and set the
grid bounds and dimensions accordingly. For users
seeking more control over the grid and mosaic parameters,
almost the full suite of mbgrid and mbmosaic commands are supported.
See the manual pages for mbgrid and mbmosaic for
complete explanations of how these programs work.

By default, mbgrid and mbmosaic generate grids in Geographic coordinates,
meaning that position is defined in longitude and latitude using
the WGS84 horizontal datum. The -J option can be used to specify
an alternate, projected coordinate system (PCS). When a PCS is used,
position will be defined in eastings and northings (meters) relative
to the origin of the particular PCS. Universal Transverse Mercator
is the most commonly used PCS in the oceanographic community, but
mbgrid supports a large number of other PCS as well. A list of
the supported PCS's is provided at the end of the mbgrid and
mbmosaic manual pages.

clip
Sets the clipping dimension for the spline interpolation. If clip=0
no spline interpolation will be done. If clip>0

-K

background
Enables filling in all undefined grid cells with bathymetry or topography
from a global or regional database accessed with the GMT program
grdraster. The background specifies which locally defined
database is accessed with grdraster.
then the spline
interpolation will fill data gaps to a distance of clip times
the grid spacing.
Default: clip = 0.

-D

xdim/ydim
Sets the dimensions of the output grid.
This option is superceded
if the user specifies the grid spacing with the -E option.
Default: xdim = ydim = 101.

-E

dx/dy/units
Sets the grid cell spacing to dx in longitude and dy
in latitude. If units is not specified, the dx
and dy values are assumed to be in meters. Valid values
for units include "km", "meters", and "degrees".
By default, the grid spacing is calculated from
the grid bounds and the grid dimensions. When the user
uses the -E option to set the grid spacing, the
grid dimensions are calculated using the grid bounds and
grid cell spacings. However, slight adjustments to the
grid cell spacing values are usually required to keep
the grid bounds as specified.

-F

format
Sets the data format for the input data.
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 = -1.

-f

mode
Sets the gridding algorithm to be used by mbgrid for bathymetry
(-A1) or topography c data.
mode = 1: Gaussian Weighted Mean

priority_range
Turns on Gaussian weighted mean mosaicing in mbmosaic
for amplitude (-A3) or sidescan (-A4) data. The
priority_range value determines which data points are
used in the mosaicing. The minimum priority threshold for
each bin is the highest priority value found among the
samples in that bin minus the priority_range value.
Only samples with priorities greater than this threshold
are used in the Gaussian weighted mean mosaicing.
The default is to simply set each bin's value equal to the
value of the highest priority sample in that bin.

If gridkind = 3, mbgrid also outputs shellscripts
which run GMT version 3 programs to provide preliminary color
fill maps of the gridded data. These shellscripts are
generated using the mbm_grdplot macro.
Default: gridkind = 3.

-H

This "help" flag cause 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 (the default),
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
the data in each one of these files.
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.

-J

projection
By default, mbgrid and mbmosaic generate grids in Geographic coordinates,
meaning that position is defined in longitude and latitude using
the WGS84 geographic coordinate system.
The -J option can be used to specify
an alternate, projected coordinate system (PCS). When a PCS is used,
position will be defined in eastings and northings (meters) relative
to the origin of the particular PCS. Universal Transverse Mercator
is the most commonly used PCS in the oceanographic community, but
mbgrid supports a large number of other PCS's as well.
The underlying projection functions derive from the PROJ.4 library
written by Gerald Evenden, then of the U.S. Geological Survey.

The projection argument for the -J option can be either
a PCS identifier from the projection definition list provided at the
end of this manual page, or simply -JU to specify using
UTM in whatever zone is appropriate for the grid bounds specified
with the -R option.

For instance, to fully specify a particular northern UTM
zone, set projection = UTMXXN where XX gives
the UTM zone (defined from 01 to 60). As an example, a northern UTM
zone 12 projection can be specified using -JUTM12N.
Southern UTM zones are specified as UTMXXS. The European Petroleum
Survey Group (EPSG) has defined a large number of PCS's used worldwide
and assigned number id's to each; one can also specify the northern
UTM zone 12 projection using its EPSG designation,
or -Jepsg32612.
When the projected coordinate system is fully specified
by the -J option, then the grid bounds may be specified using
-R in either longitude and latitude or in eastings and northings.

Alternatively, one may indicate a UTM projection without specifying the
zone by using -JU. In this case, the
UTM zone will be inferred from the midpoint of the
specified longitude and latitude bounds, and then the
longitude and latitude bounds given with the
-fR option are translated to UTM eastings and northings.

All grids and mosaics produced by MB-System
programs contain identifiers that are recognized
by the plotting macros mbm_grdplot,
mbm_grd3dplot, and mbm_grdtiff.
These plotting macros automatically use a
linear map projection whenever they
encounter grids and mosaics that are already
in a projected coordinate system. Also, the program mbgrdtiff
automatically inserts the appropriate projection information into
the GeoTIFF images it generates. As a result, images generated by
mbgrdtiff will be properly georeferenced when they are imported
into GIS software.

-K

background
The -Kbackground option is used to underlay a bathymetry or topography
grid with a global or regional topography model. The background data
model is accessed from a database using the GMT program grdraster.
The background value is an identifier number used to specify which
dataset to extract using grdraster. These identifiers are user
defined and vary with installations. When the -Kbackground
option is invoked, grdraster is used to extract all of the longitude,
latitude, and topography values within the specified database that lie
within the desired grid. These values are interpolated onto the desired
grid locations using the thin plate spline algorithm, and then mapped onto
the grid wherever the values are undefined by either swath data or the
spline interpolation invoked with the -C option.

-L

lonflip
Sets the range of the longitude values returned.
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

Causes two additional grids to be output. One is a grid containing
the standard deviation of the data within each grid cell relative
to the grid value, the other contains the number of data
points in each grid cell. This option is ignored when the minimum
or maximum filter gridding algorithms are used (see the -F option).

-N

Causes grid cells with no data and no interpolation to be set to a
value of NaN instead of the default value of 99999.9. The NaN value
is expected by GMT programs such grdview.

-O

root
Sets the character string to be used as the root of the
output filenames. For example, if the grid is output as a GMT
version 2 GRD format (netCDF) file (the default),
then its filename is "root.grd". If the
-G1 option is used to specify an ascii format grid, then the
output grid filename will be "root.asc". If the
-G2 option is used to specify a version 1 GRD
format (binary) grid, then the
output grid filename will be "root.grd1". If the output grid is
in the GMT version 2 GRD format, a shellscript
which will allow the contents of the grid to viewed using GMT programs
is also output with the filename "root.grd.cmd".

-P

pings
Sets the ping averaging of the input data. If pings > 0, then
that number of input pings will be averaged to produce one output
ping. If pings = 0, then the ping averaging will automatically
be done so that the along-track ping spacing is equal to the across-track
beam spacing. Default: pings = 1.

-Q

Normally, bathymetry or topography data is gridded in meters. If
this option is used, bathymetry or topography data is gridded
in feet.

-R

west/east/south/north
Sets the longitude and latitude bounds of the output grid. If the user
uses the -E option to set the grid spacing, then the dimensions
will be calculated from the grid bounds and spacing. In these
circumstances rounding errors will usually require that the eastern
and northern bounds be adjusted to fit exactly with the
grid dimensions and spacing.

tension
Sets the tension value used in the thin plate spline interpolation.

A tension of 0 gives a minimum curvature surface with free edges;
this is a pure Laplacian solution. A nonzero tension tends to
suppress spurious oscillations and flatten
the interpolation toward the edges; a tension of infinity
yields a pure spline solution. The tension must be zero or
greater.
Default: tension = 1.0e10 (pure spline solution).

-U

time
Forces mbgrid to avoid averaging overlapping swaths by
ignoring the data from later swaths. "Later" data is identified
using the time value. The time of the first data point
is saved for each bin in the grid; any other data points which
are more than time minutes before or after the initial
data point in the relevent bin are ignored. If time is
negative, the last data in a bin (within the time lag criterea)
will be saved and used instead of the first data.

-U

azimuth/factor
Enables prioritizing data points according to their look azimuth
(data on the port side of the swath have
a look azimuth equal to the heading - 90 degrees, and data on the
starboard side have a look azimuth equal to the heading + 90 degrees).
Here azimuth is the preferred look azimuth, and factor
modulates how rapidly the priority degrades away from the preferred
look azimuth. The priority (p) for a data point is assigned as follows:
p = cos(f * (Ap - Al))
when -90 < (f * (Ap - Al)) < 90 and
p = 0
otherwise, where f = factor, Ap = azimuth, and Al is the
look azimuth of the data point.
If factor = 1.0, the priority will be 1.0
at azimuth and will fall to zero for look
azimuths more than 90 degrees away from azimuth.
If factor > 1.0, the range of nonzero priorities will shrink
to azimuths closer to azimuth (e.g. if factor = 2.0,
nonzero priorities will be restricted to look azimuths within
45 degrees of azimuth). If factor < 1.0, the
range of nonzero priorities will expand (e.g. if factor = 0.5, only
look azimuths 180 degrees away from azimuth
will have a zero priority).

-V

The -V option causes mbm_grid to print out statements
indicating its progress.

-W

scale
Sets the width of the gaussian weighting function in terms of
the grid spacing. The distance to the 1/e point of the weighting
function is given by half of the grid spacing times scale.
Default: scale = 1.0

-X

extend
Extends the size of the internal grid so that the output grid is a
subset from the center of a larger grid. This allows data outside
the output grid to guide the spline interpolation of data gaps which
happen to lie at the the edge of the output grid. The amount of
extension is extend times the grid width/height to each side.
Thus, if extend=1.0, then the internal grid will have dimensions
three times the output grid.
Default: extend = 0.0

-Y

priority_file
Enables priortization of data points based on their apparent
grazing angle (this angle is the
arctan(x/z) where x is acrosstrack distance and z is depth, so
that the center of the swath has an apparent grazing angle of
zero, the port swath edge has a large negative angle, and the
starboard swath edge has a large positive angle). The file
priority_file must contain a list of data priorities
as a function of apparent grazing angle. The first line of
the file should contain the minimum, or port-most grazing angle
followed by the associated priority. The following lines
should contain increasingly large grazing angles (and associated
priorities) up to the maximum, or starboard-most, grazing angle.
The highest priority assigned should be one, and the lowest zero.
Priorities for grazing angles less than the minimum or greater
than the maximum will be zero. See the examples below for a
further explanation of the use of priority_file.

-Z

bath_default
Sets the default depth used for calculating grazing angles for
amplitude or sidescan values where depths are not available.
Default: scale = 1000.0

EXAMPLES

Suppose we have obtained a swath sonar data file called
example_hs.mb24 collected using a SeaBeam 2112 sonar.
This file contains bathymetry, beam amplitude, and
sidescan data. In order to obtain a first cut bathymetry
grid and first cut amplitude and sidescan mosaics, we
use mbm_grid to generate shellscripts which in turn
run mbgrid or mbmosaic to generate grids and mosaics.
The following four commands generate gridding shellscripts
for bathymetry, topography, amplitude, and sidescan,
respectively:

mbm_grid -F24 -I example_hs.mb24 \-A1 -V -Obath

mbm_grid -F24 -I example_hs.mb24 \

-A2 -V -Otopo

mbm_grid -F24 -I example_hs.mb24 \

-A3 -V -Oamp

mbm_grid -F24 -I example_hs.mb24 \

-A4 -V -Oss

When the following shellscripts are executed, each will
generate a both a grid (or mosaic) file and an additional
shellscript which in turn will (when run) generate and display a
postscript plot file:

bath_mbgrid.cmd

topo_mbgrid.cmd

amp_mbmosaic.cmd

ss_mbmosaic.cmd

The program mbinfo is executed by mbm_grid
to obtain the file statistics used to determine the grid
bounds and bin size. The macro mbm_grdplot is executed
by mbgrid or mbmosaic to generate the initial
plots of the gridded data.

As an example, the contents of the gridding shellscript
"bath_mbgrid.cmd" are: