plot3d¶

Plot lines, polygons, and symbols in 3-D

Synopsis¶

gmt plot3d [ table ] -Jparameters -Jz|Zparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] [ -A[m|p|x|y] ] [ -B[p|s]parameters ] [ -Ccpt ] [ -Ddx/dy[/dz] ] [ -Gfill|+z ] [ -I[intens] ] [ -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen] ] [ -N ] [ -Q ] [ -S[symbol][size][/size_y] ] [ -U[stamp] ] [ -V[level] ] [ -W[pen][attr] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -Zvalue|file] [ -aflags ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -qiflags ] [ -ttransp ] [ -:[i|o] ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description¶

Reads (x,y,z) triplets from files [or standard input] and will plot lines, polygons, or symbols at those locations in 3-D. If a symbol is selected and no symbol size given, then we will interpret the fourth column of the input data as symbol size. Symbols whose size is <= 0 are skipped. If no symbols are specified then the symbol code (see -S below) must be present as last column in the input. If -S is not used, a line connecting the data points will be drawn instead. To explicitly close polygons, use -L. Select a fill with -G. If -G is set, -W will control whether the polygon outline is drawn or not. If a symbol is selected, -G and -W determines the fill and outline/no outline, respectively.

Required Arguments¶

-Jparameters (more …): Select map projection.

-Jz|Zparameters (more …): Set z-axis scaling; same syntax as -Jx.

-Rxmin/xmax/ymin/ymax[+r][+uunit] (more …): Specify the region of interest.

For perspective view -p, optionally append /zmin/zmax. (more …)

Optional Arguments¶

table: One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input.

-A[m|p|x|y]: By default, geographic line segments are drawn as great circle arcs by resampling coarse input data along such arcs. To disable this sampling and draw them as straight lines, use the -A flag. Alternatively, add m to draw the line by first following a meridian, then a parallel. Or append p to start following a parallel, then a meridian. (This can be practical to draw a line along parallels, for example). For Cartesian data, points are simply connected, unless you append x or y to draw stair-case curves that whose first move is along x or y, respectively. Note: The -A option requires constant z-coordinates.

-B[p|s]parameters (more …): Set map boundary frame and axes attributes.

-Ccpt: Give a CPT or specify -Ccolor1,color2[,color3,…] to build a linear continuous CPT from those colors automatically. In this case colorn can be a r/g/b triplet, a color name, or an HTML hexadecimal color (e.g. #aabbcc ). If -S is set, let symbol fill color be determined by the t-value in the fourth column. Additional fields are shifted over by one column (optional size would be in 5th rather than 4th field, etc.). An exception to this rule is for multi-band 3-D columns where each band gets its color from each slice in the CPT. If -S is not set, then we expect the user to supply a multisegment file (where each segment header contains a -Zval string. The val will control the color of the line or polygon (if -L is set) via the CPT. If modern mode and no argument is given then we select the current CPT.

-Ddx/dy[/dz]: Offset the plot symbol or line locations by the given amounts dx/dy[dz] [Default is no offset].

-Gfill (more …): Select color or pattern for filling of symbols or polygons [Default is no fill]. Note that the module will search for -G and -W strings in all the segment headers and let any values thus found over-ride the command line settings. If -Z is set, use -G+z to assign fill color via -Ccpt and the z-values obtained.

-Iintens: Use the supplied intens value (nominally in the -1 to +1 range) to modulate the fill color by simulating illumination [none]. If no intensity is provided we will instead read intens from the first data column after the symbol parameters (if given).

-L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]: Force closed polygons. Alternatively, append modifiers to build a polygon from a line segment. Append +d to build symmetrical envelope around y(x) using deviations dy(x) given in extra column 4. Append +D to build asymmetrical envelope around y(x) using deviations dy1(x) and dy2(x) from extra columns 4-5. Append +b to build asymmetrical envelope around y(x) using bounds yl(x) and yh(x) from extra columns 4-5. Append +xl|r|x0 to connect first and last point to anchor points at either xmin, xmax, or x0, or append +yb|t|y0 to connect first and last point to anchor points at either ymin, ymax, or y0. Polygon may be painted (-G) and optionally outlined by adding +ppen [no outline]. All constructed polygons are assumed to have a constant z value. Note: When options like -G and -Z are passed via segment headers you will need -L to ensure your segments are interpreted as polygons.

-N[c|r]: Do NOT clip symbols that fall outside map border [Default plots points whose coordinates are strictly inside the map border only]. The option does not apply to lines and polygons which are always clipped to the map region. For periodic (360-longitude) maps we must plot all symbols twice in case they are clipped by the repeating boundary. The -N will turn off clipping and not plot repeating symbols. Use -Nr to turn off clipping but retain the plotting of such repeating symbols, or use -Nc to retain clipping but turn off plotting of repeating symbols.

-Q: Turn off the automatic sorting of items based on their distance from the viewer. The default is to sort the items so that items in the foreground are plotted after items in the background.

-S[symbol][size][/size_y]

Plot symbols. If present, size is symbol size in the unit set in gmt.conf (unless c, i, or p is appended). If the symbol code (see below) is not given it will be read from the last column in the input data; this cannot be used in conjunction with binary input. Optionally, append c, i, or p to indicate that the size information in the input data is in units of cm, inch, or point, respectively [Default is PROJ_LENGTH_UNIT]. Note: If you give both size and symbol via the input file you must use PROJ_LENGTH_UNIT to indicate the units used for the symbol size or append the units to the size in the file. Some 2-dimensional symbols optionally take a second size via size_y. If symbol sizes are expected via the fourth data column then you may convert those values to suitable symbol sizes via the -i mechanism. The general input expectations are:

*x y z* [ *w* ] [ *size* ] [ *symbol-parameters* ] [ *symbol* ]

where the optional w is required when -C is used, the optional size is required when no symbol size is specified, and the trailing text with the symbol code is required when symbol code is not specified on the command line. The symbol-parameters may vary in numbers; see specifics below.

The uppercase symbols A, C, D, G, H, I, N, S, T are normalized to have the same area as a circle with diameter size, while the size of the corresponding lowercase symbols refers to the diameter of a circumscribed circle.

You can change symbols by adding the required -S option to any of your multisegment headers.

Choose between these symbol codes:

-S-

x-dash (-). size is the length of a short horizontal (x-dir) line segment.

-S+

plus (+). size is diameter of circumscribing circle.

-Sa

star. size is diameter of circumscribing circle.

-Sb

Vertical bar extending from base to y. The size is bar width. Append u if size is in x-units [Default is plot-distance units]. By default, base = 0. Append +b[base] to change this value. If base is not appended then we read it from the last input data column. Use +B[base] if the bar height is measured relative to base [Relative to origin].

-SB

Horizontal bar extending from base to x. The size is bar width. Append u if size is in y-units [Default is plot-distance units]. By default, base = 0. Append +b[base] to change this value. If base is not appended then we read it from the last input data column. Use +B[base] if the bar length is measured relative to base [Relative to origin].

-Sc

circle. size is diameter of circle.

-Sd

diamond. size is diameter of circumscribing circle.

-Se

ellipse. Direction (in degrees counter-clockwise from horizontal), major_axis, and minor_axis must be found in columns 4, 5, and 6.

-SE

Same as -Se, 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 (-Se leaves the directions unchanged.) Furthermore, the axes lengths must be given in geographical instead of plot-distance units. An exception occurs for a linear projection in which we assume the ellipse axes are given in the same units as -R. For degenerate ellipses (circles) with just the diameter given, use -SE-. The diameter is excepted to be given in column 4. Alternatively, append the desired diameter to -SE- and this fixed diameter is used instead. For allowable geographical units, see Units [Default is k for km].

-Sf[±]gap[/size][+l|+r][+b+c+f+s+t][+i][+ooffset][+p[pen]].

Draw a front. Supply distance gap between symbols and symbol size. If gap is negative, it is interpreted to mean the number of symbols along the front instead. If gap has a leading + then we use the value exactly as given [Default will start and end each line with a symbol, hence the gap is adjusted to fit]. If size is missing it is set to 30% of the gap, except when gap is negative and size is thus required. Append +l or +r to plot symbols on the left or right side of the front [Default is centered]. Append +type to specify which symbol to plot: box, circle, fault, slip, or triangle. [Default is fault]. Slip means left-lateral or right-lateral strike-slip arrows (centered is not an option). The +s modifier optionally accepts the angle used to draw the vector [30]. Append +ooffset to offset the first symbol from the beginning of the front by that amount [0]. The chosen symbol is drawn with the same pen as set for the line (i.e., via -W). To use an alternate pen, append +ppen. To skip the outline, just use +p. To make the main front line invisible, add +i. Note: By placing -Sf options in the segment header you can change the front types on a segment-by-segment basis.

-Sg

octagon. size is diameter of circumscribing circle.

-Sh

hexagon. size is diameter of circumscribing circle.

-Si

inverted triangle. size is diameter of circumscribing circle.

-Sj

Rotated rectangle. Direction (in degrees counter-clockwise from horizontal), x-dimension, and y-dimension must be found in columns 4, 5, and 6.

-SJ

Same as -Sj, 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 (-Sj leaves the directions unchanged.) Furthermore, the dimensions must be given in geographical instead of plot-distance units. For a degenerate rectangle (square) with one dimension given, use -SJ-. The dimension is excepted to be given in column 4. Alternatively, append the dimension diameter to -SJ- and this fixed dimension is used instead. An exception occurs for a linear projection in which we assume the dimensions are given in the same units as -R. For allowable geographical units, see Units [Default is k for km].

-Sk

kustom symbol. Append <name>/size, and we will look for a definition file called <name>.def in (1) the current directory or (2) in ~/.gmt or (3) in $GMT_SHAREDIR/custom. The symbol as defined in that file is of size 1.0 by default; the appended size will scale symbol accordingly. The symbols are plotted in the x-y plane. Users may add their own custom *.def files; see CUSTOM SYMBOLS below.

-Sl

letter or text string (less than 64 characters). Give size, 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 *. Optionally, you may append %font to select a particular font [Default is FONT_ANNOT_PRIMARY] and +jjustify to change justification [CM].

-Sm

math angle arc, optionally with one or two arrow heads [Default is no arrow heads]. The size is the length of the vector head. Arc width is set by -W, with vector head outlines defaulting to half of arc width. The radius of the arc and its start and stop directions (in degrees counter-clockwise from horizontal) must be given in columns 4-6. See Vector Attributes for specifying attributes.

-SM

Same as -Sm but switches to straight angle symbol if angles subtend 90 degrees exactly.

-Sn

pentagon. size is diameter of circumscribing circle.

-So

column (3-D) extending from base to z. The size sets base width (Use xsize/ysize if not the same). Append u if size is in the users’ x-units [Default is plot-distance units]. If no size is given we expect both xsize and ysize as two extra data columns. By default, base = 0. Append +bbase to change this value. If base is not appended then we read it from the last input data column. Use +B[base] if the column height is measured relative to base [Relative to origin]. The facet colors will be modified to simulate shading. Use -SO to disable such 3-D illumination. Normally a single z value is considered. For multi-band columns, append +znbands (and provide nbands z-values on input; these must be monotonically increasing up the column) or -Znbands (and expect nbands of dz increments that must be summed to yield actual z values). The multi-band column symbol requires -C and will use the band number (0, 1, nbands-1) to assign the band color.

-Sp

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

-Sq

quoted line, i.e., lines with annotations such as contours. It is assumed that each individual line has a constant z level (i.e., each line must lie in the x-y plane). Append [d|D|f|l|L|n|x|X]info[:labelinfo]. Note the colon that separates the algorithm settings from the label information. The required argument controls the placement of labels along the quoted lines. Choose among five controlling algorithms:

ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
For lower case d, give distances between labels on the plot in your preferred measurement unit c (cm), i (inch), or p (points), while for upper case D, specify distances in map units and append the unit; choose among e (m), f (foot), k (km), M (mile), n (nautical mile) or u (US survey foot), and d (arc degree), m (arc minute), or s (arc second). [Default is 10c or 4i]. As an option, you can append /fraction which is used to place the very first label for each contour when the cumulative along-contour distance equals fraction * dist [0.25].

fffile.d
Reads the ASCII file ffile.d and places labels at locations in the file that matches locations along the quoted lines. Inexact matches and points outside the region are skipped.

l|Lline1[,line2,…]
Give start and stop coordinates for one or more comma-separated straight line segments. Labels will be placed where these lines intersect the quoted lines. The format of each line specification is start/stop, where start and stop are either a specified point lon/lat or a 2-character XY key that uses the justification format employed in text to indicate a point on the map, given as [LCR][BMT]. L will interpret the point pairs as defining great circles [Default is straight line].

nn_label
Specifies the number of equidistant labels for quoted lines line [1]. Upper case N starts labeling exactly at the start of the line [Default centers them along the line]. N-1 places one justified label at start, while N+1 places one justified label at the end of quoted lines. Optionally, append /min_dist[c|i|p] to enforce that a minimum distance separation between successive labels is enforced.

x|Xxfile.d
Reads the multisegment file xfile.d and places labels at the intersections between the quoted lines and the lines in xfile.d. X will resample the lines first along great-circle arcs. In addition, you may optionally append +rradius[c|i|p] to set a minimum label separation in the x-y plane [no limitation].

The optional labelinfo controls the specifics of the label formatting and consists of a concatenated string made up of any of the following control arguments:

+aangle
For annotations at a fixed angle, +an for line-normal, or +ap for line-parallel [Default].

+cdx[/dy]
Sets the clearance between label and optional text box. Append c|i|p to specify the unit or % to indicate a percentage of the label font size [15%].

+d
Turns on debug which will draw helper points and lines to illustrate the workings of the quoted line setup.

+e
Delay the plotting of the text. This is used to build a clip path based on the text, then lay down other overlays while that clip path is in effect, then turning of clipping with clip -Cs which finally plots the original text.

+ffont
Sets the desired font [Default FONT_ANNOT_PRIMARY with its size changed to 9p].

+g[color]
Selects opaque text boxes [Default is transparent]; optionally specify the color [Default is PS_PAGE_COLOR].

+i
Make the main quoted line invisible [Draw it per -W].

+jjust
Sets label justification [Default is MC]. Ignored when -SqN|n+|-1 is used.

+llabel
Sets the constant label text.

+Lflag
Sets the label text according to the specified flag:

+Lh Take the label from the current segment header (first scan for an embedded -Llabel option, if not use the first word following the segment flag). For multiple-word labels, enclose entire label in double quotes. +Ld Take the Cartesian plot distances along the line as the label; append c|i|p as the unit [Default is PROJ_LENGTH_UNIT]. +LD Calculate actual map distances; append d|e|f|k|n|M|n|s as the unit [Default is d(egrees), unless label placement was based on map distances along the lines in which case we use the same unit specified for that algorithm]. Requires a map projection to be used. +Lf Use text after the 2nd column in the fixed label location file as the label. Requires the fixed label location setting. +Lx As +Lh but use the headers in the xfile.d instead. Requires the crossing file option.

+ndx[/dy]
Nudges the placement of labels by the specified amount (append c|i|p to specify the units). Increments are considered in the coordinate system defined by the orientation of the line; use +N to force increments in the plot x/y coordinates system [no nudging]. Not allowed with +v.

+o
Selects rounded rectangular text box [Default is rectangular]. Not applicable for curved text (+v) and only makes sense for opaque text boxes.

+p[pen]
Draws the outline of text boxes [Default is no outline]; optionally specify pen for outline [Default is width = 0.25p, color = black, style = solid].

+rmin_rad
Will not place labels where the line’s radius of curvature is less than min_rad [Default is 0].

+t[file]
Saves line label x, y, and text to file [Line_labels.txt]. Use +T to save x, y, angle, text instead.

+uunit
Appends unit to all line labels. If unit starts with a leading hyphen (-) then there will be no space between label value and the unit. [Default is no unit].

+v
Specifies curved labels following the path [Default is straight labels].

+w
Specifies how many (x,y) points will be used to estimate label angles [Default is 10].

+=prefix
Prepends prefix to all line labels. If prefix starts with a leading hyphen (-) then there will be no space between label value and the prefix. [Default is no prefix].

Note: By placing -Sq options in the segment header you can change the quoted text attributes on a segment-by-segment basis.

-Sr

rectangle. No size needs to be specified, but the x- and y-dimensions must be found in columns 4 and 5.

-SR

Rounded rectangle. No size needs to be specified, but the x- and y-dimensions and corner radius must be found in columns 4, 5, and 6.

-Ss

square. size is diameter of circumscribing circle.

-St

triangle. size is diameter of circumscribing circle.

-Su

cube (3-D). The size) sets length of all sides. Append u if size is in x-units [Default is plot-distance units]. The facet colors will be modified to simulate shading. Use -SU to disable such 3-D illumination.

