MB-System Unix Manual Page


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


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



Version 5.0



gmt mbcontour -Jparameters -Rwest/east/south/north [-Acont_int/col_int/tic_int/lab_int/tic_int/lab_hgt/lab_spacing -Btickinfo -byr/mo/da/hr/mn/sc -Ccontourfile -ccopies -Dtime_tick/time_annot/date_annot/time_tick_len -Eyr/mo/da/hr/mn/sc -fformat -Fred/green/blue -Gname_hgt[/name_perp] -Iinfile -K -Llonflip -Mpingnumber_tick/pingnumber_annot/pingnumber_tick_len -Nnplot -O -P -ppings -Q -Sspeed -Ttimegap -U -W -Xx-shift -Yy-shift -Zalgorithm -V -H]



mbcontour is a plug-in module for plotting bathymetry contours from swath sonar data using GMT (Generic Mapping Tools). Like mbswath, mbcontour is fully compatible with the GMT package version 5. Two contouring algorithms are available; the -Z option specifies which is used. The first, default approach draws contours between successive pings; this algorithm is simple and therefore fast but produces poor looking contours when beams from one ping lie "behind" beams from a previous ping (this happens for sonars that ping at nonnull pitch angles or for the "inside" beams when ships make sharp turns). The second algorithm constructs a triangular network from the available soundings and contours the network; this approach is complicated and therefore slow but produces good looking contours under most conditions. The contour levels and colors can be controlled directly or set implicitly using contour and color change intervals. Contours can also be set to have ticks pointing downhill.

Shiptracks can also be plotted using the -D, -G, and -M options. The -D option controls the basic track plotting, including time annotation. The -G option causes the start of each swath data file to be annotated with the filename. The -M option controls ping number annotation, or shot number annotation in the case of segy format seismic data.

Before opening an input swath data file, mbcontour 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, mbcontour 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 mbcontour 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 mbswath and mbgrid also use ".inf" files in the same fashion.

In order for GMT to successfully execute mbcontour, 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



If specific contour levels are not specified with the -C option, then contours will be generated in four colors (black, red, green, and blue) with intervals, annotations, and tickmarks controlled by these parameters. Contours will be generated at invervals of cont_int meters. Color changes will occur at intervals of col_int meters. Contours will have downhill facing tickmarks tic_int inches long every tic_int meters. Contours will have annotations label_len inches high every lab_int meters. The origins of contour labels will be separated by at least lab_spacing inches (potentially overlapping labels will be omitted); if lab_spacing = 0.0 then the spacing will be defined by lab_hgt. If fewer than seven parameters are specified, the default values are used for the missing parameters. Defaults: cont_int = 25; col_int = 100; tic_int = 100; lab_int = 100; tic_int = 0.1; lab_hgt = 0.05; lab_spacing = 0.0.
Sets map boundary tickmark intervals. See psbasemap 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 file from which the contour levels and their style and color are read. This file consists of lines in the format:
    level label tick red green blue
