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

# plot3d

官方文档:

  plot3d

简介:

  在3D视角图中绘制符号、线段或多边形

从文件或标准输入读取至少 (x, y, z) 三列数据，并在 3D 空间中绘制线条、多边形或符号。 如果选择了符号但未指定符号大小，则将第四列数据解释为符号大小。符号大小小于或等于 0 的数据将被跳过。 如果未指定符号，则输入数据的最后一列必须包含符号代码（参见下方 `-S` 选项）。 如果未使用 `-S` 选项，将绘制连接数据点的线条。要显式闭合多边形，请使用 `-L` 选项。 使用 `-G` 选择填充颜色。如果设置了 `-G` ，`-W` 将控制是否绘制多边形的边框。 如果选择了绘制符号，`-G` 和 `-W` 分别决定填充颜色和是否显示边框。

## 语法

gmt plot3d [ table ] `-J` parameters `-Jz|Z` parameters `-R` west/east/south/north[/zmin/zmax][+r][+u unit] [ `-A`[x|y] ] [ `-B`[p|s]parameters ] [ `-C` cpt ] [ `-D` dx/dy[/dz] ] [ `-G` fill|+g|+z ] [ `-H`[scale] ] [ `-I`[intens] ] [ `-L`[+b|d|D][+xl|r|x0][+yl|r|y0][+p pen] ] [ `-N` ] [ `-Q` ] [ `-S`[symbol][size][/size_y] ] [ `-U`[stamp] ] [ `-V`[level] ] [ `-W`[pen][attr] ] [ `-X`[a|c|f|r][xshift] ] [ `-Y`[a|c|f|r][yshift] ] [ `-Z` value|file[+t|T] ] [ `-a` flags ] [ `-bi` binary ] [ `-di` nodata[+c col] ] [ `-e` regexp ] [ `-f` flags ] [ `-g` gaps ] [ `-h` headers ] [ `-i` flags ] [ `-l` flags ] [ `-p` flags ] [ `-qi` flags ] [ `-t` transp ] [ `-w` flags ] [ `-:`[i|o] ] [ --PAR=value ]

## 输入数据

table

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

## 必须选项

-J

-J projection

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

-Jz|Z

-J z|Z parameters

  绘制三维图时，设置垂直方向 Z 轴的线性投影尺度。 参数用法与 -Jx|X 相同。

-R

-R west/east/south/north[/zmin/zmax][+r][+u unit]

  指定数据范围。对于三维透视图（-p 选项） ，可以加上 /zmin/zmax 指定Z轴的范围。 (参数详细介绍)

## 可选选项

-A

-A[x|y]

  不使用本选项的默认情况下，地理坐标点之间会使用大圆弧连接。如果使用本选项则改为直接用直线相连。 笛卡尔坐标点无论是否使用本选项都直接用直线相连。 使用附加选项可以绘制阶梯曲线：

  - x ：绘制阶梯曲线，先沿 x 方向，再沿 y 方向。

  - y ：绘制阶梯曲线，先沿 y 方向，再沿 x 方向。

  x 和 y 的含义如下：

  - 对于笛卡尔投影，x 和 y 分别为 X 轴和 Y 轴。

  - 对于地理投影，x 和 y 分别为纬线和经线。

  - 对于极坐标投影，x 和 y 分别为方位角和半径。

  注意：在 plot3d 中，本选项要求 z 坐标固定不变。

-B

-B parameters

  设置底图边框和轴属性。 (参数详细介绍)

-C

-C[[section/]master_cpt[+h[hinge]][+u|U unit]|local.cpt|color\(_1\),color\(_2\)[,color\(_3\),...]]

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

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

  2. 自定义 CPT 文件 cpt ，例如 local.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 ，但不能禁用。

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

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

  注意 - 对于 +u|U，必须从 e|f|k|M|n|u 中选择一种单位。

> 本选项可以使符号和多边形的填充颜色、线段和多边形的线条颜色由 Z 值决定。

> 1. 若绘制符号（即使用 `-S` 选项），则符号的填充色由数据的第四列 w 决定， 其他数据列依次后移一列。绘制多波段 3D 柱体时除外，每个波段的颜色均取自 CPT 中的各个切片。

> 2. 若绘制线段或多边形（即未使用 `-S` 选项），则需要在多段数据的数据段头记录中指定 `-Z` val (参见 数据段头记录中的额外属性 )。CPT文件中 val 所对应的颜色， 即为线段或多边形的颜色。

-D

