psxy - Plot lines, polygons, and symbols on maps
psxy [ table ] -Jparameters -Rwest/east/south/north[/zmin/zmax][r] [ -A[m|p|x|y] ] [ -B[p|s]parameters ] [ -Ccpt ] [ -Ddx/dy ] [ -E[x[+]|y[+]|X|Y][n][cap][/[-|+]pen] ] [ -F[c|n|r][refpoint] ] [ -Gfill ] [ -Iintens ] [ -Jz|Zparameters ] [ -K ] [ -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen] ] [ -N[c|r] ] [ -O ] [ -P ] [ -S[symbol][size[u] ] [ -T ] [ -U[just/dx/dy/][c|label] ] [ -V[level] ] [ -W[-|+][pen][attr] ] [ -Xx_offset ] [ -Yy_offset ] [ -a<flags> ] [ -bi<binary> ] [ -ccopies ] [ -di<nodata> ] [ -f<flags> ] [ -g<gaps> ] [ -h<headers> ] [ -i<flags> ] [ -p<flags> ] [ -t<transp> ] [ -:[i|o] ]
Note: No space is allowed between the option flag and the associated arguments.
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.
For perspective view p, optionally append /zmin/zmax. (more ...)
ps=filler.ps cat << EOF > t.txt 1 1 2 3 3 2 4 4 EOF gmt psxy -R0/5/0/5 -JX3i -P -K -B0 t.txt -Gred -W2p -L+yb > $ps gmt psxy -R -J -O -K -B0 t.txt -Gred -W2p -L+yt -X3.25i >> $ps gmt psxy -R -J -O -K -B0 t.txt -Gred -W2p -L+xl -X-3.25i -Y3.25i >> $ps gmt psxy -R -J -O -K -B0 t.txt -Gred -W2p -L+xr -X3.25i >> $ps gmt psxy -R -J -O -K -B0 t.txt -Gred -W2p -L+y4 -X-3.25i -Y3.25i >> $ps gmt psxy -R -J -O -K -B0 t.txt -Gred -W2p -L+x4.5 -X3.25i >> $ps gmt psxy -R -J -O -T >> $ps
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:
quoted line, i.e., lines with annotations such as contours. Append [d|D|f|l|L|n|N|s|S|x|X]info[:labelinfo]. The required argument controls the placement of labels along the quoted 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 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 the coordinates of the end points 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_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 pstext 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_label
- Specifies the number of equidistant labels for quoted lines [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.
- s|Sn_label
- Same as n|Nn_label 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 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 -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].
- +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].
- +x[first,last]
- Append the suffices first and last to the corresponding labels. This modifier is only available when -SqN2 is in effect. Used to annotate the start and end of a line (e.g., a cross-section), append two text strings separated by comma [Default just adds a prime to the second label].
- +=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.
decorated line, i.e., lines with symbols along them. Append [d|D|f|l|L|n|N|s|S|x|X]info[:symbolinfo]. 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 pstext 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].
- +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].
- +w
- Specifies how many (x,y) points will be used to estimate symbol angles [Default is 10].
Note: By placing -S~ options in the segment header you can change the decorated lines on a segment-by-segment basis.
-X[a|c|f|r][x-shift[u]]
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. Prepend - to a distance (or the unit is no distance is given) to perform “Flat Earth” calculations (quicker but less accurate) or prepend + to perform exact geodesic calculations (slower but more accurate).
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. Below, left and right refers to the side of the vector line when viewed from the start point to the end point of the segment:
+aangle sets the angle 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, or a for arrow [Default]. Further append l|r to only draw the left or right side 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, or a for arrow [Default]. Further append l|r to only draw the left or right side of this head [both sides].
+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 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, or a for arrow head [Default]. Further append l|r to only draw the left or right side 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 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 data instead represent the start and stop opening angles of the arc segment relative to the given point.
+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. 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 two ends. 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 is instead the x, y coordinates of the vector end point.
Finally, Cartesian vectors may take these modifiers:
+zscale[unit] expects input dx,dy vector components and uses the scale to convert to polar coordinates with length in given unit.
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 tick-marks 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 CPT rgb.cpt on a linear map, use
gmt psxy quakes.xyzm -R0/1000/0/1000 -JX6i -Sc -Crgb -B200 > map.ps
To plot the file trench.txt 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.txt -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 CPT chrome on a linear map, use
gmt psxy misc.d -R0/100/-50/100 -JX6i -S -Cchrome -B20 > map.ps
If you need to place vectors on a plot you can choose among straight Cartesian vectors, math circular vectors, or geo-vectors (these form small or great circles on the Earth). These can have optional heads at either end, and heads may be the traditional arrow, a circle, or a terminal cross-line. To place a few vectors with a circle at the start location and an arrow head at the end, try
gmt psxy -R0/50/-50/50 -JX6i -Sv0.15i+bc+ea -Gyellow -W0.5p -Baf << EOF > map.ps 10 10 45 2i 30 -20 0 1.5i EOF
To plot vectors (red vector heads, solid stem) from the file data.txt that contains record of the form lon, lat, dx, dy, where dx, dy are the Cartesian vector components given in user units, and these user units should be converted to cm given the scale 3.60, try
gmt psxy -R20/40/-20/0 -JM6i -Sv0.15i+e+z3.6c -Gred -W0.25p -Baf data.txt > map.ps
Segment header records may contain one of more of the following options:
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 Custom Plot Symbols for macro definitions.