psxy(1) GMT psxy(1)
NAME
psxy - Plot lines, polygons, and symbols on maps
SYNOPSIS
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][+a][+cl|f][+n][+wcap][+ppen] ] [ -F[c|n|r][refpoint] ] [
-Gfill ] [ -Iintens ] [ -K ] [ -L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]
] [ -N[c|r] ] [ -O ] [ -P ] [ -S[symbol][size[u] ] [ -T ] [
-U[stamp] ] [ -V[level] ] [ -W[pen][attr] ] [ -Xx_offset ] [
-Yy_offset ] [ -aflags ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [
-fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ]
[ -:[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 speci-
fied 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 a|)
Select map projection.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more a|)
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|x|y]
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use the -A flag. Alterna-
tively, 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 paral-
lels, for example). For Cartesian data, points are simply con-
nected, 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 a|)
Set map boundary frame and axes attributes.
-Ccpt Give a CPT or specify -Ccolor1,color2[,color3,a|] 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 con-
trol the color of the line or polygon (if -L is set) via the
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 asymmetri-
cal 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 abox-and-whiskera (or
astem-and-leafa) symbols. The x (or y) coordinate is then taken
as the median value, and four more columns are expected to con-
tain the minimum (0% quantile), the 25% quantile, the 75% quan-
tile, 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
abox-and-whiskera 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 coor-
dinates of a refpoint which will serve as a fixed external ref-
erence point for all groups.
-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].
-K (more a|)
Do not finalize the PostScript plot.
-L[+b|d|D][+xl|r|x0][+yl|r|y0][+ppen]
Force closed polygons. Alternatively, append modifiers to build
a polygon from a line segment. Append +d to build symmetrical
envelope around y(x) using deviations dy(x) given in extra col-
umn 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 out-
line].
-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.
-O (more a|)
Append to existing PostScript plot.
-P (more a|)
Select aPortraita 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 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 col-
umn 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 diame-
ter 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 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 (cir-
cles) with just the diameter given, use -SE-. The diame-
ter is excepted to be given in column 3. Alternatively,
append the desired diameter to -SE- and this fixed diame-
ter 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 sym-
bol to plot: box, circle, fault, slip, or triangle.
[Default is fault]. Slip means left-lateral or right-lat-
eral 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). The use an alternate pen, append
+ppen. To skip the outline, just use +p. Note: By plac-
ing -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-clock-
wise 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 pro-
jection in which we assume the dimensions are given in
the same units as -R. For allowable geographical units,
see UNITS.
-Sk kustom symbol. Append name/size, and we will look for a
definition file called name.def in (1) the current direc-
tory 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 col-
umns 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 con-
tours. 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,a|]
Give the coordinates of the end points for one
or more comma-separated straight line segments.
Labels will be placed where these lines inter-
sect 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 cen-
ters them along the line]. N-1 places one jus-
tified 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 suc-
cessive 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 resam-
ple the lines first along great-circle arcs.
In addition, you may optionally append +rra-
dius[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_PRI-
MARY with its size changed to 9p].
+g[color]
Selects opaque text boxes [Default is transpar-
ent]; 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 speci-
fied for that algorithm]. Requires a map pro-
jection to be used. +Lf Use text after the 2nd
column in the fixed label location file as the
label. Requires the fixed label location set-
ting. +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 lineas 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 cor-
responding 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 sepa-
rated 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 seg-
ment-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 hor-
izontal) 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 vec-
tor 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. Append +a to just draw the arc
line or +r to just draw the radial lines.
-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.)
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.
-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 geo-
graphical 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.
-S~ 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 algo-
rithms:
ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
For lower case d, give distances between sym-
bols 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,a|]
Give the coordinates of the end points for one
or more comma-separated straight line segments.
Symbols will be placed where these lines inter-
sect 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 plac-
ing 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 suc-
cessive 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 deco-
rated 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 con-
catenated string made up of any of the following con-
trol arguments:
+aangle
For symbols at a fixed angle, +an for line-nor-
mal, 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 speci-
fied amount (append c|i|p to specify the
units). Increments are considered in the coor-
dinate system defined by the orientation of the
line; use +N to force increments in the plot
x/y coordinates system [no nudging].
+p[pen]
Draws the outline of symbols [Default is no
outline]; optionally specify pen for outline
[Default is width = 0.25p, color = black, style
= solid].
+s<symbol><size>
Specifies the code and size of the decorative
symbol.
+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.
-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 pro-
ducing any plotting output.
-U[[just]/dx/dy/][c|label] (more a|)
Draw GMT time stamp logo on plot.
-V[level] (more a|)
Select verbosity level [c].
-W[pen][attr] (more a|)
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 addi-
tional 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 dis-
tances]; +s will draw the line using a PostScript Bezier spline
[linear spline]; +vvspecs will place a vector head at the ends
of the lines. You can use +vb and +ve to specify separate vec-
tor specs at each end [shared specs]. Because +v may take addi-
tional modifiers it must necessarily be given at the end of the
pen specification. See the Vector Attributes for more informa-
tion.
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more a|)
Shift plot origin.
-bi[ncols][t] (more a|)
Select native binary input. [Default is the required number of
columns given the chosen settings].
-acol=name[^<i>a|] (more a|)
Set aspatial column associations col=name.
-dinodata (more a|)
Replace input columns that equal nodata with NaN.
-e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
Determine data gaps and line breaks. The -g option is ignored if
-S is set.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
Select input columns and transformations (0 is first column).
-:[i|o] (more a|)
Swap 1st and 2nd column on input and/or output.
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
Select perspective view.
-t[transp] (more a|)
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 explana-
tion 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.
UNITS
For map distance unit, append unit d for arc degree, m for arc minute,
and s for arc second, or e for meter [Default], f for foot, k for km, M
for statute mile, n for nautical mile, and u for US survey foot. By
default we compute such distances using a spherical approximation with
great circles. Prepend - to a distance (or the unit is no distance is
given) to perform aFlat Eartha 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 justifica-
tion 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 MAP_VECTOR_SHAPE [0].
+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 [for-
ward]. 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 cir-
cles. 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.
EXAMPLES
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 ter-
minal 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 PARSING
Segment header records may contain one of more of the following
options:
-Gfill Use the new fill and turn filling on
-G- Turn filling off
-G Revert to default fill (none if not set on command line)
-Wpen Use the new pen and turn outline on
-W Revert to default pen MAP_DEFAULT_PEN (if not set on command
line)
-W- Turn outline off
-Zzval Obtain fill via cpt lookup using z-value zval
-ZNaN Get the NaN color from the CPT
CUSTOM SYMBOLS
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 num-
ber 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 App-custom_symbols 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 spe-
cial 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.
SEE ALSO
gmt(1), gmt.conf(5), gmtcolors(5), psbasemap(1), psxyz(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 psxy(1)
gmt5 5.4.2 - Generated Thu Jun 29 16:04:26 CDT 2017