数据标签工具(Data Label Utilities)

1. 引言

数据标签工具(Data Label Utilities)本身不参与计算，主要用来在图形上显示用户定义的数据，增强图形的可视化功能。这个笔记简要总结了数据标签工具相关的命令和FISH函数。

2. Data Label命令

Data Label命令共有5个，这些命令在FLAC3D/3DEC/UDEC中通用，它们分别是：

(1) data label create

这个命令在空间的一个点上创建一个用户定义的标签。这些标签可以通过绘图逻辑进行可视化，确定感兴趣的区域。默认情况下，一个标签在原点是一个空字符串，没有箭头或线条。下列关键字可用于为创建的标签赋值：

【1】position v1

指定标签原点位置，如果不指定，标签的位置位于(0,0,0)。

【2】text s

将标签的文本设置为s，该文本将在上述v1定义的位置输出到屏幕上。

【3】end v2

如果指定终点与v1不同，那么标签将包括一个从v1到v2的线。本来以为这是一条(v1,v2)的连线，但结果不是，只是一条小的线段。

【4】arrow b

这是一个布尔操作，指定连接v1和v2的线是否以箭头结束。这只适用于已经指定结束的情况。

【5】name s

为标签指定一个唯一的名称，以便以后参考。如果不指定，则会生成一个基于内部分配的ID号的名称。 

model newzone create brick size 1 2 1data label create position (0,0.5,1) text 'Left Arrow' end (1,0.5,1) arrow on name 'left'data label create position (1,0.5,1) text 'Right Arrow' end (0,0.5,1) arrow on name 'right'

(2) data label delete

data label delete <name s > <range>

删除指定范围内的所有标签。可以选择用name关键字删除单个标签。'The label with name right has been deleted.'

data label delete name 'right'

(3) data label list

data label list <name s >

这个命令列出标签信息。如果指定了可选的关键字name，那么只列出该标签的信息。否则列出所有标签的信息。这个命令可用来检查标签的坐标和箭头状态(on/off)，非常有用。

(4) data label modify

这个命令修改一个现有的标签。必须使用关键字name来确定要修改的现有标签。关键字与data label create完全相同。

(5) data label results

data label results active b

布尔操作，在结果文件中包括标签数据，默认值是off.

3. Data Label Fish

date label的FISH函数比其命令提供了更广泛的操作和控制。这些FISH函数可以分为三类：不带参数传递，矢量和字符串传递以及标签指针传递。

3.1 不带参数传递

下面这些FISH不带参数传递

(1) [dlh = data.label.head] (指针)

获取全局标签列表的头(head), 使用data.label.next结构来遍历列表。head是旧的FISH语言的写法，目前这个函数还在使用，估计以后会取消。

(2) [dll = data.label.list] (指针)

获取全局标签列表，使用循环foreach结构来迭代该列表。

(3) [dlm = data.label.maxid] (整型)

获取最大的标签ID。

(4) [dln = data.label.num] (整型)

获取标签的数量

(5) [dlt = data.label.typeid] 

获取标签类型ID号。类型ID可以用来唯一地识别标签FISH指针，并将其与任何其他类型的FISH指针区分开来。  

3.2 矢量和字符串传递

(1) data.label.find(INT/STR)

查找一个标签。如果该标签不存在，就会创建一个新标签。

[dlf = data.label.find(2)][dl_name = data.label.name(dlf)]

这个函数返回标签的指针。测试显示，对于整型数能够成功返回，但对于string name, 显示“Unable to convert parameter type from String to Pointer.” 不知道什么原因。
(2) data.label.create(VEC<,INT/STR>)

在位置VEC创建一个新的标签，INT/STR为可选的整数或字符串名称，如果没有给出，将分配给下一个可用的ID。

[v1 = gp.near(0,0,1)][v = gp.pos(v1)][lp = data.label.create(v,'wxc')][data.label.text(lp) = 'middle']

3.3 指针传递

带有指针传递的函数共有7个，其含义与命令的含义相同。

(1) data.label.arrow(UDL_PNT)

(2) data.label.delete(UDL_PNT)

(3) data.label.end(UDL_PNT)

(4) data.label.name(UDL_PNT)

(5) data.label.next(UDL_PNT)

(6) data.label.pos(UDL_PNT)

(7) data.label.text(UDL_PNT)

下图所示的是显示每个单元的ID：

loop foreach z zone.list        v = zone.pos(z)        lp = data.label.create(v)        data.label.text(lp) = zone.id(z)endloop

如果要显示网格点的ID，只需使用gp.list, gp.pos, gp.id代替上面的zone.list, zone.pos, zone.id即可。