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


 
NAME

mbswath - GMT compatible utility for color fill or color shaded relief
swath plots of swath sonar data using Postscript.

 
VERSION

Version 5.0

 
SYNOPSIS

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 utility for plotting swath sonar data in color fill
or color shaded relief using Postscript.  Like mbcontour, mbswath
is fully compatible with the GMT package version 3, 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 stdin (the default) or from one
or more swath sonar files.

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

 
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.



Default: infile = "stdin".
-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:

        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 (assuming
you have a Sun workstation):


 #

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

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

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

 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 pageview in background...

 pageview 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

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

Back to MB-System Home Page...