✍️ 朱邓达  •  🧐 周茂  •  📅 2025-07-07

events

官方文档:

events

简介:

绘制某一时刻的事件符号、线条、多边形和标签

语法

gmt events -Jparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] -Tnow [ table ] [ -Ar[dpu[c|i][+v[value]]]|s ] [ -B[p|s]parameters ] [ -Ccpt ] [ -D[j|J]dx[/dy][+v[pen]] ] [ -E[s|t][+o|Odt][+r[c|l|q]dt][+pdt][+d[c|l|q]dt][+f[c|l|q]dt][+ldt] ] [ -F[+aangle][+ffont][+jjustify][+r[first]|z[format]] ] [ -Gcolor ] [ -Hlabelbox ] [ -L[length|t] ] [ -Mi|s|t|vval1[+cval2] ] [ -N[c|r] ] [ -Qprefix ] [ -Ssymbol[size] ] [ -U[stamp] ] [ -V[level] ] [ -Wpen ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -Zcommand ] [ -aflags ] [ -bibinary ] [ -dinodata[+ccol] ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -lflags ] [ -pflags ] [ -qiflags ] [ -wflags ] [ -:[i|o] ] [ --PAR=value ]

描述

从表数据（或标准输入）中读取 (x, y[, z] [, size], time [, length] [, label]) 数据， 并绘制出在当前指定时间下每个事件的符号应呈现的样子。 这些符号可能有所不同，原因在于事件可能具有不同的持续时间， 用户可能希望以某种方式突出符号属性，以便在事件首次出现时引起注意， 也许过一段时间后将其淡化，以减少杂乱并聚焦于更近期的事件。 用户可能还希望符号在其结束时间（GMT 称此阶段为尾声 (coda)）到达后完全消失， 或者保持可见但变淡、缩小或变暗。 视需要，每个符号都可以有一个标签，该标签可以在符号显示的同时显示规定的时间长度，或者稍有延迟。 此模块通常与 movie 模块结合使用，在其中隐式的时间循环用于调用时间序列中的 events ， 从而随着事件的发展绘制符号。

Source Code

以上是在时间窗口 -0.5 至 1.5 内对两个事件进行动画展示（仅网页端可见）。 这两个事件仅在 0 至 1 期间处于活跃状态。 一个符号（绿色）仅在活跃期间正常绘制（大小随浅绿色时间曲线变化）， 而另一个（红色）在首次到达时通过添加上升、平台、下降和淡出区间进行突出显示， 然后在不再活跃时逐渐淡出为一个持久但更小、更暗且部分透明的符号，其大小随红色时间曲线变化。 相比之下，绿色符号只是开启和关闭。红色符号的标签显示延迟了 0.25 个时间单位。 红色事件使用 -Es+rc0.25+p0.25+dc0.25+f0.25 -Et+o0.25 绘制， 而绿色事件使用默认设置（即浅绿色时间曲线）。 注： 此处绘制的时间曲线仅用于说明幕后的情况，实际 events 模块只涉及这两个事件。

必选选项

table

一个或多个ASCII或二进制表数据。若不提供表数据，则会从标准输入中读取。

-Jprojection (more …)

设置地图投影方式

-Rxmin/xmax/ymin/ymax[+r][+uunit] (more …)

指定数据范围。

对于三维透视图（-p 选项） ，可以加上 /zmin/zmax 指定Z轴的范围。

-Tnow

设置当前绘图时间 now。在 -E 中设置的时间偏移和增量都是相对于当前时间的。 如果 now 为绝对时间，则需要使用 TIME_UNIT 来指示 -E 和 -L 等选项中给出的值的单位。

可选选项

-Ar[dpu[c|i][+v[value]]]|s

