✍️ 周茂 • 📅 2026-01-12

# sphdistance

官方文档:

  sphdistance

简介:

  在球上创建 Voronoi 距离，节点或自然最邻近网格

sphdistance 读取一个或多个 ASCII（或二进制）坐标文件，使用所有的坐标创建 Voronoi 图。 得到的多边形用来创建球面上的网格，其中网格值为到坐标文件中坐标的最近距离（见 `-E` ） 。 创建 Voronoi 图使用 STRIPACK 算法。可以使用 sphtriangulate 提前创建多边形文件 以节省时间和运行时所需的空间。

## 语法

gmt sphdistance [ table ] `-G` grdfile `-I` increment `-R` region [ `-C` ] [ `-D` ] [ `-E` d|n|z[dist] ] [ `-L` unit ] [ `-N` nodetable ] [ `-Q` voronoi.txt ] [ `-V`[level] ] [ `-bi` binary ] [ `-bo` binary ] [ `-d` nodata[+c col] ] [ `-e` regexp ] [ `-h` headers ] [ `-i` flags ] [ `-j` flags ] [ `-qi` flags ] [ `-r` reg ] [ `-:`[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]

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

## 可选选项

-C

-C

  用于节省内存。该模块默认在运算过程中同时保存地理坐标和笛卡尔坐标，但对于大型数据 集，这可能会占据很大内存，因此使用该选项可以只保留其中一种坐标以节省内存，必要的 时候 GMT 会自动实现坐标转换。在使用 `-Q` 选项时，该选项无用

-D

-D

  用于删掉重复点 [默认不删除，即假定数据中不存在重复]

-E

-Ed|n|z[dist]

  指定球面网格中每个网格值的类型。

  - d 默认选项，计算球面上网格点到输入坐标的最近距离

  - n 将网格值设置为所在多边形的 ID

  - z 将网格值设置为所在多边形的节点（即 Delaunay 三角网的外接圆圆心）上的值

  dist 为在球面弧上进行重采样的间隔，默认为 1，单位为度。

-L

-L unit

  指定距离计算的单位，可选项包括 e (m)， f (foot)， k (km)， M (mile)，n (nautical mile)，u (survey foot)，或 d (spherical degree)

-N

-N nodetable

  从 nodetable 文件度读取每个 Voronoi 多边形相关的节点坐标和面积等信息 [默认从 输出 ASCII 文件的段信息中获取]。

-Q

-Q voronoi.txt

  指定 Voronoi 多边形文件 [默认使用输入数据构建 Voronoi 图]。如果输入数据为二进制文件， 需要 `-N` 选项指定节点信息。

-V

-V[level]

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

-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]

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

-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

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

-qi

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

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

-r

-r[g|p]

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

-:

-:[i|o]

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

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## ASCII 格式精度

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

## 网格值精度

不管输入数据的精度如何，创建网格文件的 GMT 程序将在内部以 4 字节浮点数组的形式保存网格。 这样做是为了节省内存，而且大多数实际数据都可以使用 4 字节浮点值存储。 具有更高精度的数据（即双精度值）将在 GMT 操作网格或写入新网格时失去该精度。 为了限制处理数据时的精度损失，用户应该始终考虑在处理之前对数据进行归一化。

## 示例

创建一个球面网格，网格值为到 `hotspots.txt` 文件中点的最近距离，然后以 200 km 为间隔在球面网格创建等值线，每 1000 km 设置标注

    gmt begin map
        gmt sphtriangulate @hotspots.txt -Qv -D > t.txt
        gmt sphdistance -Rg -I1 -Qt.txt -Gt.nc -Lk
        gmt grdcontour t.nc -JG-140/30/7i -C200 -A1000 -Bafg
    gmt end show

以 `testdata.txt` 创建 Voronoi 图，并生成 1 度分辨率的全球距离网格

    gmt sphdistance testdata.txt -Rg -I1 -Gglobedist.nc

上述代码也可分成两个命令

    gmt sphtriangulate testdata.txt -Qv > voronoi.txt
    gmt sphdistance -Qvoronoi.txt -Rg -I1 -Gglobedist.nc

此外，GMT 官方示例 35 展示了使用本模块和全球海岸线创建海洋到海岸线的距离网格。

## 注意事项

STRIPACK 算法需要输入中不包含重复点。 blockmean 等模块可以将多个接近的点合并成单个点。sphdistance 的 `-D` 选项也可以删除重复点，但是这通过对点的坐标精确比较实现，对大型 数据集来说，运行可能会很慢。STRIPACK 算法在检测到重复点时，会直接退出执行

## 参考文献

Renka, R, J., 1997, Algorithm 772: STRIPACK: Delaunay Triangulation and Voronoi Diagram on the Surface of a Sphere, AMC Trans. Math. Software, 23(3), 416-434.

## 相关模块

sphtriangulate, triangulate