怎么在 vtk.js 中将当前 3D 视图截图保存为 PNG 图片

一、为什么不建议直接读取 Canvas

很多刚从二维 Canvas 开发转到 WebGL 或 vtk.js 的开发者，习惯在点击“保存截图”按钮时直接对 DOM 中的 <canvas> 节点调用 canvas.toDataURL('image/png')。然而在实际运行中，这种做法往往只会导出纯黑色或完全透明的空白图片。

这一现象源于 WebGL 规范中的默认缓冲区管理机制。在浏览器渲染一帧时，GPU 将几何体、体渲染数据绘制到后台绘图缓冲区（DrawingBuffer）中，浏览器合成器（Compositor）随后抓取该缓冲区呈现在屏幕上。为了节约显存和提升合成性能，WebGL 上下文在创建时默认将 preserveDrawingBuffer 设置为 false。这意味着一旦当前帧被呈现在屏幕上，绘图缓冲区内的像素数据会立即被浏览器清空。

当用户在页面上点击按钮时，该点击事件属于之后的另一个 JavaScript 宏任务。此时 Canvas 底层的绘图缓冲区早已被重置，因此直接读取只能得到空像素。使用 vtk.js 官方提供的 captureImages() API，则能够在当前渲染通道完成绘制但未被清空的精确时刻完成数据捕获，从根本上保证截屏成功率。

二、使用 captureImages 导出 PNG 的核心实现

无论项目中是使用高度封装的 vtkGenericRenderWindow，还是直接使用 vtkRenderWindow，核心逻辑都是获取到渲染窗口实例后执行捕获。下面是完成截图导出的标准代码实现：

import vtkGenericRenderWindow from '@kitware/vtk.js/Rendering/Misc/GenericRenderWindow';

// 假设项目中已完成基础初始化
const genericRenderWindow = vtkGenericRenderWindow.newInstance();
genericRenderWindow.setContainer(document.getElementById('vtk-container'));
genericRenderWindow.resize();

const renderWindow = genericRenderWindow.getRenderWindow();

/**
 * 将当前 3D 视图截图并保存为本地 PNG 文件
 * @param {string} filename 保存的目标文件名
 */
async function saveSceneScreenshot(filename = 'vtk-view.png') {
  // 1. 强制刷新一帧，确保相机位置与几何状态为最新
  renderWindow.render();

  try {
    // 2. 调用 captureImages，指定 MIME 类型为 'image/png'
    // captureImages 返回包含各个视图 DataURL Promise 的数组
    const imagePromises = renderWindow.captureImages('image/png');
    
    // 3. 等待所有视图解析完成
    const images = await Promise.all(imagePromises);

    if (!images || images.length === 0 || !images[0]) {
      console.error('截图失败：未获取到有效的图像数据');
      return;
    }

    // 4. 获取主视图的 Base64 DataURL (格式形如 "data:image/png;base64,....")
    const dataURL = images[0];

    // 5. 创建虚拟 DOM 节点触发浏览器原生下载
    const downloadLink = document.createElement('a');
    downloadLink.href = dataURL;
    downloadLink.download = filename;
    document.body.appendChild(downloadLink);
    downloadLink.click();

    // 6. 清理临时节点
    document.body.removeChild(downloadLink);
  } catch (error) {
    console.error('导出 PNG 图片过程发生异常:', error);
  }
}

在这段代码中，renderWindow.captureImages('image/png') 接收一个可选的格式字符串，默认即为 image/png。该方法会遍历当前渲染窗口绑定的所有 OpenGL 视图，在下一个绘制周期将缓冲区数据转换为 Base64 编码的 DataURL，避免了开发者手动监听 WebGL 上下文事件的繁琐操作。

三、针对大分辨率场景的 Blob 流式优化

当三维视图分辨率较高（例如 4K 屏、Retina 视网膜屏或超大视口）时，导出的 Base64 字符串长度可能达到数兆甚至数十兆字节。Base64 编码相比原生二进制体积膨胀了约 33%，且直接将超长 DataURL 赋值给 a.href 容易引起页面短时掉帧，某些移动端浏览器甚至会限制超长 URL 的点击下载。

为了提高稳定性和内存效率，建议将获取到的 Base64 DataURL 转换为二进制的 Blob 对象，再通过 URL.createObjectURL() 触发下载，并在下载完成后显式释放内存地址：

