WebODM Cesium Ion 插件完全指南：将航测成果一键上云，以 3D Tiles 流式分发-平芜编程栈

后端
前端
图像处理
GIS
3D建模

【免费下载链接】WebODM

User-friendly, commercial-grade software for processing aerial imagery. ✈️ Download it for free!

项目地址：https://gitcode.com/gh_mirrors/we/WebODM

导读

本指南围绕 WebODM 内置的Cesium Ion核心插件（版本 1.3.0，代码位于 coreplugins/cesiumion/）展开，讲解如何把 WebODM 处理完成的 DOM/DSM/DTM、点云与纹理模型一键上传到 Cesium Ion 账户，借助 Cesium 客户端（如 CesiumJS）以 3D Tiles 形式在任意设备上流式加载多 GB 级三维模型。读完本文，你将掌握插件的启用与 Token 配置、端到端上传操作流程、KTX2 纹理压缩新特性，并能从源码层面理解"上传（uploading）"与"处理（processing）"两阶段流水线的工作原理及常见故障的排查方法。

1. 插件定位：为什么需要 Cesium Ion

Cesium Ion 是面向地理空间数据的托管式流式服务平台。WebODM 的 Cesium Ion 插件打通了两端的链路：WebODM 负责航拍影像的摄影测量处理（生成正射影像、高程模型、点云与三维纹理模型），Cesium Ion 负责把这些成果转换为可流式加载的 3D Tiles 瓦片集，并托管到云端，使多 GB 级模型无需下载即可在浏览器、移动端等任意 Cesium 客户端中流畅浏览。

插件在 WebODM 前端通过PluginsAPI.Dashboard.addTaskActionButton向每个任务注入操作按钮（见 templates/load_buttons.js），后端则通过 REST API 与https://api.cesium.com/v1（定义于 globals.py）交互，实现在 manifest.json 中声明的"Upload and tile ODM assets with Cesium ion"这一核心能力。

2. 前置条件

在启用插件前，需要确认以下三项：

WebODM 版本 ≥ 2.5.0：插件的webodmMinVersion声明为"2.5.0"（见 manifest.json），旧版本无法使用；
Cesium Ion Token：需在 Cesium Ion 账户中生成一个 API Token，并授予权限。README 要求至少包含assets:list, assets:read, assets:write；而插件自带的 Token 配置页 templates/app.html 更进一步要求全部权限：assets:list, assets:read, assets:write, geocode（geocode用于地形类资产上传时解析基准地形）；
稳定的互联网连接：上传与处理状态轮询均依赖网络。

3. 初始设置：启用插件与配置 Token

3.1 启用插件

登录 WebODM，进入Administration → Plugins管理页；
找到 Cesium Ion 插件并启用（默认随 WebODM 分发，disabled标记文件为空表示未被禁用，见 coreplugins/cesiumion/disabled）；
启用后，左侧导航栏会出现Cesium Ion菜单项（菜单注入逻辑见 plugin.py 的main_menu()）。

3.2 设置 Token

点击左侧 Cesium Ion 菜单，进入插件主页；
在 cesium.com/ion/tokens 生成 Token（建议勾选全部权限）；
将 Token 粘贴到页面表单中，点击Set Token保存。

Token 并非全局共享，而是按用户存储：HomeView通过plugin.get_user_data_store(request.user)将 Token 写入当前用户的 Data Store（见 app_views.py）；再次提交空 Token 则会重置。每次页面加载时，load_buttons.js 会把 Token 注入到任务操作按钮组件的 props 中——若未设置 Token，按钮不会被渲染。

4. 端到端使用流程

README 给出如下完整操作路径：

在 WebODM 仪表盘（dashboard）创建新项目；
上传航拍影像；
编辑任务选项，务必开启texturing-single-material；
启动 WebODM 处理（耗时较长）；
处理完成后，点击任务上的Tile in Cesium Ion下拉按钮，从可用资产列表中选择要上传的成果；
在弹出的对话框中，可为资产重命名、添加描述与署名（attribution），并可按资产类型启用对应的 Cesium Ion 选项，确认后提交；
上传开始后，可通过View Ion Tasks按钮随时查看上传与处理进度；
处理完成后，通过View in Cesium Ion下拉按钮在新浏览器标签页中打开并查看 Cesium Ion 中的资产。

