Metadata-Version: 2.4
Name: helmet-detector
Version: 2.1.0
Summary: 头盔检测工具 - 基于YOLOv12的视频/图片头盔佩戴检测，支持违规告警通知
Author-email: xzl <3106174526@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://gitee.com/xie-zl/open
Project-URL: Source, https://gitee.com/xie-zl/open
Keywords: helmet,detection,yolo,computer-vision,safety,notification
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23.0
Requires-Dist: opencv-python>=4.6.0
Requires-Dist: pillow>=7.1.2
Requires-Dist: torch>=1.8.0
Requires-Dist: torchvision>=0.9.0
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: pyyaml>=5.3.1
Requires-Dist: requests>=2.23.0

# 头盔检测工具 (Helmet Detector) v2.1

基于 YOLOv12 的头盔佩戴检测工具，支持二次检测复验、违规时间记录、违规视频片段保存、**违规告警通知**。

## 安装

```bash
pip install helmet_detector-2.1.0-py3-none-any.whl
```

## 使用方法

### 命令行

```bash
# 检测视频，结果保存到指定目录（默认1秒违规片段）
helmet-detect --source video.mp4 --output D:/my_results

# 自定义违规视频片段时长（2秒）
helmet-detect --source video.mp4 --output results/ --clip-duration 2

# 检测图片
helmet-detect --source image.jpg --output results/

# 调整置信度阈值
helmet-detect --source video.mp4 --output results/ --conf 0.6

# 实时显示检测画面
helmet-detect --source video.mp4 --output results/ --show
```

### 参数说明

| 参数 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--source` | `-s` | 输入视频或图片路径 | 必填 |
| `--output` | `-o` | 输出目录路径 | detection_results |
| `--conf` | `-c` | 置信度阈值 | 0.5 |
| `--model` | `-m` | 自定义模型路径 | 内置模型 |
| `--tracker` | | 跟踪算法 (botsort/bytetrack) | botsort |
| `--clip-duration` | | 违规视频片段时长（秒） | 1.0 |
| `--show` | | 实时显示检测画面 | 否 |
| `--no-video` | | 不保存标注视频 | 否 |
| `--no-notify` | | 禁用违规通知 | 否 |
| `--notify-config` | | 通知配置文件路径 | notification_config.yaml |

### Python API

```python
from helmet_detector_pkg import HelmetDetector

# 初始化检测器
detector = HelmetDetector(confidence=0.5)

# 视频检测（带违规视频片段）
result = detector.detect_video(
    video_path="video.mp4",
    output_dir="D:/my_results",
    clip_duration=2.0,  # 违规视频片段时长（秒）
    show=False
)

# 图片检测
detections = detector.detect_image(
    image_path="image.jpg",
    output_dir="results/"
)
```

## 输出内容

检测完成后，输出目录结构：

```
detection_results/
├── violation_frames/        # 违规帧（带标注框）
│   └── violation_id1_frame94.jpg
├── violation_avatars/       # 违规头像（裁剪图）
│   └── avatar_id1_frame94.jpg
├── violation_videos/        # 违规视频片段
│   └── violation_id1_frame94.mp4
├── violation_records.txt    # 违规记录（含时间）
└── detected_xxx.mp4         # 标注后的完整视频
```

### 违规记录示例

```
============================================================
Track_ID: 19 | Frame: 94
违规时间: 00:03.13 (视频第 3.13 秒)
初检置信度: 0.71 | 复验置信度: 0.71
违规帧: violation_frames/violation_id19_frame94.jpg
违规头像: violation_avatars/avatar_id19_frame94.jpg
违规视频: violation_videos/violation_id19_frame94.mp4
============================================================
```

## 新功能 (v2.1)

- **🔔 违规告警通知** - 支持邮件/企业微信/Server酱/钉钉多渠道通知
- **智能触发** - 可配置置信度阈值和冷却时间
- **附带截图** - 邮件通知可携带违规截图

## 功能列表 (v2.0+)

- **递增编号目录** - 每次运行自动创建新目录，不会覆盖
- **二次检测复验** - 提高检测准确性，减少误报
- **违规时间记录** - 精确记录违规发生的时间点
- **违规视频片段** - 自动截取违规前后的视频片段

## 检测类别

- ✅ **With Helmet** - 已佩戴头盔 (绿色框)
- ⚠️ **Without Helmet** - 未佩戴头盔 (红色框，触发复验)