-Sv

vector. Direction (in degrees counter-clockwise from horizontal) and length must be found in columns 4 and 5, and size, if not specified on the command-line, should be present in column 3, pushing the other items to later columns. The size is the length of the vector head. Vector width is set by -W, with head outline pen width defaulting to half of stem pen width. See Vector Attributes for specifying attributes. But also be aware that using color via a CPT implies a shift of columns 4 and on to accommodate the color fill determined by the z-value in new 4rd column (See -C option).

-SV

Same as -Sv, 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 (-Sv leaves the directions unchanged.) See Vector Attributes for specifying attributes.

-Sw

pie wedge. Start and stop directions (in degrees counter-clockwise from horizontal) for pie slice must be found in columns 4 and 5. Append /inner to select a separate inner diameter [0]. Append +a[dr] to draw the arc line (at inner and outer diameter); if dr is appended then we draw all arc lines separated radially by dr. Append +r[da] to draw radial lines (at start and stop directions) if da is appended then we draw all radial lines separated angularly by da. These spider-web lines are drawn using the current pen unless +ppen is added.

-SW

Same as -Sw, except azimuths (in degrees east of north) should be given instead of the two directions. The azimuths will be mapped into angles based on the chosen map projection (-Sw leaves the directions unchanged). Specify size as a geographical diameter. For allowable geographical units, see Units [Default is k for km]. To instead specify a diameter in plot units, you must append the desired unit. Append /inner to select a separate inner diameter [0]. Append +a[dr] to draw the arc line (at inner and outer diameter); if dr is appended then we draw all arc lines separated radially by dr. Append +r[da] to draw radial lines (at start and stop directions) if da is appended then we draw all radial lines separated angularly by da. These spider-web lines are drawn using the current pen unless +ppen is added.