当未使用 -S 时，events 模块将读取直线或多边形。支持两种不同的输入形式， 并通过所选的 -A 指令指定：

  • -Ar - 输入数据为轨迹线（详见 绘制轨迹线 ），输入数据格式为 x, y, time ， 这里，“事件”指受当前时间（now）、事件持续时间（-L） 和上升/淡出周期（-Es）限制的轨迹的一部分。 如果当前时间落在轨迹上的两点之间，那么使用线性插值来找到当前的终点。

  • -As - 输入数据为多个多边形或线条，输入数据格式为 x, y 。 events 模块读取每段记录，并通过段头中的 -Tstring 获取每段的显示时间 time。 这里，“事件”指受当前时间（now）、事件持续时间（-L） 和上升/淡出周期（-Es）限制的整个多边形或线条。 如果使用了 -L[t] ，则 string 的格式必须是 begin/length|end 或 begin,length|end ， 如果指定了绝对时间则需用逗号分割。

注： 线条和多边形都不允许放置任何标签。

或者，用户可以使用 -Ardpu 进行不绘制操作，而是将输入的 x, y[, zcols ]、time 数据转换为 密集采样的点， 以便稍后调用 events 时可以使用此采样数据集并以 -Sc[width] 格式将其绘制为圆形。 这样，用户就可以绘制具有可变笔色和固定或可变笔宽的“线条”， 同时还能利用 -Es 和 -Et 的完整机制以及由 -M 控制的所有符号效果。 在运行 movie 时， dpu 必须与预期的 dpu 相匹配。 请注意，如果使用的是国际单位制（SI），dpu 表示每厘米的像素数； 如果使用的是美国单位制（US），则表示每英寸的像素数（因此取决于 PROJ_LENGTH_UNIT 设置）。 另外，可以添加 c 或 i 来明确设置使用的单位。 还需注意，如果动画涉及区域或地图投影的更改，则可能需要将 -Ardpu 作为主脚本的一部分运行。 最后，可以使用 +v[value] 在密集点数据文件中插入一个 z 列 （除非附加 value ，否则将初始化为零）以用于 -Mv 。

-Bparameters (more …)

设置底图边框和轴属性。

-Ccpt

使用 cpt 转换可选的第三列中给出的 z 值，以分配符号或多边形的颜色。 如果使用 -Ar，则不允许使用该选项。

-D[j|J]dx[/dy][+v[pen]]

将文本从投影点 (x,y) 偏移 dx,dy [0/0]。如果不指定 dy 则与 dx 相同。 使用 -Dj 将文本沿对齐点偏移（即，文本对齐将决定移动的方向）。 使用 -DJ 将在拐角处缩短对角线偏移量 \(\sqrt{2}\) 倍。 添加 +v[pen]，将从原始点到移位点绘制一条线，指定 pen 以更改画笔属性。

-E[s|t][+o|Odt][+r[c|l|q]dt][+pdt][+d[c|l|q]dt][+f[c|l|q]dt][+ldt]

为符号（symbol, -Es）或文本（text, -Et）的时间函数设置相对时间节点，其中 \(0 \le \Delta t_x, x = r, p, d, f\) （详见 四种时间函数 ）。通过以下子选项设置增量：

  • +odt - 将事件整体移动 dt 时间。

  • +Odt - 与 +o 类似，但仅移动开始时间，可用于缩短事件的持续时间。

  • +ldt - 单独设置文本的持续时间（即显示时长），仅 -Et 可用 [默认和符号持续时间一致]。

  • +rdt - 设置上升阶段的时长，此时 \(t_r = t_b - \Delta t_r\) ， 可选择曲线形状：余弦型 (cosine)，线性型(linear)，二次型(quadratic) [Quadratic]。

  • +pdt - 设置平台阶段的时长，此时 \(t_p = t_b + \Delta t_p\) ，

  • +ddt - 设置下降阶段的时长，此时 \(t_d = t_p + \Delta t_d\) ， 可选择曲线形状：余弦型 (cosine)，线性型(linear)，二次型(quadratic) [Quadratic]。

  • +fdt - 设置淡出阶段的时长，此时 \(t_f = t_e + \Delta t_f\) ， 可选择曲线形状：余弦型 (cosine)，线性型(linear)，二次型(quadratic) [Linear]。

