SceneToFile 场景出图

把当前 Cesium 场景导出为图片文件：大图 PNG、缩略图 JPEG、指定尺寸 JPEG， 以及相机状态快照。四个函数均由 SDK 公共导出，本案例演示完整用法。

---

能力定位

场景出图适合：

• 大屏留档：把当前视角导出为高清 PNG 用于汇报材料；
• 场景预览：导出 1/3 尺寸缩略图用于列表展示；
• 业务截图：按指定宽高生成 JPEG dataURL，直接内嵌到弹窗或表单；
• 视角恢复：用 pickCamera 记录相机姿态，配合 BookMark 做场景书签。

公共 API

import { pickCamera, saveToFile, saveThumbnail, getSceneImage } from '@nexa/gis-cesium'

pickCamera(viewer.scene)
// → { heading, pitch, roll, x, y, z }

saveToFile(viewer.scene)          // 触发下载 scene.png（原分辨率 PNG）
saveThumbnail(viewer.scene)       // 触发下载 scene_thumb.jpg（原图 1/3 尺寸）

const url = await getSceneImage(viewer.scene, 540, 960)  // → JPEG dataURL

函数	输入	输出
pickCamera	Cesium.Scene	相机 heading/pitch/roll + 世界坐标
saveToFile	Cesium.Scene	触发下载 scene.png（PNG 原分辨率）
saveThumbnail	Cesium.Scene	触发下载 scene_thumb.jpg（1/3 尺寸）
getSceneImage	scene, height, width	Promise<string> JPEG dataURL

前置条件

SDK 的 CesiumViewer 默认开启 preserveDrawingBuffer: true（见 AirViewer.ts）， 因此 canvas.toDataURL() 可稳定截图。若自行用裸 Cesium.Viewer 创建，需在 contextOptions 中开启该选项，否则截图可能为空白。

完整示例

const nexaGis = new CesiumViewer('container')
const viewer = nexaGis.viewer
viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(106.455, 29.505, 9000),
  orientation: { heading: 0, pitch: Cesium.Math.toRadians(-60), roll: 0 },
})

// 导出大图并触发下载
saveToFile(viewer.scene)

// 导出缩略图
saveThumbnail(viewer.scene)

// 导出指定尺寸预览（回显到 <img>）
const url = await getSceneImage(viewer.scene, 540, 960)
previewImage.src = url

生命周期

四个函数均不持有运行期资源：下载完成后 URL.revokeObjectURL 由 saveToFile 内部释放；getSceneImage 返回的 dataURL 由调用方持有。示例不创建任何额外 实体资源，卸载时仅解除桥接即可。

验证命令

pnpm --filter @nexa/gis-cesium run typecheck
pnpm --filter @nexa/gis-cesium run test
pnpm --filter @nexa/gis-cesium run build:lib
pnpm --filter @nexa/gis-cesium run check:governance
pnpm lint