# FrameHunter

**Repository Path**: gxngit/FrameHunter

## Basic Information

- **Project Name**: FrameHunter
- **Description**: 自动数帧系统
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-10
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FrameHunter - 高速摄像自动化数帧分析软件

## 项目简介

FrameHunter 是一套基于计算机视觉的高速摄像自动化数帧分析软件,能够从高速相机视频中自动识别帧边界、计算帧间隔、检测掉帧/卡顿,并生成专业的性能报告。主要用于分析手机应用冷启动的启动视频,识别应用冷启动耗时。

## 主要功能

- **视频加载与预处理**: 支持高帧率视频(240fps+)加载,自动提取元数据,生成代理文件
- **ROI区域管理**: 支持多个ROI区域框选、裁剪、持久化
- **帧分析**: 帧差、SSIM、边缘检测、运动检测四种分析指标
- **关键帧标记**: 标记启动开始帧和首帧完成帧,自动计算冷启动耗时
- **缩略图网格**: 快速浏览视频内容,点击跳转
- **报告生成**: 支持PDF、HTML、Excel三种格式的专业报告

## 系统要求

- 操作系统: Windows 11
- Python: 3.9+
- 内存: 8GB+ (处理4K视频)
- 磁盘空间: 2GB+

## 安装说明

### 1. 克隆项目

```bash
git clone <repository-url>
cd FrameHunter
```

### 2. 创建虚拟环境

```bash
python -m venv venv
venv\Scripts\activate  # Windows
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 安装FFmpeg

下载FFmpeg并添加到系统PATH,或放置在项目根目录的`tools/`文件夹中。

## 使用说明

### 启动程序

```bash
python main.py
```

### 基本操作流程

1. **加载视频**: 点击"文件" → "打开视频",选择MP4视频文件
2. **框选ROI**: 点击"添加ROI"按钮,在视频预览上拖拽绘制矩形区域
3. **分析视频**: 选择ROI后,点击"开始分析"按钮
4. **标记关键帧**:
   - 按Page Down跳转到运动峰值
   - 使用方向键微调
   - 按Ctrl+S标记启动开始帧
   - 按Ctrl+E标记首帧完成帧
5. **导出报告**: 点击"导出报告",选择格式和内容模块

### 快捷键

| 快捷键 | 功能 |
|--------|------|
| Page Up/Down | 跳转到上一个/下一个运动峰值 |
| ←/→ | 逐帧移动 |
| Shift+←/→ | 逐秒移动 |
| Ctrl+S | 标记启动开始帧 |
| Ctrl+E | 标记首帧完成帧 |
| Space | 播放/暂停 |
| Tab | 切换ROI |

## 项目结构

```
FrameHunter/
├── src/
│   ├── ui/              # 用户界面模块
│   ├── services/        # 业务逻辑服务
│   ├── repositories/    # 数据访问层
│   ├── infrastructure/  # 基础设施层
│   ├── models/          # 领域模型
│   └── utils/           # 工具类
├── tests/               # 测试代码
├── resources/           # 资源文件
├── output/              # 输出目录
├── temp/                # 临时文件目录
├── .codeartsdoer/       # SDD文档
├── requirements.txt     # 依赖列表
└── README.md            # 项目说明
```

## 技术栈

- **前端UI**: Python + PyQt6
- **视频处理**: OpenCV + FFmpeg
- **视觉算法**: OpenCV + NumPy + SciPy
- **报告生成**: Matplotlib + ReportLab + openpyxl
- **数据存储**: SQLite

## 开发指南

详细的开发文档请参考`.codeartsdoer/specs/frame_hunter/`目录下的文档:
- `spec.md`: 需求规格文档
- `design.md`: 技术设计文档
- `tasks.md`: 编码任务清单

## 许可证

MIT License

## 联系方式

如有问题或建议,请提交Issue或Pull Request。