MB-System Unix Manual Page

mbm_plot

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

NAME

mbm_plot - Create an executable shellscript which will generate a GMT plot of swath sonar swath data.

VERSION

Version 5.0

SYNOPSIS

mbm_plot -Fformat -Ifile [-A[magnitude[/azimuth] -C[cont_int/col_int/tic_int/lab_int/tic_len/lab_hgt] -D[flipcolor/flipshade] -Gcolor_mode[F] -H -N[ttick/tannot/dannot/tlen[/nhgt] | F | FP] -Oroot -Ppagesize -S[color/shade] -T -Uorientation -V -W[color_style[/palette[ncolors]] | cptfile] ]

Additional Options:
[-Btickinfo -Jprojection[/scale | width] -Ltitle[:scale_label] -Mmisc -Q -Rw/e/s/n -X -Y -Zmin/max ]

Miscellaneous Options:
[-MGDgmtdef/value -MGFscale_loc -MGL[f][x]lon0/lat0/slat/length[m] -MGQdpi -MGTx/y/size/angle/font/just/text -MGU[/dx/dy/][label] -MMAfactor/mode/depth -MMByr/mo/da/hr/mn/sc -MMDmode/scale[/min/max] -MMEyr/mo/da/hr/mn/sc -MMLlonflip -MMNnplot -MMPpings -MMSspeedmin -MMTtimegap -MMZalgorithm -MNA[nhgt[/P] | P] -MNP[pingnumber_tick/pingnumber_annot/pingnumber_tick_len] -MTCfill -MTDresolution -MTGfill -MTIriver[/pen] -MTNborder[/pen] -MTSfill -MTWpen -MXGfill -MXIxy_file -MXM -MXSsymbol/size -MXWpen]

DESCRIPTION

mbm_plot is a macro to generate a shellscript of MB-System and GMT commands which, when executed, will generate a Postscript plot of the specified swath sonar data. The plot may include bathymetry color fill (-G1), bathymetry color shaded relief (-G2), bathymetry shaded with amplitudes (-G3), greyshade fill amplitude (-G4), greyshade fill sidescan (-G5), contoured bathymetry (-C), or annotated navigation. The plot may also include navigation tracks, text labels, xy data in lines or symbols, and coastlines. Five different color schemes are included. The plot will be scaled to fit on the specified page size or, if the scale is user defined, the page size will be chosen in accordance with the plot size. The primary purpose of this macro is to allow the simple, semi-automated production of nice looking maps with a few command line arguments. For users seeking more control over the plot appearance, a number of additional optional arguments are provided. Truly ambitious users may edit the plot shellscript to take advantage of MB-System and GMT capabilities not supported by this macro.

AUTHORSHIP

David W. Caress (caress@mbari.org)

  Monterey Bay Aquarium Research Institute
Dale N. Chayes (dale@ldeo.columbia.edu)

  Lamont-Doherty Earth Observatory

  Suzanne H. O'Hara (sohara@ldeo.columbia.edu)

  Lamont-Doherty Earth Observatory

SIMPLE DESCRIPTION OF BASIC OPTIONS

-A

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

-C

Given by itself, the -C option produces a contour plot of the bathymetry data with a contour interval chosen according to the data in the file or files. If the -G option is used, the default contours will be drawn in black; otherwise, the default contours will be drawn in four colors (black, red, green, and blue) with color changes, annotations, and tickmarks every fourth contour interval. Additional optional parameters are described in the COMPLETE DESCRIPTION OF OPTIONS section below.

-D

[flipcolor/flipshade]
This option flips the color and shading conventions used by mbm_plot. Normally, the color or grayscale tables used for color bathymetry maps run from cool colors (or dark grays) for large depth values to hot colors (or light grays) for small depth values. In contrast, sidescan and beam amplitude data is normally plotted using light grays (or hot colors) for small amplitudes and dark grays (or cool colors) for large amplitudes. If -D is given alone or with flipcolor = 1, it applies to the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or by overlaying amplitude data (-G3 option), then setting flipshade = 1 will cause the shading convention to be reversed (e.g. high amplitudes overlaid as light shading). Using -D0/1 will flip the shading convention but leave the default color convention.

-F

format
Sets the data format for the input data. 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

mode[F]
Turns on color fill swath plot and 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:       Grayscale fill of amplitude data.

        mode = 5:       Grayscale fill of sidescan data.

If "F" is appended to mode, then mbm_plot will attempt to plot amplitude or sidescan data that have been filtered with mbfilter. If the desired filtered data files do not exist, then the plotting script generated by mbm_plot will fail when mbswath exits 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.

-H

This "help" flag cause the program to print out a description of its operation and then exit immediately.

-I

filename
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 (the default), 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 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 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. The default input filename is "datalist.mb-1".

-N

Given by itself, this option causes a navigation track plot to be generated. Additional optional parameters, including annotation control, are described in the COMPLETE DESCRIPTION OF OPTIONS section below.

-O

root
Sets the root used to construct the filename of the output shellscript (root.cmd) and names of files created when the shellscript is run. By default, the name of the input data file or list file is used as the root.

-P

pagesize
This option sets the size of the page the plot will be centered on. If the user does not set the plot scale, the plot will be sized as large as will fit on the designated page. If the user sets the plot scale such that the plot will not fit on the designated page, a larger page will be used. The supported page sizes include ANSI A, B, C, D, E, F, and E1, as well as most metric page sizes. See the COMPLETE DESCRIPTION OF OPTIONS section below for a complete list of the supported page sizes. The default page size is A.

-S

[color/shade]
This option enables effective histogram equalization of the color and/or shading of thedata. The equalization is not achieved by changing the data values, but rather by constructing the color or shading tables so that the boundaries in the tables encompass equal fractions of the datapoints. This serves to focus color or shading contrasts in value ranges corresponding to the bulk of the data values, and is particularly useful for enhancing the contrast of sidescan and beam amplitude plots. If -S is given alone or with color = 1, it enables equalization of the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or by overlaying amplitude data (-G3 option), then setting shade = 1 will cause the shading to be equalized. Using -S0/1 will equalize the shading without equalizing the color table.

-T

If -T is given, it causes a coastline to be drawn on the map. The default is to draw the coastline and shade all dry land a uniform gray. To exercise greater control of the coastline plotting, use the -MTC, -MTD, -MTG, -MTI, -MTN, -MTS, and -MTW options described in the COMPLETE DESCRIPTION OF OPTIONS section below.

-U

orientation
Normally the orientation of the plot (portrait or landscape) is selected automatically so as to maximize the plot scale. The -U option allows the user to set the plot orientation. If orientation = 1, a portrait plot will be produced; if orientation = 2, a landscape plot will be produced.

-V

Causes mbm_plot to operate in "verbose" mode so that it outputs more information than usual.

-W

[color_style[/palette[ncolors]] | cptfile]
This option controls the color scheme used for color fill plots.

If color_style = 1 [default], then the color scheme used will be a continuous grading of colors. If color_style = 2, the color scheme will be a set of discrete color intervals. The color palette used is set using palette. Five palettes are available:
        palette = 1:    Haxby colors [default]

        palette = 2:    high Intensity colors

        palette = 3:    low Intensity colors

        palette = 4:    grayscale

        palette = 5:    uniform grayscale

A complete description of the color palettes is given in the COMPLETE DESCRIPTION OF OPTIONS section below.

The ncolors parameter sets the number of color values used in plotting, whether the colors are represented in a continuous color scale or a stepped, discrete color scale [default is 11].

If the option argument is the path to an existing GMT color palette (CPT) file, then that CPT file and its color scheme will be used for the plot

COMPLETE DESCRIPTION OF OPTIONS

-A

magnitude/azimuth or magnitude/median
Sets the parameters which control how mbm_plot 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 -G 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 -G 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.

-B

tickinfo
Sets map boundary tickmark intervals. See the psbasemap manual page for details. By default the program chooses basemap annotations based on the map boundaries.

-C

[cont_int/col_int/tic_int/lab_int/tic_len/lab_hgt]
Given by itself, the -C option produces a contour plot of the bathymetry data with a contour interval chosen according to the data in the file or files. If the -G option is used, the default contours will be drawn in black; otherwise, the default contours will be drawn in four colors (black, red, green, and blue) with color changes, annotations, and tickmarks every fourth contour interval. If any of the optional parameters are appended, these values will control the contour interval and other contour characteristics. 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_len inches long every tic_int meters. Contours will have annotations lab_hgt inches high every lab_int meters.

-D

[flipcolor/flipshade]
This option flips the color and shading conventions used by mbm_plot. Normally, the color or grayscale tables used for color bathymetry maps run from cool colors (or dark grays) for large depth values to hot colors (or light grays) for small depth values. In contrast, sidescan and beam amplitude data is normally plotted using (light grays (or hot colors) for small amplitudes and dark grays (or cool colors) for large amplitudes. If -D is given alone or with flipcolor = 1, it applies to the color table used for color or gray fill plots, shaded or unshaded. If the plot is to be shaded, either by synthetic illumination (-G2) or by overlaying amplitude data (-G3 option), then setting flipshade = 1 will cause the shading convention to be reversed (e.g. high amplitudes overlaid as light shading). Using -D0/1 will flip the shading convention but leave the default color convention.

-F

-G

mode
Turns on color fill swath plot and 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:       Grayscale fill of amplitude data.

        mode = 5:       Grayscale fill of sidescan data.

-H

This "help" flag cause the program to print out a description of its operation and then exit immediately.

-I

-J

projection[/scale | /width]
Selects the map projection. By default the map projection is Mercator and the plot scale is chosen to fit on the selected page size (see -P option). The user may specify a different projection to be used, in which case the plot scale is still automatically chosen to fit the page. The user may also specify both the projection and the plot scale. If the projection specifying character is upper case, a plot width rather than a plot scale is used. The scale values are specified in inch/degree or in 1:xxxxx ratios. Plot widths are specified in inches. If the user specifies a plot scale such that the plot will not fit on the default A size page, a appropriately larger page size will be chosen.

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.

-L

title:scalelabel
Sets the title and the label for the colorscale (if used) of the plot. Note that a colon (:) rather than a slash (/) is used to separate the labels. Colons cannot be used in the labels themselves. If this option is not used, then a default title and colorscale label are provided. If the title is supplied alone, a default colorscale label will be provided. To force no title use -L" "; to force no title or colorscale label use -L" : ".

-M

A series of "miscellaneous" options are provided which are given as -M followed by a two character identifier, followed by any other parameters associated with that option. The -M options may be strung together separated by colons, e.g. "-MGQ100:GU", which is equivalent to "-MGQ -MGU".

-MGD

gmtdef/value
Allows the user to set the GMT default values used as the plot is constructed. This command may be given repeatedly to set as many GMT defaults as required. For example, to set the basemap annotation font to Courier, use "-MGDANOT_FONT/Courier".

-MGF

scale_loc
Sets the location of the color scale. The possible values of scale_loc are:
        scale_loc = b:  bottom of plot

        scale_loc = t:  top of plot

        scale_loc = l:  left of plot

        scale_loc = r:  right of plot

[Default scale_loc = b]

-MGL

[f][x]lon0/lat0/slat/length[m]
Draws a simple map scale centered on lon0/lat0. Use -Lx to specify position in inch instead. Scale is calculated at latitude slat, length is in km [miles if m is appended]. Use -Lf to get a "fancy" scale [Default is plain].

-MGQ

dpi
Sets the resolution in dots per inch of the raster image used for color fill maps. Larger values of dpi produce larger Postscript plot files. [Default is 100].

-MGT

x/y/size/angle/font/just/text
Causes a text label to plotted on the map. size is text size in points, angle is measured in degrees counter-clockwise from horizontal, fontno sets the font type, justify sets the alignment. If fontno starts with a leading hyphen, then the remainder of fontno is taken to be a textstring with the desired fontname. See the gmtdefaults man page for names and numbers of available fonts (or run pstext -L). The alignment number refers to the part of the textstring that will be mapped onto the (x,y) point: 1 = Lower Left corner, 2 = Lower Center, 3 = Lower Right, 5 = Mid Left, 6 = Mid Center, 7 = Mid Right, 9 = Upper Left, 10 = Upper Center, 11 = Upper Right. This option may be given as many times as needed.

-MGU

[/dx/dy/][label]
Draw Unix System time stamp on plot. User may specify where the lower left corner of the stamp should fall on the page relative to lower left corner of plot in inch [Default is (-0.75,-0.75)]. Optionally, append a label, or c (which will plot the command string.)

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

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

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

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

-MMLlonflip

If the -R option is not used to explicitly set the plot bounds, then the lonflip value sets the range of the longitude values used for calculating the desired bounds. 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: mbm_plot uses the lonflip value set by mbdefaults.

-MMNnplot

Sets the number of pings to be read in before each contouring episode. See the description of the -MMZalgorithm option for advice on reasonable values Default: nplot = 50 unless -MMZ1 is specified, in which case the default is nplot = 5.

-MMPpings

Sets the ping averaging of the input swath sonar 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).

-MMSspeedmin

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.

-MMT

timegap
Sets the maximum time gap in minutes between adjacent pings allowed before the data is considered to have a gap. Default: timegap = 1.

-MMZ

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 unless format = 41.

-MNA

[nhgt[/P] | P]
Turns on filename annotation of navigation tracks. If -MNA is given without specifying any controlling parameters, then the lettering height nhgt is 0.15 and the filenames are plotted parallel to the navigation track from the start of the track. The lettering height can be specified using either -MNAnhgt or -MNAnhgt/P. If -MNAP or -MNAnhgt/P is specified, the filename will be plotted perpendicular to the navigation track. Filename annotation can also be specified using the -N option. Defaults: Filename annotation off.

-MNP

[pingnumber_tick/pingnumber_annot/pingnumber_tick_len]
Turns on ping number (or shot number) annotation of navigation tracks. Tick marks are made along the shiptrack at pingnumber_tick intervals; these are tlen inches long. Longer tick marks are made along the shiptrack at pingnumber_annot intervals; these are 1.5 times tlen inches long. Defaults: Pingnumber annotation off. If the -MNP option is given without specifying the controlling parameters, then pingnumber_tick = 50, pingnumber_annot = 100, and pingnumber_tick_len = 0.1.

-MTC

fill
Coastline plotting option. Set the shade (0-255), color (r/g/b), or pattern (p|Pdpi/pattern; see -MTG) for lakes [Default is the fill chosen for "wet" areas (-S)].

-MTD

resolution
Coastline plotting option. Selects the resolution of the coastline data set to use ((f)ull, (h)igh, (i)ntermediate, (1)ow, and (c)rude). The resolution drops off by 80% between data sets. [Default is l].

-MTG

fill
Coastline plotting option. Select painting or clipping of "dry" areas. Append a shade, color, pattern, or c for clipping. Specify the shade (0-255) or color (r/g/b), or -MTGpdpi/pattern, where pattern gives the number of the built-in pattern (1-90) OR the name of a Sun 1-, 8-, or 24-bit raster file. dpi sets the resolution of the image. See GMT Cookbook & Technical Reference Appendix E for information on individual patterns.

-MTI

river[/pen]
Coastline plotting option. Draw rivers. Specify the type of rivers and [optionally] append pen attributes [Default pen: width = 1, color = 0/0/0, texture = solid]. Choose from the list of river types below. Repeat option -I as often as necessary.
     1 = Permanent major rivers
     2 = Additional major rivers
     3 = Additional rivers
     4 = Minor rivers
     5 = Intermittent rivers - major
     6 = Intermittent rivers - additional
     7 = Intermittent rivers - minor
     8 = Major canals
     9 = Minor canals
     10 = Irrigation canals
     a = All rivers and canals (1-10)
     r = All permanent rivers (1-4)
     i = All intermittent rivers (5-7)
     c = All canals (8-10)

-MTN

border[/pen]
Coastline plotting option. Draw political boundaries. Specify the type of boundary and [optionally] append pen attributes [Default pen: width = 1, color = 0/0/0, texture = solid]. Choose from the list of boundaries below. Repeat option -MTN as often as necessary.
     1 = National boundaries
     2 = State boundaries within the Americas
     3 = Marine boundaries
     a = All boundaries (1-3)

-MTS

fill
Coastline plotting option. Select painting or clipping of "wet" areas. Append the shade (0-255), color (r/g/b), pattern (see -MTG), or c for clipping.

-MTW

pen
Coastline plotting option. Append pen attributes [Defaults: width = 1, color = 0/0/0, texture = solid].

-MXG

fill
Select filling of symbols for xy plotting. Set the shade (0-255) or color (r/g/b) [Default is no fill]. To reset no fill, use fill = "N". For polygons, you may optionally specify -Gpicon_size/pattern, where pattern gives the number of the image pattern (1-32) OR the name of a icon-format file. icon_size sets the unit size in inch. To invert black and white pixels, use -GP instead of -Gp. See GMTs Cookbook & Technical Reference Appendix E for information on individual patterns.

-MXI

xy_file
Specifies a file containing (x,y) pairs to be plotted as lines or symbols. The line and symbol characteristics are set using the last -MXG, -MXS, and -MXW options used. All of the -MX commands can be given multiple times, so by stringing series of these commands together the user can plot different files using different line or symbol characteristics. [Default is a solid black line].

-MXM

Toggles expectation for xy data files having multiple segments, in which each segment is to be plotted separately. Segments are separated by a record whose first character is '>'. By default, unsegmented files are expected. Users may give this command multiple times, allowing some input files to be handled as segmented and others not.

-MXS

symbol/size
Selects symbol to be used for plotting the next xy data file. Setting symbol = "N" causes line plotting. Choose between:

-MXSa

star. size is radius of circumscribing circle.

-MXSb

bar extending from base to y. size is bar width. By default, base = 0. Append /base to change this value. Append u if size is in x-units [Default is inch].

-MXSc

circle. size is diameter of circle.

-MXSd

diamond. size is side of diamond.

-MXSe

ellipse. Direction (in degrees counterclockwise from horizontal), major_axis (in inch), and minor_axis (in inch) must be found in columns 3, 4, and 5.

-MXSf

fault. Give distance gap between ticks and ticklength in inch. If gap is negative, it is interpreted to mean number of ticks instead. Append l or r to draw tick on the left or right side of line [Default is centered]. Upper case L or R draws a triangle instead of line segment.

-MXSh

hexagon. Give side in inch.

-MXSi

inverted triangle. Give side in inch.

-MXSl

letter or text string. Give size in inch, and append /string after the size. Note that the size is only approximate; no individual scaling is done for different characters. Remember to escape special characters like *.

-MXSp

point. No size needs to be specified (1 pixel is used).

-MXSs

square. Give side in inch.

-MXSt

triangle. Give side in inch.

-MXSv

vector. Direction (in degrees counterclockwise from horizontal) and length (in inch) must be found in columns 3 and 4. size, if present, will be interpreted as arrowwidth/headlength/headwidth (in inch) [Default is 0.03/0.12/0.1 inch]. By default arrow attributes remains invariant to the length of the arrow. To have the size of the vector scale down with decreasing size, append nnorm, where vectors shorter than norm will have their attributes scaled by length/norm.

-MXSV

Same as -MXSv, except azimuth (in degrees east of north) should be given instead of direction. The azimuth will be mapped into an angle based on the chosen map projection (-MXSv leaves the directions unchanged.)

-MXSx

cross. Give length in inch.

-MXW

pen
Set pen attributes for xy plotting. See chapter 4.12 in the GMT Technical reference for a discussion of GMT pen values. [Defaults: width = 1, color = 0/0/0, texture = solid].

-N

[ttick/tannot/dannot/tlen[/nhgt/nperp]] | F | FP]
This option causes a navigation track plot to be generated, and can also set the start of each swath file to be annotated with the filename. If the -N option is given alone, then the navigation track will be plotted without any annotation, The optional parameters allow users to control the details of the navigation track annotation. 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 tlen inches high for normal time marks and 1.5 times tlen 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 ttick, tannot, and dannot, respectively. If the nhgt parameter is not given when the other parameters are specified, then no filename annotation will be done. If given, nhgt sets the height in inches of the filename annotation and turns that annotation on. If given as 1, nperp causes the filename annotation to be perpendicular to the shiptrack rather than parallel (the default). If the -NF is given, then a navigation track will be generated using the default parameters and also with filename annotation along the shiptrack. If the -NFP is given, then a navigation track will be generated with the default parameters and also with filename annotation perpendicular to the shiptrack. Defaults if annotation is enabled: ttick = 0.25; tannot = 1.0; dannot = 4.0; tlen = 0.1; nhgt = 0.1; nperp = 0.

