模型裁切 (Model Clipper)

• Summary: 使用 parameter.clippers 定义裁切盒，用于隐藏 (discard) 模型中特定区域的点云或网格。
• Schema: PBMClipperParameter 数组，包含变换矩阵和楼层索引。
• Concepts: Clipping Box (裁切盒), Matrix Transformation (矩阵变换), Negative Space (负空间).
• Configuration: five.model.clippers.
• Examples: 创建裁切盒并应用。

Schema

Definition: PBMClipperParameter

/** 模型裁切参数 */
interface PBMClipperParameter {
  /**
   * 裁切盒的变换矩阵。
   * @description
   * 定义了一个变换后的立方体空间。
   * 基础形状为边长为 1 的立方体，中心在 (0,0,0)，范围 [-0.5, 0.5]。
   * 凡是落在这个变换后立方体内部的模型点，都会被丢弃 (discard)。
   */
  clippingBoxMatrix: THREE.Matrix4;

  /**
   * (可选) 楼层索引。
   * @description
   * 如果指定，则裁切仅对该楼层的点云生效。
   * 如果未指定 (undefined)，则对所有楼层生效。
   */
  floorIndex?: number;
}
Copy

Concepts

Clipping Box (裁切盒)

Five 的裁切机制是基于负空间的：

• 默认情况下，所有模型点都是可见的。
• 当你添加一个 Clipper 时，你实际上是在定义一个“不可见区域”。
• 任何位于 Clipper 定义的 3D 盒体内部的点，都不会被渲染。

Matrix Transformation (矩阵变换)

Clipper 的几何定义依赖于 clippingBoxMatrix。

• shader 内部逻辑是将世界坐标系下的点，乘以 clippingBoxMatrix 的逆矩阵。
• 然后判断该点是否在 [-0.5, 0.5] 的单位立方体范围内。
• 这意味着你可以直接使用 THREE.Mesh (BoxGeometry 1x1x1) 的 matrix 属性作为 clippingBoxMatrix，所见即所得。

Configuration

你可以通过 five.model.clippers 属性来读写裁切配置。

属性	类型	说明
five.model.clippers	PBMClipperParameter[]	设置裁切参数数组。设置新数组会覆盖旧配置。

Examples

基础用法 (Basic Usage)

创建一个不可见的 Box，将其位置和大小作为裁切区域。

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

// 1. 创建一个辅助 Mesh 来定义裁切区域
// 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的
const clipperMesh = new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshBasicMaterial({ color: 0xff0000, wireframe: true })
);

// 2. 设置裁切盒的位置、旋转和缩放
clipperMesh.position.set(0, 1.5, 0); // 抬高位置
clipperMesh.scale.set(2, 3, 2);      // 设定大小为 2x3x2
clipperMesh.rotation.y = Math.PI / 4; // 旋转 45 度

// 更新矩阵，确保 .matrix 属性是最新的
clipperMesh.updateMatrix();

// (可选) 将辅助 Mesh 加入场景以便调试看到范围
five.scene.add(clipperMesh);

// 3. 应用裁切参数
five.model.clippers = [
  {
    clippingBoxMatrix: clipperMesh.matrix,
    // floorIndex: 0 // 可选：仅裁切第 0 层
  }
];

// 4. 触发重绘
five.needsRender = true;
Copy

动态更新 (Dynamic Update)

如果需要动态移动裁切盒，需要重新赋值 five.model.clippers 或手动触发更新机制（虽然 setter 会自动触发更新，但如果只修改数组内部对象可能需要重新赋值）。

function updateClipper(mesh: THREE.Mesh) {
  mesh.updateMatrix();

  // 重新赋值以触发 Five 内部的 setter 和 uniform 更新
  five.model.clippers = [{
    clippingBoxMatrix: mesh.matrix
  }];
}

// 在动画循环或交互事件中调用
// ...
Copy

Debugging

• 辅助显示: 始终建议在开发阶段将用于生成矩阵的 THREE.Mesh (Wireframe 模式) 添加到 five.scene 中，这样可以直观地看到裁切范围是否正确。
• 单位问题: 确保 BoxGeometry 构造时没有传入参数 (默认 1,1,1) 或者显式传入 (1, 1, 1)。如果使用了 (10, 10, 10) 的几何体，那么 scale 设置为 1 时实际裁切范围是 10，可能会导致误解。建议统一使用单位几何体 + scale 的方式。

Common Pitfalls

1. 矩阵未更新: 修改了 Mesh 的 position/scale 后忘记调用 updateMatrix()，导致裁切位置没变。
2. 几何体尺寸: 使用了非 1x1x1 的 BoxGeometry，导致裁切范围与 Mesh视觉大小不一致（Shader 始终假定是单位立方体）。
3. 楼层索引: 设置了错误的 floorIndex 导致裁切看起来没生效（因为该区域的点可能属于另一个 floorIndex）。
4. 坐标系: clippingBoxMatrix 是世界坐标系下的变换。如果模型本身有额外的父级变换（通常 Five 的模型直接在 Scene 下，或者是 Identity 变换），通常不需要额外处理。

Related

• Model: 模型模块概览。

---

tags: [裁切, 剖面, 隐藏部分模型, 开盖, 房屋剖面, clipper, model, cut, discard, geometry, clipping-box, section-view]
Copy