✍️ 田冬冬 , 陈箫翰 , 朱邓达 • 📅 2025-12-30

# contour

官方文档:

  contour

简介:

  使用直接三角化法对数据进行等值线绘制

## 语法

gmt contour [ table ] `-J` parameters [ `-Jz|Z` parameters ] `-R` west/east/south/north[/zmin/zmax][+r][+u unit] [ `-A`[n|contours][labelinfo] ] [ `-B`[p|s]parameters ] [ `-C` contours ] [ `-D`[template] ] [ `-E` indexfile ] [ `-G`[d|f|n|l|L|x|X]params ] [ `-I` ] [ `-L` pen ] [ `-N` ] [ `-Q`[cut][+z] ] [ `-S`[p|t] ] [ `-T`[h|l][+a][+d gap[/length]][+l[labels]] ] [ `-U`[stamp] ] [ `-V`[level] ] [ `-W`[type]pen[+c[l|f]] ] [ `-X`[a|c|f|r][xshift] ] [ `-Y`[a|c|f|r][yshift] ] [ `-bi` binary ] [ `-bo` binary ] [ `-d` nodata[+c col] ] [ `-e` regexp ] [ `-f` flags ] [ `-h` headers ] [ `-i` flags ] [ `-l` flags ] [ `-p` flags ] [ `-qi` flags ] [ `-s` flags ] [ `-t` transp ] [ `-:`[i|o] ] [ --PAR=value ]

## 输入数据

table

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

## 必须选项

-J

-J projection

  设置地图投影方式。 (参数详细介绍)

-Jz|Z

-J z|Z parameters

  绘制三维图时，设置垂直方向 Z 轴的线性投影尺度。 参数用法与 -Jx|X 相同。

-R

-R west/east/south/north[/zmin/zmax][+r][+u unit]

  指定数据范围。对于三维透视图（-p 选项） ，可以加上 /zmin/zmax 指定Z轴的范围。 (参数详细介绍)

## 可选选项

-A

-A[n|contours][labelinfo]

  `-A` contours 设置标注间隔，如果在 `-C` 选项中指定标注间隔的话， 这里的设置会被覆盖。-An 则为不进行标注。也可以用 `-A20,80,100` 类似的用法，对指定的 等值线进行标注。如果只想要标注一条等值线，需要在末尾加上逗号，例如 `-A20,` ，这样 `20` 就不会被认为是标注间隔。 labelinfo 代表可以在最后追加下列额外选项:

> +a angle

>   设置标注的旋转角度 angle 。也可以写成 +an 表示标注垂直于等值线。默认设置为 +ap 表示标注 平行于等值线。 +apu 和 +apd 表示设置方向朝向山顶还是山底。

> +c dx[/dy]

>   设置标签和文本框之间的间隙。后面加上 c|i|p 来指定单位或 % 来表示标签字体大小的百分比 [15%]。

> +d

>   打开debug模式，绘制辅助点和辅助线展示等高线的设定。

> +e

>   延迟标注。这用于基于文本构建裁剪路径，在该裁剪路径生效时放置其他图层， 使用 clip -C 关闭裁剪后再标注文本，这样使标注文本不被裁剪。 请注意，裁剪路径可能会截断没有文本重叠的其他区域。反复检查以确保得到预期的正确结果。 建议每次使用 +e 后，选择合适的位置手动运行 clip 。

> +f font

>   设置字体。默认会使用 FONT_ANNOT_PRIMARY 设定的字体，但字体大小会变成9p。

> +g[color]

>   设置标注文本框的背景颜色，默认使用 PS_PAGE_COLOR 颜色，不设置本项时标注文本框的背景是透明的。

> +i

>   隐藏等值线（默认绘制等值线），只绘制标注

> +j[just]

>   设置标注相对于等值线中点的对齐方式，默认使用 MC 。

> +n dx[/dy]

>   设置标注位置的偏移，后面加上 c|i|p 来指定单位。偏移增量设定在由等值线方向定义的坐标系中 （沿等值线方向为 x ，垂直等值线方向为 y）。 将 +n 改为 +N 则所有标注在整个绘图坐标系 x/y 中整体偏移。不能和 +v 一起使用。

