video_probe/PAUSE_RESUME_FEATURE.md

# Video YOLO Object Prescan - 暂停与续传功能

## 新增功能

### ✅ 暂停功能 (Ctrl+C)

在处理视频时，随时可以按 `Ctrl+C` 暂停处理：

```bash
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt

# 处理中...
# Progress: 1500/3615 frames (41.5%) - 3 objects - Elapsed: 75.2s, ETA: 105.8s

# 按 Ctrl+C 暂停
^C
============================================================
⏸  PAUSED - Saving progress...
============================================================
✓ Progress saved to: video.yolo.json
  Frames processed: 1500/3615
  Total detections: 4500
  Elapsed time: 75.2s

💡 Run the same command again to resume from frame 1501
============================================================
```

### ✅ 断点续传

下次运行相同命令时，会自动检测已存在的 `.yolo.json` 文件：

```bash
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt

============================================================
📂 Found existing data: video.yolo.json
   Last processed frame: 1500
============================================================

Resume from last checkpoint? (Y/n): y
Resuming from checkpoint...

Loading YOLO model from: yolov8n.pt
✓ Model loaded successfully

Video Info:
  Path: video.mp4
  Resolution: 1920x1080
  FPS: 30.00
  Total frames: 3615
  Duration: 120.5s (00:02:00)
  Resume from: frame 1501

Output: video.yolo.json
============================================================

Resuming video processing...
💡 Press Ctrl+C to pause and save progress

  Progress: 1600/3615 frames (44.3%) - 2 objects - Elapsed: 5.1s, ETA: 102.3s
  ...
```

### ✅ 自动保存

处理过程中每 **60 秒**自动保存一次进度，防止意外中断导致数据丢失。

## 使用场景

### 场景 1: 长视频处理

```bash
# 开始处理 2 小时视频
python3 video_yolo_object_prescan.py long_video.mp4 yolov8n.pt

# 处理 1 小时后需要关机
# 按 Ctrl+C 暂停并保存

# 第二天继续
python3 video_yolo_object_prescan.py long_video.mp4 yolov8n.pt
# 选择 Y 继续处理
```

### 场景 2: 测试不同参数

```bash
# 第一次处理（使用 yolov8n）
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt
# 处理到一半，想测试 yolov8s

# 按 Ctrl+C 暂停
# 删除或重命名 .yolo.json
mv video.yolo.json video.yolov8n.json

# 使用新模型重新处理
python3 video_yolo_object_prescan.py video.mp4 yolov8s.pt
```

### 场景 3: 系统崩溃恢复

```bash
# 处理中系统崩溃或断电
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt
# ... 系统崩溃 ...

# 重启后继续（自动保存了最后 60 秒内的进度）
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt
# 选择 Y 从上次保存的帧继续
```

## JSON 文件格式

`.yolo.json` 文件包含状态信息：

```json
{
  "metadata": {
    "video_path": "/path/to/video.mp4",
    "total_frames": 3615,
    "processed_at": "2026-03-06T12:00:00",
    "last_saved_at": "2026-03-06T12:30:00",
    "status": "interrupted",  // 或 "completed"
    "processing_time": 1800.5,
    "total_detections": 7230
  },
  "frames": {
    "1": { ... },
    "2": { ... },
    ...
    "1500": { ... }  // 最后处理的帧
  }
}
```

**状态字段**:
- `in_progress` - 正在处理中
- `interrupted` - 用户中断（Ctrl+C）
- `completed` - 处理完成

## 命令行选项

```bash
# 基本用法
python3 video_yolo_object_prescan.py <video_path> <yolo_model>

# 示例
python3 video_yolo_object_prescan.py my_video.mp4 yolov8n.pt

# 从头开始（忽略现有文件）
python3 video_yolo_object_prescan.py my_video.mp4 yolov8n.pt
# 当提示 "Resume from last checkpoint?" 时输入 n
```

## 技术细节

### 信号处理

使用 Python `signal` 模块捕获 `SIGINT` (Ctrl+C)：

```python
signal.signal(signal.SIGINT, signal_handler)
```

### 帧定位

使用 OpenCV `cv2.CAP_PROP_POS_FRAMES` 精确定位到指定帧：

```python
cap.set(cv2.CAP_PROP_POS_FRAMES, last_frame)
```

### 数据完整性

- 每帧处理完成后立即写入内存
- 每 60 秒自动保存到磁盘
- Ctrl+C 时立即保存当前进度
- 使用 JSON 格式，易于检查和恢复

## 性能影响

- **内存**: 略有增加（保存所有已处理帧的数据）
- **磁盘 I/O**: 每 60 秒一次写入
- **CPU**: 无额外开销
- **恢复速度**: < 1 秒（仅加载 JSON 文件）

## 注意事项

1. **磁盘空间**: `.yolo.json` 文件会随处理进度增长，确保有足够空间
2. **不要修改 JSON**: 手动编辑可能导致数据损坏
3. **模型一致性**: 续传时使用相同的 YOLO 模型
4. **视频不变**: 续传时视频文件不能改变

## 故障排除

### Q: 提示 "Could not load existing file"

A: JSON 文件可能损坏，删除后重新开始：
```bash
rm video.yolo.json
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt
```

### Q: 想从头开始处理

A: 删除现有 JSON 文件或在提示时选择 `n`：
```bash
# 方法 1: 删除文件
rm video.yolo.json

# 方法 2: 运行时选择 n
python3 video_yolo_object_prescan.py video.mp4 yolov8n.pt
# Resume from last checkpoint? (Y/n): n
```

### Q: 处理速度变慢

A: JSON 文件过大导致保存变慢，这是正常现象。建议：
- 使用更快的存储设备（SSD）
- 分段处理超长视频

## 更新日志

### v2.0.0 (2026-03-06)

**新增功能**:
- ✅ Ctrl+C 暂停并保存进度
- ✅ 断点续传（自动检测并询问）
- ✅ 每 60 秒自动保存
- ✅ 状态字段记录（in_progress/interrupted/completed）
- ✅ 改进的进度显示和 ETA 计算

**改进**:
- 更友好的用户提示
- 详细的保存信息
- 自动恢复功能