rm-graphical-computing 1.0.53 → 1.0.54

package/README.md

@@ -0,0 +1,229 @@
+# rm-graphical-computing
+
+Three.js 建筑点云处理工具库 —— 提供墙体几何处理、梁线/柱线检测、点云语义合并、墙-窗匹配等功能。
+
+## 安装
+
+```bash
+npm install rm-graphical-computing
+```
+
+## API 文档
+
+### 1. 墙-窗匹配算法
+
+#### processData
+
+墙-窗匹配主函数，自动筛选窗户并完成匹配。
+
+```typescript
+processData(
+  wallSegments: WallSegment[],
+  objects: any[],
+  options?: FindWallOptions & { printOnly?: boolean }
+): { segments: WallSegment[]; matches: WindowWallMatch[]; sourceMap: number[][] }
+```
+
+**参数说明：**
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `wallSegments` | `WallSegment[]` | 墙线段数组 |
+| `objects` | `any[]` | 所有物体数组，内部自动筛选 `category === 'window'` 的物体 |
+| `options` | `FindWallOptions` | 匹配选项（可选） |
+
+**返回值：**
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `segments` | `WallSegment[]` | 合并后的墙线段（含 `drawWindow` 属性） |
+| `matches` | `WindowWallMatch[]` | 窗户匹配详情列表 |
+| `sourceMap` | `number[][]` | 每条输出线段对应的原始线段索引 |
+
+#### findWindowWalls
+
+窗户匹配核心函数。
+
+```typescript
+findWindowWalls(
+  windowObjs: WindowObject[],
+  wallSegments: WallSegment[],
+  options?: FindWallOptions
+): WindowWallMatch[]
+```
+
+#### mergeCollinearSegments
+
+共线线段合并。
+
+```typescript
+mergeCollinearSegments(
+  segments: WallSegment[],
+  angleTol?: number,      // 角度容差，默认 5°
+  gapTol?: number         // 间隙容差，默认 0.05m
+): { segments: WallSegment[]; sourceMap: number[][] }
+```
+
+#### computeLocalFloorZ
+
+计算局部地面高度。
+
+```typescript
+computeLocalFloorZ(walls: WallSegment[], cx: number, cy: number): number
+```
+
+#### FindWallOptions 选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `minLengthRatio` | `number` | `1.0` | 墙线长度至少为窗户长边的倍数 |
+| `maxDistance` | `number` | `0.5` | 窗户中心到墙线的最大垂直距离（m） |
+| `angleThreshold` | `number` | `45` | 墙线与窗户长边方向的最大夹角（°） |
+| `projectionMargin` | `number` | `0.1` | 垂足在线段上的容许范围 |
+| `printOnly` | `boolean` | `false` | 是否仅打印信息而不写入 `drawWindow` |
+
+### 2. 梁线检测
+
+```typescript
+getBeamLine(lines: any[], runDataList: any[], pcdData: any): Promise<any>
+getMainBeamLine(lines: any[], runDataList: any[], pcdData: any): Promise<any>
+usegetBeamLine(lines: any[], runDataList: any[], pcdData: any): Promise<any>
+```
+
+### 3. 柱线检测
+
+```typescript
+getColLine(lines: any[], runDataList: any[]): Promise<any>
+```
+
+### 4. 墙体几何处理
+
+```typescript
+getAllGeometry(data: any): any
+```
+
+### 5. 点云语义合并
+
+```typescript
+getMergeMeaning(allProjectionResults: any[]): any
+```
+
+### 6. 工具函数
+
+| 函数 | 说明 |
+|------|------|
+| `segmentsIntersect2D(a, b)` | 判断两条线段是否相交（2D） |
+| `isParallel(a, b, tolerance?)` | 判断两个向量是否平行 |
+| `getParallelism(a, b)` | 获取向量平行度信息 |
+| `perpendicularInfo(segment)` | 获取线段的垂直信息 |
+| `classifySegments(segments)` | 分类线段（共线/偏移/重叠） |
+| `getPointCoverageOnQuad(points, quad)` | 计算点云在四边形上的覆盖率 |
+| `getPointCloudMinMax(points)` | 获取点云的最小/最大边界 |
+| `removeNoisePoints(points, threshold)` | 去除噪点 |
+| `updateStEdPoint(line, start, end)` | 更新线段端点 |
+
+## 类型定义
+
+### Point3D
+
+```typescript
+interface Point3D {
+  x: number
+  y: number
+  z: number
+}
+```
+
+### WallSegment
+
+```typescript
+interface WallSegment {
+  start: Point3D
+  end: Point3D
+  length: number
+  direction: Point3D
+  points: Point3D[]
+  originalPoints?: Point3D[]
+  rooftopPz?: number
+  drawWindow?: DrawWindow[]
+  // ... 其他属性
+}
+```
+
+### DrawWindow
+
+```typescript
+interface DrawWindow {
+  p: Point3D          // 窗户中心点
+  width: number       // 窗户宽度（m）
+  height: number      // 窗户高度（m）
+  full: boolean       // 是否贯穿整面墙
+  groundClearance: number  // 离地高度（m）
+}
+```
+
+### WindowWallMatch
+
+```typescript
+interface WindowWallMatch {
+  windowName: string
+  windowCategory: string
+  windowCenter: Point3D
+  wallSegment: WallSegment
+  distance: number          // 窗户中心到墙线的垂直距离（m）
+  wallLengthRatio: number   // 墙线长度 / 窗户长边
+  drawWindow?: DrawWindow
+}
+```
+
+## 使用示例
+
+```typescript
+import { processData } from 'rm-graphical-computing'
+
+// 墙线段数据
+const wallSegments = [
+  {
+    start: { x: 0, y: 0, z: 0 },
+    end: { x: 5, y: 0, z: 0 },
+    length: 5,
+    direction: { x: 1, y: 0, z: 0 },
+    points: []
+  }
+]
+
+// 物体数据（包含窗户）
+const objects = [
+  {
+    name: 'Window_001',
+    category: 'window',
+    center: { x: 2.5, y: 0.2, z: 1 },
+    box: { min: { x: 2, y: 0, z: 0.5 }, max: { x: 3, y: 0.4, z: 1.5 } },
+    coordinatesByArea: { coordinates: [...] }
+  }
+]
+
+// 执行匹配
+const result = processData(wallSegments, objects, {
+  maxDistance: 0.5,
+  minLengthRatio: 0.95
+})
+
+console.log(result.segments)    // 合并后的墙线段
+console.log(result.matches)     // 匹配结果
+```
+
+## 技术特性
+
+1. **共线合并**：自动合并角度相近、方向一致的墙线段
+2. **多信号评分**：综合端点连接度、距离方差、垂直墙同侧性进行匹配评分
+3. **drawWindow 注入**：将窗户位置信息写入墙线段，便于后续渲染
+4. **TypeScript 支持**：完整的类型定义
+
+## 依赖
+
+- `three`: ^0.183.2
+- `three-mesh-bvh`: ^0.9.10
+- `d3-delaunay`: ^6.0.4
+
+## 许可证
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rm-graphical-computing",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "description": "Three.js wall segment processing utilities.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -11,7 +11,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "dev": "vite",