注意：Cesium 任务包含两个阶段——上传与处理。上传（uploading）是把 WebODM 处理好的数据传送到 Cesium Ion；处理（processing）是 Cesium Ion 将数据切片/渲染为可流式加载的模型。两者都在同一个任务视图中显示进度。

4.1 可用资产类型与文件映射

前端下拉列表中的可用资产由任务产出的文件决定。后端在ShareTaskView.get中遍历task.available_assets，通过文件名校验哪些资产可上传（见 api_views.py），映射关系如下：

资产类型（AssetType）	对应 WebODM 产物文件	Cesium Ion 输出类型
ORTHOPHOTO（正射影像）	`orthophoto.tif`	IMAGERY
TERRAIN_MODEL（地形模型/DTM）	`dtm.tif`	TERRAIN
SURFACE_MODEL（表面模型/DSM）	`dsm.tif`	TERRAIN
POINTCLOUD（点云）	`georeferenced_model.laz`	3DTILES
TEXTURED_MODEL（纹理模型）	`textured_model.zip`	3DTILES（sourceType 为 3D_CAPTURE）

前端 TaskView.jsx 依据isExported/isTask/isError三个状态将资产分为"待上传"、"已导出（可查看）"与"处理中"三类，分别呈现为 Tile / View 两个下拉按钮以及 View ion Tasks 进度弹窗。

4.2 上传对话框选项说明

上传对话框（UploadDialog.jsx）包含通用字段与按资产类型区分的专属选项：

通用字段：Name（默认预填为项目名 | 任务名 — 资产类型，数据来自项目 API）、Description、Attribution；
地形类资产（DTM/DSM）专属选项——Base Terrain：选择基准地形（默认 Mean Sea Level，或从用户 Ion 账户中类型为 TERRAIN 的资产中选择）。提交时后端自动补充toMeters: 1、heightReference: "WGS84"、waterMask: false参数；
纹理模型专属选项——Use KTX2 Compression：选择 Yes/No，对应上传时的textureFormat取值为KTX2或AUTO。

4.3 为什么必须开启 texturing-single-material

Cesium Ion 的 3D_CAPTURE 资产类型只接受单纹理材质的模型。README 明确警告：必须在新任务的 WebODM 处理选项中开启texturing-single-material，因为 WebODM 会把先前处理过的纹理模型缓存在同一个odm_textured数据目录中——若复用旧任务的缓存，即使后续勾选了该选项，上传的仍是旧的未合并纹理模型，导致上传成功但无法处理/渲染。该选项在 WebODM 预设 UI 中位于 texturing → texture-opts 分组（见 EditPresetDialog.jsx 中的定义）。

5. 源码级原理：上传两阶段流水线

点击提交后，前端向/api/.../task/<pk>/share发送 POST（携带 Token、资产类型、名称、描述、署名与选项），后端ShareTaskView.post与异步任务upload_to_ion协同完成整条流水线：

5.1 上传前准备（后端 API 层）

通过task.get_asset_download_path()定位资产文件路径；
对纹理模型（TEXTURED_MODEL）：若任务存在deferred_compress_dir（延迟压缩目录），先生成延迟压缩资产；随后自动计算任务边界（取dsm_extent/dtm_extent），把模型中心经纬度写入options.position（高度置 0，因为模型已做偏移），供 Cesium Ion 定位；
将任务标记为 upload.active，并通过run_function_async把upload_to_ion投递到 Celery 异步执行（以上逻辑见 api_views.py 的ShareTaskView.post）。

5.2 纹理模型预处理

对于纹理模型，upload_to_ion首先调用 model_tools.py 中的to_ion_texture_model对textured_model.zip进行重打包：解压后删除.conf、.vec、.spt等不兼容文件，仅保留*_geo.obj地理参考模型（若无_geo文件则抛出IonInvalidZip，回退使用原始文件），最后以 ZIP_DEFLATED 重新压缩以减少体积。

5.3 上传与处理轮询（异步任务层）

