mbm_grid(1)

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(l), mbgrid(l), mbmosaic(l), mbinfo(l), mbm_grdplot(l)

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