Cesium primitive放大后显示不全如何解决？

Question

在使用 Cesium 进行三维地理空间可视化时，开发者常遇到“Primitive 放大后显示不全”的问题。该问题通常表现为：当通过设置 `modelMatrix` 或相机视角放大某个 Primitive（如模型、多边形）时，部分几何体被裁剪或未能完整显示。造成此现象的主要原因包括视锥体裁剪（frustum culling）过于激进、包围盒（Bounding Volume）计算不准确或相机视角设置不当。解决方法包括：调整相机的 `near` 和 `far` 参数，扩大视锥范围；手动更新 Primitive 的包围盒信息；或使用 `Entity` API 替代 Primitive 以获得更高层次的自动管理能力。理解 Primitive 渲染机制与相机控制逻辑是解决此问题的关键。

Answer 1

1. 问题现象：Primitive 放大后显示不全

在使用 Cesium 进行三维地理空间可视化时，开发者常常遇到 Primitive 在放大后显示不全的问题。这种现象通常表现为：当通过设置 modelMatrix 或调整相机视角放大某个 Primitive（如模型、多边形）时，部分几何体被裁剪或未能完整显示。

该问题直接影响三维场景的可视化效果，尤其在需要高精度展示局部细节的场景中尤为明显。

2. 问题原因分析

该问题的产生主要由以下几个原因构成：

• 视锥体裁剪（Frustum Culling）过于激进：Cesium 渲染器为了优化性能，默认会对不在相机视锥体范围内的 Primitive 进行裁剪。当放大时，Primitive 可能部分或全部移出视锥范围，从而被裁剪。
• 包围盒（Bounding Volume）计算不准确：Primitive 的包围盒是用于判断其是否在视锥体内的依据。如果包围盒未能准确反映 Primitive 的实际空间范围，就会导致误裁剪。
• 相机视角设置不当：相机的 near 和 far 参数设置不合理，可能导致放大后模型被裁剪。

3. 解决方案详解

针对上述问题，我们可以从以下几个方面入手进行优化：

1. 调整相机的 near 和 far 参数：适当增大 far 值或减小 near 值，以扩大视锥体的范围，防止放大后模型被裁剪。
2. 手动更新 Primitive 的包围盒：在模型变换后，重新计算并设置包围盒，确保其准确反映模型的空间范围。
3. 使用 Entity API 替代 Primitive API：Entity 提供了更高层次的封装，自动处理包围盒更新、视锥裁剪等逻辑，更适合复杂场景。

以下是一个示例代码片段，展示如何调整相机的 near 和 far：

viewer.camera.near = 0.1;
viewer.camera.far = 10000000;
    

4. Primitive 与 Entity 的对比分析

为了更深入理解问题本质，我们对比一下 Primitive 和 Entity 的使用场景：

特性	Primitive	Entity
性能	高（适合大量静态对象）	较低（适合动态对象）
控制粒度	细（需手动管理）	粗（自动管理）
包围盒更新	需手动更新	自动更新
适用场景	静态模型、性能敏感场景	动态对象、交互式场景

5. 进阶建议与最佳实践

在实际开发中，建议遵循以下最佳实践：

• 优先使用 Entity 来管理动态或交互式对象。
• 对于需要高性能渲染的静态模型，使用 Primitive，但需注意手动更新包围盒。
• 在放大或变换模型后，调用 primitive.modelMatrix = ... 后应重新计算包围盒。

以下是一个使用 AxisAlignedBoundingBox 更新包围盒的示例：

const boundingBox = new Cesium.AxisAlignedBoundingBox(center, halfAxes);
primitive.appearance.material._boundingVolume = boundingBox;
    

6. 问题排查流程图

为帮助开发者系统性地排查该问题，我们提供如下流程图：

graph TD
            A[开始] --> B{是否使用Primitive API?}
            B -- 是 --> C[检查包围盒是否正确]
            B -- 否 --> D[使用Entity API，问题可能已解决]
            C --> E{包围盒是否准确?}
            E -- 是 --> F[检查相机near/far参数]
            E -- 否 --> G[手动更新包围盒]
            F --> H{是否仍被裁剪?}
            H -- 是 --> I[尝试扩大far值或减小near值]
            H -- 否 --> J[问题解决]