-O

-P

          American ANSI sizes:
          A     8.5 x 11.0 in.    ( 215.9 x  279.4 mm)
          B    11.0 x 17.0 in.    ( 279.4 x  431.8 mm)
          C    17.0 x 22.0 in.    ( 431.8 x  558.8 mm)
          D    22.0 x 34.0 in.    ( 558.8 x  863.6 mm)
          E    34.0 x 44.0 in.    ( 863.6 x 1117.6 mm)
          F    28.0 x 40.0 in.    ( 711.2 x 1016.0 mm)
          E1   44.0 x 68.0 in.    (1117.6 x 1727.2 mm)

          Metric ISO A sizes:
          A0   841.0 x 1189.0 mm  (33.11 x 46.81 in.)
          A1   594.0 x  841.0 mm  (23.39 x 33.11 in.)
          A2   420.0 x  594.0 mm  (16.54 x 23.39 in.)
          A3   297.0 x  420.0 mm  (11.69 x 16.54 in.)
          A4   210.0 x  297.0 mm  ( 8.27 x 11.69 in.)
          A5   148.0 x  210.0 mm  ( 5.83 x  8.27 in.)
          A6   105.0 x  148.0 mm  ( 4.13 x  5.83 in.)
          A7    74.0 x  105.0 mm  ( 2.91 x  4.13 in.)
          A8    52.0 x   74.0 mm  ( 2.05 x  2.91 in.)
          A9    37.0 x   52.0 mm  ( 1.46 x  2.05 in.)
          A10   26.0 x   37.0 mm  ( 1.02 x  1.46 in.)

          Metric ISO B sizes:
          B0   1000.0x 1414.0 mm  (39.37 x 55.67 in.)
          B1   707.0 x 1000.0 mm  (27.83 x 39.37 in.)
          B2   500.0 x  707.0 mm  (19.68 x 27.83 in.)
          B3   353.0 x  500.0 mm  (13.90 x 19.68 in.)
          B4   250.0 x  353.0 mm  ( 9.84 x 13.90 in.)
          B5   176.0 x  250.0 mm  ( 6.93 x  9.84 in.)
          B6   125.0 x  176.0 mm  ( 4.92 x  6.93 in.)
          B7    88.0 x  125.0 mm  ( 3.46 x  4.92 in.)
          B8    62.0 x   88.0 mm  ( 2.44 x  3.46 in.)
          B9    44.0 x   62.0 mm  ( 1.73 x  2.44 in.)
          B10   31.0 x   44.0 mm  ( 1.22 x  1.73 in.)

          Metric ISO C sizes:
          C0   914.4 x 1300.5 mm  (36.00 x 51.20 in.)
          C1   650.2 x  914.4 mm  (25.60 x 36.00 in.)
          C2   457.2 x  650.2 mm  (18.00 x 25.60 in.)
          C3   325.1 x  457.2 mm  (12.80 x 18.00 in.)
          C4   228.6 x  325.1 mm  ( 9.00 x 12.80 in.)
          C5   162.6 x  228.6 mm  ( 6.40 x  9.00 in.)
          C6   114.3 x  162.6 mm  ( 4.50 x  6.40 in.)
          C7    81.3 x  114.3 mm  ( 3.20 x  4.50 in.)

         MB-System large format sizes:

          m1  1371.6 x 1828.8 mm  (54.00 x 72.00 in.)
          m2  1371.6 x 2133.6 mm  (54.00 x 84.00 in.)
          m3  1371.6 x 2438.4 mm  (54.00 x 96.00 in.)
          m4  1524.0 x 1828.8 mm  (60.00 x 72.00 in.)
          m5  1524.0 x 2133.6 mm  (60.00 x 84.00 in.)
          m6  1524.0 x 2438.4 mm  (60.00 x 96.00 in.)

