MB-System Unix Manual Page: mbswath

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

    mbswath
    Section:  MB-System 5.0  (1)
    Updated:  5 February 2015
    Index

    NAME

    mbswath - GMT plug-in module for color fill or color shaded relief
    swath plots of swath sonar data using Postscript.

    VERSION

    Version 5.0

    SYNOPSIS

    gmt mbswath -Ccptfile -Jparameters
    -Rwest/east/south/north [-Afactor/mode/depth
    -Btickinfo -byr/mo/da/hr/mn/sc
    -ccopies -Dmode/scale/min/max
    -Eyr/mo/da/hr/mn/sc
    -fformat -Fred/green/blue
    -Gmagnitude/azimuth -Idatalist -K
    -Ncptfile -O -P -ppings -Qdpi -Sspeed
    -Ttimegap -U -W -Xx-shift -Yy-shift -Zmode[F]
    -0 -1 -2
    -V -H]

    DESCRIPTION

    mbswath is a plug-in module for plotting swath sonar data in color fill
    or color shaded relief using GMT (Generic Mapping Tools).
    Like mbcontour, mbswath
    is fully compatible with the GMT package version 5, including the use
    of GMT style color pallete (cpt) files to control the color table.
    A 24-bit true color PostScript file is output using one of
    three methods. Unless individual polygon fills are used (-1 option),
    only one call to mbswath can be made for each plot because the
    color image produced covers the entire plot space.
    The program can read data from a single swath sonar file or from
    multiple files as referenced by an MB-System datalist file.

    Before opening an input swath data file, mbmbswath checks for
    an ascii file in the same directory having the same name except
    that ".inf" is appended to the end. The program assumes that this
    ascii file contains the output of the program mbinfo run on
    the input data file. If the ".inf" file exists, mbswath reads
    the minimum and maximum longitude and latitude bounds from the
    mbinfo output and compares those to the bounds
    for the plot. If the ".inf" file indicates that none of the data
    in the input file lies inside the plot bounds, that input
    file is skipped. This allows users to maintain a single master list
    of data files for use in all plotting without the performance penalty
    of mbswath reading through all the data files, even those
    with no relevent data. We recommend that users maintain a ".inf"
    file for each swath data file used for gridding or plotting. The
    GMT modules mbcontour and mbgrid also use ".inf" files
    in the same fashion.

    If mbfilter has been used to filter amplitude and/or sidescan
    data in the desired input, then the -Z option can be used
    to specify plotting the filtered rather than unfiltered data.

    In order for GMT to successfully execute mbswath, the
    location of the shared library libmbgmt containing this module must be known to GMT.
    This can be accomplished by either setting the GMT_CUSTOM_LIBS parameter
    in the file gmt.conf that is part of the GMT installation, by setting
    this parameter in the file gmt.conf in the user's home directory, or by
    using the GMT module gmtset to modify this parameter in the
    current working directory. If, for instance, the libmbgmt shared library
    has been installed in the file /usr/lib/libmbgmt.dylib, then the
    GMT_CUSTOM_LIBS parameter in a gmt.conf file can be set to:

            GMT_CUSTOM_LIBS = /usr/lib/libmbgmt.dylib

    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

    factor/mode/depth

    This option determines how the along-track dimension of the
    beam or pixel footprints is calculated. If mode = 1,
    then the fore-aft beam angle width of the sonar is used so that
    the width increases towards the outer parts of the swath.
    The fore-aft beam angle width (MB-System internally stores
    a value for each format/sonar) is multiplied by the factor
    value; a factor < 1.0 can be useful if the data highly
    oversamples the seafloor and a factor > 1.0 can fill in
    plots of data which undersample the seafloor. If the data
    stream does not include depth values (e.g. one is plotting
    pure sidescan data), then the depth value sets the
    depth value in meters used in the footprint calculations.
    If mode = 2, then the along-track dimension of the beam
    or pixel footprints is just the along-track distance between
    pings multiplied by the factor value.
    If mode = 3, then each data point is plotted as a point,
    and the factor and depth parameters are ignored.
    Default: factor = 1.0, mode = 1, depth = 3000.0.
    -B

    tickinfo

    Sets map boundary tickmark intervals. See the psbasemap
    manual page for details.
    -b

    yr/mo/da/hr/mn/sc

    Sets the starting time for data allowed in the input data; pings
    with times before the starting time will be ignored.
    Default: yr/mo/da/hr/mn/sc = 1962/2/21/10/30/0.
    -C

    Sets the color palette file which controls the color of the plot.
    See documentation of the GMT package for a complete description
    of cpt files.
    -c

    copies

    Specifies the number of plot copies (the default is 1).
    -D

    mode/scale/min/max

    Sets scaling of beam amplitude or sidescan pixel values which
    can be applied before plotting. If mode = 1 or 2, then
    a linear scaling of the form:

            scaled_value = scale * (value - min) / (max - min)

    is applied.  If mode = 3 or 4, then a log10 scaling of
    the form:

            scaled_value = scale * (20 * log10(value) - min) / (max - min)

    is applied.  If mode = 2 or 4, then the value (or 20*log10(value))
    will be clipped to min if it is smaller than min or max
    if it is greater than max; this clipping happens prior to the
    multiplication by scale. Default: mode = 1, scale = 1.0,
    min = 0.0, max = 1.0.
    -E

    yr/mo/da/hr/mn/sc

    Sets the ending time for data allowed in the input data; pings
    with times after the ending time will be ignored.
    Default: yr/mo/da/hr/mn/sc = 2062/2/21/10/30/0.
    -F

    red/green/blue

    Sets the color used for Frame and annotation. [Default is black]
    -f

    format

    Sets the data format used if the input is read from stdin
    or from a file. 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.
    -G

    magnitude/azimuth or magnitude/median

    Sets the parameters which control how mbswath generates
    simulated illumination of bathymetry, which can be either
    shaded relief bathymetry or bathymetry draped with amplitude data.
    If mode is set to 2 (shaded relief bathymetry) using the
    -Z option, then the value magnitude
    is an effective vertical exageration which modulates the intensity of
    the shading; typical values are in the 1-5 range.  The value azimuth
    is the azimuth from which the bathymetry is illuminated.
    If mode is set to 3 (bathymetry shaded using amplitudes) using the
    -Z option, then the value magnitude
    modulates the intensity of the shading; the value median sets the
    amplitude value which serves as the zero or neutral level.
    -H

    This "help" flag cause the program to print out a description
    of its operation and then exit immediately.
    -I

    infile

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

    An input datafile may be accompanied by a "fast bathymetry" or "fbt" file.
    The "fbt" fine naming
    convention is to add the
    ".fbt" suffix to the original swath
    data filename.
    An "fbt" file contains only swath bathymetry information
    in a compact format (format 71),
    and is thus quick to read. If mbswath is
    generating a plot containing only bathymetry
    (-Z1 and -Z2).
    the program
    will attempt to read an "fbt" file in lieu of the original data.
    -J

    Selects the map projection. Scale is inch/degree, 1:xxxxx.
    or width in inches (upper case modifier).

    CYLINDRICAL PROJECTIONS:

    -Jclon0/lat0/scale (Cassini)

    -Jmscale (Mercator)

    -Joalon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)

    -Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)

    -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)

    -Jqlon0/scale (Equidistant Cylindrical Projection (Plate Carree))

    -Jtlon0/scale (TM - Transverse Mercator)

    -Juzone/scale (UTM - Universal Transverse Mercator)

    -Jylon0/lats/scale (Basic Cylindrical Projection)

    AZIMUTHAL PROJECTIONS:

    -Jalon0/lat0/scale (Lambert).

    -Jelon0/lat0/scale (Equidistant).

    -Jglon0/lat0/scale (Orthographic).

    -Jslon0/lat0/scale (General Stereographic)

    CONIC PROJECTIONS:

    -Jblon0/lat0/lat1/lat2/scale (Albers)

    -Jllon0/lat0/lat1/lat2/scale (Lambert)

    MISCELLANEOUS PROJECTIONS:

    -Jhlon0/scale (Hammer)

    -Jilon0/scale (Sinusoidal)

    -Jklon0/scale (Eckert VI)

    -Jnlon0/scale (Robinson)

    -Jrlon0/scale (Winkel Tripel)

    -Jwlon0/scale (Mollweide)

    NON-GEOGRAPHICAL PROJECTIONS:

    -Jpscale (Linear projection for polar (theta,r) coordinates)

    -Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear, log, and power scaling)

    More details can be found in the psbasemap manpages.
    -K

    More PostScript code will be appended later [Default terminates the plot system].
    -L

    lonflip

    Sets the range of the longitude values returned by the swath sonar i/o routines.
    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.
    -N

    cptfile

    Normally, shading of bathymetry with amplitudes (mode = 3
    as set with the -Z option) is accomplished
    by linearly mapping the amplitudes to shade values. This option
    specifies a grayscale cpt file used to map amplitude values
    to grayscale shade values.
    -O

    Selects Overlay plot mode [Default initializes a new plot system].
    -P

    Selects Portrait plotting mode [GMT Default is Landscape, see gmtdefaults to change this].
    -p

    pings

    Sets the ping averaging of the input data. If pings = 1, then
    no ping averaging is performed. 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 (no ping averaging).
    -Q

    dpi

    Sets the resolution of the color image output by mbswath
    in pixels per inch (except when the -1 option is used to force individual
    polygon color fills). Default: dpi = 100.
    -R

    west/east/south/north

    Sets the longitude and latitude bounds within which swath sonar
    data will be read and plotted. Only the data which lies within
    these bounds will be read.
    Default: west=-360, east=360, south=-90, north=90.
    -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
    processed. Default: speed = 0.
    -T

    timegap

    Sets the maximum time gap in minutes between adjacent pings allowed before
    the data is considered to have a gap. Default: timegap = 1.
    -U

    Draw Unix System time stamp on plot.  Optionally, append a label, or 'c' which will plot
    the command string.
    -V

    Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
    -W

    Normally, mbswath works with bathymetry values in meters.  If the
    -W flag is given, then mbswath will work with bathymetry
    values in feet. The color palette file used must conform to the
    range of bathymetry values in feet.
    -X -Y

    Shift origin of plot by (x-shift,y-shift) inches  [Default is (1,1) for new plots, (0,0) for overlays].
    -Z

    mode[F]

    Sets the style of the plot.

            mode = 1:       Color fill of bathymetry data.

            mode = 2:       Color shaded relief bathymetry.

            mode = 3:       Bathymetry shaded using amplitude data.

            mode = 4:       Color fill of amplitude data.

            mode = 5:       Color fill of sidescan data.

    If "F" is appended to mode, then mbswath will attempt
    to plot amplitude or sidescan data that have been filtered with mbfilter.
    If the desired filtered data files do not exist, plotting will fail and
    mbswath will exit with an error message. Filtered amplitude
    data are stored in ancilliary files ending with ".ffa", and filtered
    sidescan files end in ".ffs". Filtering of bathymetry data is not supported,
    and so appending "F" to mode values of 1 or 2 will have no effect.
    Default: mode = 1;
    -0

    Create the image using the Adobe PostScript colorimage operator.
    This is the default.
    -1

    Create the image by plotting individual color polygons.
    -2

    Create the image by color separation using three calls to image for later
    processing by psto24.

    EXAMPLES

    Suppose the user has a Hydrosweep data file in the L-DEO in-house
    binary format (MBIO format id 24) called hs_ew9302_157_mn.mb24
    which lies in the region w/s/e/n = -32.1874/-26.6236/54.6349/56.7536.
    The following will suffice to generate a color fill plot:

            gmt mbswath -Idatalist -Jm1.46578 -R-32.1874/-26.6236/54.6349/56.7536

                    -B1/1 -Ccolor.cpt -p1 -A1 -Q100 -Z2

                    -X1 -Y1.75 -V > mbswath.ps

    where the file datalist contains:

            hs_ew9302_157_mn.mb24 24

    A more complicated plot including a navigation track and a color scale
    can be created using mbswath in conjunction with other GMT
    and GMT-compatible utilities.  The following is an example of a shellscript
    which generates such a plot and then displays it on the screen:

     #

     # Shellscript to create Postscript plot of swath sonar data

     # Created by macro mbm_plot

     #

     # Make datalist file

     echo Making datalist file...

     echo hs_ew9302_157_bmn.mb24 24 > datalist

     #

     # Make color palette table file

     echo Making color palette table file...

     echo 2235 255 255 255 2372 255 221 171 > hs_ew9302_157_bmn.mb24.cpt

     echo 2372 255 221 171 2509 255 186 133 >> hs_ew9302_157_bmn.mb24.cpt

     echo 2509 255 186 133 2646 255 161 68 >> hs_ew9302_157_bmn.mb24.cpt

     echo 2646 255 161 68 2783 255 189 87 >> hs_ew9302_157_bmn.mb24.cpt

     echo 2783 255 189 87 2920 240 236 121 >> hs_ew9302_157_bmn.mb24.cpt

     echo 2920 240 236 121 3057 205 255 162 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3057 205 255 162 3193 138 236 174 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3193 138 236 174 3330 106 235 255 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3330 106 235 255 3467 87 215 255 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3467 87 215 255 3604 50 190 255 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3604 50 190 255 3741 0 160 255 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3741 0 160 255 3878 40 127 251 >> hs_ew9302_157_bmn.mb24.cpt

     echo 3878 40 127 251 4015 21 92 236 >> hs_ew9302_157_bmn.mb24.cpt

     echo 4015 21 92 236 4152 37 57 175 >> hs_ew9302_157_bmn.mb24.cpt

     #

     # Run mbswath

     echo Running mbswath...

     gmt mbswath -Idatalist -Jm1.46578 -R-32.1874/-26.6236/54.6349/56.7536          -B1.1128/1.1128":.Data File hs_ew9302_157_bmn.mb24:"  -Chs_ew9302_157_bmn.mb24.cpt -p1 -A1 -Q100 -G5/0 -Z2 -X1  -Y1.75 -K -V > hs_ew9302_157_bmn.mb24.ps

     #

     # Run mblist

     echo Running mblist...

     mblist -F24 -Ihs_ew9302_157_bmn.mb24 -OXYU > hs_ew9302_157_bmn.mb24.nav

     #

     # Run pstrack

     echo Running pstrack...

     gmt pstrack hs_ew9302_157_bmn.mb24.nav -Jm1.46578      -R-32.1874/-26.6236/54.6349/56.7536 -B1.1128/1.1128":.Data File  hs_ew9302_157_bmn.mb24:" -W1p -Mt15ma1h -O -K >> hs_ew9302_157_bmn.mb24.ps

     #

     # Run psscale

     echo Running psscale...

     gmt psscale  -Chs_ew9302_157_bmn.mb24.cpt -D4.0777/-0.5000/6.5242/0.1500h

            -B":.Depth (meters):" -O -V >> hs_ew9302_157_bmn.mb24.ps

     #

     # Delete surplus files

     echo Deleting surplus files...

     rm -f hs_ew9302_157_bmn.mb24.cpt datalist hs_ew9302_157_bmn.mb24.nav

     #

     # Run pageview

     echo Running gv in background...

     gv hs_ew9302_157_bmn.mb24.ps &

     #

     # All done!

     echo All done!

    SEE ALSO

    mbsystem(1), mbm_plot(1), mbcontour(1),  mbfilter(1),
    gmtsystem(1), psbasemap(1), psto24(1)

    BUGS

    Let us know.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    EXAMPLES
    SEE ALSO
    BUGS

Last Updated: 5 February 2015

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

Back to MB-System Home Page...