Vector Attributes
-----------------

.. figure:: /_images/GMT_vector.*
    :width: 600 px
    :align: center

    Vector attributes are controlled by options and modifiers.  We will refer to
    this figure and the labels therein when introducing the corresponding modifiers.
    All vectors require you to specify the **b**\ egin point :math:`x_b, y_b` and
    the **e**\ nd point :math:`x_e, y_e`, or alternatively the direction *d* and length
    *L*, while for map projections we usually specify the azimuth :math:`\alpha` instead.

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 beginning point (**b**) to the
end point (**e**) of a line segment:

    - **+a** - Append *argument* to set the angle :math:`\theta` of the vector head apex [30].
    - **+b** - Place a vector head at the **b**\ eginning of the vector path [none].
      Optionally, append **t** for a terminal line, **c** for a circle, **s** for a square,
      **a** for arrow [Default], **i** for tail, **A** for plain open arrow,
      and **I** for plain open tail. **Note**: For geovectors only **a** and **A** are available.
      Further append **l**\|\ **r** to only draw the left or right
      half-sides of this head [both sides].
    - **+c** - Select the vector data quantity *magnitude* for use with CPT color look-up [Default
      requires a separate data column following the 2 or 3 coordinates]. Requires that data
      quantity scaling (with unit **q** via **+v** or **+z**) and a CPT have been selected.
    - **+e** - Place a vector head at the **e**\ nd of the vector path [none].
      Optionally, append **t** for a terminal line, **c** for a circle, **s** for a square,
      **a** for arrow [Default], **i** for tail, **A** for plain open arrow,
      and **I** for plain open tail. **Note**: For geovectors only **a** and **A** are available.
      Further append **l**\|\ **r** to only draw the left or right
      half-sides of this head [both sides].
    - **+g** - Append [*fill*] sets the vector head fill [Default fill is used, which may be no fill].
      Turn off vector head fill by not appending a *fill*.  Some modules have a separate
      **-G**\ *fill* option and if used will select the fill as well.
    - **+h** Append *shape* of the vector head (range -2/2). Default
      is controlled by :term:`MAP_VECTOR_SHAPE` [default is :doc:`theme dependent </theme-settings>`].
      A zero value produces no notch. Positive values moves the notch toward the head apex while a
      negative value moves it away. The example above uses **+h**\ 0.5.
    - **+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,
      **a** for arrow [Default], **i** for tail, **A** for plain open arrow,
      and **I** for plain open tail. Further append **l**\|\ **r** to only draw the left or right
      half-sides of this head [both sides].  Cannot be combined with **+b** or **+e**.
    - **+n** - Give [*norm*\ [/*min*]] to scale down vector attributes (pen thickness, head size)
      with decreasing length, where vector plot lengths shorter than *norm* will have
      their attributes scaled by length/\ *norm* [other arrow attributes remain
      invariant to length]. Optionally, append /*min* for the minimum shrink factor (in the
      0-1 range) that we will shrink to [0.25]. For Cartesian vectors, please specify a *norm*
      in plot units, while for geovectors specify a *norm* in map units (see :ref:`reference/features:Distance units`) [k].
      Alternatively, append unit **q** to indicate we should use user quantity units in making the
      decision; this means the user also must select user quantity input via **+v** or **+z**.
      If no argument is given then **+n** ensures vector heads are not shrunk and always
      plotted regardless of vector length [Vector heads are not plotted if exceeding vector length].
    - **+o** - Specify the oblique pole [*plon*\ /\ *plat*] for the great or
      small circles.  Only needed for great circles if **+q** is given. If no
      pole is appended then we default to the north pole. Input arguments are then
      *lon lat arclength* with the latter in map distance units; see **+q** of angular limits instead.
    - **+p** - Sets the vector pen attributes [*pen*]. If no *pen* is appended
      then the head outline is not drawn. [Default pen is half the width of stem pen, and
      head outline is drawn]. Above, we used **+p**\ 2p,orange.  The vector stem attributes are
      controlled by **-W**.
    - **+q** - Means the input *direction*, *length* data instead represent the *start* and *stop*
      opening angles of the arc segment relative to the given point. See **+o** to specify
      a specific pole for the arc [north pole].
    - **+t**\ [**b**\|\ **e**]\ *trim* - Shift the beginning or end point (or both)
      along the vector segment by the given *trim*; append suitable unit (**c**, **i**, or **p**). 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 beginning and end.  Positive trims
      will shorted the vector while negative trims will lengthen it [no trim].

In addition, all but circular vectors may take these modifiers:

    - **+j** - The *just* determines how the input *x*,\ *y* point relates to the
      vector. Choose from **b**\ eginning [default], **e**\ nd, or **c**\ enter.
    - **+s** - The input *angle*, *length* are instead the :math:`x_e, y_e`
      coordinates of the vector end point.

Finally, Cartesian vectors and geovectors may take these modifiers (except in :doc:`grdvector </grdvector>`)
which can be used to convert vector components to polar form or magnify user quantity magnitudes
into plot lengths:

    - **+v**\ [**i**\|\ **l**]\ *scale* - Expects a *scale* to magnify the polar length in the given
      unit.  If **i** is prepended we use the inverse scale while if **l** is prepended then it is
      taken as a fixed length to override input lengths. Append unit **q** if input magnitudes are
      given in user quantity units and we will scale them to current plot unit for Cartesian vectors
      (see :term:`PROJ_LENGTH_UNIT` for how to change the plot unit) or to km for geovectors.  In addition,
      if **+c** is selected then the vector magnitudes may be used for CPT color-lookup (and no extra data
      column is required by **-C**).
    - **+z**\ [*scale*] - Expects input :math:`\Delta x, \Delta y` vector components and
      uses the *scale* [1] to convert to polar coordinates with length in given unit.
      Append unit **q** if input components are given in user quantity units and we will scale to current plot unit
      for Cartesian vectors (see :term:`PROJ_LENGTH_UNIT` for how to change the plot unit) or to
      km for geovectors.  In addition, if **+c** is selected then the vector magnitudes may be used
      for CPT color-lookup (and no extra data column is required by **-C**).
  
**Note**: Vectors were completely redesigned for GMT5 which separated the vector head (a polygon)
from the vector stem (a line).  In GMT4, the entire vector was a polygon and it could only
be a straight Cartesian vector. Yes, the old GMT4 vector shape remains accessible if
you specify a vector (**-Sv**\|\ **V**) using the GMT4 syntax, explained here: *size*, if present, will
be interpreted as :math:`t_w/h_l/h_w` or *tailwidth/headlength/halfheadwidth* [Default is 0.075c/0.3c/0.25c (or
0.03i/0.12i/0.1i)]. By default, arrow attributes remain invariant to the length of the
arrow. To have the size of the vector scale down with decreasing size, append **+n**\ *norm*,
where vectors shorter than *norm* will have their attributes scaled by *length*/*norm*.
To center the vector on the balance point, use **-Svb**; to align point with the vector head,
use **-Svh**; to align point with the vector tail, use **-Svt** [Default]. To give the
head point’s coordinates instead of direction and length, use **-Svs**. Upper case
**B**, **H**, **T**, **S** will draw a double-headed vector [Default is single head].
**Note**: If :math:`h_l/h_w` are given as 0/0 then only the head-less vector stick will be plotted.

.. figure:: /_images/GMT_vector4.*
    :width: 600 px
    :align: center

    A GMT 4 vector has no separate pen for the stem -- it is all part of a Cartesian polygon.
    You may optionally fill and draw its outline.  The modifiers listed above generally do
    not apply.  **Note**: While the *tailwidth* (:math:`t_w`) and *headlength* (:math:`h_l`)
    parameters are given as indicated, the *halfheadwidth* (:math:`h_w`) is oddly given as the
    half-width in GMT 4 so we retain that convention here (but have updated the documentation;
    blue lines indicate these three parameters).

