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


 
NAME

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

 
VERSION

Version 5.0

 
SYNOPSIS

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]

 
DESCRIPTION

mbcontour is a utility for swath contouring of swath bathymetry
data using Postscript.  Like mbswath, mbcontour
is fully compatible with the GMT package version 4. 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
programs mbswath and mbgrid also use ".inf" files
in the same fashion.

 
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


cont_int/col_int/tic_int/lab_int/tic_len/lab_hgt/lab_spacing



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


tickinfo



Sets map boundary tickmark intervals. See psbasemap 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


contourfile



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


time_tick/time_annot/date_annot/time_tick_len



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


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


red/green/blue



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


name_hgt[/name_perp]



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



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


pingnumber_tick/pingnumber_annot/pingnumber_tick_len



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


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


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.
-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, 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].
-Z


algorithm



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]

 
EXAMPLES

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:

    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:

    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

 
SEE ALSO

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

 
BUGS

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