-D dx/dy[/dz]

  将绘图符号或线的位置按指定的偏移量 dx/dy[/dz] 偏移 [默认无偏移]。 可以为每个值附加尺寸单位，例如 c （厘米）、i （英寸）或 p （点）。

-G

-G fill|+g|+z

  设置符号或多边形的填充颜色或图案 [默认不填充]。 本模块会在头段记录中搜索 `-G` 和 `-W` 选项，并覆盖对应选项的设置。 如果头段记录中有 `-Z` val 选项，使用 -G+z 通过 `-C` cpt 和 val 值来分配填充颜色（如果通过 `-Z` 设置了透明度，处理方式相同）。 如果 fill = auto[-segment] 或 auto-table，将循环使用由 COLOR_SET 定义的填充颜色，并按段或按表进行更改。任何 transparency 设置保持不变。

  使用 +g 启用多边形的基于顶点的颜色渐变（使用 Gouraud 着色）。会自动检测输入数据格式，并支持以下三种格式：

  1. RGB 格式：x y z r g b，其中 RGB 值的范围为 0-255。

  2. 颜色名称格式：x y z colorname，其中 colorname 可以是颜色名字（如 "red"、"blue"）、十六进制颜色（如 "#FF0000"）、斜杠分隔的 RGB（如 "255/0/0"）、H-S-V 或 C/M/Y/K 格式。

  3. CPT 格式：x y z value，其中 value 值通过 `-C` 指定的 CPT 映射为颜色。

  支持具有任意数量顶点的多边形，并使用从第一个顶点开始的扇形三角剖分自动进行三角化。 每个顶点都有自己的颜色，Gouraud 着色会在多边形面上创建平滑的颜色渐变。使用 `-W` 为渐变多边形添加轮廓。

-H

-H[scale]

  从数据中读取 scale 列，对每一条记录的符号大小和画笔宽度进行缩放。 scale 列为 w 和 size 列之后的第一个数据列。 也可以指定一个固定的 scale 数值进行统一缩放。

-I

-I intens

  使用提供的 intens 值（在 \(\pm 1\) 范围内），通过模拟光照来调节填充颜色 [默认无光照]。 如果未提供光照强度值，将从符号参数之后的第一个数据列中读取 intens。

-L

-L[+b|d|D][+xl|r|x0][+yb|t|y0][+p pen]

  强制闭合多边形。或者附加以下选项从线段构建多边形：

  - +d - 使用额外的第 3 列中提供的偏差值 dy(x)，围绕 y(x) 构建对称包络。

  - +D - 使用额外的第 3-4 列中的偏差值 dy1(x) 和 dy2(x)，围绕 y(x) 构建非对称包络。

  - +b - 使用额外的第 3-4 列中提供的边界值 yl(x) 和 yh(x)，围绕 y(x) 构建非对称包络。

  - +x - 将首点和末点连接到锚点 xmin （附加 l ）、 xmax （附加 r ）或 x0 （附加 it ）。

  - +y - 将首点和末点连接到锚点 ymin （附加 b ）、 ymax （附加 t ）或 y0 （附加 it ）。

  这些多边形可以通过 `-G` 着色，并可通过添加修饰符 +ppen 来描边 [默认无描边]。

  注意： 如果数据段头使用了 `-Z` 选项，则需要使用 `-L` 以确保数据被解释为多边形，否则它们将被视为线段。

-N

-N[c|r]

  不要裁剪落在地图边界外的符号 [默认仅绘制坐标严格位于地图边界内的点]。 对于周期性（360 度经度）的地图，若符号出现在重复边界上，则会被重复绘制两次，以防它们被重复的边界裁剪。

  - 使用 -N 可关闭裁剪，并且不绘制重复的符号。

  - 使用 -Nr 可关闭裁剪，同时保留重复符号的绘制。

  - 使用 -Nc 可保留裁剪，但关闭重复符号的绘制。

  本选项也可以用于线或多边形，但请注意，这会导致不再考虑周期性（例如经度），并可能产生意想不到的后果。

-Q

-Q

  关闭基于与观察者距离的自动排序。默认情况下，会对项目进行排序，使前景中的项目在背景中的项目之后绘制。

-S

