首页 / Cesium / API 文档

Globe

先看结论

地球本体。影像、地形、大气、光照和地表拾取都挂在它身上，通过 viewer.scene.globe 访问。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-28 · 引用本文

new Cesium.Globe(ellipsoid)

构造参数

参数	类型	默认	说明
`ellipsoid`	Ellipsoid	Ellipsoid.WGS84	参考椭球，决定经纬度到地心坐标的换算基准

实际使用时不需要自己构造：new Cesium.Viewer 和 new Cesium.CesiumWidget 都会建好 Globe。构造函数的唯一用途是替换成自定义椭球体的场景。

常用成员

成员	类型	默认	说明
`ellipsoid`	Ellipsoid	WGS84	椭球体，`globe.ellipsoid.cartographicToCartesian` 等换算入口
`imageryLayers`	ImageryLayerCollection	—	影像图层栈，只读引用，用 `add` 增删
`terrainProvider`	TerrainProvider	EllipsoidTerrainProvider	只读；换地形用 `scene.setTerrain`
`baseColor`	Color	(0, 0, 0.5, 1)	没有影像覆盖时的地表颜色
`show`	boolean	true	隐藏地球，只留图元与天空
`enableLighting`	boolean	false	按太阳方向计算昼夜明暗
`showGroundAtmosphere`	boolean	true	地面附近的大气雾化效果
`depthTestAgainstTerrain`	boolean	false	开启后被山体挡住的图元不再透出
`translucency.enabled`	boolean	false	地球半透明，可看到地下与背面
`maximumScreenSpaceError`	number	2	瓦片细分阈值，越小越清晰也越吃性能
`preloadAncestors` / `preloadSiblings`	boolean	true / false	是否预加载父级与同级瓦片，减少转动时的空洞
`cartographicLimitRectangle`	Rectangle	Rectangle.MAX_VALUE	只渲染该经纬范围内的地表，做区域场景时省算力

常用方法

方法	返回	说明
`pick(ray, scene)`	Cartesian3 \| undefined	射线与地表求交，有地形时返回真实地形交点
`getHeight(cartographic)`	number \| undefined	已加载地形的高度，未加载返回 undefined
`destroy()`	—	释放地表瓦片资源，由随 Viewer 一起销毁

示例

var globe = viewer.scene.globe;

// 深色底：没有影像的地方显示这个颜色
globe.baseColor = Cesium.Color.fromCssColorString('#14202e');

// 开启光照与地形遮挡，山体会挡住背后的点
globe.enableLighting = true;
globe.depthTestAgainstTerrain = true;

// 鼠标位置转真实地形坐标
var ray = viewer.camera.getPickRay(movement.position);
var point = globe.pick(ray, viewer.scene);
if (Cesium.defined(point)) {
  var carto = globe.ellipsoid.cartesianToCartographic(point);
  console.log(
    Cesium.Math.toDegrees(carto.longitude).toFixed(6),
    Cesium.Math.toDegrees(carto.latitude).toFixed(6),
    carto.height.toFixed(2)
  );
}

注意事项

terrainProvider 是只读属性，赋值不会生效；换地形请用 viewer.scene.setTerrain(new Cesium.Terrain(...))。
depthTestAgainstTerrain 打开后，没贴地的点和线会被地形吞掉，标注需要设置 heightReference 或 disableDepthTestDistance。
globe.pick 在影像与地形都没加载完时可能返回 undefined，交互逻辑要做空值判断。
cartographicLimitRectangle 只影响地表渲染，不影响图元，超出范围的图元仍然可见。

引用本文

经纬志（2026）。《Globe》。https://www.jingweizhi.com/cesium/api/globe.html（访问日期 2026-11-03）。