PointCloudTools

一个基于 Open3D + Streamlit + Plotly 的点云处理可视化项目，支持以下能力：

• 基础操作：点云质心、点云去质心、点云坐标最值、点云统计、归一化协方差矩阵、高程热力图
• 点云滤波：统计滤波、导向滤波、均值滤波、中值滤波、半径滤波、直通滤波
• 点云下采样：体素下采样、均匀下采样、随机下采样、FPS 下采样、曲率感知下采样
• 点云裁剪：Axis-Aligned Bounding Box 裁剪
• 点云特征：法线估计（支持点云中心外向 / 自定义方向 / 相机位置 / 一致切平面定向）、曲率计算、凸包、AABB / OBB 包围盒、FPFH 特征、ISS 关键点、基于法向量夹角的特征点
• 点云聚类：DBSCAN、KMeans、欧式聚类、快速欧式聚类
• 点云拟合：平面拟合、多平面分割、空间直线拟合、多直线分割、空间圆拟合、二次曲面拟合、区域生长分割、球体拟合
• 点云配准：粗配准（FPFH + RANSAC / FGR / PCA）、精配准（点到点 ICP / 点到面 ICP / 鲁棒 ICP / GICP / 对应点集 SVD）
• 配准结果分析：Fitness、Inlier RMSE、RMSE、变换矩阵、匹配点对连线可视化
• 结果可视化与导出（PLY / PCD / XYZ）
• 处理流程脚本导出（将 Web 操作流程导出为可复现 Python 脚本）

目录结构

pointcloudtools_web/
├── src/
│   ├── __init__.py
│   ├── app.py                 # Streamlit UI 主入口
│   └── ui/
│       ├── state.py
│       ├── views.py
│       ├── workflow_export.py
│       ├── tabs_basic.py
│       ├── tabs_filtering.py
│       ├── tabs_features.py
│       ├── tabs_clustering.py
│       ├── tabs_fitting.py
│       ├── tabs_registration.py
│       └── tabs_export.py
├── utils/
│   ├── __init__.py
│   ├── io_utils.py            # 文件读写与序列化
│   ├── basic_ops.py           # 基础操作
│   ├── filter_ops.py          # 滤波 / 下采样 / 裁剪
│   ├── segmentation_ops.py    # 聚类 / 分割
│   ├── registration_ops.py    # 配准算法
│   ├── feature_ops.py         # 点云特征
│   ├── fitting_ops.py         # 点云拟合
│   └── viz_utils.py           # Plotly 可视化辅助
├── tests/
│   └── test_pointcloud_ops.py
├── examples/
├── data/
├── pyproject.toml
└── README.md

环境准备

# 1. 创建 conda 虚拟环境（Python 3.10）
conda create -n pointcloudtools python=3.10 -y

# 2. 激活环境
conda activate pointcloudtools

# 3. 以可编辑模式安装项目 + 开发依赖（pytest / ruff / mypy）
pip install -e ".[dev]"

# 如果只需要运行，不做开发，可以省略 [dev]：
# pip install -e .

依赖说明：pip install -e ".[dev]" 会一次性安装以下内容：

类别	包
运行依赖	numpy, open3d, plotly, scipy, streamlit
开发依赖	pytest, ruff, mypy

-e（editable）表示以开发模式安装，源码修改后无需重新安装即可生效。

如需在部分拟合 / 分割模块中使用 PyRANSAC3D 风格算法，可额外安装：

pip install pyransac3d

未安装时，部分算法会自动回退到项目内置兼容实现。

启动 UI

python -m streamlit run src/app.py

打开浏览器后可上传点云文件并进行基础操作、滤波、下采样、裁剪、点云特征分析、聚类、拟合和配准等操作。

浏览器兼容性说明

• 建议使用较新版本浏览器运行 Web 可视化。
• 已验证 Firefox 149.0.2 可正常显示点云与坐标轴。
• 低版本浏览器（例如 Firefox 130.x）可能出现“点数已加载但画布空白”的渲染兼容问题，本项目不再针对该版本做兼容支持。

开发检查

python -m compileall src utils tests
python -m pytest

支持格式

• 输入：.ply, .pcd, .xyz, .xyzn, .xyzrgb, .pts, .txt
• 导出：PLY, PCD, XYZ

其中 .txt 支持常见的 xyz / xyz+intensity / xyzrgb / xyznormal / xyznormalrgb 布局。

导出处理流程脚本

在 Web UI 的 导出 标签页中，除了导出点云文件外，还支持导出处理流程脚本：

• 按钮：下载处理流程脚本 (.py)
• 默认文件名：pointcloud_workflow_export.py
• 用途：复现你在 Web 中对点云的处理链路（基础操作、滤波、下采样、裁剪、特征、聚类、拟合、配准等）

记录规则

• 仅记录会“更新当前点云”或“更新配准结果”的操作步骤。
• 对于带“应用到当前点云”选项的功能，只有应用后才会写入流程。
• 重新加载源点云或执行“重置到原始源点云”会清空已记录流程。

脚本执行示例

# 仅复现 Source 处理流程
python pointcloud_workflow_export.py \
  --source data/source.ply \
  --output output/processed_source.ply

# 包含配准流程（粗配准 / 精配准）时
python pointcloud_workflow_export.py \
  --source data/source.ply \
  --target data/target.ply \
  --output output/processed_source.ply \
  --registration-output output/registered_source.ply

工程规范说明

• 业务代码集中在 src/
• 算法和工具函数集中在 utils/
• 状态管理集中在 src/ui/state.py
• 流程脚本导出逻辑集中在 src/ui/workflow_export.py
• 使用类型注解、模块分层和可读命名
• 预置 ruff / mypy / pytest 开发配置