:author: 田冬冬, 陈箫翰, 周茂, 王亮, 何星辰, 姚家园
:date: 2026-01-23

.. index:: ! plot
.. program:: plot

plot
========

:官方文档: :doc:`gmt:plot`
:简介: 在图上绘制线段、多边形和符号

读取 (*x*,\ *y*) 坐标数据，并在图上的相应位置绘制线、多边形或符号。

- 使用 :option:`-S` 选项，在数据点所在位置绘制符号。
  如果参数中没有给出符号大小，则会将输入数据的第三列解释为符号大小，符号大小必须大于 0 。
  如果参数中没有指定具体绘制哪种符号，则输入数据的最后一列必须是符号代码。
  使用 :option:`-G` 选项设置符号的填充颜色或填充图案。
  使用 :option:`-W` 选项绘制符号的轮廓，并设置轮廓的画笔属性。

- 不使用 :option:`-S` 选项，则绘制线条把数据点依次连接。
  使用 :option:`-L` 选项会把最后一个数据点和第一个数据点相连，绘制出一个闭合多边形。
  使用 :option:`-G` 选项设置闭合多边形的填充颜色或填充图案。
  使用 :option:`-W` 选项设置线条或多边形各边的画笔属性。

语法
--------

**gmt plot**
[ *table* ]
[ :option:`-A`\ [**x**\|\ **y**] ]
[ :option:`-B`\ [**p**\|\ **s**]\ *parameters* ]
[ :option:`-C`\ *cpt* ]
[ :option:`-D`\ *dx*\ [/*dy*] ]
[ :option:`-E`\ [**x**\|\ **y**\|\ **X**\|\ **Y**][**+a**\|\ **A**][**+cl**\|\ **f**][**+n**][**+w**\ *width*\ [/*cap*]][**+p**\ *pen*] ]
[ :option:`-F`\ [**c**\|\ **n**\|\ **p**][**a**\|\ **s**\|\ **t**\|\ **r**\|\ *refpoint*] ]
[ :option:`-G`\ *fill*\|\ **+g**\|\ **+z** ]
[ :option:`-H`\ [*scale*] ]
[ :option:`-I`\ [*intens*] ]
[ :option:`-J`\ *parameters* ]
[ :option:`-L`\ [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*][**+yb**\|\ **t**\|\ *y0*][**+p**\ *pen*] ]
[ :option:`-M`\ [**c**\|\ **s**][**+l**\ *seclabel*][**+g**\ *fill*][**+p**\ *pen*][**+r**\ *pen*][**+y**\ [*level*]] ]
[ :option:`-N`\ [**c**\|\ **r**] ]
[ :option:`-R`\ *west*/*east*/*south*/*north*\ [**+r**][**+u**\ *unit*] ]
[ :option:`-S`\ [*symbol*][*size*] ]
[ :option:`-U`\ [*stamp*] ]
[ :option:`-V`\ [*level*] ]
[ :option:`-W`\ [*pen*][*attr*] ]
[ :option:`-X`\ [**a**\|\ **c**\|\ **f**\|\ **r**][*xshift*] ]
[ :option:`-Y`\ [**a**\|\ **c**\|\ **f**\|\ **r**][*yshift*] ]
[ :option:`-Z`\ *value*\|\ *file*\ [**+t**\|\ **T**] ]
[ :option:`-a`\ *flags* ]
[ :option:`-bi`\ *binary* ]
[ :option:`-di`\ *nodata*\ [**+c**\ *col*] ]
[ :option:`-e`\ *regexp* ]
[ :option:`-f`\ *flags* ]
[ :option:`-g`\ *gaps* ]
[ :option:`-h`\ *headers* ]
[ :option:`-i`\ *flags* ]
[ :option:`-l`\ *flags* ]
[ :option:`-p`\ *flags* ]
[ :option:`-qi`\ *flags* ]
[ :option:`-t`\ *transp* ]
[ :option:`-w`\ *flags* ]
[ :option:`-:`\ [**i**\|\ **o**] ]
[ :doc:`--PAR=value </conf/overview>` ]

输入数据
------------------

.. include:: explain_intables.rst_

可选选项
--------

.. include:: explain_line_draw.rst_

.. include:: explain_-B.rst_

.. include:: create_cpt.rst_
..

    本选项可以使符号和多边形的填充颜色、线段和多边形的线条颜色由 Z 值决定。

    #. 若绘制符号（即使用 :option:`-S` 选项），则符号的填充色由数据的第三列 Z 值决定，
       其他数据列依次后移一列。
    #. 若绘制线段或多边形（即未使用 :option:`-S` 选项），则需要在多段数据的数据段头记录中指定
       :option:`-Z`\ *val* (参见 :ref:`table-ascii-attrs` )。CPT文件中 *val* 所对应的颜色，
       即为线段或多边形的颜色。

.. option:: -D

**-D**\ *dx*\ [/*dy*]
    该选项会将符号或线段在给定坐标的基础上偏移 *dx*/*dy* 距离。
    可以附加单位 **c**\ \|\ **i**\ \|\ **p** 。
    若未指定 *dy*，则默认 *dy* = *dx*。

.. option:: -E

**-E**\ [**x**\|\ **y**\|\ **X**\|\ **Y**][**+a**\|\ **A**][**+cl**\|\ **f**][**+n**][**+w**\ *width*\ [/*cap*]][**+p**\ *pen*]
    绘制误差棒或箱线图（茎叶图）符号。不附带参数使用 **-E** 默认同时绘制 *x* 和 *y* 误差棒，等效于 **-Exy**。
    误差数据 *x_error* 和 *y_error* 为 (*x, y*) 或 (*x, y, z*) 后面两列。
    可以附带以下参数：

    - **x** - 在 *x* 方向绘制误差棒。误差数据 *x_error* 为 (*x, y*) 或 (*x, y, z*) 后面一列。
    - **y** - 在 *y* 方向绘制误差棒。误差数据 *y_error* 为 (*x, y*) 或 (*x, y, z*) 后面一列。
    - **X** - 在 *x* 方向绘制箱线图（茎叶图）符号。
      *x* 坐标被视为中位数，(*x, y*) 或 (*x, y, z*) 后面四列数据为 :math:`0\%` 分位数、:math:`25\%` 分位数、:math:`75\%` 分位数和 :math:`100\%` 分位数。
      可以使用 :option:`-G` 对 :math:`25\% \text{-} 75\%` 的箱体进行填充。
    - **Y** - 在 *y* 方向绘制箱线图（茎叶图）符号。其余与 **X** 相同。

    使用以下附加选项设置符号的外观：

    - **+a** - 绘制非对称误差棒 [默认是对称误差棒]。需要两个而非一个额外数据列，分别包含两个带符号的偏差值。
    - **+A** - 类似，但读取的是低限和高限值，而非带符号的偏差值。
    - **+n** - 绘制带缺口的箱线图符号，缺口宽度反映了中位数的不确定性。该符号需要第 5 个额外数据列来包含分布中的点数。
    - **+w** - 设置指示误差棒末端封顶线长度的宽度 (*width*) [默认为 7\ **p**]。
      对于箱线图符号，它同时设置默认箱体宽度和触须封顶线长度 [默认为 7\ **p**]。
      附加 *width*\ /*cap* 可为该类符号分别设置宽度和封顶线尺寸。
    - **+p** - 设置首选的误差棒画笔属性 *pen* [默认值：宽度 = 0.25p，颜色 = 黑色，样式 = 实线]。
    - **+c** - 和 :option:`-C` 同时使用，由 Z 值决定颜色。
      使用 **+cf** 只控制符号填充颜色， **+cl** 只控制误差棒画笔颜色。不带参数的 **+c** 同时控制两种颜色。

    **注意**：一般情况下误差棒会放置在符号之后。但对于大型垂直和水平条形符号（**-Sb**\|\ **B**），误差棒会绘制在顶部以避免下限被遮挡。

.. option:: -F

**-F**\ [**c**\|\ **n**\|\ **p**][**a**\|\ **r**\|\ **s**\|\ **t**\|\ *refpoint*]
    改变点的连接方式以及数据分组的方式。点的连接方式分为：

    - **c** 将每组数据中的点都依次相连 [默认]
    - **n** 将每组数据中的点都互相连接构成网
    - **p** 对每组数据设置新的参考点，从新参考点连接线段

    数据分组的方式包括：

    - **a** 忽略所有段头信息，所有点属于同一个分组，将参考点设置为第一个文件的第一个点
    - **r** 每个数据段都作为一个单独的组，每个点都是下一个点的参考点（仅适用于 **-Fp** ）
    - **s** 与 **r** 相同，但参考点设置为每个数据段的第一个点 [默认]
    - **t** 将每个文件中的所有数据视为一个单独的组，并将参考点设置为每个组的第一个点

    可以将 *refpoint* 设置为 *lon/lat* （或 *x/y* ）坐标替代 **a**\|\ **r**\|\ **s**\|\ **t**，该点将作为所有组的固定外部参考点。

    .. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_segmentize.png
        :width: 80%
        :align: center

        虚线表示原始输入数据，输入数据有两个文件 *t1.txt* 和 *t2.txt* 。而实线是改变后的连接方式和分组方式。第一张图是原始输入数据，随后的五个图表示 **-Fpa**、 **-Fpt**、 **-Fps**、 **-Fp**\ 10/35 和 **-Fna** 的效果。

.. option:: -G

**-G**\ *fill*\|\ **+g**\|\ **+z**
    设置符号或多边形的填充颜色或图案 [默认不填充]。
    本模块会在头段记录中搜索 :option:`-G` 和 :option:`-W` 选项，并覆盖对应选项的设置。
    如果头段记录中有 :option:`-Z` 选项，使用 **-G+z** 通过 :option:`-C`\ *cpt* 和 Z 值来分配填充颜色（如果通过 :option:`-Z` 设置了透明度，处理方式相同）。
    如果 *fill* = *auto*\ [*-segment*] 或 *auto-table*，将循环使用由 :term:`COLOR_SET` 定义的填充颜色，并按段或按表进行更改。任何 *transparency* 设置保持不变。

    使用 **+g** 启用多边形的基于顶点的颜色渐变（使用 Gouraud 着色）。会自动检测输入数据格式，并支持以下三种格式：

    1. **RGB 格式**：*x y r g b*，其中 RGB 值的范围为 0-255。
    2. **颜色名称格式**：*x y colorname*，其中 *colorname* 可以是颜色名字（如 "red"、"blue"）、十六进制颜色（如 "#FF0000"）、斜杠分隔的 RGB（如 "255/0/0"）、H-S-V 或 C/M/Y/K 格式。
    3. **CPT 格式**：*x y z*，其中 *z* 值通过 :option:`-C` 指定的 CPT 映射为颜色。

    支持具有任意数量顶点的多边形，并使用从第一个顶点开始的扇形三角剖分自动进行三角化。
    每个顶点都有自己的颜色，Gouraud 着色会在多边形面上创建平滑的颜色渐变。使用 :option:`-W` 为渐变多边形添加轮廓。

.. option:: -H

**-H**\ [*scale*]
    从数据中读取 *scale* 列，对每一条记录的符号大小和画笔宽度进行缩放。
    *scale* 列为 *z* 和 *size* 列之后的第一个数据列。
    也可以指定一个固定的 *scale* 数值进行统一缩放。

.. option:: -I

**-I**\ *intens*
    使用提供的 *intens* 值（在 :math:`\pm 1` 范围内），通过模拟光照来调节填充颜色 [默认无光照]。
    如果未提供光照强度值，将从符号参数之后的第一个数据列中读取 *intens*。

.. include:: explain_-J.rst_

.. option:: -L

**-L**\ [**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*][**+yb**\|\ **t**\|\ *y0*][**+p**\ *pen*]
    将第一个和最后一个数据点连接起来，将多段数据解释为闭合多边形。不使用本选项，多段数据只会被解释为线段。
    可以附加以下参数构建不同形式的多边形：

    * **+d** - 使用第 3 列额外数据中给出的偏差 :math:`dy(x)`，围绕 :math:`y(x)` 构建对称包络。
    * **+D** - 使用第 3-4 列额外数据中的偏差 :math:`dy1(x)` 和 :math:`dy2(x)`，围绕 :math:`y(x)` 构建非对称包络。
    * **+b** - 使用第 3-4 列额外数据中的上下限 :math:`yl(x)` 和 :math:`yh(x)`，围绕 :math:`y(x)` 构建非对称包络。
    * **+x** - 将第一个点和最后一个点连接到锚点。锚点可以是 *xmin*\ （附加 **l**）、 *xmax*\ （附加 **r**）或 *x0*\ （附加该数值）。
    * **+y** - 将第一个点和最后一个点连接到锚点。锚点可以是 *ymin*\ （附加 **b**）、 *ymax*\ （附加 **t**）或 *y0*\ （附加该数值）。
    * **+p**\ *pen* - 绘制轮廓 [默认无轮廓]。

    可以使用 :option:`-G` 填充颜色或图案。

.. option:: -M

**-M**\ [**c**\|\ **s**][**+l**\ *seclabel*][**+g**\ *fill*][**p**\ *pen*][**+r**\ *pen*][**+y**\ [*level*]]
    填充两条曲线 :math:`y_0(x)` 和 :math:`y_1(x)` 之间的中间区域。
    数据通过一对或多对独立的表文件提供，每对表具有相同数量的段（不同对之间的段数可以不同）。
    因此，命令行中给出的偶数个表文件的顺序非常重要。可以使用以下两个附加参数：

    * **c**：表示 :math:`y_1(x)` 与 :math:`y_0(x)` 协同配准，并在具有三列的任意数量的文件中作为第三列给出。每个文件可以包含任意数量的段。
    * **s**：与上述相同，但两条曲线通过独立的表对给出 [默认]。

    可以进一步附加以下选项：

    * **+g**：当 :math:`y_0(x)` 超过 :math:`y_1(x)` 时，使用通过 :option:`-G` 设置的 *fill* 填充该区域。对于相反的情况（即 :math:`y_1(x)` 较大时），在此处附加另一个 *fill*。
    * **+l**：为次级曲线附加图例标签。主曲线 :math:`y_0(x)` 则通过 :option:`-l` 设置图例标签。
    * **+p**：为曲线 :math:`y_1(x)` 指定单独的画笔属性 [默认与 :math:`y_0(x)` 的画笔相同]。曲线 :math:`y_0(x)` 的画笔属性参见 :option:`-W`。
    * **+r**：在图例中仅绘制线条而非矩形填充框， *pen* 只有线条宽度的设置有效，线条颜色设置无效。图例线条颜色由 *fill* 控制。
    * **+y**：将数据与一条水平恒定线进行比较。附加该水平线的值后，系统将生成 :math:`y_1(x)` 曲线，并将其与所有输入文件进行比较。

    **注意**：必须根据所需结果，至少指定一种填充或一个画笔属性。

    .. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_fill_curves.png
       :width: 80%
       :align: center

       使用本选项对曲线之间的区域进行涂色。会自动识别交点和 NaN 间隙，填充颜色取决于哪条曲线位于上方。图例可以设置为填充矩形，或者通过 **+r** 设置为线条。

.. option:: -N

**-N**\ [**c**\|\ **r**]
    不裁剪地图边界之外的符号 [默认情况下，仅绘制坐标严格位于地图边界内的点]。

    对于存在周期性的地图而言，若符号出现在重复边界上，则会被重复绘制两次。
    这种情况可以通过以下参数选项修改：

    #. **-N** 关闭裁剪，符号仅绘制一次
    #. **-Nr** 关闭裁剪，但符号依然绘制两次
    #. **-Nc** 不关闭裁剪，但符号仅绘制一次

    本选项也可以用于线或多边形，但请注意，这会导致不再考虑周期性（例如经度），并可能产生意想不到的后果。

.. include:: explain_-R.rst_

.. include:: explain_-U.rst_

.. include:: explain_-V.rst_

.. option:: -W

**-W**\ [*pen*][*attr*]
    设置线段或符号轮廓的画笔属性 *pen*，详细介绍请参考 :doc:`/basis/pen` 和 :doc:`/basis/line`。
    默认值 *width* = 0.25p, *color* = black, *style* = solid。

    附加参数 *attr* 可以设置为：

    * **+c** ：使用 CPT 文件控制颜色（参见 :option:`-C`）。
      使用 **+cl** 则表示线条颜色由 CPT 文件控制。
      使用 **+cf** 则符号的填充色由 CPT 文件控制。
      如果未给出参数， **+c** 则表示线条颜色和符号填充色同时由 CPT 文件控制。
    * **+o** ：附加 *offset*\ [*unit*]，将从距离起点终点 *offset* 的位置开始和停止绘制线条。 *unit* 为单位。
      如果线条的起点和终点有不同的偏移量， *offset* 改为 *b_offset/e_offset* 。
    * **+s** ：使用 Bezier 样条线绘制线条 [默认使用线性样条]。
    * **+v** ：使用 **+v**\ [**b**\ \|\ **e**]\ *vspecs*，在线条末端放置矢量箭头。可以单独指定 **b**\ （起点）或 **e**\ （终点）仅在其中一端添加矢量 [默认两端都添加]。
      **注意** ：由于 **+v** 可能带有额外的附带参数，因此必须放在选项参数的末尾。详细介绍请参考 :doc:`/basis/vector` 和 :doc:`/basis/line`。
    * **+z** ：如果设置了 :option:`-Z`，则通过 :option:`-C`\ *cpt* 和 *z* 值分配画笔颜色（如果通过 :option:`-Z` 设置了透明度，处理方式相同）。
      如果画笔属性 *pen* 里面的 *color* = *auto*\ [*-segment*] 或 *auto-table*，则循环使用由 :term:`COLOR_SET` 隐含的画笔颜色，并按段或按表进行更改。
      *width*、 *style* 或 *transparency* 设置保持不变。

.. include:: explain_-XY.rst_

.. option:: -Z

**-Z**\ *value*\|\ *file*\ [**+t**\|\ **T**]
    通过 Z 值控制线条和多边形的颜色和/或透明度。可以选择以下两种模式之一：

    1. 附加一个值 *value*，并通过 CPT 查找相应的颜色。
    2. 给出一个文件名 *file*，其中包含输入数据中每个多边形或线条的 Z 值（从最后一列读取）。

    控制颜色需要和 :option:`-C`\ *cpt* 、:option:`-G` 或 :option:`-W` 一起使用：

    * **-G+z** - 控制多边形填充颜色
    * **-W+z** - 控制线条颜色

    以下两个附加参数可用于处理透明度和/或颜色：

    * **+t** - 改为控制多边形或线条的透明度。Z 值将被假定为 :math:`0\text{-}100\%` 范围内的透明度。
    * **+T** - 通过 *file* 提供两列数据：最后一列必须是 Z 值，而倒数第二列为透明度（范围为 :math:`0\text{-}100\%`）。

.. include:: explain_-aspatial.rst_

.. include:: explain_-bi.rst_

.. include:: explain_-di.rst_

.. include:: explain_-e.rst_

.. include:: explain_-f.rst_

.. include:: explain_-g.rst_
..

    如果使用了 :option:`-S` 选项则本选项无效。

.. include:: explain_-h.rst_

.. include:: explain_-icols.rst_

.. include:: explain_-l.rst_

.. include:: explain_-qi.rst_

.. include:: explain_perspective.rst_

.. include:: explain_-t.rst_

.. include:: explain_-w.rst_

.. include:: explain_colon.rst_

.. include:: explain_help.rst_

.. option:: -S

*-S* 选项
-----------

使用 :option:`-S` 选项，则表示要绘制符号。 :option:`-S` 选项的基本语法是:

**-S**\ [*symbol*][*size*]

其中 *symbol* 指定了符号类型， *size* 为符号的大小，后面可添加单位。

不同的符号类型，需要的输入数据格式也不同，但可以统一写成（用 ``...`` 代表某符号
特有的输入列）::

    X   Y   ...

.. rubric:: 基本符号

**-S**\ *-|+|a|c|d|g|h|i|n|s|t|x|y|p*

14种简单的基本符号只需要一个参数 *size*

.. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_base_symbols1.png
    :width: 80%
    :align: center

    14种简单的基本符号，细圆圈表示相同 *size* 的外接圆。

- **-S-**\ *size* ：短横线
- **-S+**\ *size* ：加号
- **-Sa**\ *size* ：五角星
- **-Sc**\ *size* ：圆
- **-Sd**\ *size* ：菱形
- **-Sg**\ *size* ：八边形
- **-Sh**\ *size* ：六边形
- **-Si**\ *size* ：倒三角
- **-Sn**\ *size* ：五边形
- **-Sp**\ *size* ：点
- **-Ss**\ *size* ：正方形
- **-St**\ *size* ：三角形
- **-Sx**\ *size* ：叉号
- **-Sy**\ *size* ：短竖线

对于大写符号 ``ACDGHINST``， *size* 表示符号的面积与直径为 *size* 的圆的面积相同。
4种符号 **-**\ \|\ **+**\ \|\ **x**\ \|\ **y** 是线符号，
可以使用 :option:`-W` 选项控制线宽， :option:`-G` 或 :option:`-C` 选项控制颜色（本例中为 ``-Glightblue -W1p`` ）。
而其他符号 :option:`-W` 选项控制轮廓线属性， :option:`-G` 或 :option:`-C` 选项控制填充色。

.. rubric:: 复杂符号

5种复杂符号需要两个或更多的参数，还可以添加附加选项实现更多显示效果

.. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_base_symbols2.png
    :width: 80%
    :align: center

    5种多参数符号。大写形式 **E**, **J**, **W** 与小写形式 **e**, **j**, **w** 的区别在于大写形式使用地理方位角与地理距离。

**-Se**\ [*direction*/]\ *major_axis*\ [/*minor_axis*]
    绘制椭圆。三个参数分别为方向、长轴长度、短轴长度。其中方向是相对于水平方向逆时针旋转的角度，两个轴的长度都使用长度单位，即 ``c|i|p``

    这三个参数也可以在选项中省略，在输入数据中为每个椭圆单独指定。此时输入数据的格式为::

        X   Y   方向   长轴长度    短轴长度

    这个选项绘制的椭圆形状大小不会受到底图地理投影方式的影响。

**-SE**\ [*azimuth*/]\ *major_axis*\ [/*minor_axis*]
    绘制椭圆。与前者类似，区别在于：

    - 使用方位角（相对于正北方向顺时针旋转的度数）。该方位角会根据所选取的地图投影变换成角度
    - 对于线性投影，长短轴的长度单位为数据单位，即与 :option:`-R` 中数据范围的单位相同
    - 对于地理投影，长短轴的长度单位必须设置为地理距离单位（例如千米 *k* 、弧度 *d* ）

    如果想使用地理单位绘制一个圆形，可以简单使用 **-SE-** 。此时输入数据只需要一个参数即该圆的直径。

**-Sj**\ [*direction*/]\ *width*\ [/*height*]
    绘制旋转矩形。三个参数分别为方向、宽度、高度。其中方向是相对于水平方向逆时针旋转的角度。
    这三个参数也可以在选项中省略，在输入数据中为每个矩形单独指定。此时输入数据的格式为::

        X   Y   方向   宽度    高度

**-SJ**\ [*azimuth*/]\ *width*\ [/*height*]
    绘制旋转矩形。与前者类似，区别在于：

    - 使用方位角（相对于正北方向顺时针旋转的度数）。该方位角会根据所选取的地图投影变换成角度
    - 对于线性投影，长短轴的长度单位为数据单位，即与 :option:`-R` 中数据范围的单位相同
    - 对于地理投影，长短轴的长度单位必须设置为地理距离单位（例如千米 *k* 、弧度 *d* ）

    如果想使用地理单位绘制一个正方形，可以简单使用 **-SJ-** 。此时输入数据只需要一个参数即边长。

**-Sr**\ *width*/*height*
    绘制矩形。与 **-Sj** 类似，区别在于只需要两个参数，不进行旋转。

    如果使用 **-Sr+s** ，则输入数据分别为矩形的两个对角顶点的X和Y坐标。例如::

        echo 139.2 34.8 140.5 36 | gmt plot -Sr+s -W1p,blue

**-SR**\ *width*/*height*/*radius*
    绘制圆角矩形。 *radius* 为圆角半径。

**-Sw**\ [*outer*\ [/*startdir*/*stopdir*]][**+a**\ [*dr*]][**+i**\ [*inner*]][**+p**\ *pen*][**+r**\ [*da*]]
    绘制楔形图。需要的3个参数分别为外直径 *outer* ，起始角度 *startdir* 和结束角度 *stopdir* （相对于水平方向逆时针旋转的角度）。
    附加 **+i** 可以进一步指定内直径 *inner* （默认为0）。附加 **+a**\ [*dr*] 表示只绘制弧线。如果附加了 *dr* ，则以 *dr* 为径向间隔绘制弧线。
    附加 **+r**\ [*da*] 表示只绘制径向线。如果附加了 *da* ，则以 *da* 为弧向间隔绘制径向线。

**-SW**\ [*outer*\ [/*startaz*/*stopaz*]][**+a**\ [*dr*]][**+i**\ [*inner*]][**+p**\ *pen*][**+r**\ [*da*]]
    绘制楔形图。与前者类似，区别在于使用起始方位角 *startaz* 和结束方位角 *stopaz* （相对于正北方向顺时针旋转的度数），
    以及内直径和外直径都使用地理距离（默认为km）。

.. rubric:: 条状符号

.. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_base_symbols4.png
    :width: 80%
    :align: center

**-Sb**\ [*size*\ [**c**\|\ **i**\|\ **p**\|\ **q**]][**+b**\ \|\ **B**\ [*base*]][**+v**\|\ **i**\ *ny*][**+s**\ [*gap*]]
    绘制垂直条状符号，从 *base* 到坐标Y。 *size* 为宽度，可以使用 **c**\|\ **i**\|\ **p** 这样的长度单位，也可以使用 **q** 表示X方向单位。
    默认情况下 *base* = 0，附加 **+b**\ [*base*] 可以修改。如果只附加 **+b** 但没有设置 *base* ，则需要额外的最后一列数据来指定 *base* 的值。
    使用 **+B**\ [*base*] ，条状符号的高度将从 *base* 起算（默认从原点起算）。

    普通条状符号只需要一列Y值输入数据。如果想绘制多波段条状符号，需要附加 **+v**\|\ **i**\ *ny* ，其中 *ny* 表示波段数量。输入数据中也需要有 *ny* 列Y值。
    这里 **+i** 表示以 *dy* 为步长累加条状的值， **+v** 表示按递增顺序获得相对于 *base* 的完整值。

    默认情况下多个波段都绘制在一个条状符号上，附加 **+s** 让多波段绘制为相邻的多个条状符号。
    可选参数 *gap* 表示在相邻条状符号之间添加间隔，间隔宽度为 *size* 的百分比 *gap* 。此时 *size* 定义为多个条状符号加间隔的总宽度。

    绘制多波段条状符号需要使用CPT文件以及 :option:`-C` 选项指定颜色，其中CPT文件的取值范围必须是 0, 1, ..., *nx* - 1。
    输入数据的格式为(*x1 y x2 ... xn*)或(*dx1 y dx2 ... dxn*)。

**-SB**\ [*size*\ [**c**\|\ **i**\|\ **p**\|\ **q**]][**+b**\ \|\ **B**\ [*base*]][**+v**\|\ **i**\ *nx*][**+s**\ [*gap*]]
    与前者类似，区别在于绘制的是水平条状符号。

.. rubric:: 矢量符号

矢量符号需要长度和方向，或矢量终点坐标等参数。通过附加选项可以定制矢量头的样式。关于矢量绘制的详细说明请参考 :doc:`/basis/vector` 。

**-Sm**\ *size*\ [**+**\ *vecmodifiers*]
    绘制数学圆弧，输入数据的格式为::

        X  Y  radius  start  stop

    其中 *radius* 为圆弧半径， *start* 和 *stop* 定义为水平方向起始的逆时针角度。
    默认圆弧两端无矢量头，可以通过附加选项 **+**\ *vecmodifiers* 添加，见 :doc:`/basis/vector` 一节。 *size* 定义为矢量头的长度。
    圆弧的线宽由 :option:`-W` 选项设定，矢量头的轮廓线宽默认为圆弧线宽的一半。

**-SM**\ *size*\ [**+**\ *vecmodifiers*]
    与前者类似，唯一的区别为当圆弧的夹角恰好是90度时会用直角符号来表示。

.. gmtplot:: plot/plot_-Sm.sh
    :width: 50%
    :show-code: true

    plot -Sm|M 示意图

**-Sv**\ *size*\ [**+**\ *vecmodifiers*]
    绘制矢量，输入数据格式为::

        X   Y   direction   length

    其中 *direction* 定义为水平方向起始的逆时针角度， *length* 为矢量长度， *size* 为矢量头的长度。
    矢量杆的宽度颜色等属性由 :option:`-W` 控制，矢量头的轮廓线宽默认为其一半。
    更多矢量头的属性可以通过 **+**\ *vecmodifiers* 添加，见 :doc:`/basis/vector` 一节。

**-SV**\ *size*\ [**+**\ *vecmodifiers*]
    与前者类似，唯一的区别为第三列是方位角而不是方向，即以正北为起点顺时针旋转的角度。

**-S=**\ *size*\ [**+**\ *vecmodifiers*]
    绘制地理矢量，区别在于第三列是方位角（即以正北为起点顺时针旋转的角度），第四列长度的单位是地理单位（默认为km）。

.. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_base_symbols5.png
    :width: 80%
    :align: center

.. rubric:: 自定义符号

**-S**\ [**k**\ *name*\ [/\ *size*]]
    绘制自定义的符号。目前，GMT 官方内置了 40 个自定义符号，如下所示：

    .. figure:: https://docs.generic-mapping-tools.org/latest/_images/GMT_App_N_1.png
        :width: 50%
        :align: center

    
    如果这些内置自定义符号无法满足需求（例如没有常用的指北针），用户可以自行制作自定义符号文件并使用。详细使用方法见\ `制作和使用自定义符号`_。

.. rubric:: 带修饰物的线条

第一种类型的带修饰物线条，通常用于绘制气象锋面、断层线等。线条修饰物由附加选项控制，线条属性由 :option:`-W` 选项控制。

.. gmtplot:: plot/GMT_base_symbols7.sh
    :width: 80%
    :show-code: true

**-Sf**\ [±]\ *gap*\ [/*size*][**+l**\|\ **+r**][**+b**\|\ **c**\|\ **f**\|\ **s**\ [*angle*]\ \|\ **t**\ \|\ **v**][**+o**\ *offset*][**+p**\ [*pen*]]

    - *gap* 线段上符号之间的距离，若为负值，则解释为线段上符号的个数。
    - *size* 为符号大小

       - 若省略了 *size* ，则默认为 *gap* 的30%
       - 若 *gap* 为负值，则 *size* 不可省略

    - **+l** 和 **+r** 分别表示将符号画在线段的左侧还是右侧，默认是绘制在线段中间
    - **+b** 符号为box
    - **+c** 符号为circle
    - **+t** 符号为triangle
    - **+f** 符号表示断层（fault），默认值。
    - **+s** 符号表示断层的滑动（slip），用于表示左旋或右旋断层。
      可选的参数 *angle* 控制绘制矢量时的角度（默认为20）。
      用 **+S** 绘制一个弧形箭头。
    - **+o**\ *offset* 将线段上的第一个符号相对于线段的起点偏离 *offset* 距离，默认值为0
    - 默认符号的线属性与线段相同（ :option:`-W` 选项），可以使用 **+p**\ *pen* 为符号单独指定线属性。
      使用 **+p** 则不绘制符号的轮廓。
    - **+i** 将隐藏线段只绘制符号。

第二种类型的带修饰物线条是带标注文字的线段，常用于绘制断层名的断层线。

.. gmtplot:: plot/GMT_base_symbols8.sh
    :width: 80%
    :show-code: true

**-Sq**\ **d**\|\ **D**\|\ **f**\|\ **l**\|\ **L**\|\ **n**\|\ **N**\|\ **s**\|\ **S**\|\ **x**\|\ **X**\ *posinfo*\ [:*labelinfo*]
    有6种可选的方式控制标注文字：

    **d**\ *dist*\ [**c**\|\ **i**\|\ **p**][/\ *frac*]

    **D**\ *dist*\ [**d**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **M**\|\ **n**\|\ **s**][/\ *frac*]
        小写 **d** 指定标注之间的距离 *dist* ，单位为 **c** (cm), **i** (inch), **p** (points)。
        默认值为 *10c* 。

        大写 **D** 指定标注之间的地理距离 *dist* ，单位为 **e** (m), **f** (foot), **k** (km),
        **M** (mile), **n** (nautical mile), **u** (US survey foot),
        **d** (arc degree 弧度), **m** (arc minute 弧分), **s** (arc second 弧秒)。

        可选选项 *frac* 表示将第一个标注放在距离线段起点 ``frac * dist`` 处，默认值为0.25。

    **f**\ *file.txt*\ [/*slop*\ [**c**\|\ **i**\|\ **p**]]
        读取 ASCII 文本文件 *file.txt*，将标注放置在文件中指定的坐标位置。
        坐标位置和线段间的距离小于 *slop* 才会绘制标志文字。默认值为0即只绘制位于线段上的坐标。

    **l**\|\ **L**\ *line1*\ [,\ *line2*,...]
        每个 *line* 的格式为 *start_lon*/*start_lat*/*stop_lon*/*stop_lat* ，标注文字会绘制在这些 *line* 与线段的交点。
        小写的 **l** 表示直线，而大写的 **L** 表示使用大圆路径。

    **n**\|\ **N**\ *n_label*\ [/*min_dist*\ [**c**\|\ **i**\|\ **p**]]
        指定线段上等间隔标注的个数，默认为1即只绘制一个标注。
        小写的 **n** 表示标注位置在每段间隔的中心，而大写的 **N** 表示标注位置在每段间隔的起点。

        可选选项 /*min_dist*\ [**c**\|\ **i**\|\ **p**] 指定相邻标注的最小距离。
        该选项同时限制了只能在长度大于 *min_dist* 的线段上进行标注。

    **s**\|\ **S**\ *n_label*\ [/*min_dist*\ [**c**\|\ **i**\|\ **p**]]
        与 **n**\|\ **N**\ *n_label* 相同，但输入数据会被解释为一系列的两点线段。

    **x**\|\ **X**\ *xfile.txt*
        读取 ASCII 文本格式的多段数据文件 *xfile.txt* ，标签文字会绘制在这些多段数据与线段的交点。
        大写的 **X** 会先将输入数据重采样为大圆弧线。
        添加可选选项 **+r**\ *radius*\ [**c**\|\ **i**\|\ **p**] 可以设置 x-y 平面上标注文字之间的最小间距。

    可选选项 *labelinfo* 用于控制文字的格式，其可以是下面子选项的任意组合：

    **+a**\ *angle*
        设置文字相对于线段的角度。可以设置为 **+an** 表示文字垂直于线段。默认为 **+ap** 表示文字与线段平行。

    **+c**\ *dx*\ [/*dy*]
        设置文字与文本框之间的边距。可以添加单位 **c**\|\ **i**\|\ **p** 或百分号 % 表示边距相对字体大小的百分比，默认为15%。

    **+f**\ *font*
        设置字体属性，默认为9p。

    **+g**\ [*color*]
        绘制一个不透明的文本框背景。

    **+i**
        不绘制线段，只绘制标注文字。

    **+l**\ *label*
        手动设置固定的标注文字。

    **+Lh**
        从数据头段中读取标注文字。

    **+Ld**
        采用笛卡尔坐标系内的距离作为标注内容，在后面附加 **c**\|\ **i**\|\ **p** 之一指定单位。

    **+LD**
        采用实际的地理距离作为标注内容，在后面附加 **d\|e\|f\|k\|n\|M\|n\|s** 之一指定单位，默认为弧度 **d** 。

    **+Lf**
        从 **f**\ *file.txt* 的第二列之后读取所有文字作为标注内容（不包括第二列）。

    **+Lx**
        从 **x**\|\ **X**\ *xfile.txt* 文件头段中读取标注文字。

    **+n**\ *dx*\ [/*dy*]
        偏移标注文字的位置，可以使用单位 **c**\|\ **i**\|\ **p** 。不能与 **+v** 一起使用。

    **+o**
        使用圆角矩形文本框。不能与 **+v** 一起使用。

    **+p**\ [*pen*]
        设置文本框轮廓线型。

    **+r**\ *min_rad*
        当线段的曲率半径小于 *min_rad* 不绘制文字。

    **+t**\ [*file*]
        将每个标注文字的 *x, y, angle, text* 保存进文件 *file* [Line_labels.txt]。

    **+u**\ *unit*
        在所有标注后面附加 *unit* 作为单位。 *unit* 可以是一个用双引号括起来的任意字符串。

    **+v**
        标注文字沿着线段弯曲。

    **+=**\ *prefix*
        在所有标注前面添加前缀 *prefix* 。

标注文字的控制示例可以参考 :ref:`gmt-plot-Sq-examples`

输入数据格式
------------

:option:`-S` 选项决定了输入数据需要哪些数据列，如果在选项中未给出参数 *size* ，则数据中需要 *size* 列。
此外，使用 :option:`-H` 、 :option:`-I` 和 :option:`-t` 选项都需要给出各自的数据列。
无论选项顺序如何，数据列的顺序都是固定的::

    x y [z] [size] [scale] [intens] [transp [transp2]] [trailing-text]

其中括号中的项是可选的，并受所述选项控制：

- :option:`-C` 选项需要 *z* 列。
- :option:`-S` 选项不指定参数则需要 *size* 列。取决于选定的符号，可能需要不止一列。
- :option:`-H` 选项不指定参数则需要 *scale* 列。
- :option:`-I` 选项不指定参数则需要 *intens* 列。
- :option:`-t` 选项不指定参数则需要 *transp* 列。
- 尾随文本 *trailing-text* 总是可选的。

**注** ：(1) 如果 :option:`-S` 未指定具体的符号类型 *symbol* ，则 *symbol* 应位于尾随文本 *trailing-text* 的开头。
(2) 可以使用 :option:`-i` 重新排列数据记录以匹配预期的格式。

.. _gmt-custom-symbols:

制作和使用自定义符号
--------------------

如果 GMT 内置的自定义符号无法满足用户的需求，用户可以根据
`GMT 自定义符号文件 <https://docs.generic-mapping-tools.org/latest/reference/custom-symbols.html>`__
的格式要求自行制作自定义符号文件。或者参考中文手册中的 :doc:`指北针符号示例 </examples/ex007/index>` 和 :doc:`地应力符号示例 </dataset/WSM/index>` 。

使用自定义符号时，GMT 会依次按照如下顺序去搜索自定义符号的定义文件 :file:`name.def`：

#. 当前目录，即运行脚本所在目录
#. :file:`~/.gmt/custom` 目录（Linux/macOS/WSL 用户）或 :file:`C:\\Users\\你的当前用户名\\.gmt\\custom` 目录（Windows用户）
#. :file:`$GMT_SHAREDIR/custom` 目录

用户可以将自己制作的自定义符号复制到以上任一路径即可正常使用。
建议放在 :file:`~/.gmt/custom` 目录（Linux/macOS/WSL 用户）或
:file:`C:\\Users\\你的当前用户名\\.gmt\\custom` 目录（Windows 用户）下。

多段数据
--------

对于多段数据而言，每段数据的头段记录中都可以包含一些选项，以使得不同段数据拥有
不同的属性。头段记录中的选项会覆盖命令中选项的参数：

- **-G**\ *fill* ：设置当前段数据的填充色 *fill*
- **-G-** ：对当前数据段关闭填充
- **-G** ：恢复到默认填充色
- **-L**\ *label* ：设置当前段数据的标签，常用于断层名标注
- **-W**\ *pen* ：设置当前段数据的画笔属性 *pen* 
- **-W** ：恢复到默认画笔属性 :term:`MAP_DEFAULT_PEN`
- **-W-** ：不绘制轮廓
- **-Z**\ *zval* ：从 cpt 文件中查找 Z 值 *zval* 所对应的颜色作为填充色
- **-Z**\ *NaN* ：从 cpt 文件中获取 NaN 颜色
- **-t**\ *transparency* ：设置透明度

详情及示例参见 :ref:`table-ascii-attrs`

.. include:: explain_distunits.rst_

.. include:: auto_legend_info.rst_

基础示例
------------

请参考入门教程中的 :doc:`/tutorial/symbols/index` 。

.. _gmt-plot-Sq-examples:

*-Sq* 选项示例
----------------

对于用法较为复杂的 *-Sq* 选项，可以通过以下三个示例帮助理解学习。
示例中用到的数据文件 *@App_O_transect.txt* 是 GMT 远程数据服务器自带数据，
该数据为地球大地水准面最值点之间的大圆弧路径，并且沿着该大圆弧从 ETOPO5 数据集中提取了高程数据。
数据格式为 *经度、纬度、距离、大地水准面、高程* 。

第一个示例沿大圆弧距离放置标注和不透明文本框。

.. gmtplot:: plot/plot_-Sq_1.sh
   :width: 80%

第二个示例沿大圆弧距离放置标注和反色圆角矩形文本框。

.. gmtplot:: plot/plot_-Sq_2.sh
   :width: 80%

第三个示例采用沿大圆弧的海底地形数据作为标注的内容，按照沿大圆弧的距离，每1500km放置一个标注。
因此需要使用 **gawk** 程序从 *@App_O_transect.txt* 文件中抽取距离为1500km倍数的记录，并创建一个新文件，指定标注的位置和内容。

.. gmtplot:: plot/plot_-Sq_3.sh
   :width: 80%

*-L* 选项示例
----------------

:option:`-L` 选项常常和 :option:`-G` 选项同时使用以进行颜色填充。下面看不同搭配的画图效果:

.. gmtplot:: plot/plot_-L_1.sh
    :width: 80%

    -L 和 -G 选项不同搭配方式的效果

下面的例子分别绘制了上述三种情形。第一幅图使用 **+d** 选项，数据的第三列分别是2、2、3和1，
所以包络的上下范围在线条的每一个数据点处距离线条的距离就是2、2、3和1。
第二幅图使用 **+D** 选项，数据的第三列分别是2、2、3和1，
所以包络的下范围在线条的每一个数据点处距离线条的距离就是2、2、3和1，
也就是和第一幅图完全相同。但是，上范围的距离使用的是数据文件的第四列，也就是4、3、2和1。
第三幅图使用 **+b** 选项，包络的范围与线条的位置无关。第三、四列数据分别决定了包络的上下范围。
当第三、四列数据交叉的时候，包络图形随之出现打结的现象。

.. gmtplot:: plot/plot_-L_2.sh
    :width: 80%

    围绕线条的包络

使用 **+x** 和 **+y** 例子如下：

.. gmtplot:: plot/plot_-L_3.sh
    :width: 80%

    到指定位置的包络