-Sx

cross (x). size is diameter of circumscribing circle.

-Sy

y-dash (|). size is the length of a short horizontal (y-dir) line segment.

-S=

geovector. Azimuth (in degrees east from north) and length (in km) must be found in columns 4 and 5. The size is the length of the vector head. Vector width is set by -W. See Vector Attributes for specifying attributes. Note: Geovector stems are drawn as thin filled polygons and hence pen attributes like dashed and dotted are not available. For allowable geographical units, see Units.

-S~

decorated line, i.e., lines with symbols along them. Append [d|D|f|l|L|n|N|s|S|x|X]info[:symbolinfo]. Note the colon that separates the algorithm settings from the symbol information. The required argument controls the placement of symbols along the decorated lines. Choose among six controlling algorithms:

ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
For lower case d, give distances between symbols on the plot in your preferred measurement unit c (cm), i (inch), or p (points), while for upper case D, specify distances in map units and append the unit; choose among e (m), f (foot), k (km), M (mile), n (nautical mile) or u (US survey foot), and d (arc degree), m (arc minute), or s (arc second). [Default is 10c or 4i]. As an option, you can append /fraction which is used to place the very first symbol for each line when the cumulative along-line distance equals fraction * dist [0.25].

fffile.d
Reads the ASCII file ffile.d and places symbols at locations in the file that matches locations along the decorated lines. Inexact matches and points outside the region are skipped.

