MB-System Unix Manual Page: mbcontour

### MB-System Unix Manual Page

#

##

##

##

##

##

##

##

##

##

##

    mbcontour
    Section:  MB-System 5.0  (1)
    Updated:  26 October 2009
    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.0000/250.0000/250.0000/250.0000/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":.Data File hs_ew9302_161_bmn.mb24:"

                    -D0.25/1/4/0.1 -A50.0000/250.0000/250.0000/250.0000/0.01/0.1

                    -p1 -P -X1 -Y1 -K -V > hs_ew9302_161_bmn.mb24.ps

    SEE ALSO

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

    BUGS

    Please let us know.

     Index

    NAME
    VERSION
    SYNOPSIS
    DESCRIPTION
    AUTHORSHIP
    OPTIONS
    EXAMPLES
    SEE ALSO
    BUGS

Last Updated: 26 October 2009

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

Back to MB-System Home Page...