以上均为可选项 [默认均为 0]，且可为符号和文本分开设置。 如果 s 和 t 均不指定则为二者同时设置。

注：

  • +p 和 +d 不会应用于文本标签，线条和多边形。

  • 如果希望绘制文本标签，则需使用 -Et 。

  • 以上子选项均不支持用于线条。

-F[+aangle][+ffont][+jjustify][+r[first]|z[format]]

默认情况下，事件标签文本将使用一级标注字体属性水平放置，并以数据点为中心。 通常，要绘制的文本是输入数据的尾部文本。可使用该选项的子选项覆盖默认值：

  • +ffont - 设置字体 (size,fontname,color) [FONT_ANNOT_PRIMARY].

  • +aangle - 设置相对水平方向的旋转角 [0].

  • +jjustify - 设置对齐 [CM].

  • +r[first] - 使用段编号 (从 first [0] 数起) 作为文本标签.

  • +z[format] - 将传入的 z 值格式化作为文本标签 (要求使用 -C ，可自定义格式 format [FORMAT_FLOAT_MAP]).

-Gfill

为所有符号或多边形设置恒定的阴影或颜色。

-H[+cdx/dy][+gfill][+p[pen]][+r][+s[[dx/dy/][shade]]]

添加文本框，并提供以下一个或多个特定参数：

  • +cdx/dy - 调整边框和文本的间隔 [字体大小的 15%].

  • +gfill - 填充文本框 [no fill].

  • +p[pen] - 绘制文本框轮廓 [MAP_DEFAULT_PEN].

  • +r - 使用圆角边框 [直角框].

  • +s[[dx/dy/][shade]] - 在文本框后面放置一个偏移的背景阴影框。 这里， dx/dy 表示相对于前景文本框的偏移量 [4p/-4p]， shade 表示阴影填充 [gray50]。 +s 还要求使用 +g.

-Jz|Zparameters

设置 Z 轴的缩放比例，设置方式与 -Jx|X 相同。

-L[length|t]

指定事件的持续时间。如果所有事件的长度相同，则添加 length 。 如果文件中在 time 列之后给出的是结束时间而非长度，则添加 t 。 如果长度可以从 time 列之后的输入文件中读取，则留空。 如果未给出 -L 参数，则假定事件具有无限的持续时间。 有关线条和多边形的持续时间处理方式，请参阅 -A 。

-Mi|s|t|vval1[+cval2]

控制每个符号的四个属性 (intensity, size, transparency, and value) 在符号首次出现时，在其活动持续期间以及随时间淡出时如何变化。 首先指定类别 [默认值 val1 在中括号中给出]：

  • i - 修改颜色强度 [1] 。通常在 ±1 之间，0 无效果。用于将颜色变得更亮 (val1 > 0) 或更暗 (val1 < 0)（色相 (hue) 保持不变）。

  • s - 修改符号的相对大小 [1] 。将符号大小临时放大 val1 倍。

  • t - 修改透明度 [100] 。

  • v - 修改上升阶段的数值[0] 。 将数据 z 列数值临时加上 val1 ，从而根据 CPT 修改符号颜色 （因此 -Mv 需要使用 -C ）。

后跟的 val1 表示由 -Es 创建的相应时间函数缩放的最大振幅（详见 四种时间函数 ）。 因此随着时间的推移，实际应用的属性临时修改是变换的。 -M 选项可重复使用以设置多个属性。

视需要，对于那些在事件结束时间达到后仍需一直显示的有限持续时间事件， 用户必须添加 +c**（代表尾声）来设置相应的终端值，在尾声期间生效。 如果未给出 **+c，则默认值为 0 (intensity), 0 (size), 100 (transparency) 和 0 (value)， 这意味着除非用户通过一个或多个 +c 修饰符（每个 -M 指令一个）来更改这些属性， 否则在尾声期间符号不会被绘制出来。

注： 多边形仅能使用 -Mt 。

-N[c|r]