The default page size is A.

-Q

Normally, the output plot generation shellscript includes lines which execute a program to display the Postscript image on the screen. This option causes those lines to be commented out so that executing the shellscript produces a Postscript plot but does not attempt to display it on the screen. The program to be used to display the Postscript is set using mbdefaults; the default value can be overridden by setting the environment variable $MB_PS_VIEWER.

-R

west/east/south/north
Sets the longitude and latitude bounds within which swath sonar data will be read. Normally the bounds are automatically chosen to include all of the input data.

-S

-T

-U

-V

Causes mbm_plot to operate in "verbose" mode so that it outputs more information than usual.

-W

[color_style[/palette[ncolors]] | cptfile]
This option controls the color scheme used for color fill plots.

If color_style = 1 [default], then the color scheme used will be a continuous grading of colors. If color_style = 2, the color scheme will be a set of discrete color intervals. The color palette used is set using palette. Seven palettes are available:
        palette = 1:    Haxby colors [default]

        palette = 2:    high Intensity colors

        palette = 3:    low Intensity colors

        palette = 4:    grayscale

        palette = 5:    uniform grayscale

        palette = 6:    uniform black

        palette = 7:    uniform white

The RGB definitions of the color palettes are:

color palette 1 - Haxby Color Table
  red:   255 255 255 255 240 205 138 106  50  40  37
  green: 255 186 161 189 236 255 236 235 190 127  57
  blue:  255 133  68  87 121 162 174 255 255 251 175

