✍️ 田冬冬 , 朱邓达 , 王亮 , 陈箫翰 • 📅 2026-01-16

# xyz2grd

官方文档:

  xyz2grd

简介:

  将 xyz 数据或 z 数据转换成网格文件

xyz2grd 读取一个或多个 z 数据或 xyz 数据，并将其转换成二进制网格文件。 若某些节点没有数据值，则这些节点会被赋值为 NaN； 若某个节点由多个数据值，则该节点的值为所有数据点的平均值。

该模块的本质为：创建一个网格，将离散点数据放置在对应的格点中。 并不具备网格化/插值功能，若需要网格化，可以使用模块 surface、 greenspline、 nearneighbor 或 triangulate。

## 语法

gmt xyz2grd [ table ] `-G` grdfile `-I` increment `-R` region [ `-A`[d|f|l|m|n|r|S|s|u|z] ] [ `-D`[+x xname][+y yname][+z zname][+s scale][+o offset][+n invalid][+t title][+r remark] ] [ `-J` parameters ] [ `-S`[zfile] ] [ `-V`[level] ] [ `-Z`[flags] ] [ `-bi` binary ] [ `-di` nodata[+c col] ] [ `-e` regexp ] [ `-f` flags ] [ `-h` headers ] [ `-i` flags ] [ `-qi` flags ] [ `-r` reg ] [ `-w` flags ] [ `-:`[i|o] ] [ --PAR=value ]

## 输入数据

table

  输入表数据。可以只包含Z值，也可以包含 (x,y,z) 值。可以是ASCII格式，也可以是二进制格式。 XYZ数据不要求排序。如果只包含Z值，则必须使用 `-Z` 选项。

## 必须选项

-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[d|f|l|m|n|r|S|s|u|z]

  多个数据落在同一个网格节点内时的处理方式。

  默认情况下，若有多个数据落在同一个网格节点内，会将这些数据的均值作为该 节点的值。使用该选项可以修改这一行为（当使用 `-Z` 选项时，该选项会被忽略）：

  - -Af 将第一个落在该节点内的数据值作为节点值

  - -As 将最后一个落在该节点内的数据值作为节点值

  - -Al 将落在该节点内的所有值的最小值作为节点值

  - -Au 将落在该节点内的所有值的最大值作为节点值

  - -Ad 将落在该节点内的所有值的最大值和最小值的差作为节点值

  - -Am 将落在该节点内的所有值的均值作为节点值

  - -Ar 将落在该节点内的所有值的RMS值作为节点值

  - -AS 将落在该节点内的所有值的标准差作为节点值

  - -An 将落在该节点内的数据数目作为该节点值，该选项仅要求输入数据中有XY值

  - -Az 将落在该节点内的所有值的和作为节点值

-D

-D[+x xname][+y yname][+z zname][+c[-|cpt]][+d dname][+s scale][+o offset][+n invalid][+t title][+r remark][+v varname]

  给定网格文件头段中的基本信息：

  - +c[-|cpt] - 设置 cpt 为该网格的默认 CPT [turbo]，或使用 - 移除已设置的默认 CPT

  - +d dname - 设置数据值名称 dname

  - +n invalid - 设置 invalid 值用于表示该节点处无有效值 [NaN]

  - +o offset - 设置读入数据后并乘以因子后要加的常数 [0]

  - +r remark - 设置网格文件的注释信息

  - +s scale - 设置读入网格数据后要乘以的因子 [1]

  - +t title - 设置网格文件的标题

  - +v varname - 指定数据集变量名称 varname

  - +x xname - 指定 X 坐标名及其单位，格式为 varname [unit]，比如 "distance [km]"

  - +y yname - 指定 Y 坐标名及其单位，格式同 xname

  - +z zname - 针对 3D 网格: 指定 Z 坐标名及其单位，格式同 xname

  其它说明：

  - 未指定的项其值保持不变

  - 可以给一个空值以重置某一项，比如使用 +t 而不指定标题则设置标题为空

  - 若字符串中包含空格则需要用引号括起来

  - 若字符串中包含加号 +，需要使用 + 对其进行转义。 或者可以使用单引号套双引号的方式，例如 '"title with + inside"'

  - 若字符串中使用了shell变量，且变量值中包含加号，则需要使用 `${variable/+/\\+}`

  - 对于地理数据（比如 -fg ）和 3D 网格，xname 和 yname 会自动设置。 通常 netCDF 数据变量名为 "z"（2D 网格）或 "cube"（3D 网格）， 可通过 +v 重命名该 netCDF 变量。

-J

-J projection

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