-S[symbol][size]

  本命令可以绘制所有 plot 命令支持的二维符号，但注意在视觉效果上仅仅是从三维视角观察平面符号。 例如只能绘制出三维视角观察的平面圆点，而无法绘制一个三维球体。

  此外还支持以下真正的三维符号绘制:

  立方体和柱体符号都是 3D 的，其颜色可以根据视角进行调节（小写 u 和 o），也可以为统一颜色（大写 U 和 O）。柱体还可以通过 +v|i 修饰符表示多波段符号。

  -So size[c|i|p|q][+b|B[base]][+v|i nz]

    柱体（3D）从基底延伸到 z 坐标。 size 设置基底宽度（如果 xsize 和 ysize 不相同，则分别使用它们）。 可以用 xsize 和 ysize 作为两个额外的数据列。默认情况下，基底 base 为 0。附加 +b base 来更改此值。 如果未附加 base ，则从最后一列输入数据中读取该值。如果柱体的高度是相对于基底来测量的，请使用 +B[base] [相对于原点]。 为了模拟阴影，面颜色将会修改。使用 -SO 来禁用 3D 照明。 通常情况下，只有一个 z 值会被考虑。对于多段柱体，可以附加 +v nz （并输入相对于基底的 nz 个完整的 z 值）， 或者附加 +i nz （并提供 nz 个增量 dz ，这些增量的总和为实际的 z 值）。 多段柱体修饰符需要 `-C`，其 z 值必须等于波段号（0, 1, …, nz-1），以分配段颜色。 因此，输入记录可以是 (x y z1 z2 … zn) 或 (x y dz1 dz2 … dzn)。

  -Su size[c|i|p|q]

    绘制三维立方体。size 参数设定所有边的长度。如果 size 是以 x 单位表示的数量，则在后面添加 q [默认使用绘图距离单位]。 立方体各个面的颜色会被调整以模拟阴影效果。使用 -SU 可以禁用三维光照效果。

  -SP size[c|i|p][+a azimuth][+e elevation][+f][+n]

    直径为 size 的三维球体 [默认单位为 c (cm)]。球体通过径向渐变进行渲染，颜色从光源处的白色过渡到另一侧的填充色，从而产生三维视觉效果。 可附加以下选项：

    - +a azimuth - 设置光源方位角 [默认值：0，从右侧照射]。

    - +e elevation - 设置光源仰角 [默认值：90，垂直于观察平面]。

    - +f - 使用扁平/恒定填充色（无渐变着色）。

    - +n - 仅绘制轮廓（无填充）。

    轮廓画笔属性由 `-W` 控制。如果未通过 `-G` 指定填充色，球体默认为灰色。

-U

-U[label][+c][+j just][+o dx/dy]

  在图上绘制GMT时间戳logo。 (参数详细介绍)

-V

-V[level]

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

-W

-W[pen][attr]

  设置线条或符号轮廓的画笔属性 [默认值： width (宽度) = 0.25p， color (颜色) = 黑色， style (样式) = 实线]。可以使用以下修饰符来改变线条的外观：

  - +c ：将从 cpt 文件查找的颜色应用到符号或填充。添加 l 表示线条颜色将从 CPT 获取(参见 `-C`)。 如果添加 f，则 cpt 文件中的颜色将应用于符号填充。如果未给出参数，则颜色同时用于画笔和填充。

  - +o ：添加 offset[unit]，将在距离端点给定 offset 距离处开始和停止绘制线条。 添加 c | i | p 中的一个 unit 表示地图上的绘图距离偏移，或者添加地图距离单位[默认是笛卡尔距离]。 如果线条的起点和终点需要不同的偏移量，请将 offset 写作 b_offset/e_offset 的形式。

  - +s ：使用贝塞尔样条绘制线条[默认是线性样条]。

  - +v ：给定 [b|e]vspecs，在线条端点添加矢量箭头。在前面添加 b (起点)或 e (终点)可以仅在一端添加矢量[默认对线条两端都添加]。 注意：由于 +v 可能需要额外的修饰符，因此它必须放在画笔规格的最后。更多关于此类修饰符的信息，请参见矢量属性。

  - +z ：如果设置了 `-Z`，则通过 `-C` cpt 和获得的 value 值分配画笔颜色(如果通过 `-Z` 设置透明度也是如此)。

-X

-Y

-X[a|c|f|r][xshift[u]]

-Y[a|c|f|r][yshift[u]]

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

-Z

