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即可。