anoushkaacc/CivicVision-Infrastructure-Assessment-Toolkit-for-Cities
GitHub: anoushkaacc/CivicVision-Infrastructure-Assessment-Toolkit-for-Cities
一款基于深度学习的市政道路基础设施评估系统，通过分析道路图像实时检测路面损伤与交通状况，自动生成量化健康评分和养护建议报告。
Stars: 1 | Forks: 0
# CivicVision
**CivicVision** 是一个由 AI 驱动的市政基础设施评估系统，能够通过分析道路图像来实时检测道路损伤和交通状况。它采用最先进的深度学习模型来评估道路健康状况、生成综合报告，并提供基于数据驱动的养护建议。
## 目录
- [概述](#overview)
- [功能](#features)
- [快速开始](#quick-start)
- [安装说明](#installation)
- [使用说明](#usage)
- [输出结构](#output-structure)
- [评分系统](#scoring-system)
- [指标与算法](#metrics--algorithms)
- [输出示例](#example-output)
- [使用的模型](#models-used)
- [架构](#architecture)
- [项目结构](#project-structure)
- [环境要求](#requirements)
- [许可证](#license)
## 概述
CivicVision 通过以下方式实现道路基础设施评估的自动化：
1. **检测道路损伤**：识别并分类四种类型的道路破损（裂缝、坑洼）
2. **监测交通**：检测并统计车辆，以评估交通拥堵程度
3. **计算健康指标**：生成量化的基础设施健康评分（0-100）
4. **生成报告**：创建带标注的图像、JSON 数据、可视化图表以及交互式 HTML 报告
5. **提供建议**：根据检测到的损伤和交通模式建议养护措施
本系统适用于：
- 城市规划与基础设施管理
- 预测性养护调度
- 土木工程评估
- 交通模式分析
- 市政数据采集与报告
## 功能
### 道路损伤检测
- 检测 **4 种损伤类型**：
- 纵向裂缝
- 横向裂缝
- 龟裂
- 坑洼
- 计算损伤指标，包括面积覆盖率
- 生成损伤严重程度评级
### 交通分析
- 检测 **5 种车辆类型**：
- 轿车
- 摩托车
- 公交车
- 卡车
- 自行车
- 划分交通等级：低 / 中 / 高
- 跟踪汇总交通统计数据
### 综合指标
- **基础设施评分**：综合健康指标 (0-100)
- **道路损伤评分**：基于扣分的损伤评估 (0-100)
- **交通评分**：车辆密度评估 (0-100)
- **损伤面积百分比**：受影响路面的比例
- **严重程度评级**：定性评估（优秀 → 极度严重）
- **养护优先级**：可操作的优先级（无需养护 → 立即处理）
### 多种输出格式
- **带标注的图像**：带有边界框和叠加指标的自带原始图像
- **单张图像 JSON**：每张图像的详细检测数据和指标
- **汇总 JSON**：所有已处理图像的汇总统计数据
- **数据集图表**：柱状图、直方图和饼图
- **交互式 HTML 报告**：包含嵌入图像和图表的独立、自包含报告
### 可视化
- 为每种损伤类型提供颜色编码的边界框
- 叠加显示基础设施评分、严重程度和交通等级
- 专业的数据集可视化
- 具有样式化表格和图表的响应式 HTML 报告
## 快速开始
```
# 1. Clone the repository
git clone https://github.com/yourusername/civicvision.git
cd civicvision
# 2. Install dependencies
pip install -r requirements.txt
# 3. Download pre-trained models
# Models 应放置在项目根目录下：
# - YOLOv8_Small_RDD.pt（道路损坏 model）
# - yolo11n.pt（交通检测 model）
# 4. Process images
python main.py path/to/image_or_folder
# 5. View results
# 在浏览器中打开 outputs/report.html
```
## 安装说明
### 前置条件
- Python 3.8 或更高版本
- pip 包管理器
- 2GB+ 磁盘空间（用于存放模型）
- 推荐 4GB+ RAM
### 第一步：克隆仓库
```
git clone https://github.com/yourusername/civicvision.git
cd civicvision
```
### 第二步：创建虚拟环境（可选但推荐）
```
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
### 第三步：安装依赖项
```
pip install -r requirements.txt
```
### 第四步：下载预训练模型
下载以下模型并将其放置在项目根目录下：
1. **YOLOv8_Small_RDD.pt** (道路损伤检测器)
- 大小：~26 MB
- [从源头下载](https://github.com/RDD2020/RDD2020-Challenge)
2. **yolo11n.pt** (交通检测器)
- 大小：~25 MB
- 首次运行时通过 Ultralytics 自动下载
```
# Models 应位于：
civicvision/
├── YOLOv8_Small_RDD.pt
├── yolo11n.pt
└── ...
```
## 使用说明
### 基本用法
#### 处理单张图像
```
python main.py path/to/image.jpg
```
#### 处理图像文件夹
```
python main.py path/to/image_folder
```
#### 指定自定义输出目录
```
python main.py path/to/images --output custom_outputs
```
### 命令行参数
```
usage: main.py [-h] [--output OUTPUT] input
positional arguments:
input Path to a single image or folder containing road images
optional arguments:
-h, --help show this help message and exit
--output OUTPUT Output directory (default: outputs)
```
### 示例工作流
```
# 处理文件夹中的所有图像
python main.py ./road_images --output ./results
# 检查结果
ls -la ./results/
# outputs:
# - annotated/ （带有检测结果的图像）
# - json/ （单张图像报告）
# - plots/ （图表和可视化）
# - report.html （交互式报告）
# - summary.json （汇总统计数据）
```
## 输出结构
处理完成后，将创建以下目录结构：
```
outputs/
├── annotated/
│ ├── image_001.jpg (original image with bounding boxes)
│ ├── image_002.jpg
│ └── ...
├── json/
│ ├── image_001.json (detailed metrics and detections)
│ ├── image_002.json
│ └── ...
├── plots/
│ ├── damage_bar_chart.png
│ ├── vehicle_bar_chart.png
│ ├── infrastructure_histogram.png
│ └── severity_pie_chart.png
├── report.html (interactive HTML report)
└── summary.json (dataset-wide aggregate stats)
```
## 评分系统
### 基础设施评分 (0-100)
采用加权平均值计算的综合指标：
```
Infrastructure Score = 0.70 × Road Damage Score + 0.30 × Traffic Score
```
**权重依据：**
- 道路损伤 (70%)：决定养护决策的主要因素
- 交通 (30%)：影响紧迫性的次要因素
### 道路损伤评分 (0-100)
从 100 分开始进行扣分式评分：
```
Score = 100
- (Longitudinal Cracks × 5)
- (Transverse Cracks × 7)
- (Alligator Cracks × 10)
- (Potholes × 15)
Score Range: 0-100 (clamped)
```
### 交通评分 (0-100)
车辆密度分类：
```
Vehicle Count ≤ 5 → Traffic Score = 100 (Low Traffic)
5 < Count ≤ 15 → Traffic Score = 70 (Medium Traffic)
Count > 15 → Traffic Score = 40 (High Traffic)
```
### 严重程度评级 (定性)
基于损伤面积百分比：
```
≤ 1.0% → Excellent
1.0-3.0% → Minor
3.0-6.0% → Moderate
6.0-10% → Severe
> 10% → Critical
```
### 基础设施类别
基于基础设施评分：
```
90-100 → Excellent (No maintenance needed)
75-89 → Good (Low priority)
60-74 → Fair (Medium priority)
40-59 → Poor (High priority)
0-39 → Critical (Immediate action required)
```
### 养护优先级
基于行动级别的分类：
```
Infrastructure Score 90-100 → Priority: None
Infrastructure Score 75-89 → Priority: Low
Infrastructure Score 60-74 → Priority: Medium
Infrastructure Score 40-59 → Priority: High
Infrastructure Score 0-39 → Priority: Immediate
```
## 指标与算法
### 损伤指标
针对每种检测到的损伤类型：
| 指标 | 描述 | 计算方式 |
|--------|-------------|-------------|
| **数量** | 检测到的实例数 | 每个类别的边界框总和 |
| **总面积** | 边界框面积总和（像素） | Σ (x2-x1) × (y2-y1) |
| **平均面积** | 检测到的损伤的平均大小 | 总面积 / 数量 |
| **最大面积** | 最大的单一损伤实例 | Max(areas) |
| **损伤占比 %** | 覆盖的道路百分比 | (总面积 / 图像面积) × 100 |
### 交通指标
| 指标 | 描述 |
|--------|-------------|
| **车辆计数** | 每种车辆类型的单独计数 |
| **车辆总数** | 检测到的所有车辆的总和 |
| **交通等级** | 分类：低 / 中 / 高 |
### 质量指标
| 指标 | 描述 |
|--------|-------------|
| **图像尺寸** | 宽度和高度（以像素为单位） |
| **检测置信度** | 每次检测的模型置信度得分 (0.0-1.0) |
## 输出示例
### 单张图像 JSON 报告 (`India_000004.json`)
```
{
"image_width": 720,
"image_height": 720,
"longitudinal_crack_count": 0,
"transverse_crack_count": 0,
"alligator_crack_count": 0,
"pothole_count": 0,
"total_damage_count": 0,
"total_damage_bbox_area": 0,
"average_damage_bbox_area": 0.0,
"largest_damage_bbox_area": 0.0,
"damage_area_percentage": 0.0,
"car_count": 0,
"motorcycle_count": 0,
"bus_count": 0,
"truck_count": 0,
"bicycle_count": 0,
"total_vehicle_count": 0,
"traffic_level": "Low",
"road_damage_score": 100,
"traffic_score": 100,
"infrastructure_score": 100,
"infrastructure_category": "Excellent",
"severity": "Excellent",
"maintenance_priority": "None",
"recommendations": [],
"filename": "India_000004.jpg"
}
```
### 数据集汇总 JSON (`summary.json`)
```
{
"total_images": 1,
"average_infrastructure_score": 91.0,
"average_damage_score": 100.0,
"average_traffic_score": 70.0,
"total_potholes": 0,
"total_longitudinal_cracks": 0,
"total_transverse_cracks": 0,
"total_alligator_cracks": 0,
"total_cars": 4,
"total_motorcycles": 0,
"total_buses": 0,
"total_trucks": 2,
"total_bicycles": 0,
"distribution": {
"Excellent": 1,
"Good": 0,
"Fair": 0,
"Poor": 0,
"Critical": 0
},
"average_damage_area_percentage": 0.0,
"average_vehicle_count": 6.0
}
```
### HTML 报告功能
生成的 `report.html` 包含：
- **仪表盘概览**
- 已处理图像总数
- 平均基础设施评分
- 平均损伤和交通评分
- 关键指标卡片
- **汇总统计数据**
- 按类型划分的损伤总数
- 按类型划分的车辆总数
- 基础设施类别分布
- **可视化图表**
- 损伤柱状图
- 车辆检测柱状图
- 基础设施健康直方图
- 严重程度分布饼图
- **单张图像表**
- 带标注图像的缩略图
- 单独的损伤计数
- 单独的车辆计数
- 基础设施评分
- 养护优先级
- AI 生成的建议
- **响应式设计**
- 适配移动端的布局
- 嵌入式图像（无外部依赖）
- 专业的样式设计
## 使用的模型
### 1. YOLOv8_Small_RDD (道路损伤检测)
- **用途**：检测并分类道路损伤
- **架构**：YOLOv8 Small 变体
- **训练数据**：RDD2020 Challenge 数据集
- **输出类别**：
- 纵向裂缝
- 横向裂缝
- 龟裂
- 坑洼
- **大小**：~26 MB
- **置信度阈值**：0.25（可调整）
### 2. YOLOv11n (交通检测)
- **用途**：检测并分类车辆
- **架构**：YOLOv11 Nano 变体
- **训练数据**：COCO 数据集
- **输出类别**（已过滤）：
- 轿车 (COCO ID: 2)
- 摩托车 (COCO ID: 3)
- 公交车 (COCO ID: 5)
- 卡车 (COCO ID: 7)
- 自行车 (COCO ID: 1)
- **大小**：~25 MB
- **置信度阈值**：0.25（可调整）
## 架构
### 系统组件
```
┌─────────────────────────────────────────────────────────────┐
│ Input Images │
│ (Single file or folder of JPG/PNG) │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Load Pre-trained Models │
│ ├─ YOLOv8_Small_RDD │
│ └─ YOLOv11n │
└───────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ For Each Image │
├─ Road Damage Detection │
├─ Traffic Vehicle Detection │
└───────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Civic Engine Processing │
├─ Compute Damage Metrics │
├─ Compute Traffic Metrics │
├─ Calculate Scores │
├─ Generate Recommendations │
└───────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
Annotated JSON Report Visualization
Images (Per-image) Generation
│ │ │
└────────────────┼────────────────┘
▼
┌───────────────────────────────┐
│ Report Generation │
├─ HTML Report │
├─ Summary JSON │
├─ Charts & Plots │
└───────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Output Directory │
├─ outputs/annotated/ │
├─ outputs/json/ │
├─ outputs/plots/ │
├─ outputs/report.html │
└─ outputs/summary.json │
└───────────────────────────────┘
```
### 模块结构
```
civicvision/
├── main.py # Entry point, CLI argument parsing
├── modules/
│ ├── __init__.py
│ ├── road_detector.py # Road damage detection module
│ ├── traffic_detector.py # Traffic detection module
│ ├── civic_engine.py # Metrics computation & scoring
│ ├── visualization.py # Image annotation & charting
│ └── report_generator.py # HTML & JSON report generation
├── YOLOv8_Small_RDD.pt # Pre-trained road damage model
├── yolo11n.pt # Pre-trained traffic model
└── README.md
```
## 项目结构
```
civicvision/
├── main.py # Main entry point
├── README.md # This file
├── requirements.txt # Python dependencies
├── model_names.txt # Model information
├── pip_list.txt # Full pip package list
│
├── modules/ # Core modules
│ ├── __init__.py
│ ├── civic_engine.py # Metric computation
│ ├── report_generator.py # Report generation
│ ├── road_detector.py # Road damage detection
│ ├── traffic_detector.py # Vehicle detection
│ └── visualization.py # Visualization utilities
│
├── YOLOv8_Small_RDD.pt # Road damage model
├── yolo11n.pt # Traffic detection model
│
└── outputs/ # Generated outputs
├── annotated/ # Annotated images
├── json/ # Per-image JSON reports
├── plots/ # Generated charts
├── report.html # Interactive HTML report
└── summary.json # Dataset summary
```
## 环境要求
### Python 依赖项
```
ultralytics>=8.0.0
opencv-python>=4.8.0
numpy>=1.24.0
matplotlib>=3.7.0
Pillow>=10.0.0
```
### 系统要求
- **操作系统**：Windows、macOS 或 Linux
- **Python**：3.8+
- **RAM**：最低 4GB（推荐 8GB+）
- **磁盘空间**：2GB+（用于存放模型）
- **GPU**：可选（CUDA 11.0+ 可实现更快的推理速度）
## 高级用法
### 调整置信度阈值
编辑 `main.py` 以自定义模型置信度阈值：
```
# main.py 中的第 75-76 行
road_detector = RoadDamageDetector(model_path="YOLOv8_Small_RDD.pt", conf_threshold=0.30)
traffic_detector = TrafficDetector(model_path="yolo11n.pt", conf_threshold=0.30)
```
较低的值 (0.15-0.25) = 检测更多（灵敏度更高）
较高的值 (0.35-0.50) = 检测更少（特异性更高）
### 处理大型数据集
高效处理数以千计的图像：
```
# 处理文件夹中的所有图像
python main.py /path/to/large_dataset --output /path/to/results
# 或者拆分为 batches 并分别处理
python main.py /path/to/dataset_batch_1 --output /path/to/results_1
python main.py /path/to/dataset_batch_2 --output /path/to/results_2
```
## 性能说明
- **单张图像**：~2-5 秒（取决于图像大小和硬件）
- **批处理（100 张图像）**：~3-8 分钟
- **报告生成**：包含在处理时间内
- **GPU 加速**：比 CPU 快大约 3-5 倍
## 故障排除
### 找不到模型
```
Error: FileNotFoundError: YOLOv8_Small_RDD.pt
```
**解决方案**：确保模型文件位于项目根目录下
### 内存不足
```
Error: CUDA out of memory
```
**解决方案**：
- 每次处理较少的图像
- 在 CPU 上运行：编辑 `road_detector.py` 和 `traffic_detector.py` 以强制使用 CPU
- 降低图像分辨率
### 未发现检测结果
- 检查模型是否正确加载
- 验证图像格式（支持 JPG、PNG）
- 降低置信度阈值（见高级用法）
- 检查图像质量和分辨率
## 贡献
欢迎您的贡献！请：
1. Fork 该仓库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 发起 Pull Request
## 许可证
该项目基于 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。
标签：人工智能, 代码示例, 基础设施评估, 数据分析, 智慧交通, 深度学习, 用户模式Hook绕过, 目标检测, 计算机视觉, 逆向工具