一、圖觀統一開發API概述
圖觀統一開發 API 是一套基于 JavaScript 語言開發的二次編程接口,用于在現代瀏覽器中加載、顯示圖觀引擎提供的流渲染或端渲染三維場景,并且為開發者提供在場景中繪制業務數據、觸發場景交互、控制場景邏輯的功能。圖觀統一開發 API 兼容當前主流的 JavaScript 前端框架,例如 Vue.js 或者 React,前端開發人員可快速便捷的進行二次開發。
- 雙渲染技術架構
圖觀的渲染核心有流渲染和端渲染兩種。對于TGAPI的二次開發接口是一致的。這里簡單介紹兩種渲染核心的技術架構。
流渲染
圖觀 流渲染開發架構,是基于實時云渲染( GPU 云化)、視頻串流等技術,整合推出可視化數字孿生流渲染解決方案技術支撐體系,涵蓋:流渲染服務平臺、流渲染二次開發等技術產品,為大規模場景渲染在輕量化終端上的呈現提供技術保障。
流渲染系統架構如下圖所示:

端渲染
圖觀 端渲染開發架構,是基于 HTML5 和 WebGL 技術,整合推出的數字孿生端渲染技術支撐體系,涵蓋端渲染場景編輯器、端渲染服務平臺、端渲染二次開發等技術產品,覆蓋數字孿生應用開發的全生命周期,提供簡便、快捷、強大的數字孿生應用運行和開發平臺。
端渲染系統架構如下圖所示:

- 圖觀引擎場景和二次開發效果速覽
流渲染效果速覽

端渲染效果速覽

