MB-System Unix Manual Page


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


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



Version 5.0



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]



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



David W. Caress (caress@mbari.org)

  Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)

  Lamont-Doherty Earth Observatory



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.
Sets map boundary tickmark intervals. See the psbasemap manual page for details.
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.
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.
Specifies the number of plot copies (the default is 1).
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.
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.
Sets the color used for Frame and annotation. [Default is black]
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.
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.
This "help" flag cause the program to print out a description of its operation and then exit immediately.
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.
Selects the map projection. Scale is inch/degree, 1:xxxxx. or width in inches (upper case modifier).


-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)


-Jalon0/lat0/scale (Lambert).
-Jelon0/lat0/scale (Equidistant).
-Jglon0/lat0/scale (Orthographic).
-Jslon0/lat0/scale (General Stereographic)


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


-Jhlon0/scale (Hammer)
-Jilon0/scale (Sinusoidal)
-Jklon0/scale (Eckert VI)
-Jnlon0/scale (Robinson)
-Jrlon0/scale (Winkel Tripel)
-Jwlon0/scale (Mollweide)


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

More PostScript code will be appended later [Default terminates the plot system].
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.
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.
Selects Overlay plot mode [Default initializes a new plot system].
Selects Portrait plotting mode [GMT Default is Landscape, see gmtdefaults to change this].
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).
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.
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.
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.
Sets the maximum time gap in minutes between adjacent pings allowed before the data is considered to have a gap. Default: timegap = 1.
Draw Unix System time stamp on plot. Optionally, append a label, or 'c' which will plot the command string.
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
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].
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;
Create the image using the Adobe PostScript colorimage operator. This is the default.
Create the image by plotting individual color polygons.
Create the image by color separation using three calls to image for later processing by psto24.


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!



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



Let us know.




Last Updated: 5 February 2015

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

Back to MB-System Home Page...