l|Lline1[,line2,…]
Give the coordinates of the end points for one or more comma-separated straight line segments. Symbols will be placed where these lines intersect the decorated lines. The format of each line specification is start_lon/start_lat/stop_lon/stop_lat. Both start_lon/start_lat and stop_lon/stop_lat can be replaced by a 2-character key that uses the justification format employed in text to indicate a point on the frame or center of the map, given as [LCR][BMT]. L will interpret the point pairs as defining great circles [Default is straight line].

n|Nn_symbol
Specifies the number of equidistant symbols for decorated lines [1]. Upper case N starts placing symbols exactly at the start of the line [Default centers them along the line]. N-1 places one symbol at start, while N+1 places one symbol at the end of decorated lines. Optionally, append /min_dist[c|i|p] to enforce that a minimum distance separation between successive symbols is enforced.

s|Sn_symbol

Same as n|Nn_symbol but implies that the input data are
first to be converted into a series of 2-point line segments before plotting.

x|Xxfile.d
Reads the multisegment file xfile.d and places symbols at the intersections between the decorated lines and the lines in xfile.d. X will resample the lines first along great-circle arcs.

The optional symbolinfo controls the specifics of the symbol selection and formatting and consists of a concatenated string made up of any of the following control arguments:

+aangle
For symbols at a fixed angle, +an for line-normal, or +ap for line-parallel [Default].