> +o

>   将文本框形状设置为圆角矩形。不能和 +v 一起使用。

> +p[pen]

>   设置文本框轮廓的线型，不设置本项时无轮廓。默认宽度0.25p，颜色black，风格solid。

> +r min_rad

>   等值线的曲率半径小于 min_rad 处不作标注。默认 min_rad 设置为0。

> +t[file]

>   将等值线标注文本的坐标 x，坐标 y，旋转角度 angle 和文本保存到文件 file。 默认文件名为Contour_labels.txt。

> +u unit

>   在所有标注后面加上单位 unit ，默认无单位。如果设置为 +uz，则使用输入文件的z值单位。

> +v

>   将标注文本沿着等值线弯曲。

> +w n

>   指定使用多少个 (x,y) 点来估计标注旋转角度，默认由程序自动指定。

> +=prefix

>   在所有标注前面加上前缀 prefix 。

-B

-B parameters

  设置底图边框和轴属性。 (参数详细介绍)

-C

-C contours

  指定绘制等值线的形式，具体说明如下:

  1. 如果 contours 是一个以 ".cpt" 结尾的文件名，GMT会查找对应的CPT文件， 把CPT文件中的颜色块的边界绘制为等值线，并进行标注。如果使用了 `-An` 选项则只绘制等值线不标注。

  2. 如果 contours 是一个不以 ".cpt" 结尾的文件名，GMT会读取其中的内容作为等值线设置。 每行为一条等值线的设置，以如下格式给出： contour-level [angle] C|c|A|a [pen]，中括号表示可选项。 C 或 c 表示绘制等值线但不标注，而 A 或 a 表示绘制等值线并进行标注。 angle 设置标注的旋转角。 pen 设置等值线的线型。

  3. 如果 contours 是一串用逗号隔开的数字，例如 `-C20,80,100` ，则绘制对应的等值线。 如果只想要绘制一条等值线，需要在末尾加上逗号，例如 `-C20,` 。

  4. 如果没有指定 contours ，则默认使用当前CPT文件。

  5. 如果 contours 是一个常数，则以这个常数为间隔绘制等值线。

  如果 `-C` 和 `-A` 都没有指定的话，则自动计算合适的间隔绘制标注等值线。

-D

-D[template]

> 将每个等值线的 (x, y, z) 坐标导出到一个或多个输出文件（如果未给出 template，则导出到标准输出）。不会进行绘图。 如果 template 包含一个或多个 C 语言 printf 格式说明符 %d、%f、%c， 则线段将被写入不同的文件；否则所有线条都将写入指定的文件 (template)。C 格式说明符的使用控制了创建的文件数量以及等值线的组织方式。 如果存在浮点格式 %f（允许对宽度和精度进行标准修改，例如 %f7.3f），则文件名将包含等值线数值，因此线条会根据共同的等值线数值被分选到不同的文件中。 如果存在整数格式 %d（包括像 %05d 这样的修改），则所有等值线都会被写入单独的段文件；如果还存在其他任何说明符，它们仅影响文件名。 最后，如果存在字符格式 %c，它将被字母 C（代表闭合 closed）或 O（代表打开 open）替换，以反映每条等值线的性质。 这三个修饰符中的一个、两个或全部三个的任意组合都是有效的，会产生不同的文件名和文件数量。 例如，如果单独出现 %c，则仅创建两个文件，将打开的等值线与闭合的等值线分开（假设两种类型都存在）。 如果仅使用 %f，则同一等值线级别的所有线段都将写入同一个文件，从而产生 N 个多段文件。 如果同时结合 %f 和 %c，那么每个等值线级别将进一步细分为闭合和打开的等值线。 任何涉及 %d 的组合都会为每个线段生成一个独立的文件；此时 %c 和 %f 仅修改文件名。除非使用 -bo，否则文件均为 ASCII 格式。

-E

