bim_engine/docs/ENGINNE_3D/构件位置数据格式.md

# 构件位置与视角数据格式规范

## 概述

本文档定义了 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 数据格式 |