+d
Turns on debug which will draw helper points and lines to illustrate the workings of the decorated line setup.

+g[fill]
Sets the symbol fill [no fill].

+i
Make the main decorated line invisible [Draw it using pen settings provided by -W].

+ndx[/dy]
Nudges the placement of symbols by the specified amount (append c|i|p to specify the units). Increments are considered in the coordinate system defined by the orientation of the line; use +N to force increments in the plot x/y coordinates system [no nudging].

+p[pen]
Draws the outline of symbols [Default is no outline]; optionally specify pen for outline [Default is width = 0.25p, color = black, style = solid].

+s<symbol><size> or +skcustomsymbol/size
Specifies the code and size of the decorative symbol. Custom symbols need to be simple, i.e., not require data columns.

+w
Specifies how many (x,y) points will be used to estimate symbol angles [Default is 10].

If neither +g nor +p are set we select the default pen outline (MAP_DEFAULT_PEN). Note: By placing -S~ options in the segment header you can change the decorated lines on a segment-by-segment basis.

-U[label][+c][+jjust][+odx/dy] (more …): Draw GMT time stamp logo on plot.

-V[level] (more …): Select verbosity level [w].

-W[pen][attr] (more …): Set pen attributes for lines or the outline of symbols [Defaults: width = default, color = black, style = solid]. If the modifier +cl is appended then the color of the line are taken from the CPT (see -C). If instead modifier +cf is appended then the color from the cpt file is applied to symbol fill. Use just +c for both effects. If -Z is set, then append +z to -W to assign pen color via -Ccpt and the z-values obtained.