-E indexfile[+b]

  指定包含网络信息的文件名。每条记录必须包含一个三角形的三个节点编号 [默认使用 Delaunay 三角剖分计算这些信息（见 triangulate）]。 如果 indexfile 是二进制文件，且其读取方式与二进制输入 table 相同，则可以附加 +b 以加快读取速度 [默认以 ASCII 格式读取节点]。

-G

-G[d|f|n|l|L|x|X]params

警告

某些时候等值线图会出现标注数字消失不见的情况。这是由于数字被标注在绘图范围外所致。 这种情况应该使用下面的 `-G` 选项手动设置标注在等值线上的位置。

> 有5种可选的方式控制标注文字的位置。

> d dist[c|i|p] 或 D dist[d|e|f|k|m|M|n|s]

>   使用小写的 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)。

> 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 表示使用大圆路径。

>   还可以使用子选项 Z+ 、 Z- 代表网格数据中全局最大值点或最小值点的坐标。 例如， Z-/135W/15S 代表网格数据中最小值点与 (135ºW, 15ºS)之间的连线； Z-/Z+ 代表网格数据中最小值点与最大值点之间的连线。

> n|N n_label[/min_dist[c|i|p]]

>   指定等值线上等间隔标注的个数，默认为1即只绘制一个标注。 小写的 n 表示标注位置在每段间隔的中心，而大写的 N 表示标注位置在每段间隔的起点。

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

> x|X xfile

>   读取 ASCII 文本格式的多段数据文件 xfile.txt ，标注文字会绘制在这些多段数据与线段的交点。 大写的 X 会先将输入数据重采样为大圆弧线。

> 添加可选选项 +r radius[c|i|p] 可以设置 x-y 平面上标注文字之间的最小间距。

> `-G` 选项的用法示例可以参考 grdcontour 模块的 进阶示例 小节

-I

-I

  使用 CPT 文件对三角形着色。

-L

-L pen

  指定画笔属性绘制底层的三角形网格 [默认不绘制网格]。

-N

-N

  对绘图边界外的图形不进行裁剪 [默认会进行裁剪]。

-Q

-Q[n|length[unit]][+z]

  不绘制点数少于 n 的等值线 [默认绘制所有等值线]。 或者也可以指定最小等值线 长度*（以距离单位表示，可用单位及距离计算方式见 :doc:`/basis/unit` ）， 包括 **c**（使用用户坐标的笛卡尔距离）或 **C**（坐标投影后当前绘图单位下的绘图长度单位）。附加 **+z* 以排除零等值线。

-S

-S[p|t]

  跳过所有落在区域外的输入 x, y, z 点 [默认使用三角剖分中的所有数据]。 或者使用 -St 跳过三个顶点均在区域外的三角形。不带修饰符的 `-S` 默认为 -Sp。

-T

-T[h|l][+a][+d gap[/length]][+l[labels]]

> 仅沿着最内层的闭合等值线，每隔 gap 距离绘制指向下坡方向的短划线（示坡线）。 用户可以通过分别附加指令 h 或 l，选择仅对局部高点或局部低点绘制短划线。 可以通过以下修饰符进一步规定：

> - +a - 为所有闭合等值线绘制短划线，而不仅仅是最内层。

> - +d - 附加 gap[/length] 以设置短划线之间的间距以及可选的短划线 长度*（附加单位 **c*、i 或 p）， 或使用默认值 [15p/3p]。

> - +l - 附加 labels 以设置如何标注最内层闭合等值线的中心（即局部低点和高点）。 如果未附加 labels，则使用 - 和 + 作为标注。 如果附加恰好两个字符（例如 +l LH），则绘制这两个字符（此处为 L 和 H）作为标注。 对于更复杂的标注，请用逗号分隔低点和高点的标注字符串（例如 +l lo,hi）。 如果通过 `-C` 给出了文件且设置了 `-T` ，则只有标记为大写 C 或 A 的等值线才会有短划线 [和标注]。 注意：局部高点和低点的标注有时可能会绘制在最内层等值线之外，因为仅使用等值线坐标的平均值来确定标注位置。

-U