/**
 * 将 Base64 DataURL 转换为二进制 Blob
 */
function dataURLToBlob(dataURL) {
  const parts = dataURL.split(';base64,');
  const mimeType = parts[0].split(':')[1];
  const binaryStr = window.atob(parts[1]);
  const length = binaryStr.length;
  const uint8Array = new Uint8Array(length);

  for (let i = 0; i < length; i++) {
    uint8Array[i] = binaryStr.charCodeAt(i);
  }

  return new Blob([uint8Array], { type: mimeType });
}

/**
 * 生产环境推荐：使用 Blob 触发大图下载并及时释放内存
 */
async function saveSceneScreenshotAsBlob(filename = 'scene-hd.png') {
  renderWindow.render();
  const images = await Promise.all(renderWindow.captureImages('image/png'));
  
  if (images.length > 0 && images[0]) {
    const blob = dataURLToBlob(images[0]);
    // 生成指向内存二进制数据的临时 Blob 链接
    const objectURL = URL.createObjectURL(blob);

    const downloadLink = document.createElement('a');
    downloadLink.href = objectURL;
    downloadLink.download = filename;
    document.body.appendChild(downloadLink);
    downloadLink.click();

    // 移除节点并立即回收 Blob URL，规避长生命周期单页应用的内存驻留
    document.body.removeChild(downloadLink);
    setTimeout(() => {
      URL.revokeObjectURL(objectURL);
    }, 100);
  }
}

四、背景透明度与高清晰度控制

在工程图纸导出、科研报告插图或设计软件中，往往需要将 3D 模型保存为透明背景的 PNG，以便在 PPT 或报告中与其他内容无缝叠加。vtk.js 的 captureImages 完全支持导出包含 Alpha 透明通道的 PNG 图片。

1. 控制背景透明

vtk.js 中渲染器的背景色通过 renderer.setBackground(r, g, b, a) 设置。要导出透明背景的截图，可以在捕获前临时将 Alpha 通道设置为 0，截图完成后恢复场景原来的背景色：

const renderer = genericRenderWindow.getRenderer();

// 临时保存当前背景色
const originalColor = renderer.getBackground();

// 将背景设置为完全透明 (RGBA，取值范围 0~1)
renderer.setBackground(0, 0, 0, 0);
renderWindow.render();

// 执行捕获
const images = await Promise.all(renderWindow.captureImages('image/png'));

// 恢复原始背景色并重绘
renderer.setBackground(originalColor);
renderWindow.render();

2. 保持视口物理分辨率

在高分屏（如苹果 Retina 屏幕）设备上，若直接截取可能发现细节不够锐利。这是因为浏览器默认有设备像素比（window.devicePixelRatio）。使用 vtkGenericRenderWindow 时，初始化配置会自动适配该比例；如果希望导出高于屏幕显示分辨率的超清大图，可以临时通过 openGLRenderWindow.setSize(width, height) 调整缓冲区分辨率，渲染抓取后再复原。

五、方案选型与技术对比

除 renderWindow.captureImages() 外，开发中也有人使用在初始化时开启 preserveDrawingBuffer: true 的方案。两种方案的综合对比如下：

六、关键避坑要点与注意事项

• 等待异步数据完全加载：如果场景中的几何模型或体数据是通过 vtkHttpDataSetReader 等异步加载的，必须在 reader.onDataLoaded 或数据构建就绪后再执行截图，否则导出的 PNG 将是一张未完成渲染的空画布。
• 防抖与并发控制：在 UI 界面提供导出按钮时，应在点击后禁用按钮并加上 Loading 状态，防止用户快速连击导致多次触发渲染和显存抓取，引发浏览器垃圾回收造成的卡顿。
• 必须保留 PNG 格式：如果将导出参数改为 image/jpeg，由于 JPEG 格式规范本身不支持 Alpha 通道，设置了透明背景的场景在导出后会自动被填充为黑色底色。如需背景透明，务必保持 image/png。
• 及时清理 ObjectURL：在单页面应用（SPA）中频繁截屏时，若采用 URL.createObjectURL 生成下载链接，必须在下载完成后使用 URL.revokeObjectURL(url) 释放引用，避免堆内存持续增长。