1 前言

Cesium 是一個(gè)地球可視化平臺(tái)和工具鏈赔嚎，具有數(shù)據(jù)切片膘盖、數(shù)據(jù)分發(fā)、三維可視等功能尤误。

Cesium 支持 JS侠畔、Unity、Unreal损晤、O3DE软棺、Omniverse 等平臺(tái)，框架如下尤勋。

Cesium 相關(guān)鏈接如下：

• Cesium 官網(wǎng)：https://cesium.com
• CesiumLab 下載：https://www.cesiumlab.com/cesiumlab.html
• CesiumLab 手冊(cè)：https://www.cesiumlab.com/CesiumLab地理信息基礎(chǔ)數(shù)據(jù)處理平臺(tái)使用手冊(cè).pdf
• CesiumLab viewer：http://localhost:9003/viewer
• Cesium ion：https://ion.cesium.com
• cesium-unity-samples：https://github.com/CesiumGS/cesium-unity-samples
• cesium-unity：https://github.com/CesiumGS/cesium-unity
• cesium-native：https://github.com/CesiumGS/cesium-native
• Cesium for Unity Quickstart：https://cesium.com/learn/unity/unity-quickstart
• Building Cesium for Unity：https://github.com/CesiumGS/cesium-unity/blob/main/Documentation~/developer-setup.md
• Cesium實(shí)驗(yàn)室-CSDN：https://blog.csdn.net/weixin_43805235
• Cesium實(shí)驗(yàn)室-B站：https://space.bilibili.com/346212872

本文實(shí)驗(yàn)完整資源見(jiàn)→Cesium加載大地圖案例喘落。

2 環(huán)境搭建

本節(jié)主要參考 Cesium for Unity Quickstart。

1）創(chuàng)建 3D (URP) 或 3D (HDRP) 項(xiàng)目

說(shuō)明：官方建議 Unity Editor 最低版本為 2021.3.2f1最冰，筆者 Unity Editor 版本為 2021.3.11f1c2瘦棋；Cesium for Unity 可與通用渲染管線（URP）和高清渲染管線（HDRP）配合使用，但是暖哨，它不支持 Unity 的內(nèi)置渲染器赌朋，如果選擇 3D 項(xiàng)目作為模板，Cesium 加載的數(shù)據(jù)集將無(wú)法正確渲染篇裁。

2）添加作用域注冊(cè)表

依次點(diǎn)擊【Edit→Project Settings→Package Manager】沛慢，添加注冊(cè)表信息如下。

Name: Cesium
URL: https://unity.pkg.cesium.com
Scope(s): com.cesium.unity

3）下載 Cesium For Unity

依次點(diǎn)擊【W(wǎng)indow→Package Manager】打開(kāi)包管理器窗口达布，在 Packages 菜單中選擇 My Registries颠焦，下載 Cesium for Unity，如下往枣。

下載成功后伐庭， 菜單欄會(huì)多出一個(gè) Cesium 菜單，如下分冈。

4）連接到 Cesium ion

在 Cesium 窗口點(diǎn)擊 Connect to Cesium io 按鈕圾另，跳轉(zhuǎn)到 Web 網(wǎng)頁(yè)，點(diǎn)擊 Allow雕沉。

5）添加 Token

在 Cesium 窗口點(diǎn)擊 Token 按鈕集乔，添加 token，如果沒(méi)有 token，就創(chuàng)建一個(gè) token扰路，如果有 token尤溜，就使用已創(chuàng)建的 token。

6）創(chuàng)建世界地圖

在 Cesium 窗口點(diǎn)擊 Cesium World Terrain + Bing Maps Aerial imagery 添加世界地圖汗唱。

場(chǎng)景顯示如下宫莱。

如果看不見(jiàn)地圖，可能是相機(jī)的位置比較遠(yuǎn)哩罪，被裁剪了授霸，可以調(diào)整遠(yuǎn)裁剪平面的位置，如下际插。

7）添加動(dòng)態(tài)相機(jī)

屏蔽場(chǎng)景中默認(rèn)的相機(jī)碘耳，在 Cesium 窗口添加 Dynamic Camera，如下框弛。此時(shí)辛辨，在 Hierarchy 窗口可以看到 CesiumGeoreference 對(duì)象下面自動(dòng)生成了一個(gè)名為 DynamicCamera 的對(duì)象，該對(duì)象上掛了 Camera 組件瑟枫。