where level is the depth value to be contoured in meters, label is either 'a' for annotated or 'n' for not annotated, tick is either 't' for tick marks or 'n' for no tick marks, and red, green, and blue set the color of the contour lines (these values can range from 0 to 255). If a GMT cpt file is given as the contourfile, the color boundaries specified in the cpt file will be interpreted as contour levels to be plotted with unannotated, unticked, black contours. If contours are specified using the -C option, then any use of the -A option will be ignored.
Sets the parameters governing the annotation of the shiptrack. Time marks are made with "X" marks along the shiptrack; annotated time marks show the time in HH:MM format next to the time mark and annotated date marks show the time and julian day in HH:MM/DDD format. The "X" marks are time_tick_len inches high for normal time marks and 1.5 times time_tick_len inches high for annotated time or date marks. The interval of time ticks, annotated time ticks, and annotated date ticks are given in hours by time_tick, time_annot, and date_annot, respectively. Defaults: time_tick = 0.25; time_annot = 1.0; date_annot = 4.0; time_tick_len = 0.1.
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 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.
Sets the color used for Frame and annotation. [Default is black]
Turns on swath file name annotation. The name_hgt parameter sets the height of the lettering in inches. By default, the file name will be plotted along the shiptrack. If the name_perp parameter is given as 1, then the file name will be plotted perpendicular to the shiptrack. The -G option implies track plotting, so if the -D option is not also specified, then track plotting will be turned on with default parameters. Default: name_hgt = 0.1.
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 and by a "fast navigation" or "fnv" file. The "fbt" and "fnv" file naming convention is to add the ".fbt" or ".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. In the event that bathymetry contours is being generated, mbcontour will attempt to read an "fbt" file in lieu of the original data. An "fnv" file contains only navigation information in a compact ASCII format (format 166), and is thus even quicker to read. When mbcontour is only generating a shiptrack plot, it will attempt to read an "fnv" 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.
Sets the parameters governing the pingnumber annotation of the shiptrack. Tick marks are made along the shiptrack at pingnumber_tick intervals; these are time_tick_len inches long. Longer tick marks are made along the shiptrack at pingnumber_annot intervals; these are 1.5 times time_tick_len inches long. Defaults: pingnumber_tick = 50; pingnumber_annot = 100; pingnumber_tick_len = 0.1.
nplot Sets the number of pings to be read in before each contouring episode. See the description of the -Zalgorithm option for advice on reasonable values Default: nplot = 50 unless -Z1 is specified, in which case the default is nplot = 5.
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).
Causes the program to plot the triangles constructed as part of the contouring if the "triangle algorithm" is specified using the -Z1 option. This allows the data distribution to be directly viewed.
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, mbcontour works with bathymetry values in meters. If the -W flag is given, then mbcontour will contour the 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 contouring algorithm to be used. If algorithm=0, a simple ping to ping contouring approach is used; this algorithm is fast but produces poor looking contours when used with data where beams from one ping may lie "behind" beams from previous pings (this happens for sonars that ping at nonnull pitch angles or for the "inside" beams when ships make sharp turns). If algorithm=1 then a triangular network is constructed from the available soundings and this network is in turn contoured; this algorithm is slow but produces good looking contours in most cases. It is important to note that the time required for "triangle" algorithm increases with the square of the number of beams to be contoured; thus it is sensible to keep the number of pings contoured at a time small (e.g. use -N5). The time required for the "ping to ping" algorithm varies linearly with the number of pings contoured; thus larger numbers of pings may be reasonably contoured at a time (e.g. use -N50). Default: algorithm = 0.
Specifies the number of plot copies. [Default is 1]


Suppose the user has a Hydrosweep data file in the L-DEO in-house binary format (MBIO format id 24) called hs_ew9302_161_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 traditional four-color contour plot:
    gmt mbcontour -Idatalist -Jm2.44652         -R-25.7252/-23.0683/59.7415/61.0699
        -Ba0.5314g0.5314         -A50.0/250.0/250.0/250.0/0.01/0.1         -p1 -P -X1 -Y1 -K -V > mbcontour.ps
where the file datalist contains:
    hs_ew9302_161_mn.mb24 24
A plot including a navigation track can also be created using mbcontour. Here the -D flag is used to add a plot of the ship track annotated with time marks every 0.25 hours, annotated time marks every hour, and day annotations every four hours:
    gmt mbcontour -Idatalist -Jm2.44652         -R-25.7252/-23.0683/59.7415/61.0699         -Ba0.5314g0.5314":.File hs_ew9302_161_bmn.mb24:"         -D0.25/1/4/0.1         -A50.0/250.0/250.0/250.0/0.01/0.1         -p1 -P -X1 -Y1 -K -V > hs_ew9302_161_bmn.mb24.ps



mbsystem(1), mbm_plot(1), mbswath(1), gmtsystem(1), psbasemap(1), psto24(1)



Please let us know.




Last Updated: 5 February 2015

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

Back to MB-System Home Page...