CCTV-detector-new 0.1.0
CCTV Intelligent Detection System based on YOLOv8
License: MIT
Requires Python: >=3.8

# CCTV 智能检测系统 (CCTV Intelligent Detection System)

基于YOLOv8的CCTV智能检测系统，用于货舱监控场景下的目标检测和智能告警。系统可识别不同覆盖状态（完全覆盖、部分覆盖、未覆盖）以及机械设备等异常情况。

## 系统概述 (System Overview)

本系统采用了YOLOv8目标检测算法，实现了高效的图像分析能力，具有以下特点：

- **高性能检测**：借助YOLOv8强大的目标检测能力，快速准确地识别图像中的目标
- **智能告警**：自动分析检测结果，针对特定场景（如机械入侵）发出告警
- **灵活部署**：提供独立命令行工具和RESTful API服务两种使用方式
- **可视化结果**：自动生成直观的检测结果图像，标注目标位置和类别
- **多种输入方式**：支持本地图像路径、图像文件上传两种输入方式

## 目录结构 (Directory Structure)

```
CCTV_optimized/
├── models/                  # 模型文件目录
│   └── segment_best228.pt   # YOLOv8分割检测模型
├── results/                 # 检测结果保存目录
├── temp/                    # 临时文件目录
├── test_images/             # 测试样例图像目录
├── cctv_detector.py         # 核心检测器类
├── cctv_server.py           # RESTful API服务器
├── detect.py                # 命令行检测工具
├── start_server.sh          # Linux/Mac启动脚本
├── start_server.bat         # Windows启动脚本
├── requirements.txt         # 项目依赖列表
└── README.md                # 本文档
```

## 环境要求 (Requirements)

- Python 3.8+
- 依赖包（见requirements.txt）：
  ```
  numpy>=1.20.0
  opencv-python>=4.5.0
  torch>=1.9.0
  torchvision>=0.10.0
  ultralytics>=8.0.0
  fastapi>=0.68.0
  uvicorn>=0.15.0
  python-multipart>=0.0.5
  requests>=2.26.0
  tqdm>=4.62.0
  matplotlib>=3.4.0
  python-dotenv>=0.19.0
  ```

## 安装指南 (Installation)

1. 克隆或下载本项目到本地

2. 创建并激活虚拟环境（强烈推荐）：

   **使用Conda**:
   ```bash
   # 创建名为cctv的虚拟环境
   conda create -n cctv python=3.10
   # 激活环境
   conda activate cctv
   ```

3. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```

4. 确保模型文件已存在于`models`目录下。如不存在，请下载相应模型文件。

## 使用方法 (Usage)

两种使用方式：命令行工具和API服务器。

### 1. 命令行工具 (Command Line Tool)

无需启动服务器，直接使用命令行检测图像：

```bash
python detect.py test_images/0037.JPG --conf 0.3 --iou 0.45 --model models/segment_best228.pt
```

参数说明：
- 第一个参数: 图像文件路径
- `--conf`, `-c`: 置信度阈值 (默认: 0.25)
- `--iou`, `-i`: IoU阈值 (默认: 0.45)
- `--model`, `-m`: 模型文件路径 (默认: models/segment_best228.pt)
- `--output`, `-o`: 结果保存的JSON文件名 (可选，保存在results目录下)
- `--summary`, `-s`: 显示简洁结果摘要而非完整JSON (默认输出完整JSON)

检测结果将以JSON格式保存在`results`目录下，同时生成可视化图像。默认情况下，命令行工具的输出格式与API服务器完全一致，方便统一处理。


### 2. API服务器 (API Server)

#### 启动服务器

在Linux/Mac系统：
```bash
./start_server.sh
```

在Windows系统：
```bash
start_server.bat
```

服务器默认在`http://localhost:8000`启动。

命令行参数（可选）：
```bash
./start_server.sh --port 8000 --host 0.0.0.0 --device cpu --model models/segment_best228.pt --confidence 0.25 --iou 0.45
```