color palette 2 - High Intensity Colors
  red:   255 255 255 255 128   0   0   0   0 128 255
  green:   0  64 128 255 255 255 255 128   0   0   0
  blue:    0   0   0   0   0   0 255 255 255 255 255

color palette 3 - Low Intensity Colors
  red:   200 194 179 141  90   0   0   0   0  90 141
  green:   0  49  90 141 179 200 141  90   0   0   0
  blue:    0   0   0   0   0   0 141 179 200 179 141

color palette 4 - Grayscale
  red:   255 230 204 179 153 128 102  77  51  26   0
  green: 255 230 204 179 153 128 102  77  51  26   0
  blue:  255 230 204 179 153 128 102  77  51  26   0

color palette 5 - Uniform Grayscale
  red:   128 128 128 128 128 128 128 128 128 128 128
  green: 128 128 128 128 128 128 128 128 128 128 128
  blue:  128 128 128 128 128 128 128 128 128 128 128

color palette 6 - Uniform Black
  red:     0   0   0   0   0   0   0   0   0   0   0
  green:   0   0   0   0   0   0   0   0   0   0   0
  blue:    0   0   0   0   0   0   0   0   0   0   0

color palette 7 - Uniform White
  red:   255 255 255 255 255 255 255 255 255 255 255
  green: 255 255 255 255 255 255 255 255 255 255 255
  blue:  255 255 255 255 255 255 255 255 255 255 255