-X[a|c|f|r][xshift]

-Y[a|c|f|r][yshift] (more …): Shift plot origin.

-Zvalue|file: Instead of specifying a symbol or polygon fill and outline color via -G and -W, give both a value via -Z and a color lookup table via -C. Alternatively, give the name of a file with one z-value (read from the last column) for each polygon in the input data. To apply the color obtain to a fill, use -G+z; to apply it to the pen color, append +z to -W.

-a[col=]name[,…] (more …): Set aspatial column associations col=name.

-bi[ncols][t] (more …): Select native binary format for primary input. [Default is the required number of columns given the chosen settings].

-dinodata (more …): Replace input columns that equal nodata with NaN.

-e[~]“pattern” | -e[~]/regexp/[i] (more …): Only accept data records that match the given pattern.

-f[i|o]colinfo (more …): Specify data types of input and/or output columns.

-g[a]x|y|d|X|Y|D|[col]zgap[+n|p] (more …): Determine data gaps and line breaks. The -g option is ignored if -S is set.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …): Skip or produce header record(s).

-icols[+l][+sscale][+ooffset][,…][,t[word]] (more …): Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …): Select perspective view.

-qi[~]rows[+ccol][+a|f|s] (more …): Select input rows or data range(s) [all].

-t[transp] (more …): Set transparency level in percent.

