wall-snap-3d

3D物体墙体吸附与位置修正引擎 - 支持家具、电源等自动适配墙体

安装

npm install wall-snap-3d

快速开始

基本用法

import { snapToWalls } from 'wall-snap-3d';

const results = snapToWalls({
  items: [
    {
      obj_id: 'socket_001',
      category: 'socket',
      box: {
        min: { x: 1.0, y: 2.0, z: 0.0 },
        max: { x: 1.1, y: 2.1, z: 0.1 }
      }
    }
  ],
  walls: [
    {
      center: { x: 0, y: 0, z: 1.5 },
      normal: { x: 0, y: 1, z: 0 },
      innerSurface: { x: 0, y: -0.1, z: 1.5 },
      outerSurface: { x: 0, y: 0.1, z: 1.5 }
    }
  ]
});

console.log(results);

高级用法

import { createSnapEngine } from 'wall-snap-3d';

const engine = createSnapEngine({
  smallObjectOffset: 0.003,  // 小型物件偏移量（3mm）
  cabinetOffset: 0.02,       // 柜子偏移量（2cm）
  keepOriginalHeight: true,  // 保持原始高度
  snapCategories: ['socket', 'switch', 'cabinet'],  // 需要贴墙的类型
  keepOriginalPositionCategories: ['desk', 'sofa']  // 保持原位的类型
});

const results = engine.snapItemsToWalls({ items, walls });

// 转换电源数据
const socketData = results.filter(r => r.obj_id.includes('socket'));
const convertedSockets = engine.convertSocketToSwitchFormat(socketData);

API 文档

snapToWalls(request, config?)

便捷的吸附函数

参数：

• request: 吸附请求对象
  • items: 物品数组
  • walls: 墙面数组
• config?: 可选配置

返回： 吸附结果数组

createSnapEngine(config?)

创建吸附引擎实例

参数：

• config?: 配置对象
  • smallObjectOffset: 小型物件偏移量（默认 0.003）
  • cabinetOffset: 柜子偏移量（默认 0.02）
  • keepOriginalHeight: 是否保持原始高度（默认 true）
  • snapCategories: 需要贴墙的物品类型
  • keepOriginalPositionCategories: 保持原位的物品类型

返回： WallSnapEngine 实例

WallSnapEngine

snapItemsToWalls(request)

批量吸附物品到墙面

参数：

• request: 吸附请求对象

返回： 吸附结果数组

convertSocketToSwitchFormat(socketResults, existingContent?)

转换电源数据为开关格式

参数：

• socketResults: 吸附结果数组
• existingContent?: 可选，现有文件内容，用于自动递增 ID

返回： 转换后的电源数据数组

类型定义

IItemInfo

interface IItemInfo {
  obj_id: string;
  category: string;
  box: IBox3;
  vertices?: number[];
}

IWallInfo

interface IWallInfo {
  center: IVector3;
  normal: IVector3;
  innerSurface: IVector3;
  outerSurface: IVector3;
}

ISnapResult

interface ISnapResult {
  obj_id: string;
  snapped: boolean;
  newPosition: IVector3;
  newRotation: IVector3;
  wallIndex: number;
  distance: number;
  vertices: number[];
}

示例

电源吸附

import { snapToWalls, createSnapEngine } from 'rm-wall-adapter';

const items = [
  {
    obj_id: 'socket_001',
    category: 'socket',
    box: {
      min: { x: 1.0, y: 2.0, z: 1.4 },
      max: { x: 1.085, y: 2.085, z: 1.485 }
    }
  }
];

const walls = [
  {
    center: { x: 0, y: 2.1, z: 1.5 },
    normal: { x: 0, y: -1, z: 0 },
    innerSurface: { x: 0, y: 2.0, z: 1.5 },
    outerSurface: { x: 0, y: 2.2, z: 1.5 }
  }
];

const results = snapToWalls({ items, walls });
console.log('吸附结果:', results);

柜子吸附

import { createSnapEngine } from 'rm-wall-adapter';

const engine = createSnapEngine({
  cabinetOffset: 0.02  // 2cm 偏移
});

const items = [
  {
    obj_id: 'cabinet_001',
    category: 'cabinet',
    box: {
      min: { x: 0, y: 0, z: 0 },
      max: { x: 0.6, y: 0.4, z: 2.0 }
    }
  }
];

const results = engine.snapItemsToWalls({ items, walls });

License

MIT