✍️ 何星辰 • 📅 2025-10-20

# grd2kml

官方文档:

  grd2kml

简介:

  从单个网格创建 KML 分级切片图像

grd2kml 读取一个二维网格文件，并使用所选的图块大小生成 PNG 或 JPG 图像 以及适用于 Google Earth 的 KML 文件四叉树（quadtree）。 我们根据四叉树的不同视图层级，对网格进行高斯滤波降采样（可通过选项选择其他滤波器）。 可选地，通过提供 ±1 范围内的强度网格文件，或自动从输入网格派生强度（见 `-I` ）， 可添加光照效果。超出 ±1 范围的强度值将被裁剪。 地图颜色通过色标（CPT）查表定义，可选择是否叠加等值线。 如果选择生成纯图块（即未指定等值线），则 PNG 图像由 grdimage 直接输出； 否则将先生成 PostScript 图，再经 psconvert 转换为光栅图像。

## 语法

gmt grd2kml ingrid `-N` prefix [ `-A` a|g|s[altitude] ] [ `-C`[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),...][+h[hinge]][+i dz][+u|U unit][+s fname] ] [ `-E` URL ] [ `-F` filtercode ] [ `-H` scale ] [ `-I`[file|intens|+a azimuth][+d][+m ambient][+n args] ] [ `-L` tilesize ] [ `-S`[extra] ] [ `-T` title ] [ `-W` cfile|pen[+s scale/limit] ] [ `-V`[level] ] [ `-f` flags ] [ `-n` flags ] [ --PAR=value ]

## 输入数据

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

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

## 必须选项

-N

-N prefix

  设置用于顶层 KML 文件名及输出目录名称的唯一前缀 [默认：GMT_Quadtree]。 所有生成的 KML 文件和图像文件将存放在该目录下。

## 可选选项

-A

-A a|g|s[altitude]

  选择 Google Earth 支持的三种高度模式之一，确定图层的高度（单位：米）： a 表示绝对高度，g 表示相对于地面的高度，s 表示相对于海底的高度。 若要固定在某一高度上绘制图层，可追加 altitude（米）。 使用 0 表示将图层贴合到参考面（如地面或海面）。 [默认：图块贴合到地面或海面。]

-C