The Haxby colors have been adapted from a palette developed by Dr. William Haxby of the Lamont-Doherty Earth Observatory; this palette is pleasing to the eye and well suited for shading. The high intensity colors describe linear paths through RGB space from red to blue to green to purple; because the colors are high intensity they are not well suited to shading. The low intensity colors are similar to the high intensity, but muted and thus well suited to shading. The grayscale palette runs linearly from white to black and is commonly used for plots of sidescan and amplitude data. The uniform grayscale is useful for non-color shaded relief plots.

The ncolors parameter sets the number of color values used in plotting, whether the colors are represented in a continuous color scale or a stepped, discrete color scale [default is 11].

If the option argument is the path to an existing GMT color palette (CPT) file, then that CPT file and its color scheme will be used for the plot

-X

Normally, mbm_plot creates an executable shellscript and then exits. This option will cause the shellscript to be executed in the background before mbm_plot exits.

-Y

Normally, mbm_plot generates nicely rounded numbers for the boundaries of the color palette. Often, the resulting color bounds extend well outside the range of the gridded data. This option causes the color boundaries to be uniformly distributed between the minimum and maximum values of the grid.

-Z

min/max
This option overrides the minimum and maximum values of bathymetry data, affecting the color palette and the contour interval if those parameters are not specified by the user.

