mbswath(1)

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 pallette 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 pallette table file
 echo Making color pallette 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(l), mbm_plot(l), mbcontour(l), mbfilter(l), gmtsystem(l), psbasemap(l), psto24(l)

BUGS
Let us know.