gmt-fork/doc/rst/source/plot_common.rst_

|No-spaces|

Description
-----------

Reads (*x*,\ *y*) pairs from *files* [or standard input] and will plot lines, polygons, or symbols at those locations on a map.
If a symbol is selected and no symbol size given, then it 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.

Required Arguments
------------------

.. _-J:

.. |Add_-J| unicode:: 0x20 .. just an invisible code
.. include:: explain_-J.rst_

.. _-R:

.. |Add_-R| unicode:: 0x20 .. just an invisible code
.. include:: explain_-R.rst_

.. |Add_-Rz| unicode:: 0x20 .. just an invisible code
.. include:: explain_-Rz.rst_

Optional Arguments
------------------

.. |Add_intables| unicode:: 0x20 .. just an invisible code
.. include:: explain_intables.rst_

.. _-A:

**-A**\ [**m**\|\ **p**\|\ **x**\|\ **y**]
    By default, geographic line segments are drawn as great circle arcs by resampling
    coarse input data along such arcs. To disable this sampling and 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:

.. include:: explain_-B.rst_

.. _-C:

**-C**\ *cpt*
    Give a CPT or specify **-C**\ *color1,color2*\ [*,color3*\ ,...]
    to build a linear continuous CPT from those colors automatically,
    where *z* starts at 0 and is incremented by one for each color.
    In this case *color*\ **n** 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 it expects the user to
    supply a multisegment file where each segment header contains a
    **-Z**\ *val* string. The *val* will control the color of the line or
    polygon (if **-L** is set) via the CPT.  If modern mode and no argument is given
    then we select the current CPT.

.. _-D:

**-D**\ *dx*/*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:

**-E**\ [**x**\|\ **y**\|\ **X**\|\ **Y**][**+a**][**+cl**\|\ **f**][**+n**][**+w**\ *cap*][**+p**\ *pen*]
    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 asymmetrical 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
    "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
    [7\ **p**]. Pen attributes for error bars may also be set via **+p**\ *pen*.
    [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:

**-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 coordinates of a *refpoint* which will serve as a fixed external
    reference point for all groups.

.. _-G:

**-G**\ *fill*\|\ **+z** :ref:`(more ...) <-Gfill_attrib>`
    Select color or pattern for filling of symbols or polygons [Default is no fill].
    Note that this module will search for **-G** and **-W** strings in all the
    segment headers and let any values thus found over-ride the command line settings.
    If **-Z** is set, use **-G+z** to assign fill color via **-C**\ *cpt* and the
    *z*-values obtained.

.. _-I:

**-I**\ *intens*
    Use the supplied *intens* value (nominally in the -1 to +1 range) to
    modulate the fill color by simulating illumination [none]. If no intensity
    is provided we will instead read *intens* from the first data column after
    the symbol parameters (if given).

.. _-L:

**-L**\ [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*][**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*] |ex_OPT-L|
    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 **+p**\ *pen* [no outline].
    **Note**: When options like **-G** and **-Z** are passed via segment headers you will need **-L** to ensure
    your segments are interpreted as polygons.

.. _-N:

**-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.

.. _-S:

.. include:: explain_symbols.rst_

.. _-T:

**-T**
    Ignore all input files.  If **-B** is not used then **-R -J** are not required.
    Typically used to move plot origin via **-X** and **-Y**.

.. _-U:

.. include:: explain_-U.rst_

.. _-V:

.. |Add_-V| unicode:: 0x20 .. just an invisible code
.. include:: explain_-V.rst_

.. _-W:

**-W**\ [*pen*][*attr*] :ref:`(more ...) <-Wpen_attrib>`
    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:
    **+o**\ *offset*\ *unit* will start and stop drawing the line the given distance offsets
    from the end point.  Append unit *unit* 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 Bezier spline [linear spline];
    **+v**\ *vspecs* will place a vector head at the ends of the lines.  You can
    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.
    See the `Vector Attributes`_ for more information.
    If **-Z** is set, then append **+z** to **-W** to assign pen color via **-C**\ *cpt* and the
    *z*-values obtained.

.. _-X:

.. include:: explain_-XY.rst_

.. _-Z:

**-Z**\ *value*\|\ *file*
    Instead of specifying a symbol or polygon fill and outline color via **-G** and **-W**,
    give both a *value* via **-Z** and a color lookup table via **-C**.  Alternatively,
    give the name of a *file* with one z-value (read from the last column) for each polygon in the input data.
    To apply the color obtain to a fill, use **-G+z**; to apply it to the pen color, append **+z** to **-W**.

.. |Add_-bi| replace:: [Default is the required number of columns given the chosen settings].
.. include:: explain_-bi.rst_

.. include:: explain_-aspatial.rst_

.. |Add_-di| unicode:: 0x20 .. just an invisible code
.. include:: explain_-di.rst_

.. |Add_-e| unicode:: 0x20 .. just an invisible code
.. include:: explain_-e.rst_

.. |Add_-f| unicode:: 0x20 .. just an invisible code
.. include:: explain_-f.rst_

.. |Add_-g| replace:: The **-g** option is ignored if **-S** is set.
.. include:: explain_-g.rst_

.. |Add_-h| unicode:: 0x20 .. just an invisible code
.. include:: explain_-h.rst_

.. include:: explain_-icols.rst_

.. |Add_-l| unicode:: 0x20 .. just an invisible code
.. include:: explain_-l.rst_

.. include:: explain_-qi.rst_

.. include:: explain_colon.rst_

.. |Add_perspective| unicode:: 0x20 .. just an invisible code
.. include:: explain_perspective.rst_

.. include:: explain_-t.rst_
If no transparency is appended then we will read it from the last column per data record instead.

.. include:: explain_help.rst_

.. include:: explain_distunits.rst_

.. include:: explain_vectors.rst_