408 lines
9.1 KiB
Markdown
408 lines
9.1 KiB
Markdown
# 放置区域 API 迁移指南
|
||
|
||
## 概述
|
||
|
||
新的放置区域系统使用**参数化墙面定义**替代了旧的**包围盒自动生成**方案，提供更灵活、更精确的控制。
|
||
|
||
---
|
||
|
||
## 主要变化
|
||
|
||
### 旧方案的问题
|
||
- ❌ 依赖模型包围盒自动计算
|
||
- ❌ 只能生成固定的矩形四周
|
||
- ❌ 无法适应不规则形状
|
||
- ❌ 所有墙面必须使用相同的分割数
|
||
|
||
### 新方案的优势
|
||
- ✅ 直接定义每个墙面的起始和结束坐标
|
||
- ✅ 每个墙面可以有独立的分割数
|
||
- ✅ 支持任意数量的墙面（1个、4个、N个）
|
||
- ✅ 可以创建不规则形状（L形、U形等）
|
||
- ✅ 不依赖模型，坐标完全可控
|
||
|
||
---
|
||
|
||
## API 对比
|
||
|
||
### 旧 API（已废弃）
|
||
|
||
```typescript
|
||
import { AppDropZone } from './AppDropZone';
|
||
|
||
const appDropZone = new AppDropZone(scene);
|
||
|
||
// 旧的配置方式
|
||
const zones = appDropZone.generateDropZones({
|
||
modelName: 'myModel', // 依赖模型名称
|
||
divisions: 5, // 所有边使用相同分割数
|
||
color: '#21c7ff',
|
||
alpha: 0.3,
|
||
thickness: 2,
|
||
offset: 5, // 距离模型的偏移
|
||
scale: 1.0 // 缩放比例
|
||
});
|
||
|
||
// 返回 Mesh[]
|
||
```
|
||
|
||
### 新 API（推荐）
|
||
|
||
```typescript
|
||
import { AppDropZone } from './AppDropZone';
|
||
|
||
const appDropZone = new AppDropZone(scene);
|
||
|
||
// 新的配置方式
|
||
const zones = appDropZone.generateDropZones({
|
||
walls: [ // 墙面数组
|
||
{
|
||
name: 'front', // 墙面名称
|
||
startPoint: new Vector3(-50, 0, -50), // 起始点
|
||
endPoint: new Vector3(50, 0, -50), // 结束点
|
||
height: 30, // 高度
|
||
divisions: 5 // 这个墙面的分割数
|
||
},
|
||
{
|
||
name: 'back',
|
||
startPoint: new Vector3(50, 0, 50),
|
||
endPoint: new Vector3(-50, 0, 50),
|
||
height: 30,
|
||
divisions: 5
|
||
},
|
||
// ... 更多墙面
|
||
],
|
||
color: '#21c7ff',
|
||
alpha: 0.3,
|
||
thickness: 2,
|
||
showBorder: true, // 是否显示边框
|
||
borderColor: '#ffffff' // 边框颜色
|
||
});
|
||
|
||
// 返回 PlacementZoneInfo[]
|
||
```
|
||
|
||
---
|
||
|
||
## 迁移步骤
|
||
|
||
### 步骤 1：确定墙面坐标
|
||
|
||
如果你之前使用模型包围盒，需要先获取模型的边界坐标：
|
||
|
||
```typescript
|
||
// 获取模型的包围盒坐标
|
||
function getModelBounds(scene: Scene, modelName: string) {
|
||
const mesh = scene.getMeshByName(modelName);
|
||
if (!mesh) return null;
|
||
|
||
mesh.computeWorldMatrix(true);
|
||
const boundingInfo = mesh.getBoundingInfo();
|
||
const min = boundingInfo.boundingBox.minimumWorld;
|
||
const max = boundingInfo.boundingBox.maximumWorld;
|
||
|
||
return {
|
||
minX: min.x,
|
||
maxX: max.x,
|
||
minY: min.y,
|
||
maxY: max.y,
|
||
minZ: min.z,
|
||
maxZ: max.z
|
||
};
|
||
}
|
||
```
|
||
|
||
### 步骤 2：转换为墙面配置
|
||
|
||
```typescript
|
||
const bounds = getModelBounds(scene, 'myModel');
|
||
if (!bounds) return;
|
||
|
||
const { minX, maxX, minY, maxY, minZ, maxZ } = bounds;
|
||
const height = maxY - minY;
|
||
|
||
// 转换为新的墙面配置
|
||
const walls = [
|
||
{
|
||
name: 'front',
|
||
startPoint: new Vector3(minX, minY, minZ),
|
||
endPoint: new Vector3(maxX, minY, minZ),
|
||
height: height,
|
||
divisions: 5
|
||
},
|
||
{
|
||
name: 'back',
|
||
startPoint: new Vector3(maxX, minY, maxZ),
|
||
endPoint: new Vector3(minX, minY, maxZ),
|
||
height: height,
|
||
divisions: 5
|
||
},
|
||
{
|
||
name: 'left',
|
||
startPoint: new Vector3(minX, minY, maxZ),
|
||
endPoint: new Vector3(minX, minY, minZ),
|
||
height: height,
|
||
divisions: 5
|
||
},
|
||
{
|
||
name: 'right',
|
||
startPoint: new Vector3(maxX, minY, minZ),
|
||
endPoint: new Vector3(maxX, minY, maxZ),
|
||
height: height,
|
||
divisions: 5
|
||
}
|
||
];
|
||
```
|
||
|
||
### 步骤 3：应用偏移（如果需要）
|
||
|
||
如果旧代码中使用了 `offset` 参数，需要手动调整坐标：
|
||
|
||
```typescript
|
||
const offset = 5;
|
||
|
||
// 前墙向外偏移
|
||
walls[0].startPoint.z -= offset;
|
||
walls[0].endPoint.z -= offset;
|
||
|
||
// 后墙向外偏移
|
||
walls[1].startPoint.z += offset;
|
||
walls[1].endPoint.z += offset;
|
||
|
||
// 左墙向外偏移
|
||
walls[2].startPoint.x -= offset;
|
||
walls[2].endPoint.x -= offset;
|
||
|
||
// 右墙向外偏移
|
||
walls[3].startPoint.x += offset;
|
||
walls[3].endPoint.x += offset;
|
||
```
|
||
|
||
### 步骤 4：应用缩放（如果需要）
|
||
|
||
如果旧代码中使用了 `scale` 参数，需要调整坐标：
|
||
|
||
```typescript
|
||
const scale = 0.8; // 缩放到80%
|
||
|
||
const centerX = (minX + maxX) / 2;
|
||
const centerZ = (minZ + maxZ) / 2;
|
||
|
||
const scaledWidth = (maxX - minX) * scale;
|
||
const scaledDepth = (maxZ - minZ) * scale;
|
||
|
||
const scaledMinX = centerX - scaledWidth / 2;
|
||
const scaledMaxX = centerX + scaledWidth / 2;
|
||
const scaledMinZ = centerZ - scaledDepth / 2;
|
||
const scaledMaxZ = centerZ + scaledDepth / 2;
|
||
|
||
// 使用缩放后的坐标
|
||
walls[0].startPoint = new Vector3(scaledMinX, minY, scaledMinZ);
|
||
walls[0].endPoint = new Vector3(scaledMaxX, minY, scaledMinZ);
|
||
// ... 其他墙面类似
|
||
```
|
||
|
||
---
|
||
|
||
## 完整迁移示例
|
||
|
||
### 旧代码
|
||
|
||
```typescript
|
||
const appDropZone = new AppDropZone(scene);
|
||
|
||
const zones = appDropZone.generateDropZones({
|
||
modelName: 'warehouse',
|
||
divisions: 10,
|
||
color: '#21c7ff',
|
||
alpha: 0.3,
|
||
thickness: 2,
|
||
offset: 5,
|
||
scale: 0.9
|
||
});
|
||
```
|
||
|
||
### 新代码
|
||
|
||
```typescript
|
||
const appDropZone = new AppDropZone(scene);
|
||
|
||
// 1. 获取模型边界
|
||
const bounds = getModelBounds(scene, 'warehouse');
|
||
if (!bounds) return;
|
||
|
||
const { minX, maxX, minY, maxY, minZ, maxZ } = bounds;
|
||
|
||
// 2. 应用缩放
|
||
const scale = 0.9;
|
||
const centerX = (minX + maxX) / 2;
|
||
const centerZ = (minZ + maxZ) / 2;
|
||
const width = (maxX - minX) * scale;
|
||
const depth = (maxZ - minZ) * scale;
|
||
const height = maxY - minY;
|
||
|
||
const scaledMinX = centerX - width / 2;
|
||
const scaledMaxX = centerX + width / 2;
|
||
const scaledMinZ = centerZ - depth / 2;
|
||
const scaledMaxZ = centerZ + depth / 2;
|
||
|
||
// 3. 应用偏移
|
||
const offset = 5;
|
||
|
||
// 4. 生成放置区域
|
||
const zones = appDropZone.generateDropZones({
|
||
walls: [
|
||
{
|
||
name: 'front',
|
||
startPoint: new Vector3(scaledMinX, minY, scaledMinZ - offset),
|
||
endPoint: new Vector3(scaledMaxX, minY, scaledMinZ - offset),
|
||
height: height,
|
||
divisions: 10
|
||
},
|
||
{
|
||
name: 'back',
|
||
startPoint: new Vector3(scaledMaxX, minY, scaledMaxZ + offset),
|
||
endPoint: new Vector3(scaledMinX, minY, scaledMaxZ + offset),
|
||
height: height,
|
||
divisions: 10
|
||
},
|
||
{
|
||
name: 'left',
|
||
startPoint: new Vector3(scaledMinX - offset, minY, scaledMaxZ),
|
||
endPoint: new Vector3(scaledMinX - offset, minY, scaledMinZ),
|
||
height: height,
|
||
divisions: 10
|
||
},
|
||
{
|
||
name: 'right',
|
||
startPoint: new Vector3(scaledMaxX + offset, minY, scaledMinZ),
|
||
endPoint: new Vector3(scaledMaxX + offset, minY, scaledMaxZ),
|
||
height: height,
|
||
divisions: 10
|
||
}
|
||
],
|
||
color: '#21c7ff',
|
||
alpha: 0.3,
|
||
thickness: 2,
|
||
showBorder: true
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 新功能示例
|
||
|
||
### 1. 不同墙面使用不同分割数
|
||
|
||
```typescript
|
||
const zones = appDropZone.generateDropZones({
|
||
walls: [
|
||
{ name: 'front', ..., divisions: 10 }, // 前墙10块
|
||
{ name: 'back', ..., divisions: 10 }, // 后墙10块
|
||
{ name: 'left', ..., divisions: 5 }, // 左墙5块
|
||
{ name: 'right', ..., divisions: 5 } // 右墙5块
|
||
],
|
||
// ...
|
||
});
|
||
```
|
||
|
||
### 2. 创建L形区域
|
||
|
||
```typescript
|
||
const zones = appDropZone.generateDropZones({
|
||
walls: [
|
||
{
|
||
name: 'wall1',
|
||
startPoint: new Vector3(0, 0, 0),
|
||
endPoint: new Vector3(100, 0, 0),
|
||
height: 25,
|
||
divisions: 10
|
||
},
|
||
{
|
||
name: 'wall2',
|
||
startPoint: new Vector3(100, 0, 0),
|
||
endPoint: new Vector3(100, 0, 60),
|
||
height: 25,
|
||
divisions: 6
|
||
}
|
||
],
|
||
color: '#ff6b6b',
|
||
alpha: 0.4
|
||
});
|
||
```
|
||
|
||
### 3. 只创建单个墙面
|
||
|
||
```typescript
|
||
const zones = appDropZone.generateDropZones({
|
||
walls: [
|
||
{
|
||
name: 'display',
|
||
startPoint: new Vector3(-30, 0, 0),
|
||
endPoint: new Vector3(30, 0, 0),
|
||
height: 20,
|
||
divisions: 6
|
||
}
|
||
],
|
||
color: '#4ecdc4',
|
||
alpha: 0.35
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 获取放置区域信息
|
||
|
||
新API返回更详细的区域信息：
|
||
|
||
```typescript
|
||
const zones = appDropZone.generateDropZones(config);
|
||
|
||
// 每个zone包含：
|
||
zones.forEach(zone => {
|
||
console.log({
|
||
mesh: zone.mesh, // Babylon.js Mesh对象
|
||
wallName: zone.wallName, // 所属墙面名称
|
||
index: zone.index, // 在该墙面上的索引
|
||
center: zone.center, // 中心点坐标
|
||
width: zone.width, // 宽度
|
||
height: zone.height, // 高度
|
||
normal: zone.normal // 法线方向
|
||
});
|
||
});
|
||
|
||
// 获取特定墙面的所有区域
|
||
const frontZones = appDropZone.getZonesByWall('front');
|
||
|
||
// 获取特定的某一块
|
||
const zone = appDropZone.getZone('front', 2);
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 我必须迁移吗？
|
||
A: 旧的API已经被完全移除，必须迁移到新API。
|
||
|
||
### Q: 如何快速迁移？
|
||
A: 使用上面的 `getModelBounds` 函数获取模型边界，然后转换为墙面配置。
|
||
|
||
### Q: 新API性能如何？
|
||
A: 新API性能更好，因为不需要计算包围盒，直接使用预定义的坐标。
|
||
|
||
### Q: 可以动态调整墙面吗？
|
||
A: 可以，调用 `clearAll()` 清除旧的，然后用新坐标重新生成。
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
新的放置区域系统提供了：
|
||
- ✅ 更精确的控制
|
||
- ✅ 更灵活的配置
|
||
- ✅ 更好的性能
|
||
- ✅ 更清晰的API
|
||
|
||
虽然迁移需要一些工作，但新系统的灵活性和可控性值得这个投入！
|