3.TGAPI接口體系
TGAPI 3.3正式發布的版本,共有接口總數500多個,其中方法數量200多個、事件數量300多個。
4.TGAPI方法指令范式
TGAPI除了構造應用使用的new TGApp.app()和初始化服務appInstance.initService()兩個接口以外,都是使用appInstance.uniCall(action, parameter, callback)方法來調用的,第一個參數為指令名稱,第二個參數為指令參數,第三個參數為回調函數。
5.TGAPI指令回調結果
每個uniCall的指令調用,在第三個參數都包括一個callback回調函數?;卣{函數的結果,通過一個Object類型的對象返回。
- TGAPI事件訂閱
如上方提到的,TGAPI的事件訂閱指令為addEventListener, 參數對象中包括了eventName和一個回調函數callback,其中eventName是需要監聽的事件,callback為事件觸發時執行的方法。同一個事件,可以監聽多次,執行不同的方法。
對應的,取消事件訂閱指令為removeEventListener,可以移除指定事件和回調函數的對應關系。
在圖觀統一開發API中,事件的總數量甚至是比接口指令的數量都要多。掌握好事件監聽,能夠接收和處理事件的回調消息,對于二次開發好一個應用具有特別重要的意義。特別是對于需要和場景進行交互,感知場景狀態,獲得場景中無接口調用信息,通過場景觸發或者用戶交互觸發的消息的功能開發。在后面還會詳細說到一些事件的具體用法。
二、統一接口調試器
在本章教程中,我們主要講解圖觀統一開發API的輔助調試工具圖觀統一接口調試器。
1.接口調試器優勢
圖觀統一接口調試器主要有以下功能優勢:
-
圖觀統一接口調試器內置了一套最新的圖觀統一開發API,全部的代碼可以脫離接口調試器,在TGAPI SDK中單獨運行。
-
可以幫助開發者省去使用程序開發IDE搭建環境、運行程序的繁瑣步驟,在線輕松的測試圖觀已經發布的場景。
-
內置大量的TGAPI標準功能測試代碼,可以在您的場景中默認執行。其代碼片段亦可作為您的開發手冊進行查閱,并復制到您的工程代碼中。
-
提供繪制功能,可以在加載的圖觀場景中標繪點、線、面數據,獲得基于場景真實坐標,并且導出數據。
-
提供生成模擬代碼功能,可以根據您的標繪點線面數據,生成模擬的圖觀統一開發API中的圖層數據,生成代碼。解決您在沒有真實數據時,開發項目需要生成模擬數據的苦惱。
-
綜合測試功能可以保存您的測試代碼,或者生成的模擬代碼,以備后續調用。
2.創建調試場景
2.1預先條件
如果您準備使用圖觀統一接口調試器加載練習場景,需要具備以下硬件和軟件的條件。
硬件
8G內存,有獨立顯卡,NVIDIA GTX 960及以上的筆記本或者臺式機。
軟件
操作系統:Windows,MacOS,Linux均可
推薦使用Google Chrome 瀏覽器,版本88及以上(2021年1月之后版本),或者Microsoft Edge 版本88及以上、360瀏覽器版本13及以上
如需查看自己的Google Chrome瀏覽器版本,您可以在瀏覽器地址欄中輸入 chrome://settings/help,或者點擊菜單 -> 設置 -> 關于Chrome

2.2登錄圖觀打開接口調試器
打開谷歌瀏覽器,輸入圖觀網址http://www.hhhhh10086.cn并訪問,我們就進到了圖觀的官網點擊官網導航欄右側的 登錄 按鈕,看到了登錄界面,輸入已開通好的賬號和密碼后點擊 登錄。進到了圖觀業務管理界面,在“我的業務”中有“租戶服務”、“端渲染場景服務”、“接口調試器服務”、“應用編輯器服務”4種服務,我們選擇“接口調試器服務”點擊 前往 按鈕。

進入接口調試器首頁
2.3 接口調試器首頁介紹
進入到接口調試器的首頁頁面, 頁面左側是 場景管理列表,在這里我們可以對我們所有場景進行分類整理,便于我們后續查找。中間Tab欄切換 工作臺 和 案例庫,工作臺 可新建場景并展示所有已創建場景;案例庫 中的案例可以進行預覽到導入到自己的工作臺。頁面右上顯示公告,幫助及用戶設置。

2.4.創景場景“智慧社區”
點擊“新建場景”,將會彈出“新建場景”對話框。
場景類別選擇默認“端渲染”,場景名稱中輸入中文名稱“智慧社區”,場景鏈接輸入http://www.hhhhh10086.cn/api/sceneEditor/v1/scenes/ed402a51-a00a-48f2-8b60-f51963440e82/loadAVWS,點擊“確定”按鈕即可完成項目的創建。

鼠標懸停在場景面板上可以喚醒隱藏的功能菜單,我們可以對該場景進行“重命名”、“移動”、“復制”、“刪除”。現在我們點擊 編輯 按鈕,打開該場景。

2.5.場景首頁介紹
進入場景首頁后,可以看到:

界面上方是“單體測試”和“綜合測試”切換按鈕。
2.6 單體測試功能介紹
2.6.1單體測試介紹

在單體測試中,界面主要位置顯示的是需要調試的三維場景,場景上疊加有工具欄,工具欄的功能后續會有相應介紹。
2.6.2. 使用場景對象
在場景對象中,如果您選中了一個模型節點,將會在“模型”代碼執行的時候使用這個模型ID。

2.6.3. 使用圖層對象
如果場景已經設置好了基準點,對應了場景和經緯度信息,在圖層對象中的所有圖層測試數據都會自動圍繞著這個場景中心點的經緯度來模擬生成。
在全局對象中選中“其他控制”,點擊“獲取當前基準位置”,并執行代碼,可以在下方看到本場景已經設置了經緯度基準點,如果所示。

2.7繪制和模擬生成代碼
在二次開發場景過程中,會經常遇上在場景內獲得點位、鏡頭信息甚至是生成模擬數據的需求,這些在接口調試器中都有對應的功能。
2.7.1.獲取場景點位和鏡頭信息
如果只是獲取單個點位和鏡頭信息,最快速的方法是使用工具欄的【獲取經緯度】和【獲取當前視角參數】功能。

2.7.2 繪制
工具欄上的第三個和第四個按鈕,是非常重要的功能,這里先介紹第三個 繪制 按鈕。
進入到繪制功能之前,請先使用 設置 功能,進入 標繪設置 確認路線和區域的設置,特別是路線寬度和圍欄高度,這個數值的單位都是米。在不同大小的場景下,請確保這個數值不會過大或者過小造成看不到的問題。
請按照如圖所示設置數值,并點擊 確定。

區域繪制
添加

編輯
在三維場景中或者區域列表中,單擊一個已經繪制好的區域,可以進入到編輯狀態。這時,您可以通過 平移交互軸 調整整個區域位置。通過加號圖標在區域上添加一個新的關鍵點。
2.7.3生成模擬代碼
工具欄上的第四個按鈕,是非常重要的 生成模擬代碼 功能。點擊這個按鈕,會彈出 生成模擬代碼 對話框。

對話框分為三個Tab頁簽,分別是“圖層”, “模型/特效”和“視點”。每個Tab頁簽下方可以選擇更加具體的代碼類型,點擊右側的“加號”按鈕,可以生成對應類型的模擬代碼。
選中 圖層 Tab頁簽,在圖層類型中選擇 三維柱圖,然后點擊“+“按鈕。

鼠標懸浮在圖層上,可以激活圖層操作按鈕,如圖所示,功能分辨是“修改”,“添加到綜合測試”、“定位”和“隱藏”

2.8使用綜合測試

在上面最后的步驟中,我們已經來到了 綜合測試 頁面。
3.使用案例庫
在接口調試器中,為您提供了案例庫功能。使用案例庫,您可以快速瀏覽接口調試器的場景中的代碼執行,并且將您感興趣的案例導入到自己的工作臺中,繼續進行參考、編輯。

在接口調試器首頁點擊案例庫。
找到 開發教程卡通版。
點擊 預覽 按鈕,這是打開了接口調試器預覽頁面。

在新開的瀏覽器標簽頁里,左側綜合測試列出來當前場景的接口調試器內置測試代碼。
鼠標懸浮在列表項上,可以激活 查看代碼 按鈕。
點擊 查看代碼 按鈕,在右側代碼面板可以查看測試用例的詳細內容。
單擊列表項可以執行代碼。

返回到之前的案例庫頁面,找到 開發教程卡通版,鼠標點擊 導出 按鈕。
在彈出的導出對話框了,選擇一個希望導入工作臺的節點。一版選擇 根節點 也可以。
點擊 確定 按鈕。
這樣案例庫的示例工程就會出現在 工作臺 對應的節點目錄下。打開后,跳轉到 綜合測試 可以看到示例代碼功能。
在本教程后面的章節中,全部的示例代碼片段都存在于這個 開發教程卡通版 的案例工程里。所以請您在進行后面課程之前,導入到自己的工作臺中。
詳細開發教程 詳見圖觀官網:http://www.hhhhh10086.cn/doc/tg-api/?tutorial.tutorial_1