MB-System Unix Manual Page: mbm_grid

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

    mbm_grid
    Section:  MB-System 5.0  (1)
    Updated:  26 October 2009
    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(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!.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    EXAMPLES
    SEE ALSO
    BUGS

Last Updated: 26 October 2009

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

Back to MB-System Home Page...