If no transparency is appended then we will read it from the last column per data record instead.

-:[i|o] (more …): Swap 1st and 2nd column on input and/or output.

-^ or just -: Print a short message about the syntax of the command, then exit (NOTE: on Windows just use -).
-+ or just +: Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.
-? or no arguments: Print a complete usage (help) message, including the explanation of all options, then exit.
--PAR=value: Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Units¶

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

Vector Attributes¶

Vector attributes are controlled by options and modifiers. We will refer to this figure and the labels therein when introducing the corresponding modifiers. All vectors require you specify the begin point $x_b, y_b$ and typically direction d and length L, but for map projections we usually specify the azimuth $\alpha$ instead.¶

Several modifiers may be appended to vector-producing options for specifying the placement of vector heads, their shapes, and the justification of the vector. Below, left and right refers to the side of the vector line when viewed from the beginning point (b) to the end point (e) of a line segment:

+aangle sets the angle $\theta$ of the vector head apex [30].

+b places a vector head at the beginning of the vector path [none]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides].

+e places a vector head at the end of the vector path [none]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides].

+g[fill] sets the vector head fill [Default fill is used, which may be no fill]. Turn off vector head fill by not appending a fill. Some modules have a separate -Gfill option and if used will select the fill as well.

+hshape sets the shape of the vector head (range -2/2). Default is controlled by MAP_VECTOR_SHAPE [0]. A zero value produces no notch (e.g., the dashed line in the figure). Positive values moves the notch toward the head apex while a negative value moves away. The example above uses +h0.5.

+l draws half-arrows, using only the left side of specified heads [both sides].

+m places a vector head at the mid-point the vector path [none]. Append f or r for forward or reverse direction of the vector [forward]. Optionally, append t for a terminal line, c for a circle, a for arrow [Default], i for tail, A for plain open arrow, and I for plain open tail. Further append l|r to only draw the left or right half-sides of this head [both sides]. Cannot be combined with +b or +e.

+nnorm scales down vector attributes (pen thickness, head size) with decreasing length, where vector plot lengths shorter than norm will have their attributes scaled by length/norm [arrow attributes remains invariant to length]. For Cartesian vectors specify a length in plot units, while for geovectors specify a length in km.

+o[plon/plat] specifies the oblique pole for the great or small circles. Only needed for great circles if +q is given. If no pole is appended then we default to the north pole.

+p[pen] sets the vector pen attributes. If no pen is appended then the head outline is not drawn. [Default pen is half the width of stem pen, and head outline is drawn]. Above, we used +p2p,orange. The vector stem attributes are controlled by -W.

+q means the input direction, length data instead represent the start and stop opening angles of the arc segment relative to the given point. See +o to specify a specific pole for the arc [north pole].

+r draws half-arrows, using only the right side of specified heads [both sides].

+t[b|e]trim will shift the beginning or end point (or both) along the vector segment by the given trim; append suitable unit (c, i, or p). If the modifiers b|e are not used then trim may be two values separated by a slash, which is used to specify different trims for the beginning and end. Positive trims will shorted the vector while negative trims will lengthen it [no trim].

In addition, all but circular vectors may take these modifiers:

+jjust determines how the input x,y point relates to the vector. Choose from beginning [default], end, or center.

+s means the input angle, length are instead the $x_e, y_e$ coordinates of the vector end point.

Finally, Cartesian vectors may take these modifiers:

+zscale expects input $\Delta x, \Delta y$ vector components and uses the scale to convert to polar coordinates with length in given unit.

