Skip to main content

三维模型

三维模型的标准流程是 确认原始格式与 UP 轴 => 转成 Cesium 可用的格式/3D Tiles => 配准坐标与高度 => 检查材质/颜色 => 预览验收 成败的关键在”先轴向、再坐标、最后材质”——三件事混在一起调,越调越乱
从 Revit、3ds Max、OBJ 或 MapGIS HDB 接入 Cesium 时,常见三类现象:
  • 模型飘在空中、躺倒、UP 变成 East/North:轴向、原点或高度问题。
  • 模型整体偏移:原始坐标系/配准问题。
  • 模型变黑、不显示:材质、法线、样式或加载路径问题。
先分清现象,再按本文顺序排查。

一、先看 Cesium 的 N–Up–East 轴

Cesium N–Up–East 轴与模型 UP 轴转换 图:依据 Cesium 官方 NUE/ENU 定义绘制的轴示意图,以及 Z-up 模型到 Y-up 的旋转关系。 Cesium 官方提供两种常用本地轴: 关键点:
  • NUE 的 y 是 Up,不是 North;看到”UP 变成了 East”,本质是模型的 UP 轴被映射到了错误的轴。
  • Cesium 世界坐标是 ECEF;本地轴只用于把模型放到某个经纬度/高程点。
  • glTF 规范是 Y-up;Revit、3ds Max、OBJ 常见 Z-up。源模型的 UP 轴与 Cesium/glTF 不一致时,必须旋转。
  • 3D Tiles 还要看 tileset.json 的 root.transform/transform,不要只靠”旋转 90°“猜。

二、模型飘在空中 / 躺倒 / UP 变 East

先判断属于哪一种:

2.1 先确认原始 UP 轴

不要凭扩展名猜:
  • Revit(RVT):常见 Z-up;导出 OBJ/glTF 时看导出器是否做了 Y-up 转换。
  • 3ds Max:Z-up。
  • OBJ:本身没有统一轴规范,取决于导出软件;常见 Z-up。
  • glTF/GLB:Y-up,+Z 为前方。
  • 3D Tiles:看 tileset.json 的 transform 和内容类型;不要把 3D Tiles 的瓦片坐标直接当成经纬度。
最稳的办法:在原始软件里确认”哪根轴朝天”,再问导出器是否转换。不同的模型软件”正北”也不一样(项目北/真北/世界北),朝向问题不能只靠旋转 UP 轴解决。

2.2 旋转:Z-up → Y-up

先确认导出器是否已经转换:如果 OBJ/glTF 导出时已经把 Z-up 转成 Y-up,页面不要再转;只有原始顶点仍是 Z-up 时才用上面的 rotX。判断方法:不加任何旋转先看模型是否躺倒,或检查导出器的 axis/up 设置。 3D Tiles 的写法类似,但先确认是否已经带 root.transform:

2.3 原点与高度:漂浮不一定是轴的问题

轴向正确但模型悬空,通常是:
  • 模型原点在建筑底部、中心或世界原点,和落点高程不一致;
  • 3D Tiles 里已经带了世界坐标,页面又叠了一次 modelMatrix;
  • 用了 heightReference 但模型不是 Entity,或者地面高程不可靠;
  • 原始数据没有高程,转换时被默认成 0,导致模型贴地/埋地。
处理顺序:
  1. 用 3dtiles_cli inspect tileset 看 boundingVolume、transform 和内容类型。
  2. 确认模型局部原点(包围球中心)与落点的关系。
  3. 调整 height 或 modelMatrix 的平移,不要先改相机。
  4. 如果坐标系本身不对,先回到空间参考系处理 CRS,再做高度。

2.4 Cesium.Matrix3.fromColumns 报错

这个报错不是模型问题,是 Cesium 版本/API 用错。 产品固定使用 Cesium 1.122,1.122 的 Matrix3 没有 fromColumns 方法。可用的写法:
相关 API 以官方文档为准:Matrix3.fromColumnMajorArray、Matrix3.fromRotationX。 不要为了一个方法去升级 Cesium;也不要照抄 1.123+ 的示例。页面里出现 is not a function,先检查是不是用了 1.122 不存在的接口。

三、模型变黑 / 不显示

3.1 变黑

按概率排查:
  • 法线缺失或翻转:没有 NORMAL 或法线朝内,光照下就是黑的;在建模软件里重算法线/翻面。
  • 材质本身就是黑色:glTF 的 baseColorFactor、OBJ 的 .mtl、顶点色为黑;先看原始材质。
  • 贴图路径丢失:OBJ 的 .mtl/贴图没有一起导出,或相对路径断了;3dtiles_cli convert 会读同目录/相对路径的 .mtl 和 diffuse 贴图,保持目录结构。
  • 前端样式覆盖:tileset.style.color / Cesium3DTileStyle 把颜色改黑;先移除自定义 style 验证。
  • 光照/环境:Cesium 默认光照下纯黑材质不会变亮;需要材质有非零 baseColor 和正确法线。

