Atlaslog / Field Notes / 3D & Cesium
Field note · 3D & Cesium
Camera goes below ground and the screen turns black
Quick answer
Holding right-drag upward tilts the view past the horizon until camera height becomes negative, logged as -1840.5 metres, and the frustum points at the geoid. Collision detection or its settings have been disabled.
Symptom
- camera.positionCartographic.height reads -1840.5 after a tilt.
- The screen goes black or shows the far side of the globe.
- Dragging further makes the earth appear from the opposite side.
Checklist
- Read viewer.scene.screenSpaceCameraController.enableCollisionDetection in the console.
- Listen to camera.changed and warn when height drops below 5 metres, printing the call stack.
- Grep for flyTo and setView and inspect the destination height literals, since 0 or negative values land underground.
- Check minimumZoomDistance, because a value of 0 lets the camera reach the surface.
- Check whether terrain is enabled, since collision then tests against terrain height.
Fix
Re-enable enableCollisionDetection, set minimumZoomDistance to 30, minimumTrackBallHeight to 10 and a positive pitch limit, and always give flyTo a positive height such as Cesium.Cartesian3.fromDegrees(116.391, 39.907, 1200) with pitch -35 degrees.
Code
var carto = viewer.camera.positionCartographic;
console.log(Cesium.Math.toDegrees(carto.longitude),
Cesium.Math.toDegrees(carto.latitude),
carto.height);
// 116.39 39.90 -1840.5viewer.camera.changed.addEventListener(function () {
var h = viewer.camera.positionCartographic.height;
if (h < 5) {
console.warn('相机高度过低', h);
}
});
viewer.camera.percentageChanged = 0.01;
Watch out
- Copying a free-camera example that sets enableCollisionDetection to false and never restoring it.
- Turning on depthTestAgainstTerrain and reading a black screen as an underground camera, when in fact clamped labels simply disappear.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Camera goes below ground and the screen turns black. https://www.jingweizhi.com/en/cookbook/cesium-camera-underground.html (accessed 2026-11-03).