# plot¶

Plot lines, polygons, and symbols in 2-D

## Synopsis¶

gmt plot [ table ] -Jparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] [ -A[m|p|x|y] ] [ -B[p|s]parameters ] [ -Ccpt ] [ -Ddx/dy ] [ -E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen] ] [ -F[c|n|r][a|f|s|r|refpoint] ] [ -Gfill ] [ -I[intens] ] [ -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen] ] [ -N[c|r] ] [ -S[symbol][size[u] ] [ -U[stamp] ] [ -V[level] ] [ -W[pen][attr] ] [ -X[a|c|f|r][xshift[u]] ] [ -Y[a|c|f|r][yshift[u]] ] [ -Z[l|f]value ] [ -aflags ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -lflags ] [ -pflags ] [ -ttransp ] [ -:[i|o] ] [ --PAR=value ]

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

## Description¶

Reads (x,y) pairs from files [or standard input] and will plot lines, polygons, or symbols at those locations on a map. If a symbol is selected and no symbol size given, then it will interpret the third column of the input data as symbol size. Symbols whose size is <= 0 are skipped. If no symbolsare 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.
-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. To 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.
-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, where z starts at 0 and is incremented by one for each color. 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 z-value in the third column. Additional fields are shifted over by one column (optional size would be 4th rather than 3rd field, etc.). If -S is not set, then it expects 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
Offset the plot symbol or line locations by the given amounts dx/dy [Default is no offset]. If dy is not given it is set equal to dx.
-E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen]
Draw symmetrical error bars. Append x and/or y to indicate which bars you want to draw (Default is both x and y). The x and/or y errors must be stored in the columns after the (x,y) pair [or (x,y,z) triplet]. If +a is appended then we will draw asymmetrical error bars; these requires two rather than one extra data column, with the low and high value. If upper case X and/or Y are used we will instead draw “box-and-whisker” (or “stem-and-leaf”) symbols. The x (or y) coordinate is then taken as the median value, and four more columns are expected to contain the minimum (0% quantile), the 25% quantile, the 75% quantile, and the maximum (100% quantile) values. The 25-75% box may be filled by using -G. If +n is appended the we draw a notched “box-and-whisker” symbol where the notch width reflects the uncertainty in the median. This symbol requires a 5th extra data column to contain the number of points in the distribution. The +w modifier sets the cap width that indicates the length of the end-cap on the error bars [7p]. Pen attributes for error bars may also be set via +ppen. [Defaults: width = default, color = black, style = solid]. When -C is used we can control how the look-up color is applied to our symbol. Append +cf to use it to fill the symbol, while +cl will just set the error pen color and turn off symbol fill. Giving +c will set both color items.
-F[c|n|r][a|f|s|r|refpoint]
Alter the way points are connected (by specifying a scheme) and data are grouped (by specifying a method). Append one of three line connection schemes: c: Draw continuous line segments for each group [Default]. r: Draw line segments from a reference point reset for each group. n: Draw networks of line segments between all points in each group. Optionally, append the one of four segmentation methods to define the group: a: Ignore all segment headers, i.e., let all points belong to a single group, and set group reference point to the very first point of the first file. f: Consider all data in each file to be a single separate group and reset the group reference point to the first point of each group. s: Segment headers are honored so each segment is a group; the group reference point is reset to the first point of each incoming segment [Default]. r: Same as s, but the group reference point is reset after each record to the previous point (this method is only available with the -Fr scheme). Instead of the codes a|f|s|r you may append the coordinates of a refpoint which will serve as a fixed external reference point for all groups.
-Gfill (more …)
Select color or pattern for filling of symbols or polygons [Default is no fill]. Note that this 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.
-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] Example
X

## -L example

cat << EOF > t.txt
1 1
2 3
3 2
4 4
EOF
gmt begin filler pdf
gmt plot -R0/5/0/5 -JX3i -B t.txt -Gred -W2p -L+yb
gmt plot -B t.txt -Gred -W2p -L+yt -X3.25i
gmt plot -B t.txt -Gred -W2p -L+xl -X-3.25i -Y3.25i
gmt plot -B t.txt -Gred -W2p -L+xr -X3.25i
gmt plot -B t.txt -Gred -W2p -L+y4 -X-3.25i -Y3.25i
gmt plot -B t.txt -Gred -W2p -L+x4.5 -X3.25i
gmt end show

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 3. Append +D to build asymmetrical envelope around y(x) using deviations dy1(x) and dy2(x) from extra columns 3-4. Append +b to build asymmetrical envelope around y(x) using bounds yl(x) and yh(x) from extra columns 3-4. 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].
-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.
-S[symbol][size[u]]

Plot symbols (including vectors, pie slices, fronts, decorated or quoted lines). 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 provide both size and symbol via the input file you must use PROJ_LENGTH_UNIT to indicate the unit used for the symbol size or append the units to the sizes in the file. If symbol sizes are expected via the third data column then you may convert those values to suitable symbol sizes via the -i mechanism.

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.

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[size[c|i|p|u]][+b[base]]
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[size[c|i|p|u]][+b[base]]
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 3, 4, and 5.
-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 3. 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].
-Sfgap[/size][+l|+r][+b+c+f+s+t][+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 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 [20]. Alternatively, use +S which draws arcuate arrow heads. 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. 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 3, 4, and 5.
-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 3. 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

## GMT4 Vector¶

Note: The old-style, single-polygon vector available in GMT4 and earlier versions has been added to GMT5 for backwards compatibility with old scripts. For reference, the old vector syntax is listed here: The size, if present, will be interpreted as arrowwidth/headlength/headwidth. By default, arrow attributes remain invariant to the length of the arrow. To have the size of the vector scale down with decreasing length, append nnorm, so that vectors shorter than norm will have their dimensions scaled by the vector length divided by norm. To center the vector on the balance (mid) point, use -Svb; to align point with the vector head, use -Svh; to align point with the vector tail, use -Svt [Default]. If the input has the head point’s coordinates instead of direction and length, use -Svs. Upper case B, H, T, or S will draw a double-headed vector [Default is single head].

## Polar Caps¶

We will automatically determine if a closed polygon is containing a geographic pole, i.e., being a polar cap. Such polygons requires special treatment under the hood to ensure proper filling. Many tools such as GIS packages are unable to handle polygons covering a pole and some cannot handle polygons crossing the Dateline. They work around this problem by splitting polygons into a west and east polygon or inserting artificial helper lines that makes a cut into the pole and back. Such doctored polygons may be misrepresented in GMT.