Tools API

u-space 提供了一组实用工具类，包括测量、剖切和标注功能。

MeasureTool

用于 3D 场景中的距离测量、面积测量和角度测量，测量结果会以可视化线条渲染到场景中。

import { MeasureTool } from 'u-space';

const measureTool = new MeasureTool(viewer.scene);

measureDistance(pointA, pointB, options?)

测量两点之间的距离，并在场景中绘制连线。

const result = measureTool.measureDistance(
  { x: 0, y: 0, z: 0 },
  { x: 5, y: 0, z: 5 },
  { lineColor: 0xffff00 },
);
console.log(result.value, result.unit); // 7.071 m

measureArea(points, options?)

测量由 3 个或更多共面点围成的多边形面积。

const result = measureTool.measureArea([
  { x: 0, y: 0, z: 0 },
  { x: 5, y: 0, z: 0 },
  { x: 5, y: 0, z: 5 },
  { x: 0, y: 0, z: 5 },
], { lineColor: 0x00ff00 });
console.log(result.value, result.unit); // 25 m²

measureAngle(pointA, vertex, pointC, options?)

测量以中间点为顶点的夹角（单位：度）。

const result = measureTool.measureAngle(
  { x: 3, y: 0, z: 0 },
  { x: 0, y: 0, z: 0 },
  { x: 0, y: 0, z: 3 },
);
console.log(result.value, result.unit); // 90 °

MeasureResult

所有测量方法返回 MeasureResult 对象：

属性	类型	说明
id	string	测量的唯一标识。
type	string	'distance' / 'area' / 'angle'。
value	number	测量值。
unit	string	单位（m、m²、°）。
points	Vector3[]	测量点坐标。
object	Group	场景中的可视化对象。

MeasureStyleOptions

属性	类型	默认值	说明
lineColor	ColorRepresentation	因方法而异	线条颜色。

管理方法

measureTool.get('measure_dist_0');  // 获取指定测量
measureTool.remove('measure_dist_0'); // 移除指定测量
measureTool.removeAll();              // 清除全部
measureTool.getAll();                 // 获取所有测量结果
measureTool.dispose();                // 释放资源

---

ClippingTool

提供剖切面和剖切盒功能，基于 WebGPU 的 ClippingGroup 实现。需要被剖切的对象必须是 ClippingGroup 的子节点。

import { ClippingTool } from 'u-space';

const clippingTool = new ClippingTool(viewer.scene);

// 将场景中已有的物体移入 ClippingGroup，使其受剖切影响
clippingTool.attach();

attach() / detach()

attach() 将场景根节点的所有子对象移入内部的 ClippingGroup，使其受剖切面影响。detach() 反向操作，将对象移回场景根节点。

也可以手动将对象添加到 clippingTool.group 中：

clippingTool.group.add(myModel); // 仅 myModel 受剖切

addPlane(id, options?)

添加一个剖切面。

clippingTool.addPlane('cutY', {
  normal: { x: 0, y: -1, z: 0 },  // 法线方向
  constant: 1.5,                    // 距离原点的偏移
  showHelper: true,                 // 显示 Helper
  helperSize: 5,
  helperColor: 0xff0000,
});

ClippingPlaneOptions

属性	类型	默认值	说明
normal	{x, y, z}	{x:0, y:-1, z:0}	法线方向。
constant	number	0	距原点偏移。
showHelper	boolean	false	是否显示 PlaneHelper。
helperSize	number	5	Helper 尺寸。
helperColor	ColorRepresentation	0xff0000	Helper 颜色。

addBox(id, box, options?) / addBoxFromObject(id, object, padding?, options?)

添加由 6 个面组成的剖切盒。

import { Box3 } from 'three/webgpu';

// 从 Box3 创建
const box = new Box3().setFromObject(myModel);
clippingTool.addBox('clipBox', box);

// 从对象创建（带边距）
clippingTool.addBoxFromObject('clipBox', myModel, 0.5);

动态调整

clippingTool.setPlaneConstant('cutY', 2.0); // 修改剖切位置
viewer.render();

Helper 控制

clippingTool.showHelper('cutY', 5, 0xff0000);
clippingTool.hideHelper('cutY');

管理方法

clippingTool.get('cutY');       // 获取 Plane 对象
clippingTool.removePlane('cutY'); // 移除单个
clippingTool.removeBox('clipBox'); // 移除剖切盒（6 个面）
clippingTool.removeAll();          // 移除全部
clippingTool.enable();             // 启用剖切
clippingTool.disable();            // 禁用剖切
clippingTool.dispose();            // 释放资源（对象移回场景根节点）

---

AnnotationManager

管理 3D 标注，支持引线标注和 HTML 标签。配合 CSSRenderer 使用可实现 HTML 浮动标签。

import { AnnotationManager } from 'u-space';

const annotationManager = new AnnotationManager(viewer.scene);

setCSSObjectFactory(factory)

设置 CSS 对象工厂函数（来自 CSSRenderer），使标注可渲染为 CSS 叠加元素。

annotationManager.setCSSObjectFactory(
  (el) => viewer.cssRenderer.createCSS2DObject(el),
);

add(id, options)

添加一个标注。

annotationManager.add('label-01', {
  position: { x: 0, y: 3, z: 0 },
  content: '<b>设备 A</b><br>温度: 25°C',
  labelOffset: { x: 0, y: 2, z: 0 },
  showLeaderLine: true,
  lineColor: 0xffffff,
  labelStyle: {
    background: 'rgba(0, 0, 0, 0.8)',
    padding: '8px 12px',
    borderRadius: '6px',
  },
});

AnnotationOptions

属性	类型	默认值	说明
position	{x, y, z}	—	标注锚点位置。
content	string	—	HTML 内容。
labelOffset	{x, y, z}	{0, 2, 0}	标签相对锚点的偏移。
showLeaderLine	boolean	true	是否显示引线。
lineColor	ColorRepresentation	0xffffff	引线颜色。
labelStyle	AnnotationLabelStyle	—	自定义 CSS 样式。

addText(text, position, options?)

快捷添加纯文本标注。

annotationManager.addText('入口', { x: 5, y: 0, z: 0 });

更新与控制

annotationManager.updateContent('label-01', '温度: 30°C');
annotationManager.updatePosition('label-01', { x: 1, y: 3, z: 0 });
annotationManager.show('label-01');
annotationManager.hide('label-01');
annotationManager.showAll();
annotationManager.hideAll();

管理方法

annotationManager.get('label-01');   // 获取标注对象
annotationManager.remove('label-01'); // 移除标注
annotationManager.removeAll();        // 移除全部
annotationManager.keys();             // 获取所有 ID
annotationManager.size;               // 标注数量
annotationManager.dispose();          // 释放资源