EXAMPLES

Suppose we have obtained a swath sonar data file called sb2112_example.mb41 collected using a SeaBeam 2112 sonar. This file contains bathymetry, beam amplitude, and sidescan data. In order to obtain initial views of the data in the file, we use mbm_plot to generate shellscripts which in turn generate plots when executed. The following five commands generate plotting shellscripts for color fill bathymetry overlaid with contours, color shaded relief bathymetry, color fill bathymetry overlaid with amplitudes, grayscale amplitudes, and grayscale sidescan, respectively:

        mbm_plot -F41 -I sb2112_example.mb41 -G1 -C    \

                -N -V -Obathcont

        mbm_plot -F41 -I sb2112_example.mb41 -G2       \

                -N -V -Obathshade

        mbm_plot -F41 -I sb2112_example.mb41 -G3 -S0/1 \

                -N -V -Obathamp

        mbm_plot -F41 -I sb2112_example.mb41 -G4 -S    \

                -N -V -Oamp

        mbm_plot -F41 -I sb2112_example.mb41 -G5 -S    \

                -N -V -Oss

When the following shellscripts are executed, each will generate a postscript plot file and then display the plot on the screen:

        bathcont.cmd

        bathshade.cmd

        bathamp.cmd

        amp.cmd

        ss.cmd

