Cesium进阶教程：巧用PolygonGeometry与ArcType实现全球行政区高亮蒙版

1. 从“一张蒙版”说起：为什么你的全球覆盖总是不对劲？

大家好，我是老张，一个在三维GIS和Cesium里摸爬滚打了十来年的老码农。今天咱们不聊那些花里胡哨的粒子效果或者复杂着色器，就聊一个看似简单，但几乎每个做Cesium地图应用的朋友都会踩的坑：怎么给地球“盖”上一层半透明的蒙版，然后只把特定的行政区“挖”出来高亮显示？

听起来是不是挺简单的？不就是画个覆盖全球的矩形，然后抠掉几个洞嘛。但当你兴冲冲地写下代码，用一个从[-180, 90]到[180, -90]的矩形去覆盖地球时，你会发现——啥也没发生！地图干干净净，你的蒙版仿佛隐身了。我第一次遇到这问题时，也懵了半天，对着屏幕怀疑人生。

这背后的原因，恰恰是Cesium三维世界和我们二维平面思维的一个巨大差异。在Cesium里，地球不是一个平面，而是一个椭球体（WGS84）。当你指定一个覆盖全球的矩形顶点时，这些顶点在地球曲面上其实连成了一条“线”，而不是一个“面”。Cesium的渲染引擎很聪明，它会优先渲染面积较小的那个面，而你这个“全球矩形”在球面上计算出的面积趋近于零，所以它直接被忽略了，根本不会渲染出来。

那怎么办？难道要画一个极其复杂的、完全贴合地球曲面的多边形吗？当然不用。老司机们有一个经典且优雅的解决方案：把地球“劈”成两半。不是真的劈开，而是在逻辑上，我们分别绘制东半球和西半球两个多边形。这样，每个多边形在球面上都是一个实实在在的、有面积的面片，渲染引擎就能正确识别并绘制了。这个思路，就是我们实现全球蒙版的基石。

2. 庖丁解牛：PolygonGeometry与PolygonHierarchy的挖孔艺术

解决了覆盖的问题，接下来就是“挖孔”了。我们要在蒙版上，把中国、美国或者其他任何行政区的形状给镂空，让底层地图透出来。这就要请出我们今天的主角之一：Cesium.PolygonHierarchy。

2.1 PolygonHierarchy：不只是点数组，更是层级关系

很多新手会把PolygonGeometry的polygonHierarchy参数简单理解为一个顶点数组。这其实只对了一半。PolygonHierarchy的精髓在于“层级”（Hierarchy）。它允许你定义多边形的外环和内环（洞）。

// 一个简单的带孔多边形示例 const polygonHierarchy = new Cesium.PolygonHierarchy([ // 外环顶点：一个大矩形 Cesium.Cartesian3.fromDegrees(-110.0, 40.0), Cesium.Cartesian3.fromDegrees(-100.0, 40.0), Cesium.Cartesian3.fromDegrees(-100.0, 30.0), Cesium.Cartesian3.fromDegrees(-110.0, 30.0) ], [ // 内环（洞）顶点：内部一个小矩形 new Cesium.PolygonHierarchy([ Cesium.Cartesian3.fromDegrees(-108.0, 38.0), Cesium.Cartesian3.fromDegrees(-102.0, 38.0), Cesium.Cartesian3.fromDegrees(-102.0, 32.0), Cesium.Cartesian3.fromDegrees(-108.0, 32.0) ]) ]);

在上面的代码里，我们定义了一个大的四边形作为外环（蒙版），又定义了一个小的四边形作为内环（要挖掉的区域）。Cesium在渲染时，会自动将内环区域处理为透明空洞。这就是我们实现行政区划高亮的核心理念：用一个巨大的、覆盖全球的多边形作为外环，然后把每一个行政区的边界坐标作为内环传进去。

2.2 实战：构建全球蒙版与挖孔

理论说再多不如一行代码。我们直接上干货，看看如何结合“东西半球”思路和PolygonHierarchy来实现功能。

