# tunnelSmart

**Repository Path**: lbluekey/tunnel-smart

## Basic Information

- **Project Name**: tunnelSmart
- **Description**: 三峡云隧智能隧洞质量分析系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 三峡智隧 隧洞三维激光点云处理分析系统

基于 `doc/` 中《三峡智隧 隧洞三维激光点云处理分析系统操作手册》与《使用教程》
复刻的**完整工程框架**，采用 Python + PySide6 + VTK + Open3D 技术栈。

> 说明：本工程为
> 面向信创环境、自主可控的 Python 复刻框架，算法与 UI 完全解耦。

## 核心定位

隧道断面几何检测 + 超欠挖定量分析，一条主线：

```
点云 → 工程坐标注册 → 线路/断面设计数据 → 里程截取 → 断面提取
     → 设计轮廓比对 → 超欠挖面积/方量 → 报告 / 三维云图
```

## 技术选型

| 组件 | 选型 | 说明 |
|------|------|------|
| 语言 | Python 3.9+ | 算法与 UI 一体 |
| GUI | PySide6（兼容 PyQt5） | Qt 官方绑定，LGPL，信创许可友好 |
| 渲染 | VTK 9.x | 大规模点云/云图渲染，与原版一致 |
| 点云算法 | Open3D | 承担 PCL 等效能力（滤波/配准/下采样），纯 pip 可装 |
| 几何/分析 | NumPy（纯手写） | 断面切取、超欠挖计算零重依赖，最易部署 |

### 关于 "PCL"

纯 Python 生态中 `python-pcl` 编译复杂、信创环境安装困难。本工程以
**Open3D + NumPy** 替代 PCL：
- Open3D 覆盖 `VoxelGrid`、`StatisticalOutlierRemoval`、`ICP` 等 PCL 常用能力；
- 超欠挖核心算法（断面切取、符号距离、方量积分）用 NumPy 手写，不依赖任何
  重库，保证信创环境可移植。

如需原生 PCL 绑定，可在 `tunnelsmart/core/pointcloud.py` 中按需替换为 `python-pcl`。

## 目录结构

```
tunnelsmart/
├── core/            # 算法核心（无 UI 依赖，可无头运行）
│   ├── models.py       # 数据模型：线路/断面/测站/工程
│   ├── alignment.py    # 线形精确计算：直线/圆曲线/回旋线/竖曲线
│   ├── geometry.py     # 几何引擎：断面切取、弧长积分、符号距离
│   ├── pointcloud.py   # 点云处理：载入、滤波、配准、里程截取
│   ├── analysis.py     # 超欠挖分析：偏差计算、面积/方量
│   ├── defect.py       # 缺陷检测：正射展开 + 裂缝/渗水/钢筋
│   └── convergence.py  # 多期断面收敛监测
├── io/              # 数据读写
│   ├── dxf.py          # DXF 断面/点云导出（纯手写，无重依赖）
│   ├── report.py       # 报告生成（HTML + SVG 图表）
│   └── project_io.py   # .proj 工程文件序列化
├── gui/             # 界面 + 渲染
│   ├── vtk_renderer.py # VTK 渲染器（点云/云图/线路/断面）
│   └── main_window.py  # PySide6 主窗口
└── app/             # 入口
    ├── main.py         # GUI + CLI 双入口
    └── generate_sample.py  # 样例点云生成
tests/               # 单元测试（pytest，18 用例）
samples/             # 样例数据与报告
docs/                # 架构与适配文档
```

## 快速开始

### 安装

```bash
# 仅核心算法（无 GUI，可无头批处理）
pip install -e .

# 完整桌面环境
pip install -e ".[all]"

# 或分步（按需）
pip install numpy PySide6 vtk            # GUI + 渲染
pip install open3d                        # 点云增强（PCD/PLY 载入、滤波、配准，可选）
pip install python-docx opencv-python     # Word 报告 / 缺陷图像识别增强（可选）
```

### 依赖兼容性（重要，踩坑记录）

| 依赖 | 版本 | 注意 |
|------|------|------|
| Python | 3.9 ~ 3.12 推荐 | **Open3D 最高支持到 3.12**，3.13 装不上 |
| PySide6 | ≥ 6.5 | **6.11 起 `QAction` 从 `QtWidgets` 移到 `QtGui`**（代码已适配两版） |
| vtk | ≥ 9.2 | 纯 pip 可装 |
| open3d | ≥ 0.17 | **可选**，缺省时点云算法降级 NumPy（XYZ 载入/里程截取/超欠挖分析不受影响） |

> 核心算法（超欠挖、断面、里程）**不依赖 Open3D**，`pointcloud.py` 内置
> `HAS_OPEN3D` 降级；Open3D 仅用于 PCD/PLY 载入、体素滤波、统计去噪、ICP 配准。
> 信创环境（通常 Py3.9~3.11）反而 Open3D 可用，无此限制。

### 运行 GUI

```bash
python -m tunnelsmart.app.main
```

操作：工具栏「载入点云」→ 选 `samples/tunnel.xyz` →「开始超欠挖分析」
→ 右侧显示超欠挖云图（红=超挖、绿=欠挖），拖 Slider 调云图上下限。

### 运行无头 CLI（批处理/测试）

