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


 
NAME

mbm_grid - Create an executable shellscript which will generate
a grid (bathymetry or topography) or mosaic (amplitude or sidescan)
of swath sonar swath data.

 
VERSION

Version 5.0

 
SYNOPSIS

mbm_grid -Ifile
-Fformat -Oroot
-Rwest/east/south/north
[-Adatatype -Bborder -Cclip
-Dxdim/ydim -Edx/dy/units
{-fpriority_range | -fmode}
-Ggridkind -H
-Jprojection -Kbackground
-Llonflip -M -N -Ppings
-Sspeed -Ttension
-U{azimuth/factor | time}
-V -Wscale -Xextend
-Ypriority_file -Zbathdef]

 
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.

 
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


datatype



Sets the type of data to be read and gridded or mosaiced.
If datatype = 1,
bathymetry data will be gridded (positive downwards).
If datatype = 2,
bathymetry data will be gridded as topography (positive upwards).
If datatype = 3,
amplitude data will be mosaiced.  If datatype = 4,
sidescan data will be mosaiced.
Default: datatype = 1 (bathymetry).
-B


border



Sets the border of a smoothly interpolated grid
to the value border
wherever no data exist, provided border > 0.0.
Default: border = 0.0
-C


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


        mode = 2:         Median Filter


        mode = 3:         Minimum Filter


        mode = 4:         Maximum Filter

The default is mode = 1 (Gaussian Weighted Mean).
-f


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


gridkind



Sets the format of the output grid file.

        gridkind = 1:   Ascii table


        gridkind = 2:   binary file (GMT version 1 GRD file)


        gridkind = 3:   netCDF file (GMT version 2 GRD file)




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


speed



Sets the minimum speed in km/hr (5.5 kts ~ 10 km/hr) allowed in
the input data; pings associated with a smaller ship speed will not be
output. Default: speed = 0.
-T


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:


 #! /bin/csh -f

 #

 # Shellscript to grid or mosaic swath sonar data

 # Created by macro mbm_grid

 #

 # This shellscript created by following command line:

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

 #

 # Define shell variables used in this script:

 set REGION       = -49.316085/-49.096415/12.06972/12.18588

 set INPUT_FILE   = example_hs.mb24

 set INPUT_FORMAT = 24

 set ROOT         = bath

 #

 # Make datalist file

 echo Making datalist file...

 echo $INPUT_FILE $INPUT_FORMAT >! datalist$$

 #

 # Run mbgrid

 echo Running mbgrid...

 mbgrid -Idatalist$$ \

        -R$REGION \


        -O$ROOT \


        -A1 -N \


        -E363.3/363.3/meters \


 #

 # All done!

 echo All done!

 
SEE ALSO

mbsystem(1), mbgrid(1),
mbmosaic(1), mbinfo(1),
mbm_grdplot(1)

 
BUGS

This macro is new and hasn't been tested in serious
usage yet - let us know what to fix, add, or
change!.



 
Index

NAME

VERSION

SYNOPSIS

DESCRIPTION

AUTHORSHIP

OPTIONS

EXAMPLES

SEE ALSO

BUGS

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

Back to MB-System Home Page...