更新了版本
This commit is contained in:
yuding
89
docs/ENGINNE_3D/jumpToCamera-使用指南.md
Normal file
89
docs/ENGINNE_3D/jumpToCamera-使用指南.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# jumpToCamera 方法使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
`jumpToCamera` 是 BIM 引擎提供的一个视角跳转方法，允许开发者通过传入相机配置 JSON 数据，将 3D 视图快速定位到指定构件或特定视角。
|
||||
|
||||
## 方法签名
|
||||
|
||||
```javascript
|
||||
engine.engine.jumpToCamera(cameraData)
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
- `cameraData` - 相机配置 JSON 对象
|
||||
|
||||
### 返回值
|
||||
|
||||
- `true` - 跳转成功
|
||||
- `false` - 跳转失败
|
||||
|
||||
## 基本使用
|
||||
|
||||
```javascript
|
||||
// 跳转到指定视角
|
||||
engine.engine.jumpToCamera({
|
||||
type: "orthographic",
|
||||
position: { x: 229.68, y: 247.98, z: 233.79 },
|
||||
target: { x: -4.58, y: 13.72, z: -0.47 },
|
||||
orthographicHeight: 140.56
|
||||
});
|
||||
```
|
||||
|
||||
## 配合 getModelPosition 使用
|
||||
|
||||
```javascript
|
||||
// 1. 获取构件位置数据（返回的 modelJson 中包含 cameraRestorePose）
|
||||
const data = engine.engine.getModelPosition({
|
||||
url: "模型URL",
|
||||
ids: [465979]
|
||||
});
|
||||
|
||||
// 2. 使用返回的 cameraRestorePose 跳转视角
|
||||
if (data?.modelJson?.cameraRestorePose) {
|
||||
engine.engine.jumpToCamera(data.modelJson.cameraRestorePose);
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 调用前确保引擎已初始化
|
||||
2. 参数为 JSON 对象格式
|
||||
3. 数据可通过 `getModelPosition` 方法获取
|
||||
|
||||
## 完整示例
|
||||
|
||||
```javascript
|
||||
const engine = new BimEngine(container, { theme: 'dark' });
|
||||
|
||||
// 初始化引擎
|
||||
engine.engine.initialize({
|
||||
version: 'v2',
|
||||
showStats: false,
|
||||
showViewCube: true
|
||||
});
|
||||
|
||||
// 加载模型
|
||||
engine.engine.loadModel(['模型URL'], {
|
||||
position: [0, 0, 0],
|
||||
rotation: [0, 0, 0],
|
||||
scale: [1, 1, 1]
|
||||
});
|
||||
|
||||
// 获取构件位置并跳转
|
||||
const componentData = engine.engine.getModelPosition({
|
||||
url: "模型URL",
|
||||
ids: [465979]
|
||||
});
|
||||
|
||||
if (componentData?.modelJson?.cameraRestorePose) {
|
||||
const success = engine.engine.jumpToCamera(
|
||||
componentData.modelJson.cameraRestorePose
|
||||
);
|
||||
|
||||
if (success) {
|
||||
console.log('跳转成功');
|
||||
}
|
||||
}
|
||||
```
|
||||
225
docs/ENGINNE_3D/构件位置数据格式.md
Normal file
225
docs/ENGINNE_3D/构件位置数据格式.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# 构件位置与视角数据格式规范
|
||||
|
||||
## 概述
|
||||
|
||||
本文档定义了 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 数据格式 |
|
||||
Reference in New Issue
Block a user