# 槍枝檢測模型 Charade 評估報告

## 緣起

接續 `2026-05-07_gun_detection_training_log.md`，訓練完成後進行 CoreML 匯出與真實影片（Charade 1963）實測。

## 訓練結果摘要

- **模型**: YOLOv8n fine-tuned on gun dataset (CC BY 4.0, 905 images)
- **Classes**: grenade (0), knife (1), pistol (2), rifle (3)
- **Best mAP50**: 0.813 (epoch 84)
- **Weights**: 6.0MB (best.pt), CoreML export 5.9MB (best.mlpackage, FP16)
- **Validation 表現**: 對 dataset 測試圖片（近距離槍枝特寫）檢出率良好，pistol 最高 0.906

## Charade 掃描結果（24 取樣點，每 300s）

| 時間 | 類別 | 信心 | 真實內容（人工判定） | 截圖 |
|------|------|------|---------------------|------|
| t=600s | pistol×2, rifle | 0.16–0.30 | ❌ 非槍 | `output_dev/gun_detections/gun_t600s.jpg` |
| t=1200s | knife | 0.37 | ❌ 非刀 | `output_dev/gun_detections/gun_t1200s.jpg` |
| t=1800s | pistol | 0.19 | ❌ 非槍 | `output_dev/gun_detections/gun_t1800s.jpg` |
| t=2400s | knife | 0.18 | ❌ 非刀 | `output_dev/gun_detections/gun_t2400s.jpg` |
| t=3000s | pistol | 0.16 | ❌ 非槍 | `output_dev/gun_detections/gun_t3000s.jpg` |
| t=5400s | pistol×2 | **0.45**, 0.17 | ❌ 非槍（實際為 **郵票**） | `output_dev/gun_detections/gun_t5400s.jpg` |
| t=6600s | grenade | 0.22 | ❌ 非手榴彈 | `output_dev/gun_detections/gun_t6600s.jpg` |

**結論：7 個觸發點全部為 False Positive，無一真實槍枝。**

## 問題分析

1. **訓練資料偏差**: 905 張全為 Roboflow 槍枝特寫（近距離、置中、清晰），與電影中中遠景、手持、部分遮蔽的槍枝畫面分布完全不同
2. **電影本身限制**: Charade 為 1963 年輕喜劇懸疑片，槍枝鏡頭稀少且多為遠景
3. **類別定義寬鬆**: dataset 含 grenade/knife/pistol/rifle，但電影中可能出現的「槍」形式與訓練集差異大

## 意外發現

t=5400s 畫面中模型辨識為 pistol (0.45) 的物體實際上是 **郵票** — 恰好是 Charade 劇情核心（價值 25 萬美金的稀有郵票）。這是一個有意義的誤判，提示未來可以將「郵票偵測」納入模型。

## 後續建議

### 模型改善
1. 收集 200-500 張電影真實槍枝畫面（動作片如 John Wick, Die Hard），重新標註訓練
2. 改用 COCO pre-trained weights 初始化（YOLOv8n.pt），提升泛化能力
3. 加入郵票類別（stamp），成為 5-class detector

### Pipeline 整合（暫緩）
- 在模型達到可接受準確率之前，不整合進主 pipeline
- 保留 scripts/gun_detector.py 作為獨立工具供後續測試

## 相關檔案

- `models/gun/gun_detector/weights/best.pt` — PyTorch 權重（6MB）
- `models/gun/gun_detector/weights/best.mlpackage` — CoreML 匯出版（5.9MB, FP16, ANE-ready）
- `output_dev/gun_detections/` — 7 張標註截圖
- `data/gun_yolo/` — 訓練資料集（905 images, CC BY 4.0）
