psxy

psxy - Plot lines, polygons, and symbols on maps

Synopsis

psxy [ table ] -Jparameters -Rwest/east/south/north[/zmin/zmax][r] [ -A[m|p] ] [ -B[p|s]parameters ] [ -Ccptfile ] [ -Ddx/dy ] [ -E[x|y|X|Y][n][cap][/[-|+]pen] ] [ -Gfill ] [ -Iintens ] [ -Jz|Zparameters ] [ -K ] [ -L ] [ -N ] [ -O ] [ -P ] [ -S[symbol][size[u] ] [ -U[just/dx/dy/][c|label] ] [ -V[level] ] [ -W[-|+][pen] ] [ -X[a|c|f|r][x-shift[u]] ] [ -Y[a|c|f|r][y-shift[u]] ] [ -acol=name[...] ] [ -bi[ncols][type][w][+L|+B] ] [ -ccopies ] [ -f[i|o]colinfo ] [ -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ -h[i|o][n][+c][+d][+rremark][+rtitle] ] [ -icols[l][sscale][ooffset][,...] ] [ -p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] ] [ -t[transp] ] [ -:[i|o] ]

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

Description

psxy reads (x,y) pairs from files [or standard input] and generates PostScript code that will plot lines, polygons, or symbols at those locations on a map. If a symbol is selected and no symbol size given, then psxy will interpret the third 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. The PostScript code is written to standard output.

Required Arguments

-Jparameters (more ...)
Select map projection.
-R[unit]xmin/xmax/ymin/ymax[r] (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. Use -T to ignore all input files, including standard input (see below).
-A[m|p]
By default 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 lines along parallels, for example).
-B[p|s]parameters (more ...)
Set map boundary intervals.
-Ccptfile
Give a color palette file. 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 psxy 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 file.
-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][n][cap][/[-|+]pen]
Draw 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,size) triplet]. The cap parameter indicates the length of the end-cap on the error bars [7p]. Pen attributes for error bars may also be set [Defaults: width = default, color = black, style = solid]. A leading + will use the lookup color (via -C) for both symbol fill and error pen color, while a leading - will set error pen color and turn off symbol fill. If upper case X and/or Y is 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 4 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 to X (or Y) we draw a notched “box-and-whisker” symbol where the notch width reflects the uncertainty in the median. Then a 5th extra data column is expected to contain the number of points in the distribution.
-Gfill
Select color or pattern for filling of symbols or polygons [Default is no fill]. Note that psxy 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].
-Jz|Zparameters (more ...)
Set z-axis scaling; same syntax as -Jx.
-K (more ...)
Do not finalize the PostScript plot.
-L
Force closed polygons: connect the endpoints of the line-segment(s) and draw polygons. Also, in concert with -C and any -Z settings in the headers will use the implied color for polygon fill [Default is polygon pen color].
-N
Do NOT skip symbols that fall outside map border [Default plots points inside border only]. The option does not apply to lines and polygons which are always clipped to the map region.
-O (more ...)
Append to existing PostScript plot.
-P (more ...)
Select “Portrait” plot orientation.
-S[symbol][size[u]]

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

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[size[c|i|p|u]][b[base]]
Vertical bar extending from base to y. size is bar width. Append u if size is in x-units [Default is plot-distance units]. By default, base = ymin. Append b[base] to change this value. If base is not appended then we read it from the last input data column.
-SB[size[c|i|p|u]][b[base]]
Horizontal bar extending from base to x. size is bar width. Append u if size is in y-units [Default is plot-distance units]. By default, base = xmin. Append b[base] to change this value. If base is not appended then we read it from the last input data column.
-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 km 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 diameter given in km, use -SE-.
-Sf
front. -Sfgap[/size][+l|+r][+b+c+f+s+t][+ooffset]. 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). Append +ooffset to offset the first symbol from the beginning of the front by that amount [0]. 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 km instead of plot-distance units. An exception occurs for a linear projection in which we assume the dimensions are given in the same units as -R.
-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. Users may add their own custom *.def files; see CUSTOM SYMBOLS below.
-Sl
letter or text string (less than 256 characters). Give size, and append +tstring 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 +ffont 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. The radius of the arc and its start and stop directions (in degrees counter-clockwise from horizontal) must be given in columns 3-5. See VECTOR ATTRIBUTES for specifying other 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.
-Sp
point. No size needs to be specified (1 pixel is used).
-Sq