運(yùn)行后斗搞，可以通過(guò)鼠標(biāo)和方向按鍵控制相機(jī)位置和姿態(tài)，如下力奋。

說(shuō)明：視覺(jué)的變化通過(guò)調(diào)整 CesiumGeoreference 組件下的 Latitude 和 Longitude 屬性實(shí)現(xiàn)，如下幽七。

補(bǔ)充：讀者也可以下載 Cesium 官方 Deom 體驗(yàn)一下景殷，詳見(jiàn)→cesium-unity-samples。

3 地圖切片

本節(jié)主要介紹 fbx 文件切片流程澡屡，對(duì)于其他文件的切片猿挚，可以參考 CesiumLab地理信息基礎(chǔ)數(shù)據(jù)處理平臺(tái)使用手冊(cè)。

3.1 切片

下載并安裝 CesiumLab 后驶鹉，打開(kāi) CesiumLab 客戶端绩蜻，fbx 文件的切片如下。

在處理日志中可以查看任務(wù)是否處理成功室埋，如下办绝。如果切片失敗，可能是 fbx 文件中包含相機(jī)或燈光姚淆，使用 Blender 刪除相機(jī)和燈光孕蝉，再重新導(dǎo)出 fbx 文件。

生成的文件如下腌逢，加載切片時(shí)降淮，需要用到 tileset.json 文件。

3.2 預(yù)覽切片

在分發(fā)服務(wù)中可以查看切片搏讶，步驟如下佳鳖。

點(diǎn)擊預(yù)覽后霍殴，會(huì)跳轉(zhuǎn)到另一個(gè)網(wǎng)頁(yè)，顯示切片如下系吩。

用戶在瀏覽器中輸入：http://localhost:9003/viewer/index.html来庭，再按以下步驟添加切片，也可以預(yù)覽切片淑玫。

3.3 上傳切片到 Cesium ion

在 Cesium ion 官網(wǎng)登錄賬號(hào)后巾腕，按以下步驟上傳切片。

選擇文件后絮蒿，上傳切片尊搬。

在 My Assets 窗口可以查看已經(jīng)上傳的切片，如下土涝。

注意：第一列的 ID 在加載資源時(shí)會(huì)用到佛寿；用戶也可以將 Asset Depot 中的資源添加到 My Assets 中。

4 Unity 中加載切片

4.1 加載 Cesium ion 中切片

在 Cesium 窗口單擊 Add 按鈕但壮，在底部 Console 右邊會(huì)出現(xiàn) Cesium ion Assets 窗口冀泻，選擇地圖添加到場(chǎng)景中，如下蜡饵。

在 Hierachy 窗口雙擊 CesiumGeoreference 下面的地圖對(duì)象弹渔，使相機(jī)聚焦到地圖，地圖顯示如下溯祸，通過(guò)修改 ion Asset ID 可以加載不同地圖肢专。

4.2 加載 CesiumLab 服務(wù)中切片

在 Cesium 窗口點(diǎn)擊 Blank 3D Tiles Tileset，在 Hierarchy 窗口會(huì)生成 CesiumGeoreference 和 Cesium3DTileset 對(duì)象焦辅，選中 Cesium3DTileset 對(duì)象博杖，設(shè)置切片的 url，如下筷登。

url 來(lái)自 CesiumLab剃根，如下。

在 Hierachy 窗口雙擊 Cesium3DTileset 對(duì)象前方，使相機(jī)聚焦到地圖狈醉，地圖顯示如下。

可以看到惠险，地圖方位異常舔糖，在 4.4 節(jié)將介紹調(diào)整地圖方位的方法。

4.3 加載本地切片

將切片拷貝到項(xiàng)目目錄下的 Resources / city 目錄下莺匠。在 Cesium 窗口點(diǎn)擊 Blank 3D Tiles Tileset金吗，在 Hierarchy 窗口會(huì)生成 CesiumGeoreference 和 Cesium3DTileset 對(duì)象，選中 Cesium3DTileset 對(duì)象，設(shè)置切片的 url摇庙，如下旱物。