> 将地理参考信息以符合 CF-1 标准的元数据保存到 netCDF 网格文件中。 PROJ 语法可以直接在参数中使用，并且可以被 GDAL 识别。

-S

-S[zfile]

  对输入的Z文件做字节序转换并输出到标准输出或保存到文件 zfile 中。 该选项只做字节序转换，不生成网格文件。该选项必须与 `-Z` 选项一起使用。

-V

-V[level]

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

-Z

-Z[flags]

  指定Z数据的格式。

  对于Z数据而言，由于没有XY坐标信息，因而Z数据中必须提供所有节点处的值且按照 一定的顺序排列。输入Z值的顺序由 flags 决定。 在确定数据的排列顺序时，需要指定数据的起点以及数据排序的方向。

  - 数据起点：可以取网格的四个顶点中的任意一个作为起点，四个顶点分别用 TL、TR、BL和 BR 表示， 其中 T 代表 Top，B 代表Bottom，L 代表Left，R 代表Right。

  - 排序方式：选取数据顶点之后，数据可以是行优先也可以是列优先，所以有两种 排序方式。若是行优先，则 T|B 位于 L|R 的前面；若列优先，则 L|R 位于 T|B 的前面。

  对于网格线配准的数据，若数据在X方向是周期性的但输入数据中并不包含x=xmax处的 冗余列，则加上 x；若数据在Y方向是周期性的但输入数据中并不包含y=ymax处的 冗余行，则加上 y；加上 s n 用于跳过数据中最前面的 n 个字节； 若需要转换数据的字节序，则加上 w。

  除此之外，还需要再加上一个字符表征数据类型：

  - `A`: ASCII表示，每行一个或多个浮点数

  - `a`: ASCII表示，每行一项，不仅可以处理浮点数还可以处理日期时间数据和经纬度数据

  - `c`: int8_t，有符号单字节字符

  - `u`: uint8_t，无符号单字节字符

  - `h`: int16_t，有符号双字节整型

  - `H`: uint16_t，无符号双字节整型

  - `i`: int32_t，有符号四字节整型

  - `I`: uint32_t，无符号四字节整型

  - `l`: int64_t，长整型（8字节）

  - `L`: uint64_t，无符号长整型（8字节）

  - `f`: 4字节单精度浮点型

  - `d`: 8字节双精度浮点型

  默认的输入数据格式为 -ZTLa。需要注意，`-Z` 选项仅对Z数据有效。

-bi

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

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

> 该选项仅适用于XYZ数据。对于Z数据，应使用 `-Z` 选项。

-di

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

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

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

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

-:

-:[i|o]

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

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## 网格值精度

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

## 地理坐标和时间坐标

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

## 交换限制

所有数据类型都可以读取，甚至是 64 位整数，但在内部网格是以浮点数 (float) 存储的。 因此，超过浮点类型 23 位尾数 (mantissa) 的整数值可能无法精确表示。当使用 `-S` 时，不涉及网格，我们将数据读取到中间的双精度 (double) 容器中。 这意味着除了 64 位整数之外，所有数据都可以使用双精度类型的 53 位尾数来表示。

## 示例

将ASCII文件转换为网格数据:

    gmt xyz2grd hawaii_grv.xyz -D+xdegree+ydegree+zGal+t"Hawaiian Gravity"+r"GRS-80 Ellipsoid used" \
        -Ghawaii_grv_new.nc -R198/208/18/25 -I5m -V

将二进制格式的XYZ文件（单精度）转换为网格文件:

    gmt xyz2grd raw.b -D+xm+ym+zm -Graw.nc -R0/100/0/100 -I1 -V -Z -bi3f

从 NCEI 全球起伏数据 CD-ROM 上的原始二进制 USGS DEM（短整型扫描线导向数据 topo30.b，其中值为 -9999 表示缺失数据）制作网格文件， 在某些机器上必须反转字节序（如 Sun）:

    gmt xyz2grd topo30.b -D+xm+ym+zm -Gustopo.nc -R234/294/24/50 -I30s -di-9999 -ZTLhw

一个包含 4 字节浮点数的二进制文件，该文件是在字节序不同的机器上写入的。可以使用以下命令交换字节序:

    gmt xyz2grd floats.bin -Snew_floats.bin -V -Zf

针对笛卡尔数据集中分配给每个节点的点数制作一个像素配准的 TIFF 文件:

    gmt xyz2grd data.txt -R0/100/0/100 -r -I10 -An -Gnumber_of_points.tif=gd:GTiff

## 相关模块

grd2xyz, grdedit, grdconvert, greenspline, nearneighbor, surface, triangulate