```bash
# 生成样例点云
python -m tunnelsmart.app.generate_sample -o samples/tunnel.xyz --length 60 --radius 5

# 执行超欠挖分析
python -m tunnelsmart.app.main --cli --input samples/tunnel.xyz --start 0 --end 60 --interval 2 --radius 5
```

输出示例：

```
载入点云：samples/tunnel.xyz，共 294000 点
{'start_station': 0.0, 'end_station': 60.0, 'section_count': 31,
 'overbreak_volume': 43.39, 'underbreak_volume': 49.62,
 'max_overbreak': 0.198, 'max_underbreak': -0.221}
```

### 运行测试

```bash
pytest tests/ -q
```

## 已实现能力对照

| 原版手册功能 | 本框架实现 |
|-------------|-----------|
| 点云载入（xyz/fls/pcd/ply） | `pointcloud.load_points` |
| 工程坐标注册（两棱镜球刚体变换） | `pointcloud.register_by_two_points` |
| 体素滤波 / 统计去噪 | `pointcloud.voxel_downsample` / `remove_statistical_outlier` |
| 线路管理（平面线形） | `models.HorizontalAlignment` + `geometry` |
| 横断面管理（断面绘制） | `models.DesignSection` / `geometry.make_*_section` |
| 里程截取 | `pointcloud.crop_by_station` |
| 断面提取 | `geometry.extract_section` |
| 超欠挖分析（面积/方量） | `analysis.analyze_over_under` |
| 超欠挖云图 | `vtk_renderer.show_deviation_cloud` |
| 云图上下限调节（QSlider / 原版按 L 键） | `vtk_renderer.set_color_range` |
| 导出 DXF 断面 | `io.dxf.export_*` |
| 缓和曲线（回旋线）精确展开 | `alignment.ClothoidElement`（Fresnel 积分） |
| 竖曲线里程对齐 | `alignment.VerticalAlignment` |
| 断面面积弧长精确积分 | `geometry.over_under_area_by_arc_length` |
| 正射影像展开 + 缺陷检测 | `defect.unfold_to_ortho` / `detect_cracks` / `detect_seepage` / `detect_rebar` |
| 多期断面收敛监测 | `convergence.compute_section_convergence` |
| 报告自动生成（HTML/SVG） | `io.report.generate_*_report` |
| 报告 Word 导出 | `io.report.write_*_report_docx`（python-docx） |
| 设计断面弧段精确表示 | `models.SectionArc`（直线/圆弧，消除弦离散化） |

## 设计约定

- **着色**：超挖（正偏差）→ 红，欠挖（负偏差）→ 绿（国内工程配色）。
- **坐标**：里程从小里程到大里程；平面线形左转正半径、右转负半径。
- **单位**：米（DXF/报告输出时为米，注册误差内部以 mm 表示）。

## 核心模块说明

### 线形精确计算（`core/alignment.py`）

完整支持**直线 / 圆曲线 / 回旋线（缓和曲线）/ 竖曲线**：

- 回旋线用 **Fresnel 积分**（复化 Simpson）精确展开，满足 A²=R·L 关系，
  切向连续，端点曲率精确逼近设定半径。
- 竖曲线为二次抛物线，里程与平面线形对齐，坡度线性过渡。

### 断面面积弧长积分（`core/geometry.py`）

超欠挖面积不再用"点密度估计"，而是：

1. 实测点投影到设计轮廓，得到弧长坐标 s 与符号距离 δ；
2. 沿轮廓周长 [0, P] 排序分段；
3. 超挖面积 = ∫ max(δ,0) ds，欠挖面积 = ∫ max(-δ,0) ds（梯形积分）。

对点密度不均鲁棒，面积精度更高。

### 缺陷检测（`core/defect.py`）

隧道内表面沿"里程 × 环向"展开为正射影像，再做：
- **裂缝**：拉普拉斯增强 + 细长条状连通域（长宽比 > 3）
- **渗水**：灰度偏暗斑块（湿度导致反射率降低）
- **钢筋裸露**：高反射率亮斑（金属高反射）

可选依赖 OpenCV，无 OpenCV 时降级为纯 NumPy。

### 收敛监测（`core/convergence.py`）

两期点云在同一里程切断面 → 转极坐标 → 统一角度网格插值半径 →
径向位移（正=外扩，负=收敛），输出沿里程的收敛曲线。

### 报告生成（`io/report.py`）

超欠挖 / 收敛 / 缺陷三类报告，输出 **HTML + 内嵌 SVG 图表**（折线图、
径向位移玫瑰图），不依赖 matplotlib，浏览器即可查看、可直接打印为 PDF。
另提供 **Word (.docx) 导出**（`write_*_report_docx`，依赖 python-docx），
含统计指标表与断面明细表。

### 设计断面弧段表示（`models.SectionArc`）

设计断面轮廓用**直线段 + 圆弧段**精确表示（圆弧 = 圆心+半径+起止角），
消除"弦逼近圆弧"的离散化误差：

- 符号距离用点到直线/圆弧的**解析投影**，精确圆上的点偏差达到机器精度（~1e-15）；
- DXF 导出为真正的 **ARC / LINE 实体**，而非折线；
- `to_polygon()` 仍保留，供渲染、inside 判定等需要闭合多边形的场景兜底。

`make_circular_section` / `make_horseshoe_section` 已默认生成弧段表示。