#### API使用示例

##### 1. 上传图像检测
```bash
curl -X POST "http://localhost:8000/detect" \
  -F "file=@test_images/0037.JPG" \
  -F "confidence=0.25" \
  -F "iou=0.45"
```

##### 2. 使用本地路径检测
```bash
curl -X POST "http://localhost:8000/detect/path" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/absolute/path/to/image.jpg",
    "confidence": 0.25,
    "iou": 0.45
  }'
```

##### 3. 获取检测结果图像
```
http://localhost:8000/results/filename.jpg
```

## API响应格式 (API Response Format)

所有API端点返回统一的JSON格式：

```json
{
  "success": true,
  "data": {
    "image_path": "原始图像路径",
    "timestamp": "2023-01-01 12:00:00",
    "processing_time": 0.123,
    "detections": [
      {
        "id": 0,
        "class_name": "partially_covered",
        "confidence": 0.987,
        "bbox": {
          "x1": 3,
          "y1": 62,
          "x2": 407,
          "y2": 350
        }
      }
    ],
    "alarms": {
      "machinery_intrusion": [
        {
          "object_class": "machine",
          "confidence": 0.871,
          "location": {
            "x1": 145,
            "y1": 0,
            "x2": 217,
            "y2": 160
          }
        }
      ]
    },
    "visualization_path": "results/image_result_12345678.jpg",
    "visualization_url": "/results/image_result_12345678.jpg"
  },
  "error": null
}
```

**说明**:
- `success`: 表示请求是否成功处理
- `data`: 包含检测结果的详细信息
  - `detections`: 检测到的所有目标列表
  - `alarms`: 触发的告警信息
  - `visualization_path`: 可视化结果的服务器文件路径
  - `visualization_url`: 可视化结果的URL访问路径

## 调用示例

### Python

```python
import requests
import json

# 1. 上传文件方式
with open("image.jpg", "rb") as f:
    files = {"file": f}
    response = requests.post(
        "http://localhost:8000/detect",
        files=files,
        data={"confidence": 0.25, "iou": 0.45}
    )

# 2. 本地路径方式
response = requests.post(
    "http://localhost:8000/detect/path",
    json={
        "path": "/absolute/path/to/image.jpg",
        "confidence": 0.25,
        "iou": 0.45
    }
)

# 处理结果
result = response.json()
if result["success"]:
    # 获取检测结果
    detections = result["data"]["detections"]
    # 获取告警信息
    alarms = result["data"]["alarms"]
    # 获取可视化图像URL (已经过URL编码)
    vis_url = f"http://localhost:8000{result['data']['visualization_url']}"
    print(f"检测到 {len(detections)} 个目标，可视化结果地址: {vis_url}")
else:
    print(f"检测失败: {result['error']}")
```

### JavaScript

```javascript
// 上传文件
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('confidence', 0.25);
formData.append('iou', 0.45);

fetch('http://localhost:8000/detect', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(result => {
  if (result.success) {
    console.log(`检测到 ${result.data.detections.length} 个目标`);
    // 显示可视化结果
    const visUrl = `http://localhost:8000${result.data.visualization_url}`;
    document.getElementById('resultImage').src = visUrl;
  }
})
.catch(error => console.error('Error:', error));
```

## 检测结果说明 (Result Explanation)

系统能够识别的主要类别：

- `covered`: 完全覆盖状态
- `partially_covered`: 部分覆盖状态
- `uncovered`: 未覆盖状态
- `machine`: 机械设备
- `person`: 人员
- `ship`: 船舶
- `camera_error`: 摄像头异常

告警类型：

- `machinery_intrusion`: 机械入侵告警，当检测到机械设备时触发
- `person_intrusion`: 人员入侵告警，人员出现在货舱范围内触发
- `vessel_approach`: 船只靠近告警，其他船只靠近时触发
- `camera_alarm`: 摄像头异常告警，摄像头无正常信号或被意外遮挡时触发

## 许可协议 (License)

本项目采用MIT许可协议