不要裁剪落在地图边界外的符号 [默认仅绘制坐标严格位于地图边界内的点]。 对于周期性（360 度经度）的地图，可能需要将所有符号绘制两次，以防它们被重复的边界裁剪。

  • 使用 -N 可关闭裁剪，并且不绘制重复的符号。

  • 使用 -Nr 可关闭裁剪，同时保留重复符号的绘制。

  • 使用 -Nc 可保留裁剪，但关闭重复符号的绘制。

-Qprefix

将中间事件符号和标签保存到永久文件中，而不是在完成后删除它们。 文件将被命名为 prefix_symbols.txt 和 prefix_labels.txt。

-Ssymbol[size]

指定用于该事件的符号（默认为绘制线条或多边形；请参阅 -A ）。 视需要，将符号大小与单位 (c|i|p) 一起添加。 如果没有给出大小，则会从数据文件的第三列（如果使用 -C 则为第四列） 读取事件特定的大小。 注： 并非 plot 中所有符号都能在此处使用。 目前本模块仅支持基本符号和自定义符号； 不支持 bars, vectors, ellipses, fronts, decorated and quoted lines。 从数据文件读取的符号大小的单位将假定为由 PROJ_LENGTH_UNIT 控制，除非指定了单位 (c|i|p) 。如果只是绘制文本标签，则不需要 -S 。

-U[label][+c][+jjust][+odx/dy] (more …)

在图上绘制GMT时间戳logo

-V[level] (more …)

设置 verbose 等级 [w]

-Wpen

指定符号轮廓 [默认无轮廓].

-X[a|c|f|r][xshift[u]]

-Y[a|c|f|r][yshift[u]] (more …)

移动绘图原点

-Zcommand

绘制由 coupe 、 meca 或 velo 模块生成的符号。 command 命令部分必须以这些模块名称之一开头， 然后提供所选模块正常定义图形所需的所有特定选项， 不包括 -C，-G，-J，-N，-R 和 -W （这些选项可能用于本模块）。 此外，用户不能使用 -I 或 -t 选项，因 为这些选项将作为由 -Mi 和 -Mt 引入的变体的一部分自动设置。 例如，绘制沙滩球的自定义命令可能是 -Z“meca -Sa5c+f0”， 而要在剖面图中显示沙滩球可能需要更复杂的命令 -Z“coupe -Q -L -Sc3c -Ab128/11/120/250/90/400/0/100+f -Fa0.1i/cc”。 注： 如果使用经典模式，则需使用对应的经典模块名称。

-acol=name[,…] (more …)

设置非空间数据项与数据列之间的对应关系

-bi[ncols][type][w][+l|b] (more …)

设置二进制输入数据的格式

-dinodata (more …)

将输入数据中值为 nodata 的列替换为 NaN

-e[~]“pattern” | -e[~]/regexp/[i] (more …)

筛选或剔除匹配指定模式的数据记录

-f[i|o]colinfo (more …)

指定输入或输出列的数据类型

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

跳过或生成指定数目的头段记录

-icols[+l][+sscale][+ooffset][,…][,t[word]] (more …)

设置输入数据列及简单变换（0表示第一列，t 表示文本列）

-l[label][+Dpen][+Ggap][+Hheader][+L[code/]txt][+Ncols][+Ssize[/height]][+V[pen]][+ffont][+gfill][+jjust][+ooff][+ppen][+sscale][+wwidth] (more …)

为当前绘制的符号或线段增加一个自动图例记录

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)

设置3D透视视角

-qi[~]rows[+ccol][+a|f|s] (more …)

筛选输入的行或数据范围

-:[i|o] (more …)

交换输入或输出中的第一和第二列

-^ 或 -

显示简短的帮助信息，包括模块简介和基本语法信息（Windows下只能使用 -）

-+ 或 +

显示帮助信息，包括模块简介、基本语法以及模块特有选项的说明

-? 或无参数

显示完整的帮助信息，包括模块简介、基本语法以及所有选项的说明

--PAR=value