function createGlobalHighlightMask(viewer, regionBoundaries) { // 1. 定义西半球多边形顶点（经度-180到0附近） // 注意：纬度范围我们用了-60到60，原因后面会细说 const westPositions = Cesium.Cartesian3.fromDegreesArray([ -0.00001, 60, // 靠近本初子午线，北纬60度 -0.00001, -60, // 靠近本初子午线，南纬60度 -180, -60, // 西经180度，南纬60度 -180, 60, // 西经180度，北纬60度 -0.00001, 60 // 闭合多边形 ]); // 2. 定义东半球多边形顶点（经度0到180附近） const eastPositions = Cesium.Cartesian3.fromDegreesArray([ 0.00001, 60, 0.00001, -60, 180, -60, 180, 60, 0.00001, 60 ]); // 3. 将行政区边界数据转换为内环（洞）的 PolygonHierarchy 数组 const holes = regionBoundaries.map(boundary => { // 假设 boundary 是每个行政区的经纬度坐标数组 [[lng, lat], ...] const positions = Cesium.Cartesian3.fromDegreesArray(boundary.flat()); return new Cesium.PolygonHierarchy(positions); }); // 4. 创建西半球的 PolygonGeometry，包含所有挖孔 const westGeometry = new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy(westPositions, holes), arcType: Cesium.ArcType.GEODESIC, // 关键参数！ vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT }); // 5. 创建东半球的 PolygonGeometry，同样包含所有挖孔 const eastGeometry = new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy(eastPositions, holes), arcType: Cesium.ArcType.GEODESIC, vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT }); // 6. 创建 GeometryInstance 和 Primitive 进行渲染 const westInstance = new Cesium.GeometryInstance({ geometry: westGeometry }); const eastInstance = new Cesium.GeometryInstance({ geometry: eastGeometry }); const material = new Cesium.Material({ fabric: { type: 'Color', uniforms: { color: new Cesium.Color(0.0, 0.4, 0.8, 0.3) // 半透明蓝色蒙版 } } }); const appearance = new Cesium.MaterialAppearance({ material }); const primitive = new Cesium.GroundPrimitive({ geometryInstances: [westInstance, eastInstance], appearance: appearance }); viewer.scene.primitives.add(primitive); return primitive; }

这段代码就是完整的核心实现。你只需要准备好你的行政区划数据（regionBoundaries），调用这个函数，一个带有高亮挖孔效果的全球蒙版就出现了。这里有几个细节我踩过坑，特别提醒你注意：

1. 东西半球分割线：我们在本初子午线（0度经线）两侧用了-0.00001和0.00001这样极其接近的值，而不是直接用0。这是为了避免在精确的0度经线上可能出现的三角面片剖分奇异问题，让分割更稳定。
2. 纬度范围：你肯定注意到了，我用的纬度是-60到60，而不是从南极到北极的-90到90。为什么用60度就能覆盖全球？这就要引出我们今天另一个至关重要的概念——ArcType。

3. 灵魂参数ArcType：GEODESIC与RHUMB的魔法与陷阱

ArcType是PolygonGeometry和PolylineGeometry的一个属性，它决定了Cesium如何在地球曲面上连接你给出的两个点。它主要有两个选项：Cesium.ArcType.GEODESIC（测地线，默认值）和Cesium.ArcType.RHUMB（恒向线）。这个选择，直接导致了我们用-60到60的纬度就能“骗过”眼睛，实现全球覆盖的视觉效果。

3.1 GEODESIC（测地线）：球面上的“最短路径”

你可以把GEODESIC理解为地球表面两点之间的“最短空中直线”。比如从北京飞往纽约，飞机会选择一条经过北极附近的弧形航线，而不是沿着纬线直飞，因为那条弧形航线才是大圆航线，距离最短。

在蒙版构建中，GEODESIC做了什么？当我们用GEODESIC模式绘制一个从[-180, 60]到[180, 60]的边时，Cesium不会傻傻地在纬度60度这条线上画一条直线。它会计算这条边在球面上的测地线。由于经度从-180度到180度，跨越了整个360度，这条测地线会沿着球面“绕行”一周。更重要的是，Cesium的三角剖分算法在遇到这种环绕球体的大多边形时，会自动将缺口闭合。

想象一下：你在地球仪上，沿着北纬60度圈贴了一个窄窄的纸条（从西经180度贴到东经180度）。由于纸条是沿着球面贴的，它和北极点之间会形成一个“碗状”的缺口。GEODESIC算法会智能地生成三角面片，把这个“碗”的底面（也就是北极区域）给封上。同理，在南纬60度圈以下的部分也会被自动封上。所以，你只画了-60度到60度之间的带子，但Cesium帮你把两极的“盖子”都补全了，最终视觉效果就是一个包裹全球的完整蒙版。

这就是为什么代码里纬度只用-60到60就够了。你甚至可以试试换成-30到30，蒙版依然会覆盖全球（虽然理论上三角面片在极区会拉伸得更厉害）。GEODESIC的这种特性，让我们可以用一个相对简单的多边形来近似表示复杂的球面覆盖，性能好，效果也自然。

3.2 RHUMB（恒向线）：航海家的“等角线”

RHUMB是另一个世界。它保持恒定的方位角。在经典的墨卡托投影地图上，RHUMB线显示为一条直线。古代航海家没有GPS，靠罗盘导航，保持固定航向行驶的路径就是恒向线。

RHUMB在蒙版中会怎样？如果我们把上面代码中的arcType改成Cesium.ArcType.RHUMB，情况就完全不同了。Cesium会在墨卡托投影的空间里进行线性插值。这时，从[-180, 60]到[180, 60]的边，就会真的被画成一条平行于赤道的直线（在投影空间里）。它不会自动去环绕球面，更不会去补全极区。

那么，用RHUMB模式画一个[-60, 60]的矩形，最终你得到的就真的只是一个环绕地球中低纬度的“腰带”，北极和南极区域会是空洞，地图会露出来。这对于需要精确控制覆盖范围（比如只高亮显示热带地区）的场景可能有用，但对于我们“全球蒙版”的需求，就完全不对了。

3.3 对比与选型：一张表看懂区别

为了更直观，我把两者的核心差异总结成了下面这个表格：

所以，答案很明显了：要实现全球行政区高亮蒙版，ArcType.GEODESIC是我们的不二之选。它利用球面几何的特性，用最小的数据量（一个环状带）和最高的效率，实现了视觉上的全球覆盖，完美契合我们的需求。

4. 性能优化与实战进阶：处理大量行政区划数据

理论很美，但现实往往骨感。当你真的拿到一份包含成百上千个行政区划（比如中国所有县级行政区）的边界数据时，直接把它们全部作为holes塞进一个PolygonGeometry，很可能会导致浏览器卡顿甚至崩溃。因为每一个洞都是一个复杂的多边形，计算量和渲染压力巨大。

4.1 数据分层与视图裁剪

我的经验是，不要一次性渲染所有细节。这是三维GIS性能优化的黄金法则。

1. LOD（细节层次）：为不同层级的行政区划准备不同精度的边界数据。当镜头拉远看全省时，使用粗略的省级边界；当镜头拉近到某个城市时，再加载并渲染该城市下精细的区县级边界。Cesium的Cesium3DTileset是干这个的专家，但对于我们这种自定义蒙版，可能需要自己实现视图距离判断和动态加载逻辑。
2. 视图裁剪：只渲染当前相机视锥体范围内的行政区划。你可以用Cesium.BoundingSphere或Cesium.Occluder来快速判断一个行政区的大致范围是否在视野内。如果不在，就暂时不把它加入挖孔的holes数组。这能极大减少每帧需要处理的几何数据量。

function getVisibleRegions(viewer, allRegions) { const camera = viewer.camera; const frustum = camera.frustum; const visibleRegions = []; allRegions.forEach(region => { // 假设 region.boundingSphere 是该行政区边界的包围球 if (Cesium.IntersectionTests.frustumIntersectsSphere(frustum, region.boundingSphere)) { visibleRegions.push(region); } }); return visibleRegions; } // 在相机移动事件中更新蒙版 viewer.camera.moveEnd.addEventListener(function() { const visibleRegions = getVisibleRegions(viewer, allRegionData); updateMaskWithHoles(visibleRegions); // 重新创建只包含可见区蒙版的函数 });

4.2 几何合并与实例化

在我们的代码中，我们创建了两个GeometryInstance（东半球和西半球）。如果行政区划非常多且更新频繁，反复创建和销毁GroundPrimitive开销不小。一个更高级的优化是使用Cesium.Primitive配合GeometryInstance的实例化渲染。

我们可以为蒙版本身创建一个静态的GeometryInstance，而为所有行政区划的“洞”创建另一个GeometryInstance。通过给不同实例赋予不同的颜色（蒙版实例有颜色，洞实例为完全透明），并利用深度测试和模板测试，也可以实现类似挖孔的效果。这种方式将计算转移到了GPU端，对于动态变化的区域有更好的性能。不过实现起来更复杂，涉及到Appearance的renderState配置，属于高阶玩法，这里先不展开。

4.3 数据格式与预处理

行政区的边界数据通常是GeoJSON或者KML格式。我强烈建议在服务器端或数据预处理阶段完成繁重的计算工作：

• 坐标简化：使用道格拉斯-普克算法之类的工具，在保持形状大致不变的前提下，大幅减少多边形边界点的数量。一个省级边界从几千个点简化到几百个点，视觉差异很小，但性能提升是数量级的。
• 三角剖分：对于特别复杂的行政区（比如有飞地、中间有湖需要嵌套挖洞的），可以预先将多边形三角剖分好。Cesium虽然能实时处理，但预处理能减轻客户端压力。
• 瓦片化：如果做全球范围的应用，可以考虑将蒙版和行政区数据也做成瓦片，像在线地图一样按需加载。

5. 常见坑点与调试技巧

就算掌握了上面的所有原理，实际开发中还是难免遇到各种妖魔鬼怪。我分享几个我踩过的坑和解决办法。

坑点一：蒙版闪烁或Z-fighting有时候蒙版会和底层地形或地图瓦片“打架”，一闪一闪的。这是因为它们的深度（距离相机的距离）太接近了。解决方法是给GroundPrimitive设置一个合适的height偏移，或者调整tileLoadPriority。更根本的方法是确保你的蒙版几何完全贴合地表（GroundPrimitive就是干这个的），并使用Cesium.HeightReference.CLAMP_TO_GROUND。

坑点二：跨日期变更线的行政区显示异常就是180度经线附近，比如俄罗斯东部或者斐济这些地方。当你用GEODESIC时，Cesium能很好处理从-180到180的过渡。但你的行政区数据本身如果横跨了这条线，在数据预处理时就需要小心。一个常见的做法是，将跨180度经线的多边形在经度上进行分割，比如将[170, 60, -170, 60]这样的数据，拆分成[170, 60, 180, 60]和[-180, 60, -170, 60]两部分，再分别处理。

坑点三：性能突然下降打开浏览器开发者工具的Performance面板，录制几秒操作。你会发现瓶颈可能不在JavaScript执行，而在GPU渲染或者图层合成。这时候，检查一下：

• 是不是行政区边界点数太多了？用简化工具。
• 蒙版的材质是不是太复杂？半透明颜色混合（Blending）开销很大，如果不需要半透明，尽量用不透明颜色。
• 是否开启了阴影？GroundPrimitive接收和投射阴影的计算量很大，非必要可以关掉。

调试利器：Cesium Inspector一定要善用Cesium自带的调试工具。在浏览器控制台输入viewer.extend(Cesium.viewerCesiumInspectorMixin)，然后刷新页面，界面会出现一个调试按钮。打开它，你可以：

• 查看当前场景中所有的Primitive和数量。
• 查看帧率、绘制调用（Draw Call）次数。一个优化的目标是尽量减少Draw Call。
• 高亮显示被裁剪的几何体，帮你检查视图裁剪是否生效。

实现全球行政区高亮蒙版，就像是在三维地球这个曲面上完成一次精妙的剪纸艺术。PolygonGeometry是你的剪刀，PolygonHierarchy定义了剪纸的轮廓和要挖去的图案，而ArcType.GEODESIC则是那把让剪刀能沿着球面自然弯曲的灵巧工具。理解它们背后的球面几何原理，不仅能帮你解决眼前“为什么画不出来”的问题，更能让你在以后面对更复杂的三维空间可视化挑战时，心中有图，手下不慌。