在 Hierachy 窗口雙擊 Cesium3DTileset 對(duì)象，使相機(jī)聚焦到地圖卫袒，地圖顯示同 4.2 節(jié)宵呛。

4.4 調(diào)整地圖方位

1）通過(guò) CesiumLab 預(yù)覽參數(shù)調(diào)整地圖

使用 3.2 節(jié)中方法預(yù)覽切片，調(diào)整好方位后夕凝，將鼠標(biāo)放在屏幕正中間宝穗，記錄底部的經(jīng)度、緯度码秉、高度逮矛，如下。

選中 CesiumGeoreference 對(duì)象转砖，設(shè)置經(jīng)度须鼎、緯度、高度為上面記錄的值府蔗，如下晋控。

在 Hierachy 窗口雙擊 CesiumGeoreference 對(duì)象，使相機(jī)聚焦到地圖姓赤，地圖顯示如下赡译。

可以看到，地圖的方位已正確顯示不铆，用戶如果對(duì)該方位還是不滿意蝌焚，在調(diào)整好視覺(jué)后，點(diǎn)擊 Place Origin Here 按鈕重置該視覺(jué)下的經(jīng)度狂男、緯度综看、高度品腹，如下岖食。

2）通過(guò) tileset 文件中 transform 參數(shù)調(diào)整地圖

在 CesiumLab地理信息基礎(chǔ)數(shù)據(jù)處理平臺(tái)使用手冊(cè) 的 2.2.2.1 節(jié) “輸出數(shù)據(jù)的空間參考” 中，我們可以看到以下公式：

其中舞吭，3dtiles 里的 transform 矩陣是指切片文件中的 tileset.json 文件泡垃，如下。

可以看到 transform 矩陣是一個(gè) 4x4 的矩陣羡鸥，并且最后一列的列向量是 [0, 0, 0, 1]'蔑穴，類似于平移矩陣的形式（平移矩陣詳見(jiàn)空間和變換中 2.1.1 節(jié)，這篇文章的變換是列向量右乘惧浴，Cesium 中是行向量左乘）存和，因此 transform 矩陣的最后一行是平移偏移量，我們將該偏移量設(shè)置到 Cesium Georeference 中，如下捐腿，地圖顯示效果同 4.4 1）節(jié)纵朋。

5 添加對(duì)象

5.1 CesiumGlobalAnchor

給場(chǎng)景中添加 DynamicCamera，并屏蔽掉 Main Camera茄袖，添加熱氣球?qū)ο蟛偃恚缦隆?/p>

運(yùn)行后，發(fā)現(xiàn)氣球跟隨相機(jī)一起運(yùn)動(dòng)宪祥，如下聂薪。

將氣球?qū)ο笠频?CesiumGeoreference 下面，并添加 CesiumGlobalAnchor 組件蝗羊，如下藏澳。

運(yùn)行效果如下，可以看到氣球?qū)ο鬀](méi)有跟隨相機(jī)一起運(yùn)動(dòng)了肘交。

5.2 參考子場(chǎng)景

選中 CesiumGeoreference 對(duì)象笆载，點(diǎn)擊 Create Sub-Scene Here 添加子場(chǎng)景，CesiumGeoreference 對(duì)象下面會(huì)生成一個(gè)掛有 CesiumSubScene 組件的對(duì)象涯呻，重命名為 Sub-Scene凉驻。

調(diào)整 CesiumSubScene 組件中的 Activation Radius、Latitude复罐、Longitude涝登、Height 屬性，如下效诅。Latitude胀滚、Longitude、Height 確定了子場(chǎng)景的中心乱投，Activation Radius 為子場(chǎng)景的半徑咽笼，只有相機(jī)在子場(chǎng)景范圍內(nèi)，才激活子場(chǎng)景內(nèi)的物體（子對(duì)象）戚炫。

將氣球?qū)ο笸献У?Sub-Scene 對(duì)象下面剑刑，如下（氣球?qū)ο蟛恍枰獟?CesiumGlobalAnchor 組件）。

運(yùn)行效果如下双肤，可以看到施掏，只有相機(jī)進(jìn)入子場(chǎng)景范圍內(nèi)，才激活子場(chǎng)景內(nèi)的物體（子對(duì)象）茅糜。

6 Native 編譯

本節(jié)主要參考 Building Cesium for Unity七芭。

1）編譯環(huán)境準(zhǔn)備

