1 Introduction
Cesium is an earth visualization platform and tool chain with functions such as data slicing, data distribution, and 3D visualization.
Cesium supports JS, Unity, Unreal, O3DE, Omniverse and other platforms, the framework is as follows.
Cesium related links are as follows:
- Cesium official website: https://cesium.com
- Download CesiumLab: https://www.cesiumlab.com/cesiumlab.html
- CesiumLab manual: https://www.cesiumlab.com/CesiumLab geographic information basic data processing platform user manual.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 Lab-CSDN: https://blog.csdn.net/weixin_43805235
- Cesium Lab - Station B: https://space.bilibili.com/346212872
2 Environment Construction
This section mainly refers to Cesium for Unity Quickstart .
1) Create a 3D (URP) or 3D (HDRP) project
Note: The official recommended minimum version of Unity Editor is 2021.3.2f1, and the author’s version of Unity Editor is 2021.3.11f1c2; Cesium for Unity can be used with Universal Rendering Pipeline (URP) and High Definition Rendering Pipeline (HDRP), but it does not support Unity’s built-in renderer. If you choose a 3D project as a template, the dataset loaded by Cesium will not be rendered correctly.
2) Add scope registry
Click [Edit→Project Settings→Package Manager] in turn, and add the registry information as follows.
Name: Cesium
URL: https://unity.pkg.cesium.com
Scope(s): com.cesium.unity3) Download Cesium For Unity
Click [Window→Package Manager] to open the package manager window, select My Registries in the Packages menu, and download Cesium for Unity, as follows.
After the download is successful, there will be a Cesium menu in the menu bar, as follows.
4) Connect to Cesium ion
Click the Connect to Cesium io button in the Cesium window, jump to the Web page, and click Allow.
5) Add Token
Click the Token button in the Cesium window to add a token. If there is no token, create a token. If there is a token, use the created token.
6) Create a world map
Click Cesium World Terrain + Bing Maps Aerial imagery in the Cesium window to add a world map.
The scene is displayed as follows.
If you cannot see the map, it may be that the camera is far away and has been clipped. You can adjust the position of the far clipping plane, as follows.
7) Add dynamic camera
Shield the default camera in the scene, add Dynamic Camera in the Cesium window, as follows. At this point, in the Hierarchy window, you can see that an object named DynamicCamera is automatically generated under the CesiumGeoreference object, and the Camera component is hung on the object.
After running, you can control the camera position and attitude through the mouse and direction keys, as follows.
Note: Visual changes can be realized by adjusting the Latitude and Longitude properties under the CesiumGeoreference component, as follows.
Supplement: Readers can also download the official Cesium Deom to experience it, see → cesium-unity-samples for details .
3 map slices
This section mainly introduces the fbx file slicing process. For other file slicing, you can refer to the CesiumLab geographic information basic data processing platform manual .
3.1 Slicing
After downloading and installing CesiumLab , open the CesiumLab client, and the slice of the fbx file is as follows.
In the processing log, you can check whether the task is processed successfully, as follows. If the slicing fails, it may be that the fbx file contains cameras or lights, use Blender to delete the cameras and lights, and then re-export the fbx file.
The generated files are as follows. When loading slices, the tileset.json file is required.
3.2 Preview slice
Slices can be viewed in the distribution service, the steps are as follows.
After clicking preview, it will jump to another web page, displaying the slice as follows.
The user enters: http://localhost:9003/viewer/index.html in the browser , and then adds slices according to the following steps, and the slices can also be previewed.
3.3 Upload slices to Cesium ion
After logging in to your account on the Cesium ion official website, follow the steps below to upload slices.
After selecting the file, upload the slice.
In the My Assets window, you can view the uploaded slices, as follows.
Note: The ID in the first column will be used when loading assets; users can also add assets from Asset Depot to My Assets.
4 Load slices in Unity
4.1 Load slices in Cesium ion
Click the Add button in the Cesium window, and the Cesium ion Assets window will appear on the right side of the Console at the bottom, select the map to add to the scene, as follows.
Double-click the map object under CesiumGeoreference in the Hierachy window to focus the camera on the map. The map is displayed as follows. Different maps can be loaded by modifying the ion Asset ID.
4.2 Load slices in CesiumLab service
Click Blank 3D Tiles Tileset in the Cesium window, and the CesiumGeoreference and Cesium3DTileset objects will be generated in the Hierarchy window. Select the Cesium3DTileset object and set the slice url, as follows.
The url is from CesiumLab, as follows.
Double-click the Cesium3DTileset object in the Hierachy window to focus the camera on the map, and the map is displayed as follows.
It can be seen that the orientation of the map is abnormal, and the method of adjusting the orientation of the map will be introduced in section 4.4.
4.3 Load local slices
Copy the slice to the Resources / city directory under the project directory. Click Blank 3D Tiles Tileset in the Cesium window, and the CesiumGeoreference and Cesium3DTileset objects will be generated in the Hierarchy window. Select the Cesium3DTileset object and set the slice url, as follows.
Double-click the Cesium3DTileset object in the Hierachy window to focus the camera on the map, and the map display is the same as Section 4.2.
4.4 Adjust the orientation of the map
Use the method in Section 3.2 to preview the slice, and after adjusting the orientation, place the mouse in the middle of the screen and record the longitude, latitude, and height of the bottom, as follows.
Select the CesiumGeoreference object, and set the longitude, latitude, and altitude to the values recorded above, as follows.
Double-click the CesiumGeoreference object in the Hierachy window to focus the camera on the map, and the map is displayed as follows.
It can be seen that the orientation of the map has been displayed correctly. If the user is still not satisfied with the orientation, after adjusting the vision, click the Place Origin Here button to reset the longitude, latitude, and altitude under the vision, as follows.
5 Add objects
5.1 CesiumGlobalAnchor
Add a DynamicCamera to the scene, block the Main Camera, and add a hot air balloon object, as follows.
After running, it is found that the balloon moves with the camera, as follows.
Move the balloon object under CesiumGeoreference, and add CesiumGlobalAnchor component, as follows.
The running effect is as follows, you can see that the balloon object does not move with the camera.
5.2 Reference sub-scenario
Select the CesiumGeoreference object, click Create Sub-Scene Here to add a sub-scene, an object with a CesiumSubScene component will be generated under the CesiumGeoreference object, and it will be renamed Sub-Scene.
Adjust the Activation Radius, Latitude, Longitude, and Height properties in the CesiumSubScene component, as follows. Latitude, Longitude, and Height determine the center of the sub-scene, and Activation Radius is the radius of the sub-scene. Only when the camera is within the range of the sub-scene, can the objects (sub-objects) in the sub-scene be activated.
Drag the balloon object under the Sub-Scene object, as follows (the balloon object does not need to hang the CesiumGlobalAnchor component).
The running effect is as follows. It can be seen that the objects (sub-objects) in the sub-scene are activated only when the camera enters the range of the sub-scene.
6 Native compilation
This section mainly refers to Building Cesium for Unity .
1) Compilation environment preparation
dotnet --version # 6.0 or later
cmake --version # 3.15 or later
Visual Studio 2022
Git Bash # 拉代码和编译命令都可以在 Git Bash里执行2) Pull the cesium-unity-samples code
Cesium-unity-samples source code.
git clone --recurse-submodules [email protected]:CesiumGS/cesium-unity-samples.git3) Pull the cesium-unity code
Cesium-unity source code.
cd cesium-unity-samples/Packages
git clone --recurse-submodules [email protected]:CesiumGS/cesium-unity.git com.cesium.unityIf you forget to add --recurse-submodules when cloning, you can use the following command to recursively pull submodule dependencies.
cd cesium-unity-samples/Packages/com.cesium.unity
git submodule update --init --recursiveNote: Do not download the zip file of the cesium-unity source code through the browser, because it will not pull the sub-module code, and do not try to download the zip files of all sub-modules and then merge them, because there are too many sub-modules, and some sub-modules contain sub-modules, which are easy to miss. The source code of cesium-unity is relatively large, about 1.89 GB (including all submodules). If the download is slow, you can use the method in the summary of common Git commands to configure the proxy to speed up the download.
The following are the dependency files of the submodules.
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\.gitmodulesThe content of com.cesium.unity\.gitmodules is as follows. You can see that cesium-native is a submodule of cesium-unity , which is the native submodule we want to compile.
[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.git4) Build Reinterop
Reinterop is a Roslyn (C# compiler) source code generator, which is automatically called by Unity when compiling cesium-unity C# code, and generates an interaction layer between C# and C++.
cd cesium-unity-samples/Packages/com.cesium.unity
dotnet publish Reinterop~ -o .5) Open the cesium-unity-samples project
Use the Unity Editor to punch in the cesium-unity-samples project, and Unity will automatically compile the cesium-unity C# source code, and at the same time call Reinterop to generate the C# and C++ source code. At this time, the functions of Cesium cannot be used normally, and the following exceptions will be thrown. This is because the C++ code is not yet compiled.
DllNotFoundException: CesiumForUnityNative assembly:<unknown assembly> type:<unknown type> member:(null)
NotImplementedException: The native implementation is missing so OnValidate cannot be invoked.The address of the generated C++ source code is: com.cesium.unity/native~/build, users can open the CesiumForUnityNative.sln file through Visual Studio to view the source code.
6) Compile C++ code
Close the cesium-unity-samples project, and open the project after executing the following command lines.
Build the Debug version.
# compile the C++ code for use in the Editor
cd cesium-unity-samples/Packages/com.cesium.unity/native~
# 在 build 目录中生成 CMake 构建配置, 并将构建类型设置为 Debug, 以便在构建项目时启用调试信息(只需执行一次, 第二次编译时不需要执行该命令)
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
# 在 build 目录中执行构建操作, 使用 14 个构建线程并生成 Debug 版本的可执行文件或库, 将构建结果安装到 install 指向的目录中
cmake --build build -j14 --target install --config DebugBuild the Release version.
# build a release build
cd cesium-unity-samples/Packages/com.cesium.unity/native~
# 在 build 目录中生成 CMake 构建配置, 并将构建类型设置为 RelWithDebInfo, 它允许在 Release 版本中包含调试信息(只需执行一次, 第二次编译时不需要执行该命令)
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo
# 在 build 目录中执行构建操作, 使用 14 个构建线程并生成带有调试信息的 Release 版本的可执行文件或库, 将构建结果安装到 install 指向的目录中
cmake --build build -j14 --target install --config RelWithDebInfoIf in the subsequent compilation process, an error is reported: could not find any instance of Visual Studio, you can refer to the blog → Solve the problem of "could not find any instance of Visual Studio" in CMake .
7) View the installation directory
Open the com.cesium.unity/native~/CMakeLists.txt file and search for "CMAKE_INSTALL_PREFIX", as follows.
# 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()It can be seen that the installation directory is "${CMAKE_CURRENT_LIST_DIR}/../Editor", which is the com.cesium.unity/Editor directory, so the directory for construction and installation is as follows.
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.dll7 Modify the Native code case
1) Open the native source code project
Use Visual Studio to open the CesiumForUnityNative.sln file to view the source code, as follows.
2) Modify the source code
Modify the CesiumCreditSystemImpl.cpp file under the CesiumForUnityNative-Runtime module (source location: com.cesium.unity/native~/Runtime/src/CesiumCreditSystemImpl.cpp), as follows.
3) Compile the source code
# compile the C++ code for use in the Editor
cd cesium-unity-samples/Packages/com.cesium.unity/native~
# 在 build 目录中生成 CMake 构建配置, 并将构建类型设置为 Debug, 以便在构建项目时启用调试信息(只需执行一次, 第二次编译时不需要执行该命令)
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
# 在 build 目录中执行构建操作, 使用 14 个构建线程并生成 Debug 版本的可执行文件或库, 将构建结果安装到 install 指向的目录中
cmake --build build -j14 --target install --config DebugAfter the compilation is complete, you can see that the modification date of the com.cesium.unity/Editor/CesiumForUnityNative-Runtime.dll file has changed.
4) Comparison before and after modification
There is a line of text at the bottom before modification.
After modification, the bottom text disappears.
