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

# grdcontour

官方文档:

  grdcontour

简介:

  根据网格文件绘制等值线

grdcontour 读取一个二维grid网格文件，并绘制等值线。 或者将等值线的 x, y, z 位置保存到一个或多个输出文件（或标准输出），不绘制图像。

## 语法

gmt grdcontour ingrid `-J` parameters [ `-A`[n|contours][labelinfo] ] [ `-B`[p|s]parameters ] [ `-C` contours|cpt ] [ `-D` template ] [ `-F`[l|r] ] [ `-G`[d|f|n|l|L|x|X]params ] [ `-L` low/high|n|N|P|p ] [ `-N`[cpt] ] [ `-Q`[n|length[unit]][+z] ] [ `-R` west/east/south/north[+r][+u unit] ] [ `-S` smoothfactor ] [ `-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] ] [ `-Z`[+o shift][+s factor][+p] ] [ `-bo` binary ] [ `-do` nodata[+c col] ] [ `-f` flags ] [ `-h` headers ] [ `-l` flags ] [ `-p` flags ] [ `-t` transp ] [ --PAR=value ]

## 输入数据

ingrid[=ID|?varname][+b band][+d divisor][+n invalid][+o offset][+s scale]

> 输入网格名。通过追加 =ID 可指定 网格格式 [默认为 =nf]。 追加 ?varname 可指定 NetCDF 变量 [默认为 GMT 找到的第一个 2-D 网格]。 参数详细介绍请参考 读 netCDF 文件。

## 必须选项

-J

-J projection

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

## 可选选项

-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

  将等值线转存为线段文件，不绘制图像。后面可以加上C语言的 printf 函数 的格式说明符作为输出文件名模板。如果不指定文件名模板则全部打印到标准输出。如果文件名不含格式说明符则全部输出到 单个文件。

  - 如果有浮点数格式(e.g., %6.2f)，其被替换为等值线的z值。

  - 如果有整数格式(e.g., %06d)，其被替换为等值线的计数索引。

  - 如果有字符格式(%c)，其被替换为 C 或 O ，分别代表闭合等值线和开放等值线。

  这3个说明符可以任何顺序组合在一起，以定义输出的文件名。

  例如，只给定 %c 则输出两个文件，只给定 %f 则等值线的每一级输出为一个文件，给定 %d 则每条等值线输出到独立文件中。

-F

-F[l|r]

  使用 `-D` 时，设置按顺序输出等值线的线段。 -Fl （默认值）表示沿着高z值在左侧的等值线方向， -Fr 表示沿着高z值在右侧的等值线方向，不使用 `-F` 则为任意方向。

-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 平面上标注文字之间的最小间距。

-L

-L low/high|n|N|P|p

  不绘制小于 low 大于 high 的等值线。 也可以设置为 -Ln 只绘制负值， 或 -Lp 只绘制正值。使用大写的 -LN 或 -LP 表示包括0等值线。

-N

-N[cpt]

  使用 cpt 指定的离散颜色表填充等值线之间的区域。 同时可以使用 `-C` 和 `-A` 来控制等值线和标注。 如果未附加 cpt，则必须改为通过 `-C` 提供离散颜色表。

-Q

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

  不绘制少于 n 个点的等值线（默认绘制所有等值线）。或者，以距离 unit 为单位给出最小等值线长度 length ， 其中 unit 可使用地理距离单位 d|m|s|e|f|k|M|n|u ， 也可使用 c（用户坐标的笛卡尔距离）和 C（坐标投影后的笛卡尔距离）。可加上 +z 以去除零等值线。

-R

-R xmin/xmax/ymin/ymax[+r][+u unit]

  指定数据范围。 (参数详细介绍)

-S

-S smoothfactor

  在 网格尺寸/smoothfactor 间隔下重采样等值线。

-T

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

  在最内层闭合等值线上每隔一段 gap 距离向着下降方向的刻度。 用户可以加上 h 或 l 来选择分别只在极大值区域或极小值区域绘制。还支持以下选项：

  - +a - 对所有闭合等值线绘制刻度，而不只是最内层。

  - +d - 后面加上 gap[/length] 来设置刻度间的距离 gap 以及刻度线长度 length （可加上单位 c，i或p），默认 15p/3p 。

  - +l - 在极小值和极大值区域中的最内层闭合等值线中心进行标注。 如果不设置 label 则使用 - 和 + 作为标注。如果正好为两个字符，例如 +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]]

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

-Z

-Z[+o shift][+s factor][+p]

  在计算等值线之前，从数据中减去 shift 再乘以 factor （默认-o0+s1）。 在 `-A`，`-C`和`-L`中指定的值是缩放之后的。 后面加上 +p 表明网格数据的z值是360度周期循环的（例如相位数据，角度分布）， 这要求零等值线必须特殊处理。

-bo

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

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

-do

-do nodata

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

-f

-f[i|o]colinfo

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

-h

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

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

-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] 这种格式，来选择普通等值线或两者都选。 如果其中任何一个标签包含斜杠 (/) 字符，则使用 | 作为这两个标签的分隔符。

-p

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

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

-t

-t[transp]

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

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## 距离单位

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

## ASCII 格式精度

ASCII 格式输出数据通过 gmt.conf 配置文件控制。控制经纬度格式的参数为 FORMAT_GEO_OUT ；控制绝对时间的的参数包括 FORMAT_DATE_OUT 和 FORMAT_CLOCK_OUT ；普通浮点数通过参数 FORMAT_FLOAT_OUT 控制。上述格式控制可能会导致精度损失，这会在下游计算中导致一些问题。 如果用户需要保证数据精度，则应考虑将数据写为二进制文件，或者使用 FORMAT_FLOAT_OUT 指定更多的有效数字。

## 注意事项

等值线的角度是通过对沿等值线的 n 个点取平均值来计算的。 如果得到的角度不理想，可以调整两个变量：通过 `-A` 的 +w 修饰符更改 n，和/或通过 `-S` 对等值线进行重采样。 在 n 固定时， `-S` 会使计算更加局部化；反之，在 `-S` 保持不变的情况下增加 n，计算结果则会更加整体化。

## 自动图例

本模块允许使用 `-l` 选项来指定一个自动图例条目。该选项仅适用于线条或符号。 如果符号大小是可变的，并且是根据其他信息计算得出的，那么需要通过 +S 修饰符提供一个具有代表性的图例尺寸。

## 基础示例

使用网格文件AK_gulf_grav.nc，以10为间隔绘制等值线，以20为间隔标注，标注文字大小10p。

    #!/usr/bin/env bash
    gmt begin alaska_grav1
        # @AK_gulf_grav.nc 是 GMT 远程数据服务器自带的网格数据
        gmt grdcontour @AK_gulf_grav.nc -JM16c -C10 -A20+f10p -Baf
    gmt end show

只绘制20和60两条等值线，只标注40等值线。

    #!/usr/bin/env bash
    gmt begin alaska_grav2
        gmt grdcontour @AK_gulf_grav.nc -JM16c -C20,60 -A40,+f10p -Baf
    gmt end show

以10为间隔绘制等值线，以50为间隔标注，设置图标题为"Gravity Anomalies"。 将有标注的等值线设置为粗红线，将无标注的等值线设置为蓝色的细短划线。

    #!/usr/bin/env bash
    gmt begin alaska_grav3
        # -Wathick,red 将有标注的等值线设置为粗红线
        # -Wcthinnest,blue,- 将无标注的等值线设置为蓝色的细短划线
        gmt grdcontour @AK_gulf_grav.nc -JM16c -C10 -A50 -Baf -B+t"Gravity Anomalies" -Wathick,red -Wcthinnest,blue,-
    gmt end show

将负值等值线设置为蓝色，正值等值线设置为红色，0等值线设置为黑色。

    #!/usr/bin/env bash
    gmt begin alaska_grav4
        # -Ln -Wathick,blue -Wcthinnest,blue,- 将负值等值线设置为蓝色
        gmt grdcontour @AK_gulf_grav.nc -JM16c -C10 -A50 -Baf -B+t"Gravity Anomalies" -Ln -Wathick,blue -Wcthinnest,blue,-
        # -Lp -Wathick,red -Wcthinnest,red,- 正值等值线设置为红色
        gmt grdcontour @AK_gulf_grav.nc -C10 -A50 -Lp -Wathick,red -Wcthinnest,red,-
        # 0等值线设置为黑色（默认）
        gmt grdcontour @AK_gulf_grav.nc -A0,
    gmt end show

分两个文件 contours_C.txt 和 contours_O.txt 保存闭合等值线和开放等值线:

    gmt grdcontour @AK_gulf_grav.nc -C150 -S4 -DAK_contours_%c.txt

## 进阶示例

第1个实例绘制等值线，并通过指定 -Gd 选项的参数，沿等值线每1.5英寸放置一个标注。

    #!/usr/bin/env bash
    gmt begin contour_annot1
        gmt coast -R50/160/-15/15 -JM5.3i -Gburlywood -Sazure -A500
        # @App_O_geoid.nc 是 GMT 远程数据服务器自带的网格数据
        # -C10：以10为间隔绘制等值线
        # -A20+f8p：以20为间隔对等值线进行标注，标注字体大小设置为8p。有标注的等值线会被加粗。
        # -Gd1.5i：沿等值线每1.5英寸放置一个标注
        # -T+lLH：在极小值和极大值区域标注 L 和 H
        gmt grdcontour @App_O_geoid.nc -B20f10 -BWSne -C10 -A20+f8p -Gd1.5i -S10 -T+lLH
    gmt end show

第2个实例通过指定 -Gn 选项的参数，指定每条等值线上标注的个数。每条等值线上只放置1个标注，并且要求等值线的长度不小于1英寸。

    #!/usr/bin/env bash
    gmt begin contour_annot2
        gmt coast -R50/160/-15/15 -JM5.3i -Gburlywood -Sazure -A500
        # -Gn1/1i：每条等值线上只放置1个标注，并且要求等值线的长度不小于1英寸
        gmt grdcontour @App_O_geoid.nc -B20f10 -BWSne -C10 -A20+f8p -Gn1/1i -S10 -T+lLH
    gmt end show

第3个实例通过指定 -Gf 选项的参数，给定标注所在位置的坐标。 由于坐标不是严格位于等值线上，因此需要在参数中指定标注位置与等值线距离的上限。标注的位置为等值线上与给定点距离最小的点。 模块会根据等值线的几何形状，自动计算标注的角度。

    #!/usr/bin/env bash

    # 生成文本文件 fix.txt，指定一系列坐标
    cat << EOF > fix.txt
    80      -8.5
    55      -7.5
    102     0
    130     10.5
    EOF

    gmt begin contour_annot3
        gmt coast -R50/160/-15/15 -JM5.3i -Gburlywood -Sazure -A500
        # -Gffix.txt/0.1i：现实中不可能完美指定一个位于等值线上的坐标，因此需要一个额外参数 0.1i
        # 模块会自动计算出等值线上离给定坐标距离最小并且距离小于 0.1i 的位置，进行标注
        gmt grdcontour @App_O_geoid.nc -B20f10 -BWSne -C10 -A20+f8p -Gffix.txt/0.1i -S10 -T+lLH
    gmt end show

第4个实例通过指定 -GL 选项的参数来定义线段，将标注放置在大圆弧线段与等值线的交点。 图中的标注位于数据最值点连线(Z-/Z+)与等值线的交点。同一幅地图中，可以分别指定多条线段。

    #!/usr/bin/env bash
    gmt begin contour_annot4
        gmt coast -R50/160/-15/15 -JM5.3i -Gburlywood -Sazure -A500
        # -GLZ-/Z+：定义一条大圆路径连线，为数据 @App_O_geoid.nc 中最大值和最小值点的连线
        # 在该连线与等值线的交点上进行标注
        # 使用 -A 中的 +d 附加选项会绘制出连线。如果不想绘制连线可以去掉 +d
        gmt grdcontour @App_O_geoid.nc -B20f10 -BWSne -C10 -A20+f8p+d -GLZ-/Z+ -S10 -T+lLH
    gmt end show

如果需要指定的与等值线相交的线段比较多，或线段数据来自其他数据集，可以使用广义的相交算法确定标注的位置。 通过指定 -GX 选项的参数(多段数据文件 cross.txt )，确定标注的位置。 多段数据文件 cross.txt 中定义了三条折线，模块在这三条折线与等值线交点位置处进行标注。

    #!/usr/bin/env bash

    # 生成多段数据文件，定义三条折线
    cat << EOF > cross.txt
    >
    58 -11
    63 -6
    68 -2
    72 -1
    78 3
    >
    150 3
    158 13
    >
    95 -8
    102 -7
    110 -8
    120 -2
    123 0
    EOF

    gmt begin contour_annot5
        gmt coast -R50/160/-15/15 -JM5.3i -Gburlywood -Sazure -A500
        # -GXcross.txt：从 cross.txt 读取折线数据，在折线与等值线的交点处标注
        # 在该连线与等值线的交点上进行标注
        # 使用 -A 中的 +d 附加选项会绘制出连线。如果不想绘制连线可以去掉 +d
        gmt grdcontour @App_O_geoid.nc -B20f10 -BWSne -C10 -A20+f8p+d -GXcross.txt -S10 -T+lLH
    gmt end show

## 相关模块

basemap, grdimage, grdview, contour