dotnet --version # 6.0 or later
cmake --version # 3.15 or later
Visual Studio 2022
Git Bash # 拉代碼和編譯命令都可以在 Git Bash里執(zhí)行

2）拉 cesium-unity-samples 代碼

cesium-unity-samples 源碼。

git clone --recurse-submodules git@github.com:CesiumGS/cesium-unity-samples.git

3）拉 cesium-unity 代碼

cesium-unity 源碼蔑赘。

cd cesium-unity-samples/Packages
git clone --recurse-submodules git@github.com:CesiumGS/cesium-unity.git com.cesium.unity

clone 時(shí)如果忘記添加 --recurse-submodules狸驳，可以通過(guò)以下命令遞歸拉取子模塊依賴预明。

cd cesium-unity-samples/Packages/com.cesium.unity
git submodule update --init --recursive

注意：不要通過(guò)瀏覽器下載 cesium-unity 源碼的 zip 文件，因?yàn)檫@樣不會(huì)拉子模塊代碼耙箍，也不要試 圖把所有子模塊的 zip 文件下載下來(lái)后再合并贮庞，因?yàn)樽幽K太多了，有的子模塊里面又包含子模塊究西，很容易漏掉窗慎。cesium-unity 源碼比較大，大概 1.89 GB（包含所有子模塊）卤材，如果下載比較慢遮斥，可以使用 Git常用命令總結(jié) 中方法配置代理來(lái)加速下載。

以下是子模塊的依賴文件扇丛。

com.cesium.unity\.gitmodules
com.cesium.unity\native~\extern\cesium-native\.gitmodules
com.cesium.unity\native~\extern\cesium-native\extern\draco\.gitmodules
com.cesium.unity\native~\extern\cesium-native\extern\earcut\.gitmodules
com.cesium.unity\native~\extern\cesium-native\extern\rapidjson\.gitmodules

com.cesium.unity.gitmodules 內(nèi)容如下术吗，可以看到 cesium-native 是 cesium-unity 的一個(gè)子模塊，這正是我們要編譯的 native 子模塊帆精。

[submodule "native~/extern/cesium-native"]
    path = native~/extern/cesium-native
    url = ../cesium-native.git
[submodule "native~/extern/tidy-html5"]
    path = native~/extern/tidy-html5
    url = https://github.com/htacg/tidy-html5.git
[submodule "native~/extern/enum-flags"]
    path = native~/extern/enum-flags
    url = https://github.com/grisumbras/enum-flags.git

4）構(gòu)建 Reinterop

Reinterop 是一個(gè) Roslyn（C# 編譯器）源代碼生成器较屿，在編譯 cesium-unity C# 代碼時(shí)由 Unity 自動(dòng)調(diào)用，并生成 C# 與 C++的交互層卓练。

cd cesium-unity-samples/Packages/com.cesium.unity
dotnet publish Reinterop~ -o .

5）打開(kāi) cesium-unity-samples 項(xiàng)目

使用 Unity Editor 打卡 cesium-unity-samples 項(xiàng)目隘蝎，Unity 將自動(dòng)編譯 cesium-unity C# 源代碼，同時(shí)調(diào)用 Reinterop 生成 C# 和 C++ 源代碼襟企。此時(shí) Cesium 的功能還不能正常使用嘱么，會(huì)拋出以下異常。這是因?yàn)?C++ 的代碼還沒(méi)編譯顽悼。

DllNotFoundException: CesiumForUnityNative assembly:<unknown assembly> type:<unknown type> member:(null)
NotImplementedException: The native implementation is missing so OnValidate cannot be invoked.

生成的 C++ 源碼地址為：com.cesium.unity/native~/build曼振，用戶可以通過(guò) Visual Studio 打開(kāi) CesiumForUnityNative.sln 文件來(lái)查看源碼。

6）編譯 C++ 代碼

關(guān)閉 cesium-unity-samples 項(xiàng)目蔚龙，執(zhí)行完以下命令行再打開(kāi)項(xiàng)目冰评。

構(gòu)建 Debug 版本。

