魔方比赛视频处理工具

三大功能：

1. 方向校正 — 快速检测横倒视频并无损写入标准显示方向，不重编码
2. OCR 识别成绩 — 自动读取大显上的还原时间，重命名视频文件
3. 人脸分类 — 按选手人脸将视频自动分到对应文件夹

快速开始

安装依赖

uv sync   # 建 .venv 并装齐依赖 (一次性)

一键处理 (推荐)

# 先预览，不实际操作
.\process-videos.ps1 "Z:\魔方比赛\260307" -DryRun

# 确认无误后，正式执行 (OCR重命名 + 人脸分类)
.\process-videos.ps1 "Z:\魔方比赛\260307"

# 分类时复制而非移动
.\process-videos.ps1 "Z:\魔方比赛\260307" -Copy

只跑其中一步

# 只 OCR 重命名，不分类
.\process-videos.ps1 "Z:\魔方比赛\260307" -SkipClassify

# 只分类，不 OCR (视频已命名好)
.\process-videos.ps1 "Z:\魔方比赛\260307" -SkipOCR

处理流程

原始视频目录       快速方向校正           OCR 重命名               人脸分类
┌─────────────────┐      ┌───────────────┐      ┌────────────────┐
│ IMG_0001.MP4    │ ──→  │ 显示矩阵转正 │ ──→  │ 4.716.MP4     │ ──→  │ 张三/4.716.MP4 │
│ IMG_0002.MP4    │      │ 不重新编码   │      │ 1_46.315.MP4  │      │ 李四/1_46.315… │
│ IMG_0003.MP4    │      │ 正常片不改动 │      │ 43.243.MP4    │      │ unknown/…      │
└─────────────────┘      └──────────────┘      └───────────────┘      └────────────────┘

方向检测会把三帧缩到最长边 640 像素，再比较四个方向的人脸检测得分。只有证据明显时才修改 MP4/MOV 的标准显示矩阵；画面和音频码流原样保留。被替换的原片会进入 Windows 回收站，方向无法可靠判断的视频保持原样。

uv run python orient_videos.py "D:\video\5.746.MP4" --dry-run
uv run python orient_videos.py "D:\video\5.746.MP4"

方向校正只修改 MP4/MOV；AVI/MKV 等其他视频会跳过并继续后续 OCR 和分类。

OCR 成绩识别 (ocr_timer.py)

从视频最后几秒的画面中识别七段 LED 大显上的还原时间。

# 仅识别，不重命名
uv run python ocr_timer.py "Z:\魔方比赛\260307"

# 识别并重命名
uv run python ocr_timer.py "Z:\魔方比赛\260307" --rename

# 预览重命名
uv run python ocr_timer.py "Z:\魔方比赛\260307" --rename --dry-run

支持的成绩格式：

• X.XXX → 4.716.MP4
• XX.XXX → 43.243.MP4
• X:XX.XX → 1_46.315.MP4 (分钟用 _ 分隔)

支持的大显品牌： QiYi (红色 LED), MoYu (橙/黄色 LED) 等

人脸分类 (classify.py)

准备参考照片

在 person/ 目录下，为每位选手创建子文件夹，放入 1~3 张正脸照片：

person/
├── 张三/
│   ├── photo1.jpg
│   └── photo2.jpg
├── 李四/
│   └── photo1.jpg
└── ...

照片要求：正脸、光线好、无遮挡。1 张就够，2~3 张可提高精度。

uv run python classify.py "Z:\魔方比赛\260307" --dry-run
uv run python classify.py "Z:\魔方比赛\260307"
uv run python classify.py "Z:\魔方比赛\260307" --copy

参数一览

process-videos.ps1

参数	说明
-DryRun	仅预览，不实际操作
-Copy	分类时复制而非移动
-SkipOCR	跳过 OCR 重命名
-SkipClassify	跳过人脸分类
-SkipOrient	跳过快速方向检测和校正

ocr_timer.py

参数	说明	默认值
--rename	识别后重命名视频	否
--dry-run	仅预览不重命名	否
--seconds	取最后多少秒	4.0
--frames	采样帧数	25

classify.py

参数	说明	默认值
--dry-run	仅预览不移动	否
--copy	复制而非移动	移动
--threshold	匹配阈值 (0~1)	0.35
--ref-dir	参考照片目录	./person/

故障排除

• OCR 识别失败？ → 视频最后几秒必须拍到大显，且画面稳定
• 很多视频进了 unknown？ → 降低阈值: --threshold 0.30
• 张冠李戴？ → 提高阈值: --threshold 0.45，或增加参考照片

---

AI 识别成绩 (ai_ocr_timer.py) ⭐ 推荐

传统七段 OCR (ocr_timer.py) 对遮挡、模糊、特殊角度的大显可能失败。 ai_ocr_timer.py 改用 AI 视觉识别，几乎不会错。

工作流（三步，近乎一键）

Step 1 — 提取帧（自动）

# 单目录
uv run python ai_ocr_timer.py "Z:\魔方比赛\260329\耿暄一\3x3 R2"

# 多目录 (空格分隔，自动去重)
uv run python ai_ocr_timer.py "Z:\魔方比赛\260329" "Z:\魔方比赛\260329\沈懿"

每个视频提取最后几秒中大显亮着的最佳帧，保存到： D:\cube\video-by-face\jpg\need_ai\

Step 2 — AI 识别（在聊天中）

在 AI 聊天窗口说：

/ocr Z:\魔方比赛\260329\耿暄一\3x3 R2

AI 会自动提取帧、看图识别、列表给你确认。

Step 3 — 重命名（自动）

uv run python ai_ocr_timer.py --apply "4.098, 4.574, 3.455"

识别失败时的文件名

AI 看不清时会直接把原因写入文件名，方便后续处理：

情况	文件名示例
大显是灭的	FAIL_灭屏.MP4
被手/身体遮挡	FAIL_遮挡.MP4
画面模糊	FAIL_模糊.MP4
画面中无大显	FAIL_无大显.MP4
数字残缺无法确认	FAIL_残缺.MP4

ai_ocr_timer.py 参数

参数	说明	默认值
paths	视频文件或目录，可多个	—
--apply "t1, t2"	用AI识别结果重命名（不需要路径）	—
--dry-run	仅预览不重命名	否
--seconds	取最后多少秒	4.0

与 ocr_timer.py 的关系

	ocr_timer.py	ai_ocr_timer.py
识别方式	七段数码管查表	AI 视觉 (人眼级)
速度	全自动，无需人工	需 AI 在聊天中确认
准确率	高，但难例有误	近乎 100%
适用场景	大批量批处理	难例兜底 / 日常推荐

ocr_timer.py 保留备用，不删除。