psxy & GMT 6.0.0_r18654 documentation
psxy - Plot lines, polygons, and symbols on maps
psxy [ table ] parameters
west/east/south/north[/zmin/zmax][+r]
[ [m|p|x|y] ]
[ [p|s]parameters ]
[ cpt ] [ dx/dy ]
[ [x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen] ]
[ [c|n|r][refpoint] ]
[ intens ]
[ [+b|d|D][+xl|r|x0][+yl|r|y0][+ppen] ]
[ [symbol][size[u] ]
[ [stamp] ]
[ [level] ]
[ [pen][attr] ]
[ x_offset ]
[ y_offset ]
[ -:[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
Select map projection.
-Rxmin/xmax/ymin/ymax[+r][+uunit]
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax.
Optional Arguments
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|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
Set map boundary frame and axes attributes.
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 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.
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 asy 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 eac 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.
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.
Use the supplied intens value (nominally in the -1 to + 1 range) to
modulate the fill color by simulating illumination [none].
Do not finalize the PostScript plot.
-L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]
-L example
ps=filler.ps
cat < t.txt
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
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].
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.
Append to existing PostScript plot.
Select “Portrait” plot orientation.
-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
(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
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
]. Note: if you provide both size and symbol via the
input file you must use
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:
x-dash (-). size is the length of a short horizontal (x-dir) line segment.
plus (+). size is diameter of circumscribing circle.
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.
circle. size is diameter of circle.
diamond. size is diameter of circumscribing circle.
ellipse. Direction (in degrees counter-clockwise from horizontal),
major_axis, and minor_axis must be found in columns 3, 4, and 5.
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.
-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
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).
The use an
alternate pen, append +ppen.
To skip the outline, just use
Note: By placing -Sf
options in the segment header you can change the front types on a
segment-by-segment basis.
octagon. size is diameter of circumscribing circle.
hexagon. size is diameter of circumscribing circle.
inverted triangle. size is diameter of circumscribing circle.
Rotated rectangle. Direction (in degrees counter-clockwise from
horizontal), x-dimension, and y-dimension must be found in columns 3, 4,
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.
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 the appended size will scale symbol accordingly. Users
may add their own custom *. see CUSTOM SYMBOLS below.
letter or text string (less than 256 characters). Give size, and
append +tstring after the size. Note that the size
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 ] and
+jjustify to change justification [CM].
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.
Same as -Sm but switches to straight angle symbol if angles subtend
90 degrees exactly.
pentagon. size is diameter of circumscribing circle.
point. No size needs to be specified (1 pixel is used).
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
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].
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:
For annotations at a fixed angle, +an for line-normal, or
+ap for line-parallel [Default].
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%].
Turns on debug which will draw helper points and lines to illustrate
the workings of the quoted line setup.
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.
Sets the desired font [Default
size changed to 9p].
Selects opaque text boxes [Default is transparent]; optionally
specify the color [Default is ].
Sets label justification [Default is MC]. Ignored when
-SqN|n+|-1 is used.
Sets the constant label text.
Sets the label text according to the specified flag:
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.
Take the Cartesian plot distances along t
append c|i|p as the unit [Default is
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
Use text after the 2nd column in the fixed label location file
as the label. Requires the fixed label location setting.
As +Lh but use the headers in the xfile.d instead.
Requires the crossing file option.
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
ori use +N to force increments in the
plot x/y coordinates system [no nudging]. Not allowed with +v.
Selects rounded rectangular text box [Default is rectangular].
Not applicable for curved text (+v) and only makes sense for
opaque text boxes.
Draws the outline of text boxes [Default is no outline];
optionally specify pen for outline [Default is width = 0.25p,
color = black, style = solid].
Will not place labels where the line’s radius of curvature is
less than min_rad [Default is 0].
Saves line label x, y, and text to file [Line_labels.txt].
Use +T to save x, y, angle, text instead.
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].
Specifies curved labels following the path [Default is straight
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.
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].
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.
rectangle. No size needs to be specified, but the x- and
y-dimensions must be found in columns 3 and 4.
Rounded rectangle. No size needs to be specified, but the x-
and y-dimensions and corner radius must be found in columns 3, 4,
square. size is diameter of circumscribing circle.
triangle. size is diameter of circumscribing circle.
vector. Direction (in degrees counter-clockwise from
horizontal) and length must be found in columns 3 and 4, and size,
if not specified on the command-line, should be
present in column 5.
The size is the length of the vector head. Vector width is set by -W.
See VECTOR ATTRIBUTES for specifying other attributes.
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.
pie wedge. Start and stop directions (in degrees
counter-clockwise from horizontal) for pie slice must be found in
columns 3 and 4.
Append +a to just draw the arc line or +r
to just draw the radial lines.
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.)
For geo-wedges, specify size as a radial
geographical distance.
For allowable geographical units, see UNITS.
Append +a to just draw the arc or +r to just draw the radial lines.
cross (x). size is diameter of circumscribing circle.
y-dash (|). size is the length of a short vertical (y-dir) line
geovector. Azimuth (in degrees east from north) and geographical 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 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.
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
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].
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:
For symbols at a fixed angle, +an for line-normal, or
+ap for line-parallel [Default].
Turns on debug which will draw helper points and lines to illustrate
the workings of the decorated line setup.
Sets the symbol fill [no fill].
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
ori use +N to force increments in the
plot x/y coordinates system [no nudging].
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&
Specifies the code and size of the decorative symbol.
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.
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]
Draw GMT time stamp logo on plot.
Select verbosity level [c].
-W[pen][attr]
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.
You can also append one or more additional line attribute modifiers:
+ooffsetu will start and stop drawing the line the given distance offsets
from the end point.
Append unit u from c|i|p to
indicate plot distance on the map or append map distance units instead (see below)
[Cartesian distances];
+s will draw the line using a PostScript Bezier spline [linear spline];
+vvspecs will place a vector head at the ends of the lines.
use +vb and +ve to specify separate vector specs at each end [shared specs].
Because +v may take additional modifiers it must necessarily be given
at the end of the pen specification.
for more information.
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]]
Shift plot origin.
-bi[ncols][t]
Select native binary input. [Default is the required number of columns given the chosen settings].
-acol=name[...]
Set aspatial column associations col=name.
Replace input columns that equal nodata with NaN.
-e[~]“pattern” | -e[~]/regexp/[i]
Only accept data records that match the given pattern.
-f[i|o]colinfo
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u]
Determine data gaps and line breaks. The -g option is ignored if -S is set.
-h[i|o][n][+c][+d][+rremark][+rtitle]
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,...]
Select input columns and transformations (0 is first column).
Swap 1st and 2nd column on input and/or output.
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]
Select perspective view.
-t[transp]
Set PDF transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then exits (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 exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
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).
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. 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,
a for arrow [Default], i for tail, A for plain arrow,
and I for plain tail.
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,
a for arrow [Default], i for tail, A for plain arrow,
and I for plain tail.
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].
+hshape sets the shape of the vector head (range -2/2). Default
is controlled by
+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 are 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.2 cm) at the positions listed
in the file DSDP.txt on a Mercator map at 0.3 cm/degree of the area 100E to
160E, 20S to 30N, with automatic tick-marks and gridlines, use
gmt psxy DSDP.txt -R100/160/-20/30 -Jm0.3c -Sc0.2c -Gred -Bafg & 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
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
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 . 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
for macro definitions.
Polar Caps
psxy 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.
doctored polygons may be misrepresented in GMT.
