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

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

概述

本文档定义了 BIM 引擎中构件位置查询（issueReport）返回的数据格式。该数据结构用于问题报告、构件定位、视角恢复等场景。

数据格式

完整数据结构

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 配置

当前相机的位置和方向信息：

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（相机恢复姿态）

用于恢复特定视角的完整配置：

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 模型中发现问题时，可以记录构件位置和当前视角，生成问题报告：

// 获取构件位置数据
const positionData = engine.engine?.getModelPosition({
  url: "https://.../model/",
  ids: [465979]
});

// 提交到问题系统
issueReport.create({
  title: "发现结构问题",
  location: positionData
});

2. 视角恢复

通过 cameraRestorePose 数据，可以精确恢复到查看该构件时的视角：

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. 构件信息展示

展示构件的基础位置信息：

const info = {
  楼层: data.Floor,
  轴线: data.Axis,
  构件ID: data.ElementId,
  构件名称: data.ElementName || "未命名构件"
};

注意事项

1. 坐标系: 所有坐标数据均采用世界坐标系（World Coordinate System）
2. 单位: 角度单位为弧度（radians），长度单位与模型单位一致（通常为毫米）
3. 空值处理: ElementName 可能为空字符串，调用方需要做好默认值处理
4. 相机类型: 根据 cameraRestorePose.type 判断当前是透视还是正交投影
5. 数据时效性: 相机数据反映了查询瞬间的视角状态

相关 API

获取构件位置

engine.engine?.getModelPosition(params: {
  url: string;
  ids: number[];
}): ComponentPositionData | null

参数说明:

• url: 模型的 URL 地址
• ids: 要查询的构件 ID 数组

返回值: 构件位置与视角数据，失败返回 null

示例调用

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 数据格式