临时修改GMT参数的值，可重复多次使用。参数列表见 配置参数

time 的含义

通常情况下，”time”（例如在 -T 参数的输入中）的含义实际上是指所绘制现象的时间， 但它也可以是任何其他便于使用的单调递增量，比如运行时间、模型时间、帧数或类似距离的其他物理量。 这完全取决于动画的上下文。在 -E 中给出的下降、淡出等值， 均假定与 -T 参数给出的 “time” 参数使用相同的单位。 因此，如果 “time” 是一个单调递增的帧计数器，那么 -E 和 -L 中的值就表示帧数。 当 “time” 实际上是通过日期/时钟标记给出的日历时间，会出现一种特殊情况。 在此情况下， -E 和 -L 参数的单位由 TIME_UNIT 设置决定[second]。 在解释用户的 -E 和 -L 参数时，用户需要指定应使用的时间单位。 下面的地震活动示例使用了实际的地震时间，但示例使用天作为单位，因为“秒”太小了。

四种时间函数

事件通常要么有有限的持续时间，例如某位君主统治时期的时长，要么是无限的。 这里所说的“无限”仅仅意味着其持续时间超过了用户所绘制的时间范围。 在一个动画中，将这些事件的基本情况以地图上的点的形式呈现出来， 就是从事件开始时开始绘制符号，然后让这个符号在所有帧中保持可见状态直到事件结束 （在无限持续时间的情况下则一直持续绘制）。 然而，为了突出新事件的到来，用户可以暂时改变符号的四个属性： 其大小、颜色强度、透明度和颜色（通过 CPT 查找）。 可以把这四个属性视为时间的函数。

  1. 对于 -Ms 设置，下面的图表展示了符号大小的变化情况。

https://docs.generic-mapping-tools.org/latest/_images/psevents_size.png

根据 -Es 中的时间节点以及 -Ms 中的放大倍数， 推导出一个符号大小随时间变化的隐含规律。 在此过程中，先将符号大小临时放大五倍，然后逐渐缩小至预期大小， 最终在淡出和尾声阶段进一步缩小至较小尺寸。

  1. 同样，为了吸引人们对新到达事件的注意，用户可能需要暂时将颜色变白； 这可以通过 -Mi 选项完成，下图说明了强度如何相应变化。

https://docs.generic-mapping-tools.org/latest/_images/psevents_intensity.png

根据 -Es 中的时间节点以及 -Mi 中的强度， 推导出一个颜色强度随时间变化的隐含规律。 这里试图在事件到达时将符号变白，并在永久的结束阶段使其变暗。

  1. 接下来，对于有限的事件，用户可能希望将它们完全淡出， 或者简单地将它们淡出到一个恒定但仍然可见的透明度；这个未来的阶段被称为尾声， 其程度可以通过 -Mt 选项指定。下图说明了透明度如何随时间变化。

https://docs.generic-mapping-tools.org/latest/_images/psevents_transparency.png

这里展示了一个符号如何在事件开始时从不可见到完全不透明， 最后在达到其长度后逐渐消失到近乎不可见的阶段。

  1. 最后，用户无需为符号指定固定颜色，而是可以使用 -C 选项来设置一个颜色表， events 将用它来调节符号的颜色。这是通过在数据的 z 列中添加一个可变比例的 dz 来实现的， 因此查找 CPT 时将在不同时间返回不同的颜色。 振幅通过 -Mv 选项进行控制，它将在 0-val1 范围内生成 dz 值 [默认值为 0-1]。 在大多数情况下，数据集的 z 值将为零，因此 CPT 将针对 0-1 范围进行设置 （但请注意，coda 的 val2 值可能为负，因此如果使用 coda，请相应地设置 CPT）。 下图展示了 dz 如何随时间变化。

https://docs.generic-mapping-tools.org/latest/_images/psevents_dz.png

这里展示了一个符号如何在事件开始时从一个恒定的颜色到变化的颜色， 最后在达到它的长度后褪色到一个不同的颜色阶段。 在查 CPT 获取颜色之前，该曲线缩放到某个幅值[1]并添加到 z 列数据。