quoted line, i.e., lines with annotations such as contours. Append [d|D|f|l|L|n|x|X]info[:labelinfo]. 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 pstext 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 psclip -Ct 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].
+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].
+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 3 and 4.
-SR
Rounded rectangle. No size needs to be specified, but the x- and y-dimensions and corner radius must be found in columns 3, 4, and 5.
-Ss
square. size is diameter of circumscribing circle.
-St
triangle. size is diameter of circumscribing circle.
-Sv
vector. Direction (in degrees counter-clockwise from horizontal) and length must be found in columns 3 and 4. The size is the length of the vector head. Vector width is set by -W. See VECTOR ATTRIBUTES for specifying other attributes.
-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 other attributes.
-Sw
pie wedge. Start and stop directions (in degrees counter-clockwise from horizontal) for pie slice must be found in columns 3 and 4.
-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.)
-Sx
cross (x). size is diameter of circumscribing circle.
-Sy
y-dash (|). size is the length of a short vertical (y-dir) line segment.
-S=
geovector. Azimuth (in degrees east from north) and length (in km) must be found in columns 3 and 4. The size is the length of the vector head. Vector width is set by -W. See VECTOR ATTRIBUTES for specifying attributes.
-T
Ignore all input files, including standard input. This is the same as specifying /dev/null (or NUL for Windows users) as input file. Use this to activate only the options that are not related to plotting of lines or symbols, such as psxy -R -J -O -T to terminate a sequence of GMT plotting commands without producing any plotting output.
-U[just/dx/dy/][c|label] (more ...)
Draw GMT time stamp logo on plot.
-V[level] (more ...)
Select verbosity level [c].
-W[-|+][pen]
Set pen attributes for lines or the outline of symbols [Defaults: width = default, color = black, style = solid]. A leading + will use the lookup color (via -C) for both symbol fill and outline pen color, while a leading - will set outline pen color and turn off symbol fill.

-X[a|c|f|r][x-shift[u]]

-Y[a|c|f|r][y-shift[u]] (more ...)
Shift plot origin.
-bi[ncols][type] (more ...)
Select binary input. [Default is the required number of columns given the chosen settings].
-acol=name[...] (more ...)
Set aspatial column associations col=name.
-ccopies (more ...)
Specify number of plot copies [Default is 1].
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
Determine data gaps and line breaks. The -g option is ignored if -S is set.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-icols[l][sscale][ooffset][,...] (more ...)
Select input columns.
-:[i|o] (more ...)
Swap 1st and 2nd column on input and/or output.
-p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
Select perspective view.
-t[transp] (more ...)
Set PDF transparency level in percent.
-^
Print a short message about the syntax of the command, then exits. (NOTE: on Windows use just -)
+
Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits
-?
Print a complete usage (help) message, including the explanation of options, then exits.
--version
Print GMT version and exit.
--show-datadir
Print full path to GMT share directory and exit.

Vector Attributes

Several modifiers may be appended to the vector-producing options to specify the placement of vector heads, their shapes, and the justification of the vector:

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

+b places a vector head at the beginning of the vector path [none].

+e places a vector head at the end of the vector path [none].

+g-|fill turns off vector head fill (if -) or sets the vector head fill [Default fill is used, which may be no fill].

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

+nnorm scales down vector attributes (pen thickness, head size) with decreasing length, where vectors shorter than norm will have their attributes scaled by length/norm [arrow attributes remains invariant to length].

+oplon/plat specifies the oblique pole for the great or small circles. Only needed for great circles if +q is given.

+p[-][pen] sets the vector pen attributes. If pen has a leading - then the head outline is not drawn. [Default pen is used, and head outline is drawn]

+q means the input angle, length is instead the start and stop opening angles of the arc segment relative to the point.

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

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 is instead the x, y coordinates of the vector end point.

Examples

To plot solid red circles (diameter = 0.25 cm) at the positions listed in the file DSDP.xy on a Mercator map at 5 cm/degree of the area 150E to 154E, 18N to 23N, with tickmarks every 1 degree and gridlines every 15 minutes, use

gmt psxy DSDP.xy R150/154/18/23 -Jm5c -Sc0.25c -Gred -B1g15m > map.ps

To plot the xyz values in the file quakes.xyzm as circles with size given by the magnitude in the 4th column and color based on the depth in the third using the color palette cpt on a linear map, use

gmt psxy quakes.xyzm -R0/1000/0/1000 -JX6i -Sc -Ccpt -B200 > map.ps

To plot the file trench.xy on a Mercator map, with white triangles with sides 0.25 inch on the left side of the line, spaced every 0.8 inch, use

gmt psxy trench.xy -R150/200/20/50 -Jm0.15i -Sf0.8i/0.1i+l+t -Gwhite -W -B10 > map.ps

To plot the data in the file misc.d as symbols determined by the code in the last column, and with size given by the magnitude in the 4th column, and color based on the third column via the color palette cpt on a linear map, use

gmt psxy misc.d -R0/100/-50/100 -JX6i -S -Ccpt -B20 > map.ps

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 file

Custom Symbols

psxy allows 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 #). psxy 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 N for macro definitions.