获取屏幕像素 (Get Screen Pixels)

• Summary: five.getPixels 方法用于获取 Five 画布指定区域的像素数据（RGBA），常用于实现放大镜、取色器或截图功能。
• Schema: GetPixelsOptions。
• Concepts: WebGLRenderTarget, gl.readPixels, Magnifier。
• Examples: 放大镜实现、获取中心点颜色。

Schema

Definition: GetPixelsOptions

five.getPixels 支持两种调用方式：参数列表（旧版）和对象参数（推荐）。

推荐调用方式

five.getPixels(options: GetPixelsOptions): Uint8Array | Uint8ClampedArray;

interface GetPixelsOptions {
  /** 获取像素区域的起始坐标 x (基于 Canvas 左下角，除非 flipY 为 true) */
  x: number;
  /** 获取像素区域的起始坐标 y */
  y: number;
  /** 获取像素区域的宽度 */
  width: number;
  /** 获取像素区域的高度 */
  height: number;
  /** 获取区域的像素比 (默认 1) */
  pixelRatio?: number;
  /** 是否显示辅助元素 (默认 false) */
  helperVisible?: boolean;
  /** 是否跳过全景图渲染 (仅渲染模型) */
  skipPanorama?: boolean;
  /** 是否 Y 轴翻转 (通常设为 true 以匹配 Canvas 2D 坐标系) */
  flipY?: boolean;
  /** 存储数组 (可选，复用数组以提升性能) */
  buffer?: Uint8Array | Uint8ClampedArray;
}
Copy

简写调用方式 (不推荐)

five.getPixels(
  x: number,
  y: number,
  width: number,
  height: number,
  pixelRatio?: number,
  flipY?: boolean,
  buffer?: Uint8Array | Uint8ClampedArray
): Uint8Array | Uint8ClampedArray;
Copy

Concepts

坐标系统 (Coordinate System)

• WebGL 坐标系: 原点在左下角。
• Canvas 2D 坐标系: 原点在左上角。
• flipY 参数: 当你需要将数据绘制到 Canvas 2D Context (putImageData) 时，通常需要将 flipY 设置为 true，否则图像是倒置的。

性能注意事项 (Performance)

• five.getPixels 会触发 WebGL 的 readPixels 操作，这是一个同步且耗时的操作（会阻塞 GPU 流水线）。
• 优化建议:
  • 避免在每一帧都调用。
  • 尽量复用 buffer 数组，避免频繁创建新的 Uint8Array。
  • 仅获取需要的区域（width 和 height 越小越好）。

Examples

放大镜 (Magnifier)

这是一个经典的放大镜实现示例。通过获取鼠标周围的像素，并以更高的 pixelRatio 重新渲染，从而获得清晰的放大效果。

import * as THREE from 'three';
import { Five } from '@realsee/five';

// 假设有一个用于显示的 canvas
const magnifierCanvas = document.getElementById('magnifier-canvas') as HTMLCanvasElement;
const ctx = magnifierCanvas.getContext('2d')!;
const magnifierSize = 200; // 放大镜尺寸 200px
const scale = 2; // 放大倍数

// 预先创建 Buffer 以提升性能
const pixelWidth = magnifierSize * scale;
const pixelHeight = magnifierSize * scale;
let magnifierImageData = ctx.createImageData(pixelWidth, pixelHeight);

five.on('gesture.mousemove', (event) => {
  // 1. 获取鼠标在 Canvas 上的坐标
  const mouse = event.pointers[0]?.coords;
  if (!mouse) return;

  // 转换归一化坐标 (-1 到 1) 到 像素坐标
  const renderSize = five.getSize(new THREE.Vector2());
  const x = (mouse.x + 1) / 2 * renderSize.x;
  const y = (mouse.y + 1) / 2 * renderSize.y;

  // 2. 获取像素数据
  // 注意：我们以更高的分辨率 (pixelRatio * scale) 渲染小区域，从而获得“无损”放大效果
  const pixelRatio = five.renderer?.getPixelRatio() ?? 1;
  const targetPixelRatio = Math.ceil(pixelRatio * scale);

  five.getPixels({
    x: x - magnifierSize / 2, // 居中
    y: y - magnifierSize / 2,
    width: magnifierSize,
    height: magnifierSize,
    pixelRatio: targetPixelRatio,
    flipY: true, // 翻转以适配 Canvas 2D
    buffer: magnifierImageData.data, // 复用 buffer
    helperVisible: false, // 隐藏辅助线等干扰元素
  });

  // 3. 将数据绘制到放大镜 Canvas 上
  // 需要调整 Canvas 尺寸以匹配数据
  magnifierCanvas.width = pixelWidth;
  magnifierCanvas.height = pixelHeight;
  ctx.putImageData(magnifierImageData, 0, 0);

  // 4. 更新放大镜位置 (CSS)
  magnifierCanvas.style.left = `${x - magnifierSize / 2}px`;
  magnifierCanvas.style.top = `${renderSize.y - y - magnifierSize / 2}px`; // 注意 Y 轴方向
});
Copy

获取中心点颜色 (Color Picker)

获取屏幕中心点的颜色。

function getCenterColor(five: Five) {
  const size = five.getSize(new THREE.Vector2());
  const x = size.x / 2;
  const y = size.y / 2;

  const pixels = five.getPixels({
    x: x,
    y: y,
    width: 1,
    height: 1,
    flipY: true
  });

  const r = pixels[0];
  const g = pixels[1];
  const b = pixels[2];
  const a = pixels[3];

  return `rgba(${r}, ${g}, ${b}, ${a / 255})`;
}
Copy

Common Pitfalls

1. 坑点1: 图像倒置:

   • 现象: 获取到的图像是上下颠倒的。
   • 解决: 检查 flipY 参数。如果直接用于 Canvas 2D putImageData，通常需要 flipY: true。

2. 坑点2: 性能卡顿:

   • 现象: 开启放大镜后，页面帧率显著下降。
   • 解决:
     • 确保使用了 buffer 参数复用内存。
     • 检查 width 和 height 是否过大。
     • 确保 pixelRatio 不要设置得过高（例如不要超过 4）。

3. 坑点3: 渲染内容不全:

   • 现象: 放大镜里只有背景，没有模型。
   • 解决: 检查 skipPanorama 参数。如果需要看全景图，确保设为 false（默认）。如果只想看模型细节（如在 Floorplan 模式），可以设为 true。

Related

• API Reference: Five 核心 API 说明。

---

tags: [截图, 放大镜, 取色器, 颜色拾取, 像素数据, getPixels, magnifier, screenshot, pixel, canvas, screen-capture, color-picker]
Copy