Note: Vectors were completely redesigned for GMT5 which separated the vector head (a polygon) from the vector stem (a line). In GMT4, the entire vector was a polygon and it could only be a straight Cartesian vector. Yes, the old GMT4 vector shape remains accessible if you specify a vector (-Sv|V) using the GMT4 syntax, explained here: size, if present, will be interpreted as arrowwidth/headlength/headwidth [Default is 0.075c/0.3c/0.25c (or 0.03i/0.12i/0.1i)]. By default, arrow attributes remain 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. To center the vector on the balance point, use -Svb; to align point with the vector head, use -Svh; to align point with the vector tail, use -Svt [Default]. To give the head point’s coordinates instead of direction and length, use -Svs. Upper case B, H, T, S will draw a double-headed vector [Default is single head].

Auto-legend entries¶

This module allows you to use the -l option to specify an automatic legend entry. This option is available for lines or symbols only. If there is no size specified (which is always true for lines) or if the symbol size is computed from other information (which may be true for some symbols deriving size from other input columns), then you need to supply a legend size (i.e., length of a line symbol) via the +S modifier.

Examples¶

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

To plot blue columns (width = 1.25 cm) at the positions listed in the file heights.xyz on a 3-D projection of the space (0-10), (0-10), (0-100), with tickmarks every 2, 2, and 10, viewing it from the southeast at 30 degree elevation, use:

gmt plot3d heights.xyz -R0/10/0/10/0/100 -Jx1.25c -Jz0.125c -So1.25c \
          -Gblue -Bx2+lXLABEL -By2+lYLABEL -Bz10+lZLABEL -B+t"3-D PLOT" -p135/30 \
          -U+c -W -pdf heights

To plot a point with color and outline dictated by the t.cpt file for the level-value 65, try

echo 175 30 0 | gmt plot3d -R150/200/20/50 -JM15c -B -Sc0.5c -Z65 -G+z -Ct.cpt -pdf map

Segment Header Parsing¶

Segment header records may contain one of more of the following options:

-Gfill: Use the new fill and turn filling on
-G-: Turn filling off
-G: Revert to default fill (none if not set on command line)
-Wpen: Use the new pen and turn outline on
-W: Revert to default pen MAP_DEFAULT_PEN (if not set on command line)
-W-: Turn outline off
-Zzval: Obtain fill via cpt lookup using z-value zval
-ZNaN: Get the NaN color from the CPT

Custom Symbols¶

We allow users to define and plot their own custom symbols. This is done by encoding the symbol using our custom symbol macro code described in Appendix N. Put all the macro codes for your new symbol in a file whose extension must be .def; you may then address the symbol without giving the extension (e.g., the symbol file tsunami.def is used by specifying -Sktsunami/size. The definition file can contain any number of plot code records, as well as blank lines and comment lines (starting with #). The module will look for the definition files in (1) the current directory, (2) the ~/.gmt directory, and (3) the $GMT_SHAREDIR/custom directory, in that order. Freeform polygons (made up of straight line segments and arcs of circles) can be designed - these polygons can be painted and filled with a pattern. Other standard geometric symbols can also be used. See Appendix Custom Plot Symbols for macro definitions.

Bezier spline¶

The +s modifier to pen settings (-W) is limited to plotting lines and polygons. Lines with embellishments (fronts, decorated, or quoted lines) are excluded.

Auto-Legend¶

The -l option for symbols expects the symbol color, size, and type to be given on the command line. If you have variable symbol sizes then you must append +ssize to set a suitable size for the legend entry. For other symbol cases the -l option will be ignored. Legend entries also work for lines and polygons, but not more complicated features such as decorated and quoted lines, fronts, etc.

Bugs¶

No hidden line removal is employed for polygons and lines. Symbols, however, are first sorted according to their distance from the viewpoint so that nearby symbols will overprint more distant ones should they project to the same x,y position.

The module cannot handle filling of polygons that contain the south or north pole. For such a polygon, make a copy and split it into two and make each explicitly contain the polar point. The two polygons will combine to give the desired effect when filled; to draw outline use the original polygon.