225 lines
6.0 KiB
Markdown
225 lines
6.0 KiB
Markdown
# 构件位置与视角数据格式规范
|
||
|
||
## 概述
|
||
|
||
本文档定义了 BIM 引擎中构件位置查询（issueReport）返回的数据格式。该数据结构用于问题报告、构件定位、视角恢复等场景。
|
||
|
||
## 数据格式
|
||
|
||
### 完整数据结构
|
||
|
||
```typescript
|
||
interface ComponentPositionData {
|
||
/** 楼层/标高名称 */
|
||
Floor: string;
|
||
|
||
/** 轴线位置 */
|
||
Axis: string;
|
||
|
||
/** 构件唯一标识符 */
|
||
ElementId: number;
|
||
|
||
/** 构件名称（可能为空） */
|
||
ElementName: string;
|
||
|
||
/** 模型与视角数据 */
|
||
modelJson: ModelJson;
|
||
}
|
||
|
||
interface ModelJson {
|
||
/** 模型资源的 URL 地址 */
|
||
Url: string;
|
||
|
||
/** 构件 ID 数组 */
|
||
ids: number[];
|
||
|
||
/** 当前相机参数 */
|
||
camera: CameraConfig;
|
||
|
||
/** 相机恢复姿态（包含正交/透视模式） */
|
||
cameraRestorePose: CameraRestorePose;
|
||
}
|
||
```
|
||
|
||
## 字段详解
|
||
|
||
### 基础信息
|
||
|
||
| 字段 | 类型 | 描述 | 示例 |
|
||
|------|------|------|------|
|
||
| `Floor` | string | 构件所在的楼层或标高名称 | `"标高B1FL"` |
|
||
| `Axis` | string | 构件在平面图中的轴线位置 | `"C-D交5-6"` |
|
||
| `ElementId` | number | 构件在模型中的唯一标识符 | `465979` |
|
||
| `ElementName` | string | 构件名称，可能为空字符串 | `""` |
|
||
|
||
### modelJson 对象
|
||
|
||
#### Url
|
||
- **类型**: `string`
|
||
- **描述**: 模型资源的完整 URL 地址
|
||
- **示例**: `"https://lyz-1259524260.cos.ap-guangzhou.myqcloud.com/iflow/models/417664a3-76c8-4d94-9344-1337246a5d4e/"`
|
||
|
||
#### ids
|
||
- **类型**: `number[]`
|
||
- **描述**: 关联的构件 ID 数组，通常包含当前查询的构件 ID
|
||
- **示例**: `[465979]`
|
||
|
||
### Camera 配置
|
||
|
||
当前相机的位置和方向信息：
|
||
|
||
```typescript
|
||
interface CameraConfig {
|
||
position: Vector3; // 相机位置
|
||
forwardDirection: Vector3; // 相机前向方向（视线方向）
|
||
upDirection: Vector3; // 相机的上方向
|
||
}
|
||
|
||
interface Vector3 {
|
||
x: number;
|
||
y: number;
|
||
z: number;
|
||
}
|
||
```
|
||
|
||
**示例值**:
|
||
- **position**: `{"x": 229.68, "y": 247.98, "z": 233.79}` - 相机在世界坐标系中的位置
|
||
- **forwardDirection**: `{"x": -0.577, "y": -0.577, "z": -0.577}` - 相机朝向（单位向量）
|
||
- **upDirection**: `{"x": -0.408, "y": 0.816, "z": -0.408}` - 相机的上方向（单位向量）
|
||
|
||
### Camera Restore Pose（相机恢复姿态）
|
||
|
||
用于恢复特定视角的完整配置：
|
||
|
||
```typescript
|
||
interface CameraRestorePose {
|
||
type: "orthographic" | "perspective"; // 投影类型
|
||
position: Vector3; // 相机位置
|
||
rotation: Euler; // 欧拉角旋转
|
||
quaternion: Quaternion; // 四元数旋转
|
||
target: Vector3; // 目标点（观察中心）
|
||
zoom: number; // 缩放级别
|
||
orthographicHeight: number; // 正交相机的高度（仅正交模式）
|
||
}
|
||
|
||
interface Euler {
|
||
x: number; // 绕X轴旋转（弧度）
|
||
y: number; // 绕Y轴旋转（弧度）
|
||
z: number; // 绕Z轴旋转（弧度）
|
||
}
|
||
|
||
interface Quaternion {
|
||
x: number;
|
||
y: number;
|
||
z: number;
|
||
w: number;
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
|
||
| 字段 | 类型 | 描述 |
|
||
|------|------|------|
|
||
| `type` | string | 投影模式：`orthographic`（正交）或 `perspective`（透视） |
|
||
| `position` | Vector3 | 相机在世界坐标系中的位置 |
|
||
| `rotation` | Euler | 相机的欧拉角旋转（弧度） |
|
||
| `quaternion` | Quaternion | 相机的四元数旋转（更稳定的旋转表示） |
|
||
| `target` | Vector3 | 相机的观察目标点 |
|
||
| `zoom` | number | 缩放级别，1 为默认 |
|
||
| `orthographicHeight` | number | 正交投影下的视口高度（单位：世界坐标） |
|
||
|
||
## 使用场景
|
||
|
||
### 1. 问题报告定位
|
||
|
||
当用户在 BIM 模型中发现问题时，可以记录构件位置和当前视角，生成问题报告：
|
||
|
||
```typescript
|
||
// 获取构件位置数据
|
||
const positionData = engine.engine?.getModelPosition({
|
||
url: "https://.../model/",
|
||
ids: [465979]
|
||
});
|
||
|
||
// 提交到问题系统
|
||
issueReport.create({
|
||
title: "发现结构问题",
|
||
location: positionData
|
||
});
|
||
```
|
||
|
||
### 2. 视角恢复
|
||
|
||
通过 `cameraRestorePose` 数据，可以精确恢复到查看该构件时的视角：
|
||
|
||
```typescript
|
||
function restoreCamera(pose: CameraRestorePose) {
|
||
if (pose.type === 'orthographic') {
|
||
camera.setOrthographic(pose.orthographicHeight);
|
||
} else {
|
||
camera.setPerspective(fov);
|
||
}
|
||
|
||
camera.position.set(pose.position.x, pose.position.y, pose.position.z);
|
||
camera.lookAt(pose.target.x, pose.target.y, pose.target.z);
|
||
camera.zoom = pose.zoom;
|
||
}
|
||
```
|
||
|
||
### 3. 构件信息展示
|
||
|
||
展示构件的基础位置信息：
|
||
|
||
```typescript
|
||
const info = {
|
||
楼层: data.Floor,
|
||
轴线: data.Axis,
|
||
构件ID: data.ElementId,
|
||
构件名称: data.ElementName || "未命名构件"
|
||
};
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **坐标系**: 所有坐标数据均采用世界坐标系（World Coordinate System）
|
||
2. **单位**: 角度单位为弧度（radians），长度单位与模型单位一致（通常为毫米）
|
||
3. **空值处理**: `ElementName` 可能为空字符串，调用方需要做好默认值处理
|
||
4. **相机类型**: 根据 `cameraRestorePose.type` 判断当前是透视还是正交投影
|
||
5. **数据时效性**: 相机数据反映了查询瞬间的视角状态
|
||
|
||
## 相关 API
|
||
|
||
### 获取构件位置
|
||
|
||
```typescript
|
||
engine.engine?.getModelPosition(params: {
|
||
url: string;
|
||
ids: number[];
|
||
}): ComponentPositionData | null
|
||
```
|
||
|
||
**参数说明**:
|
||
- `url`: 模型的 URL 地址
|
||
- `ids`: 要查询的构件 ID 数组
|
||
|
||
**返回值**: 构件位置与视角数据，失败返回 `null`
|
||
|
||
### 示例调用
|
||
|
||
```typescript
|
||
const result = engine.engine?.getModelPosition({
|
||
url: "https://lyz-1259524260.cos.ap-guangzhou.myqcloud.com/iflow/models/417664a3-76c8-4d94-9344-1337246a5d4e/",
|
||
ids: [465979]
|
||
});
|
||
|
||
console.log('楼层:', result.Floor); // "标高B1FL"
|
||
console.log('轴线:', result.Axis); // "C-D交5-6"
|
||
console.log('构件ID:', result.ElementId); // 465979
|
||
console.log('相机位置:', result.modelJson.camera.position);
|
||
```
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| 1.0.0 | 2026-03-24 | 初始版本，定义 issueReport 数据格式 | |