-Z value|file[+t|T]

  控制线条和多边形的颜色或透明度。本选项需要使用 `-C` 指定cpt，然后选择以下两种模式之一：

  1. 添加一个 value，颜色通过 CPT 查找。

  2. 提供一个文件 file 的名称，该文件为输入数据中的每个多边形或线条提供一个 value 值(从最后一列读取)。

  控制颜色需要和 `-G` 或 `-W` 一起使用：

  - -G+z ：控制多边形填充颜色

  - -W+z ：控制线条颜色

  以下两个附加参数可用于处理透明度和/或颜色：

  - +t ：改为控制多边形或线条的透明度。 value 值将被假定为 \(0\text{-}100\%\) 范围内的透明度。

  - +T ：通过 file 提供两列数据：最后一列必须是 value 值，而倒数第二列为透明度（范围为 \(0\text{-}100\%\)）。

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

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

> 如果使用了 `-S` 选项则本选项无效。

-h

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

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

-i

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

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

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

  为当前绘制的符号或线段增加一个自动图例记录。 (参数详细介绍)

-qi

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

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

-p

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

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

-t

-t[transp]

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

-w

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

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

-:

-:[i|o]

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

-^ 或 -

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

-+ 或 +

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

-? 或无参数

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

--PAR=value

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

## 距离单位

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

## 自动图例

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

## 输入数据格式

`-S` 选项决定了输入数据需要哪些数据列，如果在选项中未给出参数 size ，则数据中需要 size 列。 此外，使用 `-H` 、 `-I` 和 `-t` 选项都需要给出各自的数据列。 无论选项顺序如何，数据列的顺序都是固定的:

    x y z [w] [size] [scale] [intens] [transp [transp2]] [trailing-text]

其中括号中的项是可选的，并受所述选项控制：

- `-C` 选项需要 w 列，在 CPT 文件中查找颜色。

- `-S` 选项不指定参数则需要 size 列。取决于选定的符号，可能需要不止一列。

- `-H` 选项不指定参数则需要 scale 列。

- `-I` 选项不指定参数则需要 intens 列。

- `-t` 选项不指定参数则需要 transp 列。

- 尾随文本 trailing-text 总是可选的。

注 ：(1) 如果 `-S` 未指定具体的符号类型 symbol ，则 symbol 应位于尾随文本 trailing-text 的开头。 (2) 可以使用 `-i` 重新排列数据记录以匹配预期的格式。

## 示例

在三维空间(0-10)、(0-10)、(0-100)的投影上，按照 heights.xyz 文件中列出的位置绘制蓝色柱状图(宽度 = 1.25 厘米)， 刻度间隔分别为 2、2、10，从东南方向以 30 度仰角进行观察:

    gmt plot3d heights.xyz -R0/10/0/10/0/100 -Jx1.25c -Jz0.125c -So1.25c \
              -Gblue -Bx2+lXLABEL -By2+lYLABEL -Bz10+lZLABEL -B+t"3-D PLOT" -p135/30 \
              -U+c -W -pdf heights

根据 level 值 65，使用 t.cpt 文件指定的颜色和轮廓来绘制一个点:

    echo 175 30 0 | gmt plot3d -R150/200/20/50 -JM15c -B -Sc0.5c -Z65 -G+z -Ct.cpt -pdf map

## 社区绘图示例

绘制三维地形图, 绘制三维有限断层模型

## 官方绘图示例

https://docs.generic-mapping-tools.org/latest/gallery/ex10.html

    #!/usr/bin/env bash
    #               GMT EXAMPLE 10
    #
    # Purpose:      Make 3-D bar graph on top of perspective map
    # GMT modules:  coast, text, plot3d, legend, makecpt, math
    #
    gmt begin ex10
            gmt coast -Rd -JQ0/37.5/20c -Sazure2 -Gwheat -Wfaint -A5000 -p200/40
            gmt makecpt -Cpurple,blue,darkgreen,yellow,red -T0,1,2,3,4,5
            gmt math -T @languages_10.txt -o0:2 -C2 3 COL ADD 4 COL ADD 5 COL ADD 6 COL ADD = \
                    | gmt text -p -Gwhite@30 -D-0.6c/0 -F+f30p,Helvetica-Bold,firebrick=thinner+jRM+z
            gmt plot3d @languages_10.txt -R-180/180/-90/90/0/2500 -JZ6c -So0.75c+Z5 -C -Wthinner \
                    --FONT_TITLE=30p,Times-Bold --MAP_TITLE_OFFSET=-2c -p --FORMAT_GEO_MAP=dddF \
                    -B -Bza500+lLanguages -BWSneZ+t"World Languages By Continent"
            gmt legend -JZ -DjLB+o0.5c+w3.5c/0+jBL --FONT=Helvetica-Bold \
                    -F+glightgrey+pthinner+s-4p/-6p/grey20@40 -p @legend_10.txt
    gmt end show