# PointCloud Processor

**Repository Path**: xxthink/point-cloud-processor

## Basic Information

- **Project Name**: PointCloud Processor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 点云对比工具 (PointCloud Processor)

一个高效的3D点云对比分析工具，支持生成工业级热点图和高清截图，用于检测点云之间的偏差。

## 功能特性

- ✅ **高效距离计算**：基于 scipy cKDTree 实现快速最近邻搜索，支持多线程并行处理
- ✅ **工业级热点图**：采用深蓝->青->绿->黄->红的专业配色方案，直观展示偏差分布
- ✅ **高清截图输出**：自动生成1920x1080分辨率的PNG截图
- ✅ **详细统计分析**：提供平均偏差、最大/最小偏差、标准差等关键指标
- ✅ **双模式运行**：支持对比模式和单点云查看模式
- ✅ **鲁棒的PCD解析**：自动处理各种格式的PCD文件，包括header异常的情况

## 系统要求

- Python 3.7+
- macOS / Linux / Windows

## 安装

### 1. 克隆仓库

```bash
git clone <repository-url>
cd pointcloud_processor
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

主要依赖：
- `open3d>=0.18.0` - 3D点云处理库
- `numpy>=1.24.0` - 数值计算
- `matplotlib>=3.5.0` - 可视化渲染
- `scipy>=1.7.0` - KD树实现

## 使用方法

### 对比两个点云

```bash
python main.py compare <基准点云.pcd> <待检测点云.pcd> <输出热图.pcd> <输出截图.png>
```

**示例：**
```bash
python main.py compare baseline.pcd test.pcd heatmap.pcd screenshot.png
```

**参数说明：**
- `基准点云.pcd` - 作为参考的标准点云文件
- `待检测点云.pcd` - 需要检测的点云文件
- `输出热图.pcd` - 输出的带颜色热点图的PCD文件
- `输出截图.png` - 输出的高清PNG截图文件

### 查看单个点云

```bash
python main.py view <点云.pcd>
```

**示例：**
```bash
python main.py view pointcloud.pcd
```

## 输出说明

### 统计信息

程序会输出以下统计数据：
- **点数**：测试点云的总点数
- **平均偏差**：所有点到基准点云的平均距离
- **最大偏差**：最大距离值
- **最小偏差**：最小距离值
- **标准差**：距离分布的标准差

### 输出文件

1. **彩色点云 (.pcd)**：每个点根据偏差值着色，可直接在3D软件中查看
2. **高清截图 (.png)**：1920x1080分辨率的热点图，适合报告和演示

### 颜色映射

| 颜色 | 偏差程度 | 说明 |
|------|---------|------|
| 🔵 深蓝 | 最小 | 与基准点云几乎重合 |
| 🔵 青色 | 较小 | 轻微偏差 |
| 🟢 绿色 | 中等 | 可接受的偏差范围 |
| 🟡 黄色 | 较大 | 需要注意的偏差 |
| 🔴 红色 | 最大 | 严重偏差，需检查 |

## 配置

可在 [`config.py`](file:///Users/hehui/workspace/pointcloud_processor/config.py) 中调整以下参数：

- **COLOR_MAP**：热点图颜色映射方案
- **RENDER_CONFIG**：截图分辨率、背景色、点大小等
- **CAMERA_CONFIG**：相机视角和缩放
- **DISTANCE_THRESHOLD**：最大搜索距离阈值
- **STAT_PRECISION**：统计数值精度

## 项目结构

```
pointcloud_processor/
├── main.py              # 主程序入口
├── processor.py         # 核心处理模块
├── config.py           # 配置文件
├── logger.py           # 日志模块
├── requirements.txt    # Python依赖
└── test_data/          # 测试数据目录
```

## 技术细节

### 性能优化

- 使用 `scipy.spatial.cKDTree` 替代传统KD树，查询速度提升3-5倍
- 支持多线程并行查询（`workers=-1` 使用所有CPU核心）
- 内存友好的批量处理策略

### 兼容性

- 自动检测和修复PCD文件格式问题
- 支持ASCII和二进制PCD格式
- 兼容带/不带颜色信息的点云

## 常见问题

### Q: 提示 "文件不存在" 错误？
A: 请确认输入文件路径正确，建议使用绝对路径。

### Q: 截图背景不是白色？
A: 可在 `config.py` 中修改 `RENDER_CONFIG['background_color']` 参数。

### Q: 如何调整热点图颜色？
A: 编辑 `config.py` 中的 `COLOR_MAP` 配置项。

## 许可证

MIT License

## 联系方式

如有问题或建议，请提交 Issue。