3.2 不显示

  • tileset.json/.glb 路径 404,或只加载了目录而不是 tileset.json。
  • modelMatrix 出现 NaN/0 缩放,或模型被移到相机外。
  • maximumScreenSpaceError 过大/过小、boundingVolume 错误、瓦片被裁剪。
  • 模型在相机背后/地下,或 show=false。
  • 点云点太小/颜色透明,看起来”没有”。
先用 3dtiles_cli inspect tileset 确认入口、content 类型、包围盒和 transform;再看 F12 Network 是否有 404。

3.3 401 与 404 不要归因到模型

  • 401:常见是天地图 tk 过期/限频。F12 → Network 找到 401 的 URL;如果是 tianditu.gov.cn,换 tk 或申请新 tk。不是模型轴向问题。
  • 404:tileset.json、.glb、.pnts 路径不对;检查发布目录和相对路径。
  • 502/503/504:模型服务/网络问题,先重试或换网络,不要改模型。

四、位置偏移:高斯、CGCS2000、无地理坐标

“模型姿态对了,但整体偏移”通常是坐标问题,不是轴向问题。
原则:CRS、投影、局部原点、分块尽量在 3dtiles_cli 生成阶段解决,Cesium 页面不要承载坐标修正逻辑。若 tileset.json 的包围盒还是百万米级原始投影大坐标,回到生成阶段输出局部居中或 4978,不要在页面里硬调相机/裁剪面。

五、建筑精模与树木点云要分开

对话里的”建筑模型灰色 #B4B4B4、植物点云绿色 #228B22”是两类数据,不要塞进同一条管线: 要点:
  • 建筑走精模,树木走点云;不要把建筑塞进 pnts,也不要把点云当精模补面。
  • i3dm/pnts 是 3D Tiles 的内容类型;选错类型会导致”看起来有数据但显示不对”。
  • 建筑和树木用独立的 tileset/图层,分别设置样式;不要让一个 tileset.style.color 同时管两类。
  • 颜色:建筑精模保留材质/贴图(例如 #B4B4B4 的灰色),树木点云用 Cesium3DTileStyle 按分类/属性着色(例如 #228B22 的绿色)。颜色应来自模型材质或点云属性,而不是导入后被统一改黑。

六、RVT / MapGIS HDB 怎么导出

Cesium 和 3dtiles_cli 都不能直接读 RVT;RVT 要先导出为 OBJ/glTF/IFC,再进 3D Tiles 管线。

6.1 MapGIS 10 导出

精模导出需要 MapGIS 10 授权环境。在 MapGIS 10 中打开 HDB 后,按实际版本菜单走:
  • 三维服务 → 导出为 3D Tiles / OBJ / glTF;
  • 或 三维模型 → 数据转换 → 导出;
  • 或 工具 → 数据导出 → 选择 OBJ 或 glTF。
不同 MapGIS 10 版本的菜单名可能略有差异;以现场授权版本为准。

6.2 FME 备选

有 FME 授权时,FME 可以读取 MapGIS HDB,直接导出 OBJ/glTF;导出后同样走 3dtiles_cli convert。

6.3 导出后怎么进 3D Tiles

  • OBJ(带 .mtl 和贴图):保持目录结构,3dtiles_cli convert model.obj --out model_tiles --spec-version 1.1 --jobs 1 --execute --allow-write --compact。
  • glTF/GLB:可以先在 Cesium 里用 Cesium.Model.fromGltfAsync 做单模型快速验证(看轴向/材质);要做 3D Tiles/精模发布,优先走 OBJ/IFC → 3dtiles_cli convert。
  • IFC:3dtiles_cli convert model.ifc ...,适合 BIM 构件和属性。
  • 转换后用 3dtiles_cli inspect tileset 检查,再交给 Cesium 页面加载。

七、给 AI 的排查顺序

把下面这段直接发给 AI,比只说”模型漂了/黑了”有效得多:
常见报错的定向说法:
  • Cesium.Matrix3.fromColumns is not a function: “当前是 Cesium 1.122,请改用 Matrix3.fromColumnMajorArray / fromRotationX 等 1.122 支持的接口,不要升级库。”
  • 401 且 URL 是 tianditu.gov.cn: “这是天地图 tk 过期/限频,不是模型问题;先换 tk 或申请新 tk。”
  • 模型不显示: “先查 tileset.json 路径、Network 404、boundingVolume 和 modelMatrix;不要先怀疑轴向。”

使用提示: 先确认”哪根轴朝天”,再确认”模型落在哪个经纬度/高程”,最后才调材质。轴向、坐标、材质三件事分开验收,三维模型接入会快很多。