# compile the C++ code for use in the Editor
cd cesium-unity-samples/Packages/com.cesium.unity/native~
# 在 build 目錄中生成 CMake 構(gòu)建配置, 并將構(gòu)建類型設(shè)置為 Debug, 以便在構(gòu)建項(xiàng)目時(shí)啟用調(diào)試信息(只需執(zhí)行一次, 第二次編譯時(shí)不需要執(zhí)行該命令)
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
# 在 build 目錄中執(zhí)行構(gòu)建操作, 使用 14 個(gè)構(gòu)建線程并生成 Debug 版本的可執(zhí)行文件或庫(kù), 將構(gòu)建結(jié)果安裝到 install 指向的目錄中
cmake --build build -j14 --target install --config Debug

構(gòu)建 Release 版本木羹。

# build a release build
cd cesium-unity-samples/Packages/com.cesium.unity/native~
# 在 build 目錄中生成 CMake 構(gòu)建配置, 并將構(gòu)建類型設(shè)置為 RelWithDebInfo, 它允許在 Release 版本中包含調(diào)試信息(只需執(zhí)行一次, 第二次編譯時(shí)不需要執(zhí)行該命令)
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo
# 在 build 目錄中執(zhí)行構(gòu)建操作, 使用 14 個(gè)構(gòu)建線程并生成帶有調(diào)試信息的 Release 版本的可執(zhí)行文件或庫(kù), 將構(gòu)建結(jié)果安裝到 install 指向的目錄中
cmake --build build -j14 --target install --config RelWithDebInfo

若在后面的編譯過(guò)程中甲雅，報(bào)錯(cuò)：could not find any instance of Visual Studio，可以參考博客→解決CMake時(shí)“could not find any instance of Visual Studio”的問(wèn)題汇跨。

7）查看安裝目錄

打開(kāi) com.cesium.unity/native~/CMakeLists.txt 文件务荆，搜索 "CMAKE_INSTALL_PREFIX"妆距，如下穷遂。

# When building for the Editor, both Runtime and Editor assemblies are
# written to the Editor directory so that Unity won't load them in
# a standalone build.
if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${CMAKE_CURRENT_LIST_DIR}/../Editor" CACHE PATH "Installed to the Editor directory." FORCE)
endif()

可以看到，安裝目錄為 "${CMAKE_CURRENT_LIST_DIR}/../Editor"娱据，即 com.cesium.unity/Editor 目錄蚪黑，由此得構(gòu)建和安裝的目錄如下盅惜。

com.cesium.unity\native~\build\Editor\Debug\CesiumForUnityNative-Editor.dll ->
com.cesium.unity\Editor\CesiumForUnityNative-Editor.dll

com.cesium.unity\native~\build\Runtime\Debug\CesiumForUnityNative-Runtime.dll ->
com.cesium.unity\Editor\CesiumForUnityNative-Runtime.dll

7 修改 Native 代碼案例

1）打開(kāi) native 源碼工程

使用 Visual Studio 打開(kāi) CesiumForUnityNative.sln 文件來(lái)查看源碼，如下忌穿。

2）修改源碼

修改 CesiumForUnityNative-Runtime 模塊下的 CesiumCreditSystemImpl.cpp 文件（源碼位置：com.cesium.unity/native~/Runtime/src/CesiumCreditSystemImpl.cpp）抒寂，如下。

3）編譯源碼

# compile the C++ code for use in the Editor
cd cesium-unity-samples/Packages/com.cesium.unity/native~
# 在 build 目錄中生成 CMake 構(gòu)建配置, 并將構(gòu)建類型設(shè)置為 Debug, 以便在構(gòu)建項(xiàng)目時(shí)啟用調(diào)試信息(只需執(zhí)行一次, 第二次編譯時(shí)不需要執(zhí)行該命令)
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
# 在 build 目錄中執(zhí)行構(gòu)建操作, 使用 14 個(gè)構(gòu)建線程并生成 Debug 版本的可執(zhí)行文件或庫(kù), 將構(gòu)建結(jié)果安裝到 install 指向的目錄中
cmake --build build -j14 --target install --config Debug

編譯完成后掠剑，可以看到 com.cesium.unity/Editor/CesiumForUnityNative-Runtime.dll 文件修改日期發(fā)生變化屈芜。

4）修改前后對(duì)比

修改前底部有一行文字。

修改后底部文字消失朴译。

聲明：本文轉(zhuǎn)自【Unity3D】Cesium加載大地圖井佑。