.\" Man page generated from reStructuredText.
.
.TH "GRDVECTOR" "1gmt" "Sep 07, 2019" "6.0.0rc4" "GMT"
.SH NAME
grdvector \- Plot vector field from two component grids
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgmt grdvector\fP \fIcompx.nc\fP \fIcompy.nc\fP \fB\-J\fP\fIparameters\fP [  \fB\-A\fP ]
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-C\fP\fIcpt\fP ]
[  \fB\-G\fP\fIfill\fP ]
[  \fB\-I\fP[\fBx\fP]\fIdx\fP[/\fIdy\fP] ]
[  \fB\-N\fP ] [  \fB\-Q\fP\fIparameters\fP ]
[  \fB\-R\fP\fIregion\fP ]
[  \fB\-S\fP[\fBi\fP|\fBl\fP]\fIscale\fP[\fIunit\fP] ]
[  \fB\-T\fP ]
[  \fB\-U\fP[\fIstamp\fP] ]
[  \fB\-W\fP\fIpen\fP ]
[  \fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIxshift\fP[\fBu\fP]] ]
[  \fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIyshift\fP[\fBu\fP]] ]
[  \fB\-Z\fP ]
[ \fB\-f\fPflags ]
[ \fB\-p\fPflags ]
[ \fB\-t\fPtransp ]
[ \fB\-\-PAR\fP=\fIvalue\fP ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBgrdvector\fP reads two 2\-D grid files which represents the \fIx\fP\- and
\fIy\fP\-components of a vector field and produces a vector field plot by
drawing vectors with orientation and length according to the information
in the files. Alternatively, polar coordinate \fIr\fP, \fItheta\fP grids may be given
instead.
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
.B \fIcompx.nc\fP
Contains the x\-components of the vector field.
.TP
.B \fIcompy.nc\fP
Contains the y\-components of the vector field. (See GRID FILE FORMATS below.)
.UNINDENT
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection.  
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-A\fP
The grid files contain polar (r, theta) components instead of
Cartesian (x, y) [Default is Cartesian components].
.UNINDENT
.INDENT 0.0
.TP
\fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP (more ...)
Set map boundary frame and axes attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP[\fIcpt\fP |\fImaster\fP[\fB+i\fP\fIzinc\fP] |\fIcolor1,color2\fP[,\fIcolor3\fP,...]]
Use \fIcpt\fP to assign colors based on vector length. Alternatively,
supply the name of a GMT color master dynamic CPT [turbo] to
automatically determine a continuous CPT from
the grid\(aqs z\-range; you may round up/down the z\-range by adding \fB+i\fP\fIzinc\fP\&..
Yet another option is to specify \fB\-C\fP\fIcolor1,color2\fP[,\fIcolor3\fP,...]
to build a linear continuous cpt from those colors automatically.
In this case \fIcolor\fP\fBn\fP can be a r/g/b triplet, a color name,
or an HTML hexadecimal color (e.g. #aabbcc ).  If no argument is given to \fB\-C\fP
then under modern mode we select the current CPT.
.UNINDENT
.INDENT 0.0
.TP
\fB\-G\fP\fIfill\fP
Sets color or shade for vector interiors [Default is no fill].
.UNINDENT
.INDENT 0.0
.TP
\fB\-I\fP[\fBx\fP]\fIdx\fP[/\fIdy\fP]
Only plot vectors at nodes every \fIx_inc\fP, \fIy_inc\fP apart (must be
multiples of original grid spacing). Append \fBm\fP for arc minutes or
\fBs\fP for arc seconds.  Alternatively, use \fB\-Ix\fP to specify the
multiples \fImultx\fP[/\fImulty\fP] directly [Default plots every node].
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP
Do NOT clip vectors at map boundaries [Default will clip].
.UNINDENT
.INDENT 0.0
.TP
\fB\-Q\fP\fIparameters\fP
Modify vector parameters. For vector heads, append vector head
\fIsize\fP [Default is 0, i.e., stick\-plot]. See VECTOR ATTRIBUTES for
specifying additional attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest. Specify a subset of the grid.
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP[\fBi\fP|\fBl\fP]\fIscale\fP[\fIunit\fP]
Sets scale for vector plot length in data units per plot distance measurement
unit [1]. Append \fBc\fP, \fBi\fP, or \fBp\fP to indicate the measurement
unit (cm, inch, or point); if no unit is given we use the default value that
is controlled by PROJ_LENGTH_UNIT\&. Alternatively,
use \fB\-Sl\fP\fIlength\fP[\fIunit\fP] to set a fixed plot length for all vectors.  Vectors given
via plot unit scaling will plot as straight vectors and their lengths are not
affected by map projection and coordinate locations.
For geographic data you may alternatively give \fIscale\fP in data units per
map distance unit (see Unit_attributes). Then, your user units are scaled to map distances in the given unit
which are projected to plot dimensions.  These are geo\-vectors that follow
great circle paths and their lengths are affected by the map projection and their
coordinates.  Finally, use \fB\-Si\fP if it is simpler to give the reciprocal scale in
measurement unit per data unit or km per data unit.  To report the minimum, maximum,
and mean scaled vector length, use \fB\-Vl\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP
Means the azimuths of Cartesian data sets should be adjusted according to the
signs of the scales in the x\- and y\-directions [Leave alone].  This option can
be used to convert vector azimuths in cases when a negative scale is used in
one of both directions (e.g., positive down).
.UNINDENT
.INDENT 0.0
.TP
\fB\-U\fP[\fIlabel\fP][\fB+c\fP][\fB+j\fP\fIjust\fP][\fB+o\fP\fIdx\fP/\fIdy\fP] (more ...)
Draw GMT time stamp logo on plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-W\fP\fIpen\fP
Set pen attributes used for vector outlines [Default: width =
default, color = black, style = solid].
.UNINDENT
.sp
\fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIxshift\fP[\fBu\fP]]
.INDENT 0.0
.TP
\fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIyshift\fP[\fBu\fP]] (more ...)
Shift plot origin.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Z\fP
The theta grid provided contains azimuths rather than directions (implies \fB\-A\fP).
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-p\fP[\fBx\fP|\fBy\fP|\fBz\fP]\fIazim\fP[/\fIelev\fP[/\fIzlevel\fP]][\fB+w\fP\fIlon0\fP/\fIlat0\fP[/\fIz0\fP]][\fB+v\fP\fIx0\fP/\fIy0\fP] (more ...)
Select perspective view.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-t\fP[\fItransp\fP] (more ...)
Set transparency level in percent.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.TP
\fB\-\-PAR\fP=\fIvalue\fP
Temporarily override a GMT default setting; repeatable. See /gmt.conf for parameters.
.UNINDENT
.SH UNITS
.sp
For map distance unit, append \fIunit\fP \fBd\fP for arc degree, \fBm\fP for arc
minute, and \fBs\fP for arc second, or \fBe\fP for meter [Default], \fBf\fP
for foot, \fBk\fP for km, \fBM\fP for statute mile, \fBn\fP for nautical mile,
and \fBu\fP for US survey foot. By default we compute such distances using
a spherical approximation with great circles (\fB\-jg\fP). You can use \fB\-jf\fP to perform
"Flat Earth" calculations (quicker but less accurate) or \fB\-je\fP to perform
exact geodesic calculations (slower but more accurate; see
PROJ_GEODESIC for method used).
.SH GRID FILE FORMATS
.sp
By default GMT writes out grid as single precision floats in a
COARDS\-complaint netCDF file format. However, GMT is able to produce
grid files in many other commonly used grid file formats and also
facilitates so called "packing" of grids, writing out floating point
data as 1\- or 2\-byte integers. (more ...)
.SH VECTOR ATTRIBUTES
.sp
Several modifiers may be appended to vector\-producing options for
specifying 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 a segment:
.INDENT 0.0
.INDENT 3.5
\fB+a\fP\fIangle\fP sets the angle of the vector head apex [30].
.sp
\fB+b\fP places a vector head at the beginning of the vector path [none].
Optionally, append \fBt\fP for a terminal line, \fBc\fP for a circle,
\fBa\fP for arrow [Default], \fBi\fP for tail, \fBA\fP for plain open arrow,
and \fBI\fP for plain open tail.
Further append \fBl\fP|\fBr\fP to only draw the left or right
half\-sides of this head [both sides].
.sp
\fB+e\fP places a vector head at the end of the vector path [none].
Optionally, append \fBt\fP for a terminal line, \fBc\fP for a circle,
\fBa\fP for arrow [Default], \fBi\fP for tail, \fBA\fP for plain open arrow,
and \fBI\fP for plain open tail.
Further append \fBl\fP|\fBr\fP to only draw the left or right
half\-sides of this head [both sides].
.sp
\fB+g\fP\-|\fIfill\fP turns off vector head fill (if \-) or sets the vector
head fill [Default fill is used, which may be no fill].
.sp
\fB+h\fP\fIshape\fP sets the shape of the vector head (range \-2/2). Default
is controlled by MAP_VECTOR_SHAPE [0].
.sp
\fB+l\fP draws half\-arrows, using only the left side of specified heads [both sides].
.sp
\fB+m\fP places a vector head at the mid\-point the vector path [none].
Append \fBf\fP or \fBr\fP for forward or reverse direction of the vector [forward].
Optionally, append \fBt\fP for a terminal line, \fBc\fP for a circle,
\fBa\fP for arrow [Default], \fBi\fP for tail, \fBA\fP for plain open arrow,
and \fBI\fP for plain open tail. Further append \fBl\fP|\fBr\fP to only draw the left or right
half\-sides of this head [both sides].  Cannot be combined with \fB+b\fP or \fB+e\fP\&.
.sp
\fB+n\fP\fInorm\fP scales down vector attributes (pen thickness, head size)
with decreasing length, where vector plot lengths shorter than \fInorm\fP will have
their attributes scaled by length/\fInorm\fP [arrow attributes remains
invariant to length]. For Cartesian vectors specify a length in plot units, while
for geovectors specify a length in km.
.sp
\fB+o\fP[\fIplon\fP/\fIplat\fP] specifies the oblique pole for the great or
small circles.  Only needed for great circles if \fB+q\fP is given. If no
pole is appended then we default to the north pole.
.sp
\fB+p\fP[\-][\fIpen\fP] sets the vector pen attributes. If \fIpen\fP has a
leading \- then the head outline is not drawn. [Default pen is half the width of stem pen, and
head outline is drawn]
.sp
\fB+q\fP means the input \fIangle\fP, \fIlength\fP data instead represent the \fIstart\fP and \fIstop\fP
opening angles of the arc segment relative to the given point. See \fB+o\fP to specify
a specific pole for the arc [north pole].
.sp
\fB+r\fP draws half\-arrows, using only the right side of specified heads [both sides].
.sp
\fB+t\fP[\fBb\fP|\fBe\fP]\fItrim\fP[\fIunit\fP] will shift the beginning or end point (or both)
along the vector segment by the given \fItrim\fP; append suitable unit (\fBc\fP, \fBi\fP, or \fBp\fP). If the modifiers
\fBb\fP|\fBe\fP are not used then \fItrim\fP may be two values separated by a slash,
which is used to specify different trims for the beginning and end.  Positive trims
will shorted the vector while negative trims will lengthen it [no trim].
.UNINDENT
.UNINDENT
.sp
In addition, all but circular vectors may take these modifiers:
.INDENT 0.0
.INDENT 3.5
\fB+j\fP\fIjust\fP determines how the input \fIx\fP,\fIy\fP point relates to the
vector. Choose from \fBb\fPeginning [default], \fBe\fPnd, or \fBc\fPenter.
.sp
\fB+s\fP means the input \fIangle\fP, \fIlength\fP are instead the \fIx\fP, \fIy\fP
coordinates of the vector end point.
.UNINDENT
.UNINDENT
.sp
Finally, Cartesian vectors may take these modifiers:
.INDENT 0.0
.INDENT 3.5
\fB+z\fP\fIscale\fP[\fIunit\fP] expects input \fIdx\fP,\fIdy\fP vector components and
uses the \fIscale\fP to convert to polar coordinates with length in given unit.
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
To draw the vector field given by the files r.nc and theta.nc on a
linear plot with scale 5 cm per data unit, using vector rather than
stick plot, scale vector magnitudes so that 10 units equal 1 inch, and
center vectors on the node locations, run
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvector r.nc theta.nc \-Jx5c \-A \-Q0.1i+e+jc \-S10i \-pdf gradient
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To plot a geographic data sets given the files comp_x.nc and comp_y.nc,
using a length scale of 200 km per data unit and only plot every 3rd node in either direction, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvector comp_x.nc comp_y.nc \-Ix3 \-JH0/20c \-Q0.1i+e+jc \-S200k \-pdf globe
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH NOTES
.sp
Be aware that using \fB\-I\fP may lead to aliasing unless
your grid is smoothly varying over the new length increments.
It is generally better to filter your grids and resample at a
larger grid increment and use these grids instead of the originals.
.SH SEE ALSO
.sp
gmt, gmtcolors,
grdcontour, plot
.SH COPYRIGHT
2019, The GMT Team
.\" Generated by docutils manpage writer.
.