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

关键点:
- 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 的瓦片坐标直接当成经纬度。
2.2 旋转:Z-up → Y-up
rotX。判断方法:不加任何旋转先看模型是否躺倒,或检查导出器的 axis/up 设置。
3D Tiles 的写法类似,但先确认是否已经带 root.transform:
2.3 原点与高度:漂浮不一定是轴的问题
轴向正确但模型悬空,通常是:- 模型原点在建筑底部、中心或世界原点,和落点高程不一致;
- 3D Tiles 里已经带了世界坐标,页面又叠了一次
modelMatrix; - 用了
heightReference但模型不是 Entity,或者地面高程不可靠; - 原始数据没有高程,转换时被默认成 0,导致模型贴地/埋地。
- 用
3dtiles_cli inspect tileset看boundingVolume、transform和内容类型。 - 确认模型局部原点(包围球中心)与落点的关系。
- 调整
height或modelMatrix的平移,不要先改相机。 - 如果坐标系本身不对,先回到空间参考系处理 CRS,再做高度。
2.4 Cesium.Matrix3.fromColumns 报错
这个报错不是模型问题,是 Cesium 版本/API 用错。
产品固定使用 Cesium 1.122,1.122 的 Matrix3 没有 fromColumns 方法。可用的写法:
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、无地理坐标
“模型姿态对了,但整体偏移”通常是坐标问题,不是轴向问题。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;不要先怀疑轴向。”
使用提示: 先确认”哪根轴朝天”,再确认”模型落在哪个经纬度/高程”,最后才调材质。轴向、坐标、材质三件事分开验收,三维模型接入会快很多。