-C[section/]master|cpt|color\(_1\),color\(_2\)[,color\(_3\),...][+h[hinge]][+i dz][+u|U unit][+s fname]

  指定主 CPT 名称，CPT 文件或用逗号分割的多个颜色， 以创建一个 CPT。如果不指定参数，则在现代模式下使用当前 CPT（如果可用）。 支持以下多种输入：

  1. 主 CPT 名称，例如 earth （详见 内置CPT ）， 可使用 CPT 名称 master 或包括相对路径的 section/master 来指定（内置 CPT 不可添加 .cpt 扩展名）。

  2. 自定义 CPT 文件 cpt ，例如 my_colors.cpt 。

  3. 自动从多个颜色 color\(_1\),color\(_2\)[,color\(_3\),...] 中创建线性连续的 CPT，其中 z 值从 0 开始， 每添加一种颜色 z 值加 1。在这种情况下， color\(_i\) 可以是 r/g/b (e.g. 255/100/75)， h-s-v (e.g. 180-0.8-1)， c/m/y/k (e.g. 80/50/40/30)，HTML十六进制 (e.g. #aabbcc) 或 颜色名称。逗号之间不能有空格。

  支持以下选项：

  - +h - 对于有软铰链 (soft hinge) 的主 CPT，可指定 hinge 值启用铰链， 而对于有硬铰链 (harde hinge) 的 CPT，可以修改铰链位置 hinge ，但不能禁用。

  - +i - 指定 dz 使网格 z 值范围分层，默认使用精确范围。

  - +s - 将创建的 CPT 保存到文件 fname。当 CPT 是自动创建时这很有用， 但必须用于 `-C` 的末尾。

  - +u - 对于任何其他主 CPT，可以通过指定其原始单位 unit 将其 z 值单位转换为米。

  - +U - 与 +u 类似，但是将 z 值单位从米转换为指定单位 unit 。

-E

-E URL

  若不希望将所有文件保存在本地，可指定远程站点的 URL 作为前缀。 生成的顶层 prefix.kml 文件将通过该 URL 查找其引用的文件。 构建完成后，需将整个 prefix 目录上传到该远程地址。 这样，你可以通过邮件或下载方式分享 prefix.kml， 用户在 Google Earth 中打开后将自动从远程服务器加载所需文件。

-F

-F filtercode

  指定用于网格降采样的滤波器。 可选： b （Boxcar 方窗）、 c （余弦弓形）、 g （高斯） 、 m （中值）[默认：Gaussian]。 滤波宽度会自动随四叉树层级调整。

-H

-H scale

  设置传递给 psconvert 的亚像素平滑尺度，以提高光栅化质量 （等同于 psconvert 的 -H 选项）[默认无平滑]。 当未使用 `-W` 时，该选项被忽略。

-I

-I[file|intens|+a azimuth][+d][+m ambient][+n args]

  增加光照效果 [默认不做照明]。可使用多种方法：

  - 给定一个 Z 值范围为 ±1 的网格文件 file ，要求和输入网格相同配准。

  - 给定一个常数 intens 作为全局光照强度 （会影响环境光）。

  - 通过调用 grdgradient 模块，设置子选项，从输入网格 grid 中计算光照强度。此时可指定 +a azimuth, +n args 和 +m ambient 传入 grdgradient 模块的 -A, -N 和 -E 选项， 或直接指定 +d 使用默认值 [+a-45+nt1+m0]。对于具体的光照场景，建议先单独运行 grdgradient 。

  如果希望从另一个文件而非输入网格中计算光照强度，则可将该文件指定为 file 然后设置合适的子选项。 如果输入文件 grid 实际是一个图片，则必须指定 file 或 intens ，因为无法从图片中计算导数作为光照强度。

-L

-L tilesize

  设置图块的固定尺寸。必须为 2 的整数幂。 常用值：256 或 512 [默认 256]。 注意：对于全球网格（即经度范围为 360° 的数据），若未指定 `-L`， 则自动设置 tilesize = 360。

-S

-S[extra]

  增加超出原数据分辨率所需的额外层级 [默认无]。 这样 GMT 将通过插值生成更高分辨率的图块，而不是让 Google Earth 自行插值。

-T

-T title

  设置顶层文档的标题（即其描述信息）。

-V

-V[level]

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

-W

-W cfile|pen[+s scale/limit]

  提供一个包含等值线值与画笔样式的文件，用于在影像上叠加等值线 [默认无等值线]。 因此，使用 `-W` 时图块将通过 PostScript 渲染生成，速度较慢。 若 cfile 无效，则认为输入为 pen，并依据 `-C` 所定义的 cpt 自动绘制等值线。 等值线通过 grdcontour 绘制。 注意：画笔宽度指的是最高分辨率图块的宽度； 对于低一层的图块，其宽度按比例 scale [默认 sqrt(2)] 缩减。 若缩放后宽度小于 limit [默认 0.1] 点，则跳过该等值线 （除非画笔宽度为 0 或 “faint”）。 可通过 +s 修改这些值。

-f

-f[i|o]colinfo

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

-n

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

  设置网格文件的插值方式。 (参数详细介绍)

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## 距离单位

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

## 四叉树构建

输入网格必须在经纬度方向上具有相同间距。若不满足此条件，可使用 grdsample 预处理。 我们通过 grdcut 扩展网格，使其形成可被连续二等分的正方形区域， 直到图块尺寸与原始网格分辨率相当。 对于全球网格（经度范围 360°），我们扩展至 360×360 的笛卡尔区域， 初始分辨率为 1°，这是第一个全局图块。 随后不断四分网格并减半分辨率，直到接近原始间隔。 对于局部或区域性网格，我们将其扩展至 tilesize × 网格间隔的 2 的整数倍。 仅输出含有非 NaN 数据的图块。 所有图块均为像素注册。 若输入为网格线注册，则在降采样时我们将其转换为像素注册网格， 并将滤波宽度乘以 sqrt(2)。 若检测到某图块中存在 NaN 值，则输出透明 PNG 图块； 否则输出不透明 JPG 图块。

## 轮廓叠加

由于每个图块的像素尺寸固定（如 512×512 像素）， 但每层级代表的数据量随层级增加而变化（每层×4）， 因此无法在所有层级使用相同厚度的等值线笔宽。 输入的画笔宽度应视为最高分辨率层的宽度。 由于生成的图像分辨率（dpi）比常规 GMT 图低得多， 建议使用亚像素平滑（ `-H` ）以改善等值线外观。 生成 PostScript 图块及平滑处理均会显著增加计算时间。

## 备注

光照强度网格可通过 grdgradient 从数据网格生成， 并可使用 grdmath 或 grdhisteq 进一步处理。 若使用多个不同光照角度的强度网格，可通过 grdmath 合并。 对于单一光照角度，也可使用自动光照模式。

## 示例

注: 下面是该模块的一些有效语法示例。使用远程文件（文件名以 `@` 开头）的示例可以剪切并粘贴到您的终端中进行测试。其他需要输入文件的命令只是常见的使用类型的虚拟示例，但不能按编写的原样运行。

若要测试低分辨率地形网格 earth_relief_06m 的四叉树影像表示， 使用自动配色及合适标题，可执行:

    gmt grd2kml @earth_relief_06m -NEarth6m -T"Earth Relief 6x6 arc minutes" -Cearth

若要对大型地形网格 ellice_basin.nc 生成四叉树影像， 自动根据地形生成阴影，使用 512×512 图块，设置标题， 并对无数据区域使用颜色遮罩，可执行:

    gmt grd2kml ellice_basin.nc -I+d -Nellice -L512 -T"Ellice Basin Bathymetry"

## 相关模块

gmt2kml, grdgradient, grdhisteq, grdimage, grdmath, grdsample, kml2gmt, psconvert