legend
- 官方文档
- 简介
在图上添加图例
legend 模块用于绘制图例，图例由图例文件控制。如无特别说明，标注的字体由 FONT_ANNOT_PRIMARY 控制。若图例中含有中文，必须将 FONT_ANNOT_PRIMARY 设置为中文字体。
语法
gmt legend [ specfile ] -Drefpoint [ -B[p|s]parameters ] [ -Cdx/dy ] [ -Fbox ] [ -Jparameters ] [ -Rregion ] [ -Sscale ] [ -Tfile ] [ -U[stamp] ] [ -V[level] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -pflags ] [ -ttransp ] [ --PAR=value ]
必须选项
- -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing][+odx[/dy]]
指定图例框的尺寸和位置
简单介绍各子选项的含义，详情见 修饰物
g|j|J|n|x]refpoint指定地图上的参考点
+jjustify 指定图例框的锚点（默认锚点在左下角(BL)）
+odx/dy 在参考点的基础上设置图例框的额外偏移量
+wwidth[/height] 指定图例框的尺寸。若 height 为0或未指定，则根据图例内容自动估算图例框高度。
+lspacing 设置图例里的行间距 [默认值1.1，即当前字体大小的1.1倍]
该选项几个比较有用的用法是：
将图例放在左下角： -DjBL+w4c+o0.2c/0.2c
将图例放在左上角： -DjTL+w4c+o0.2c/0.2c
将图例放在右下角： -DjBR+w4c+o0.2c/0.2c
将图例放在右上角： -DjTR+w4c+o0.2c/0.2c
可选选项
- -Bparameters (more …)
设置底图边框和轴属性
- -Cdx/dy
设置图例边框与内部图例之间的空白 [默认值 4p/4p]
- -F[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
控制图例的背景面板属性
若只使用 -F 而不使用其它子选项，则绘制图例框。下面简单介绍各子选项，详细用法见 修饰物
+gfill 指定面板填充颜色 [默认不填充]
+ppen 绘制面板边框。pen 为边框的画笔属性，若不指定 pen，则默认使用 MAP_DEFAULT_PEN
+r[radius] 绘制圆角边框，radius 为圆角的半径
+i[[gap/]pen] 在边框内部绘制一个内边框，gap 为内外边框空白距离 [默认为 2p]， pen 为内边框的画笔属性 [默认使用 MAP_DEFAULT_PEN]
+cclearance 设置修饰物与面板之间的空白距离。默认情况下面板的大小由修饰物的大小决定，使用该子选项可以为面板增加额外的尺寸。 clearance 的具体设置包括下面 3 种情况：
gap 为四个方向增加相同的空白距离
xgap/ygap 分别为 X 方向和 Y 方向指定不同的空白距离
lgap/rgap/bgap/tgap 分别为四个方向指定不同的空白距离
+s[[dx/dy/][shade]] 设置面板背景阴影。dx/dy 为阴影区相对于面板的偏移量， shade 为阴影区颜色 [默认为 4p/-4p/gray50]
- -Jprojection (more …)
设置地图投影方式
- -Rxmin/xmax/ymin/ymax[+r][+uunit] (more …)
指定数据范围
- -Sscale
对图例中的所有符号大小乘以 scale [默认值为 1]
- -Tfile
将隐藏的图例文件输出到文件中 [仅适用于现代模式]
现代模式下，某些模块（如 plot）可以使用 -l 选项自动编辑一个隐藏的图例文件。在最终成图时，会根据这一图例文件绘制图例。该选项可将该隐藏图例文件的内容保存到新文件中，使得用户可以在自动图例文件的基础上做进一步自定义。
- -U[label][+c][+jjust][+odx/dy] (more …)
在图上绘制GMT时间戳logo
- -V[level] (more …)
设置 verbose 等级 [w]
-X[a|c|f|r][xshift[u]]
- -Y[a|c|f|r][yshift[u]] (more …)
移动绘图原点
- -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)
设置3D透视视角
- -t[transp] (more …)
设置图层透明度（百分比）。取值范围为0（不透明）到100（全透明）
- -^ 或 -
显示简短的帮助信息，包括模块简介和基本语法信息（Windows下只能使用 -）
- -+ 或 +
显示帮助信息，包括模块简介、基本语法以及模块特有选项的说明
- -? 或无参数
显示完整的帮助信息，包括模块简介、基本语法以及所有选项的说明
- --PAR=value
临时修改GMT参数的值，可重复多次使用。参数列表见 配置参数
图例文件格式
图例文件用于控制图例中各项的布局。图例文件中的每个记录对应图例中的一项，图例中每项的顺序由记录的先后顺序决定。每个记录的第一个字符决定了当前记录的图例类型。GMT中共有14种图例类型，列举如下：
- # comment
以 # 开头的行或空行是注释行，会被跳过
- A cptname
指定CPT文件，使得某些记录可以通过指定Z值来设定颜色，可以多次使用该记录以指定不同的CPT文件
- B cptname offset height [ optional arguments ]
绘制水平colorbar
- C textcolor
接下来的文本所使用的颜色
可以直接指定颜色，也可以用 z=val 指定Z值，以从CPT文件中查找相应的颜色（CPT文件由 A 记录指定）。若 textcolor 为 -，则使用默认颜色。
- D [offset] pen [-|+|=]
绘制一条水平线
offset 为线条左右顶端与图例边框的空白距离 [默认为0]
pen 为线条的画笔属性。若未指定 pen，则使用 MAP_GRID_PEN_PRIMARY。若 pen 设置为 -，则绘制一条不可见的线（供 V 记录使用）
默认情况下，线条上下各留出四分之一的行间距，-|+|= 分别表示线条上方无空白、线条下方无空白和线条上下均无空白。
- F fill1 fill2 … filln
指定单元的填充色。
可以直接指定颜色，也可使用 z=value 形式指定从CPT文件（由 A 记录指定）中查找颜色。若只给定了一个 fill，则整行都使用相同的填充色，否则依次为当前行的每列应用不同的 fill（列数由 N 记录控制）。若 fill 为 -，则不填充。
- G gap
给定一个垂直空白
空白的高度由 gap 决定，gap 可以用 i|c|p 单位，也可以用 l 作为单位表示几倍行距的空白，gap 也可以取负值，表示将当前行上移。
- H font|- header
为图例指定一个居中的标题。
header 为标题，font 为文字属性。若字体为 - 则使用默认字体 FONT_TITLE。
- I imagefile width justification
将EPS或光栅文件放在图例中
width 为图片宽度；justification 为图片的对齐方式。
- L font|- justification label
在某一列增加指定的文字
label 为显示的文本，font 为字体。若 font 为 - 则使用默认字体 FONT_LABEL。justification 为对齐方式，可以取 L|C|R，分别表示左对齐、居中对齐和右对齐
- M slon|- slat length[+f][+l[label]][+u] [-Fparam] [ -Rw/e/s/n -Jparam ]
在图例中绘制比例尺。
slon 和 slat 用于指定绘制哪一点的比例尺。slon 仅对特定的倾斜投影有效。对于一般投影，应设置为 -。
length 为比例尺长度，其后可以接长度单位，以及多个子选项。子选项的具体含义见 basemap 模块的 -L 选项。
若想要为比例尺加上背景面板，则可以使用 basemap 的 -F 选项。此外，还可以加上 -R 和 -J 指定比例尺所使用的投影参数。
- N [ncolumns or relwidth1 relwidth2 … relwidthn]
修改图例中的列数 [默认为1列]
该记录仅对 S 和 L 记录有效。该记录指定的列数会一直有效直到再次使用 N 记录。 ncolumns 用于指定若干个等宽的列，relwidth1 relwidth2 … relwidthn 用于指定每列所占的相对宽度，所有宽度的和应等于 -D 选项所设置的宽度相等。
- P paragraph-mode-header-for-pstext
在图例中添加文本段落，参考 text 命令中的段落模式
- S [dx1 symbol size fill pen [ dx2 text ]]
在图例中绘制符号
dx1 符号中心与左边框的距离。若为 - 则自动设置为最大的符号大小的一半。 dx1 除了可以指定距离，还可以使用 L|C|R 表示符号在当前列的对齐方式
size 符号大小
fill 符号的填充色。使用 - 表示不填充。fill 也可以用 z=val 的形式从CPT文件中根据Z值查找颜色
pen 符号的轮廓属性。使用 - 表示不绘制轮廓
dx2 是 text 与左边框的距离。使用 - 则自动设置为最大符号大小的1.5倍
text 是符号的文字说明，字体由 FONT_ANNOT_PRIMARY 控制
若只有 S 而不接其它任何信息，则直接跳至下一列。若 symbol 取 f q 或 v，可以在符号后加上更多的子选项，详情见 plot 模块 -S 选项。某些符号（例如矩形、椭圆等）需要指定多个 size，应将多个 size 用逗号分隔作为 size 即可。如果只给了一个 size，则其余 size 由GMT默认值决定。
- T paragraph-text
打印一段文本，字体由 FONT_ANNOT_PRIMARY 控制
- V [offset] pen
在两列之间绘制垂直的线条
offset 为线条上下两端与图例边框的空白距离 [默认为0]。
默认值
对于如下符号，若用户不显式指定属性，绘制图例时使用如下默认值：
front符号 f：front 符号位于左侧，其大小为指定符号大小的30%
矢量符号 v：箭头大小为符号大小的30%
椭圆符号 e|E：主轴长度为符号大小，次轴长度是符号大小的65%，方位角为0
矩形符号 r：宽度为符号大小，高度为宽度的65%
旋转矩形符号 j|J：宽度为符号大小，高度为宽度的65%，旋转角度为30度
圆角矩形符号 R：宽度为符号大小，高度为宽度的65%，角半径为宽度的10%
数学圆弧符号 m|M：角度在-10°-45°，箭头大小为符号大小的30%
楔形符号 w：角度为-30°到30°
示例
#!/usr/bin/env bash
gmt begin legend
gmt makecpt -Cpanoply -T-8/8/1 -H > tt.cpt
gmt set FONT_ANNOT_PRIMARY 12p
gmt legend -R0/10/0/10 -JM6i -Dx0.5i/0.5i+w5i+jBL+l1.2 -C0.1i/0.1i -F+p+gazure1+r -B5f1 << EOF
# Legend test for gmt pslegend
# G is vertical gap, V is vertical line, N sets # of columns, D draws horizontal line,
# H is ps=legend.ps
#
G -0.1i
H 24p,Times-Roman My Map Legend
D 0.2i 1p
N 2
V 0 1p
S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
S 0.1i e 0.15i yellow 0.25p 0.3i This ellipse is yellow
S 0.1i w 0.15i green 0.25p 0.3i This wedge is green
S 0.1i f 0.25i blue 0.25p 0.3i This is a fault
S 0.1i - 0.15i - 0.25p,- 0.3i A contour
S 0.1i v 0.25i magenta 0.5p 0.3i This is a vector
S 0.1i i 0.15i cyan 0.25p 0.3i This triangle is boring
D 0.2i 1p
V 0 1p
N 1
M 5 5 600+u+f
G 0.05i
I @SOEST_block4.png 3i CT
G 0.05i
B tt.cpt 0.2i 0.2i -B0
G 0.05i
L 9p,Times-Roman R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
G 0.1i
T Let us just try some simple text that can go on a few lines.
T There is no easy way to predetermine how many lines may be required
T so we may have to adjust the height to get the right size box.
EOF
rm -f tt.cpt
gmt end show
legend示例图1