如以上示例所示，上升、平台、淡出和尾声周期都是可选的，可以根据需要通过 -E 选择或忽略。 用户可以选择指定三个时间历史中的任何一个，也可以不指定。 默认情况下，符号大小是恒定的，没有强度变化，所有符号都是不透明的。

如果绘制的是尾部文本标签（即通过选择 -Et 实现），则仅使用透明度的时间函数， 而不会应用平台期或下降。因此，标签的出现和消失取决于一个初始（且可选的）上升时间 （在此期间标签会逐渐变得完全可见）、一个正常时间（在此期间标签保持可见） 以及一个可选的淡出时间（在此期间文本逐渐消失）。下面的图示展示了这种设置：

https://docs.generic-mapping-tools.org/latest/_images/psevents_labels.png

这里展示标签如何在事件开始时从不可见变为完全不透明，在给定的持续时间内保持可见， 然后最终完全消失。对于标签，平台期和下降期不适用。

数据排序

虽然只会在通过 -T 设置的给定时间绘制应该可见的事件，但绘制的顺序仅由文件中记录的顺序给出。 因此，如果文件没有按升序时间排序，那么后面的事件可能会位于前面的事件之下。 为了防止这种情况，用户可以通过 gmtconvert -N 将文件按升序排序。

绘制轨迹线

如果使用 -Ar 来绘制轨迹线（具有 x, y, t 坐标的线条）， 那么正如前面所述，本模块将使用线性插值来找到中间的终端点。 对于地理数据，特别是如果原始点间距较大，用户可能希望首先通过 sample1d 对此类轨迹沿大圆进行插值，而不是让较大的间隔接受线性插值。 注： 如果使用 -Ardpu 来对线条进行离散化， 那么请注意，重采样会受到当前样条插值方法的影响，该插值方法由 GMT_INTERPOLANT 控制。 如果用户确实需要直线（不论哪种坐标系），就使用线性插值。

示例

为了展示 2018 年 5 月 1 日可观察到的地震事件的显示情况（基于当年发生的大于 5 级的地震数据集）， 采用以下处理方式：先在 2 天的时间内增加符号大小并将其颜色淡化，随后在 6 天内逐渐减弱， 最后缩小至原来大小的一半并加深颜色:

gmt begin layer
    gmt convert "https://earthquake.usgs.gov/fdsnws/event/1/query.csv?starttime=2018-01-01%2000:00:00&endtime=2018-12-31%2000:00:00&minmagnitude=5&orderby=time-asc" \
        -i2,1,3,4+s50,0 -hi1 > q.txt
    gmt makecpt -Cred,green,blue -T0,70,300,10000
    gmt events -Rg -JG200/5/6i -Baf q.txt -SE- -C --TIME_UNIT=d -T2018-05-01T -Es+r2+d6 -Ms5+c0.5 -Mi1+c-0.6 -Mt+c0
gmt end show

为了将时间序列文件 seismic_trace.txt (time, amplitude) 转换为一个 (time, amplitude, time) 格式的文件，以便 events 能够使用可变笔进行绘制 （通过绘制密集分布的圆点来实现），使用参数 -i 来确保对 time 列进行两次读取， 然后使用每厘米 80 像素的 dpu （HD movie）以及相关投影参数:

gmt events seismic_trace.txt -R1984-09-10T03:15/1984-09-10T03:45/-15/15 -JX20cT/10c -Ar80c -i0,1,0 > seismic_trace_pts.txt

注： 如果 PROJ_LENGTH_UNIT 设置为英寸(i) ， 那么用户需要使用相当于每英寸 200 像素的 dpu，或者指定 -Ar200i。

参考文献

Wessel, P., Esteban, F., & Delaviel-Anger, G. (2024). The Generic Mapping Tools and Animations for the Masses. Geochemistry, Geophysics, Geosystems, 25(6). https://doi.org/10.1029/2024GC011545

相关模块

plot , movie