✍️ 田冬冬 , Tche LIU , 陈箫翰 • 📅 2026-01-02

# grdmask

官方文档:

  grdmask

简介:

  根据多边形数据或点数据创建掩膜网格文件

grdmask 可以以两种不同的模式运行。

1. 读取一个或多个各自定义了一个闭合多边形的 pathfiles。 多边形外部、内部和边界上的节点可以通过 `-N` 设置为不同的 z 值。 如果多个多边形重叠在相同的节点上，则选定的多边形取决于 `-C` 的选择。 生成的掩膜网格文件可用于后续涉及 grdmath 的操作，以屏蔽多边形区域的数据。

2. pathfiles 仅代表数据点位置，根据节点是否位于最近数据点的最大距离范围内，将其判定为内部或外部。 如果指定的距离为零，则只有最靠近每个数据点的节点才被视为“内部”。

## 语法

gmt grdmask table `-G` outgrid `-I` increment `-R` region [ `-A`[m|p|x|y|r|t] ] [ `-C` f|l|o|u ] [ `-N`[z|Z|p|P]values ] [ `-S` radius|xlim/ylim ] [ `-V`[level] ] [ `-a` flags ] [ `-bi` binary ] [ `-di` nodata[+c col] ] [ `-e` regexp ] [ `-f` flags ] [ `-g` gaps ] [ `-h` headers ] [ `-i` flags ] [ `-j` flags ] [ `-n` flags ] [ `-qi` flags ] [ `-r` reg ] [ `-w` flags ] [ `-x`[[-]n] ] [ `-:`[i|o] ] [ --PAR=value ]

## 输入数据

table

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

## 必须选项

-G

-G outgrid[=ID][+d divisor][+n invalid][+o offset|a][+s scale|a][:driver[dataType][+c options]]

> 输出网格文件名。通过追加 =ID 可指定 网格格式。 参数详细介绍请参考 写 netCDF 文件。

-I

-I xinc[+e|n][/yinc[+e|n]]

  指定X和Y方向的网格间隔

  - xinc 和 yinc 为 X 和 Y 方向的网格间隔。对于地理坐标，可以指定网格间隔单位 [默认单位为度]

  - +e 微调X和Y方向范围的最大值，使得其是网格间隔的整数倍（默认会微调 网格间隔以适应给定的数据范围）

  - +n 表明 xinc 和 yinc 不是网格间隔，而是X和Y方向的节点数。 此时会根据节点数、网格区域范围以及网格配准方式重新计算网格间隔。

  注意：

  - 若 yinc 设置为0，则表示其与 xinc 相同

  - 若使用 -R grdfile 选项，则网格间隔和配准方式已经根据网格文件自动初始化， 此时依然可以使用 -I 和 -r 覆盖相应的值

-R

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

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

## 可选选项

-A

-A[m|p|x|y]

  控制两点之间的连接方式。

  如果输入数据是地理坐标数据（可用 `-f` ig 表明输入是地理坐标），不使用本选项时默认多边形的各边将由大圆弧连接。 如果使用本选项，各边将用直线连接。附加 m 先沿经线再沿纬线连接。附加 p 先沿纬线再沿经线连接。

  对于笛卡尔坐标数据，各点会被直接连接，除非附加 x 或 y 来构建阶梯式路径，首个连接分别沿 x 或 y 方向。 如果笛卡尔坐标数据是极坐标 (theta, r)，则附加 t 或 r 来构建阶梯式路径，首个连接分别沿 theta 或 r 方向。

-C

-C f|l|o|u

  多个多边形重叠在相同的节点上时选择哪个多边形。

  - f 选择覆盖节点的第一个多边形

  - o 选择覆盖节点的最后一个多边形 [默认值为 o]

  - l 选择具有最小 z 值的多边形

  - u 选择具有最大 z 值的多边形

  注意：不适用于 `-S` 。关于多边形的 z 值，请参见 `-N` 。

-N

-N[z|Z|p|P]values

  设置位于多边形外部 (out)、边界 (edge) 和内部 (in) 的节点值， 默认值为 0/0/1 ，即多边形内部节点值为1，其他节点值为0。 values 的形式为 out/edge/in 。可以是任意数值，也可以是 NaN。

  - Nz 将多边形内的节点设置为从多段数据的段头记录中获取的 Z 值，比如多边 形段头记录中的 -Z zval 、 -L header 或 -aZ=name

  - -NZ 与 -Nz 类似，会将多边形的边界也当做是多边形的内部

  - -Np 使用一个默认从开始0递增的数字作为多边形的ID，也可以在其后加上一个数字以 指定序列的起始值

  - -NP 与 -Np 类似，会将多边形的边界也当做多边形的内部

  注意： 本选项不能与 -S 同时使用。它们也都可以选择性地接受 /out [默认值为 0]。

-S

