Initial implementation of video_probe (Rust)

Core modules: - probe.rs: ffprobe execution logic - parser.rs: JSON parsing logic - output.rs: Output formatting - lib.rs: Library interface - main.rs: CLI entry point Features: - Extract video metadata using ffprobe - Parse video/audio/subtitle streams - Save to JSON file - Console summary output Documentation: - Added QUICKSTART.md - Added ENVIRONMENT_SETUP_REPORT.md
2026-03-07 10:10:19 +08:00
commit f3e2d2dca7
464 changed files with 125611 additions and 0 deletions
--- a/PAUSE_RESUME_FEATURE.md
+++ b/PAUSE_RESUME_FEATURE.md
@@ -0,0 +1,236 @@
+# 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 计算
+
+**改进**:
+- 更友好的用户提示
+- 详细的保存信息
+- 自动恢复功能