-U[label][+c][+j just][+o dx/dy]

  在图上绘制GMT时间戳logo。 (参数详细介绍)

-V

-V[level]

  设置 verbose 等级 [w]。 (参数详细介绍)

-W

-W[type]pen[+c[l|f]]

  设置等值线的线型。默认情况下，有标注的等值线线型 pen 为 `0.75p,black` ， 无标注的等值线线型 pen 为 `0.25p,black` 。如果要设置有标注的等值线线型，type 应该设置为 a ， 例如 `-Wa1.75p,red` 。无标注的等值线线型，type 应该设置为 c ，例如 `-Wc1.25p,red` 。 如果加上 +cl ，则使用 `-C` 选项所指定的CPT文件为不同的等值线设置颜色; 如果使用 +cf ，则为标注设置颜色; 使用 +c 则同时为等值线和标注设置颜色。

-X

-Y

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

-Y[a|c|f|r][yshift[u]]

  移动绘图原点。 (参数详细介绍)

-bi

-bi[ncols][type][w][+l|b]

  控制二进制文件的输入格式。 (参数详细介绍)

-bo

-bo[ncols][type][w][+l|b]

  控制二进制文件的输出格式。 (参数详细介绍)

-d

-d[i|o]nodata

  将某些特定值当作 NaN。 (参数详细介绍)

-e

-e[~]"pattern" | -e[~]/regexp/[i]

  筛选或剔除匹配指定模式的数据记录。 (参数详细介绍)

-f

-f[i|o]colinfo

  显式指定当前输入或输出数据中每一列的数据类型。 (参数详细介绍)

-h

-h[i|o][n][+c][+d][+m segheader][+r remark][+t title]

  在读/写数据时跳过文件开头的若干个记录。 (参数详细介绍)

-i

-i cols[+l][+s scale][+o offset][,...][,t[word]]

  对输入的数据进行列选择以及简单的代数运算。 (参数详细介绍)

-l

-l[label][+D pen][+G gap][+H header][+L[code/]txt][+N cols][+S size[/height]][+V[pen]][+f font][+g fill][+j just][+o off][+p pen][+s scale][+w width]

  为当前绘制的符号或线段增加一个自动图例记录。 (参数详细介绍)

> 通常，图例中默认选择带标注的等值线。通过将 label 设置为 [annotcontlabel][/contlabel] 格式， 可以改选普通等值线或者同时选择两者。如果任一标签中包含斜杠 (/) 字符，则改用 | 作为这两个标签的分隔符。

-qi

-qi[~]rows[+c col][+a|f|s]

  筛选输入的行或数据范围。 (参数详细介绍)

-:

-:[i|o]

  交换输入或输出数据的前两列。 (参数详细介绍)

-p

-p[x|y|z]azim[/elev[/zlevel]][+w lon0/lat0[/z0]][+v x0/y0]

  设置3D透视视角。 (参数详细介绍)

-s

-s[cols][+a|+r]

  设置 NaN 记录的处理方式。 (参数详细介绍)

-t

-t[transp]

  设置图层透明度（百分比）。取值范围为0（不透明）到100（全透明）。 (参数详细介绍)

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## 距离单位

GMT支持多种不同的距离单位，以及三种不同的球面距离计算方式。 详情见 单位 和 -j 选项。

## 示例

使用 GMT 远程数据服务器上的数据文件 @Table_5_11.txt ，以25为间隔绘制等值线，以50为间隔标注：

    #!/usr/bin/env bash
    gmt begin contour_ex1
        gmt contour @Table_5_11.txt -Wthin -C25 -A50 -Baf
    gmt end show

只绘制并标注750和800两条等值线：

    #!/usr/bin/env bash
    gmt begin contour_ex2
        gmt contour @Table_5_11.txt -A750,800 -W0.5p -Baf
    gmt end show

使用CPT文件temp.cpt定义的间隔绘制等值线

>     gmt contour temp.xyz -R0/150/0/100 -Jx0.1i -Ctemp.cpt -W0.25p

## 相关模块

grdcontour, grdimage, nearneighbor, basemap, colorbar, surface, triangulate