-S radius|xlim/ylim

  根据节点到最近数据点的距离，将其设置为内部、边界上或外部。 距离最近数据点在搜索半径 radius [默认值为 0] 之内的节点被视为内部。 如果 radius 为 z，则改为从输入数据的第三列读取每个点的半径。 笛卡尔坐标数据除外，地理坐标数据都需要在 -Sz 之后附加单位来指定这些半径的单位。

  如果未设置本选项，则认为输入数据定义了一个或多个闭合多边形。对于具有不同单位的笛卡尔数据，可以改为附加 xlim/ylim 执行矩形搜索， 数据点 ±xlim 和 ±ylim 范围内的所有节点都将被视为内部。 也可以使用 -S n_cells c 形式来实现矩形选择效果。此处 n_cells 表示每个数据点周围的节点数量。 例如， -S0c 表示仅数据点所在的节点， -S1c 则表示周围的一个节点的范围（即形成以数据点为中心 3x3 的矩阵区域）。

-V

-V[level]

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

-a

-a[[col=]name][,...]

  控制输入或输出为 OGR/GMT 格式时对非空间元数据的处理方式。 (参数详细介绍)

-bi

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

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

-di

-di nodata

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

-e

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

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

-f

-f[i|o]colinfo

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

-g

-g[a]x|y|d|X|Y|D|[col]z gap[+n|p]

  确定数据或线段的间断。 (参数详细介绍)

-h

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

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

-i

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

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

-j

-je|f|g

  设置球面距离的计算方式。 (参数详细介绍)

-n

-n[b|c|l|n][+a][+b BC][+t threshold]

  附加 +b BC 以设置要使用的边界条件。 BC 可以选择:

  - g 表示地理边界条件

  - p 表示周期性边界条件

  - n 表示自然边界条件

  对于后两者，可以附加 x 或 y 以仅指定一个方向，否则默认两个方向 [如果网格是地理网格，则默认为地理边界条件]。

-qi

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

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

-r

-r[g|p]

  设置网格配置方式 [默认为网格线配准]。 (参数详细介绍)

-w

-wy|a|w|d|h|m|s|c period[/phase][+c col]

  将输入坐标转换为循环坐标。 (参数详细介绍)

-x

-x[[-]n]

  限制多核算法中能使用的核数（需要GMT开启OpenMP支持）。 (参数详细介绍)

-:

-:[i|o]

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

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## 距离单位

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

## 地理坐标和时间坐标

当输出文件为 netCDF 格式时，根据输入数据、网格或者 -f 以及 -R 选项，会自动将输出坐标命名为“longitute”，“lattitude” 或者 “time”。例如： -f0x -f1t 和 -R90w/90e/0t/3t 都会生成 longitude/time 网格。 当 x，y 或者 z 坐标为时间时，在网格中将会存储为相对时间，其相对于 TIME_EPOCH 和 TIME_UNIT 指定的历元。其中时间变量的单位 属性将会默认与上述两个参数一致。

## 点位于多边形内/外

为了确定点在多边形内，外或在边界上，GMT 会平衡数据类型以及多边形形状等因素来 确定算法。对于笛卡尔坐标，GMT 使用 non-zero winding 算法，该算法非常快。对于 地理坐标，如果多边形不包括两极点且多边形的经度范围不超过 360 度，同样使用该 算法。否则，GMT 会采用 full spherical ray-shooting 方法。

## 注意事项

由 grdmask 生成的网格是一个 分类型 数据集，即所有数据只能取几个固定的值。 因此，必须注意不要使用标准方法（如样条插值）进行插值。 比如 -N0/1 会将水域内的网格值设置为0，将陆地内的网格值设置为1。 在这种情况下，对这种数据用标准方法进行插值通常会得到无意义的结果，使用时需要小心。

然而，如果使用地图投影来绘制该网格，网格将被重新投影，从而在投影坐标系中生成一个矩形矩阵。 这个过程中涉及到了网格插值，默认情况下，这种插值是使用样条插值完成的，因此可能会在图中产生假象。 对于此类情况，建议使用 grdimage -nn 来改为使用最近邻插值 nearest neighbor 插值算法以避免这一问题。

## 节省存储空间

由于 grdmask 的大多数用途是围绕创建仅包含少量整数值（可能还有 NaN）的掩码网格展开的， 通过在所需的网格文件名后附加后缀 =nb，可以将它们作为字节网格 (byte grids) 写入磁盘。 某些情况存储的整数可能会超出字节网格的可用范围，对于这些情况，可以使用 =ns 指定短整型网格。 对于更大的整数，可以考虑使用 =ni，否则请使用默认的浮点网格格式。

## 示例

多边形内和边界上的节点值为0，外部值为1:

    gmt grdmask coastline_*.xy -R-60/-40/-40/-30 -I5m -N1/0/0 -Gland_mask.nc=nb -V

数据点周围50千米范围的节点值为1，其余为NaN:

    gmt grdmask data.xyz -R-60/-40/-40/-30 -I5m -NNaN/1/1 -S50k -Gdata_mask.nc=nb -V

将多边形的ID作为多边形内部节点的值:

    gmt grdmask plates.gmt -R-40/40/-40/40 -I2m -Nz -Gplate_IDs.nc=ns -aZ=POL_ID -V

将多边形的ID作为多边形内部节点的值，但多边形ID从100开始:

    gmt grdmask plates.gmt -R-40/40/-40/40 -I2m -Np100 -Gplate_IDs.nc=ns -V

## 相关模块

grdlandmask, grdmath, grdclip, mask, clip