uploader.py 中的upload_to_ion是核心执行者，步骤为：

若环境缺少boto3，自动通过 pip 安装；
调用POST {ION_API_URL}/assets创建资产请求，从响应中取出assetMetadata（资产 ID）、uploadLocation（AWS S3 临时凭据、endpoint、bucket、prefix）与onComplete（回调信息）；
用 boto3 的upload_file把资产文件上传到 Ion 分配的 S3 存储，TaskUploadProgress回调按字节数实时计算上传百分比并写入插件 Data Store；
上传完成后调用onComplete回调通知 Ion；
进入处理阶段轮询：每 2 秒请求一次GET {ION_API_URL}/assets/{ion_id}，解析status与percentComplete更新处理进度，直到进度达到 100% 或状态进入 ERROR；
整个流程的状态（上传/处理进度、active 标记、错误信息）都持久化在插件级GlobalDataStore中（键名形如task_<id>_<ASSET_TYPE>），供前端定时刷新展示。

5.4 进度展示与状态清理

前端TaskView.jsx中，TaskFetcher每 4 秒（打开任务弹窗时 2 秒）自动刷新资产状态；TasksDialog.jsx（TasksDialog.jsx）把每个资产的 upload/process 进度与错误渲染为进度条列表；
RefreshIonTaskView（/task/<pk>/refresh）会清理两类陈旧状态：Ion 侧已不存在（HTTP 非 200）的资产记录，以及 Celery 中已不活跃的"僵尸任务"记录；
ClearErrorsTaskView（/task/<pk>/clear）用于一键清除失败记录（对应任务弹窗中的Remove Failed Tasks按钮）；
通过 Django 信号监听task_removed/task_completed，任务被删除或重新处理时自动清空该任务的全部资产信息，保证可重新分享（见 api_views.py 的oam_cleanup）。

6. v1.3.0 新特性：KTX2 纹理压缩

插件 1.3.0（manifest.json）随 Cesium Ion 流式管线升级而引入新特性：

Cesium Ion 自动将瓦片集升级为1.1版本（即新标准的 3D Tiles 瓦片集规范）；
新版本支持KTX2（Khronos 组织的纹理容器格式，支持 Basis Universal 超级压缩）作为纹理压缩选项，可生成更小的瓦片集，获得更好的流式传输性能。

在 WebODM 端，用户只需在上传纹理模型（3D_CAPTURE）时，在弹出对话框的Use KTX2 Compression选项中选择Yes，后端即会把textureFormat设置为KTX2（选择 No 则为AUTO，由 Ion 自动决定）。前端该选项的帮助文案也说明了其用途："使用 KTX2 压缩创建更小的瓦片集，以获得更好的流式性能"（见 UploadDialog.jsx）。注意 README 中该小节标题的 "KVX 2.0" 为笔误，实际指 KTX2。

7. 故障排查与 FAQ

7.1 常见问题：纹理模型上传成功但无法处理/渲染

现象：纹理模型成功上传到 Cesium Ion，但处理或渲染失败。
原因：Cesium Ion 的 3D_CAPTURE 仅接受单纹理材质模型；而 WebODM 在odm_textured目录中缓存了先前处理过的多纹理模型。
解决：在新任务上开启texturing-single-material后再进行 WebODM 处理（切勿复用旧任务缓存）。

7.2 常见错误提示的代码依据

上传过程中若 Cesium Ion API 返回 HTTP 错误，插件会写入明确的错误信息（见 uploader.py）：

401 →Invalid ion token!：Token 无效或已过期，请重新生成并在插件页更新；
404 →Missing permissions on ion token!：Token 缺少所需权限（如assets:write），请按第 3 节重新生成并授予全部权限。

7.3 常见问题：Token 设置不生效 / 按钮不出现

Token 按用户存储且每次页面加载注入；若任务上未出现 Tile in Cesium Ion 按钮，请确认：当前登录用户已设置 Token、任务存在可用资产（orthophoto.tif / dsm.tif / dtm.tif / georeferenced_model.laz / textured_model.zip 之一）。若资产列表为空，任务页还会显示Refresh Available ion Assets按钮用于手动刷新。