Note that we use the -S option to apply histogram equalization to the amplitude and sidescan data, but not the bathymetry data. Also note that by specifying -N we obtain a track plot of the ship's navigation overlaid on the color or grayscale file plots.

Now suppose we have a set of SeaBeam 2112 data files comprising a short survey and that we want a plot of all the data together. We create an ASCII text file which has a list of the filenames, each followed by the appropriate MBIO format id number, e.g.:

        sb2112_example_1.mb41 41

        sb2112_example_2.mb41 41

        sb2112_example_3.mb41 41

If the name of the data file list is "datalist", then using "-F-1 -Idatalist" will cause the macro to operate on all of the files together. We desire a plot including color fill bathymetry overlaid with 25 meter contours and the ship's navigation. For this plot, we want a very bright colortable and we would like the colors to be discretely stepped rather than continuous; thus we use -W2/2. We also choose to use the -X option, which causes mbm_plot to execute the shellscript it creates in the background before exiting. The mbm_plot command is:

mbm_plot -F-1 -Idatalist -G1 -C25 -N \

-X -V -Obathtest

As an example, the contents of the plotting shellscript "bathtest.cmd" are:

#
# Shellscript to create Postscript plot of swath sonar data
# Created by macro mbm_plot
#
# This shellscript created by following command line:
# mbm_plot -F-1 -Idatalist -G1 -C25 -N -V -Obathtest
#
# Save existing GMT defaults
echo Saving GMT defaults...
gmtdefaults -L > gmtdefaults$$
#
# Set new GMT defaults
echo Setting new GMT defaults...
gmtset ANOT_FONT Helvetica
gmtset LABEL_FONT Helvetica
gmtset HEADER_FONT Helvetica
gmtset ANOT_FONT_SIZE 8
gmtset LABEL_FONT_SIZE 8
gmtset HEADER_FONT_SIZE 10
gmtset FRAME_WIDTH 0.074999999999999997
gmtset TICK_LENGTH 0.074999999999999997
gmtset PAGE_ORIENTATION LANDSCAPE
gmtset COLOR_BACKGROUND 0/0/0
gmtset COLOR_FOREGROUND 255/255/255
gmtset COLOR_NAN 255/255/255
#
# Make color palette table file
echo Making color palette table file...
echo   2975 255 255 255   3150 255 186 133 > bathtest.cpt
echo   3150 255 186 133   3325 255 161  68 >> bathtest.cpt
echo   3325 255 161  68   3500 255 189  87 >> bathtest.cpt
echo   3500 255 189  87   3675 240 236 121 >> bathtest.cpt
echo   3675 240 236 121   3850 205 255 162 >> bathtest.cpt
echo   3850 205 255 162   4025 138 236 174 >> bathtest.cpt
echo   4025 138 236 174   4200 106 235 255 >> bathtest.cpt
echo   4200 106 235 255   4375  50 190 255 >> bathtest.cpt
echo   4375  50 190 255   4550  40 127 251 >> bathtest.cpt
echo   4550  40 127 251   4725  37  57 175 >> bathtest.cpt
#
# Run mbswath
echo Running mbswath...
mbswath -f-1 -Idatalist \
        -Jm22.198543775528325 \

        -R114.210795/114.430905/-31.91322/-31.62458 \

        -Cbathtest.cpt \

        -p1 -A1 -Z1 \

        -p1 \

        -P -X1.8069392647842304 -Y2 -K -V > bathtest.ps

#
# Run mbcontour
echo Running mbcontour...
mbcontour -f-1 -Idatalist \
        -Jm22.198543775528325 \

        -R114.210795/114.430905/-31.91322/-31.62458 \

        -A50/100000/100000/100000/0.01/0.1 \

        -D0.25/1/4/0.15 \

        -p1 \

        -P -K -O -V >> bathtest.ps

#
# Make color scale
echo Running psscale...
psscale -Cbathtest.cpt \
        -D2.4431/-0.5000/4.8861/0.1500h \

        -B":.Depth (meters):" \

        -P -K -O -V >> bathtest.ps

#
# Make basemap
echo Running psbasemap...
psbasemap -Jm22.198543775528325 \
        -R114.210795/114.430905/-31.91322/-31.62458 \

        -B5m/5m:."Data List File datalist": \

        -P -O -V >> bathtest.ps

#
# Delete surplus files
echo Deleting surplus files...
rm -f bathtest.cpt
#
# Reset GMT default fonts
echo Resetting GMT fonts...
mv gmtdefaults$$ .gmtdefaults
#
# Run xpsview
echo Running xpsview in background...
xpsview -ps a -maxp 4m bathtest.ps &
#
# All done!
echo All done!