基于屏幕实时识别的麻将辅助工具：框选屏幕中的手牌区域，自动识别牌面并给出最优切牌建议。支持手动框选、定时自动刷新；模板由配套采集工具（template_capture.py）建立，识别精度随样本积累逐步提升。
- 实时识别：截取屏幕指定区域，自动识别牌的花色与点数（模板匹配 + 维特比序列平滑）。
- 智能切牌建议：日麻向听数（普通形 / 七对子 / 国士无双）计算 + 有效进张评估，推荐打出后向听最低、进张最多的牌；红5 作为宝牌优先保留；13 张时显示当前向听与摸牌建议。建议文本以半透明标签单行显示在识别区域上方。
- 绿色高亮：建议打出的牌，其名称标签以绿色显示，清晰直观。
- 模板采集工具：通过真实截图半自动标注建立 37 类模板库（含红5），样本越多识别越准。
- 原始像素匹配：电子麻将画面渲染稳定，模板与实时识别统一使用原始像素匹配，不做降噪/白化等预处理，保留全部判别细节。
- 定时刷新：可在设置中开启自动识别（1s / 2s / 3s 间隔）。
- 全局热键 + 系统托盘：常驻托盘，不打断操作。
- 调试截图工具：附带
debug_capture.py，可一键完成截屏或框选并保存测试图，便于收集各类牌面样本。 - 解压即用：Release 提供完整压缩包，无需安装 Python 环境。
- 前往 Releases 页面 下载最新版本的压缩包（如
MahjongHelper-v1.1.0.zip）。 - 解压到任意目录。请保持
MahjongHelper.exe与_internal文件夹在同一目录下，不要单独移动 exe。 - 运行
MahjongHelper.exe。若游戏以管理员身份运行，请同样以管理员身份启动，保证全局热键能捕获到按键。 - 启动后按 F2 框选手牌区域，程序自动识别并显示结果。
提示：
config.json（用户设置）、mahjong_helper.log（日志）、debug_output（调试输出）会在 exe 所在目录自动生成。
需要 Python 3.8+（推荐 3.10+）。
git clone https://github.com/toki-2004/MahjongHelper.git
cd MahjongHelper
pip install -r requirements.txt
python main.py源码版使用项目根目录下的
templates/作为牌面模板；打包版内置在_internal/templates。
| 按键 | 功能 |
|---|---|
F2 |
进入框选模式（重新划定识别区域） |
F1 |
刷新识别（沿用当前区域，重新识别） |
ESC |
取消当前操作（取消框选或关闭覆盖层） |
- 框选建议：按 F2 后拖拽鼠标，建议仅框选一行完整牌面，减少背景及其他元素的干扰，以提高识别稳定性。
- 自动模式：右键托盘图标 → 设置，可切换为“自动 1s / 2s / 3s”，程序会定时识别当前区域。
- 模板目录：源码版为
templates/，打包版为_internal/templates/。模板与样本均保存原始像素，识别时不做任何预处理，保证电子麻将画面细节完整。 - 重建模板：使用
template_capture.py对截图自动检测牌面、人工标注真实花色并保存样本，采集完成后点击"重建模板库"生成模板。正式识别界面不提供在线修正下拉框。
用于从真实截图批量建立模板库，全程不需要任何已有模板：程序先通过几何特征（白色牌面、尺寸、间距）自动定位每张牌的位置和数量，再由人工标注每张牌的真实花色，即可保存为样本并重建模板。
python template_capture.py使用流程：
- 点击"打开图片"，选择一张手牌截图（建议先用
debug_capture.py框选一行完整牌面，或用游戏截图）。 - 点击"检测牌"，程序自动检测每张牌并编号（只保留主行，吃碰杠副牌会被过滤；支持 14、13、11、10、8、7、5、4、2、1 张）。
- 在右侧下拉框中为每张牌选择真实花色；不需要的牌选"(跳过)"。
- 点击"保存本图样本"，样本写入
templates/samples/{牌id}/（自动统一尺寸，保留原始像素）。 - 重复多张截图，覆盖全部 37 类牌（34 种常规牌 + 3 种红5）后点击"重建模板库"。
重建规则：每类模板从全部样本中挑选一张真实代表样本（平移配准后取与类内中位数最接近的一张），不做叠化平均，避免模板越叠越模糊；原始样本同时保留，供样本级匹配使用。
建议：每类牌收集 5~10 张不同局面的样本（不同亮度、缩放、牌面朝向），模板库更稳。
debug_capture.py 内置图形界面，用于快速收集各种牌面的测试截图：可自定义截图热键和保存目录，设置保存在 capture_config.json，重启后自动生效。窗口常驻系统托盘，关闭窗口不退出程序。
python debug_capture.py [monitor_index]| 按键 | 功能 |
|---|---|
F2（可在界面中修改） |
截取鼠标所在屏幕并保存 |
F3（可在界面中修改） |
在鼠标所在屏幕拖拽框选并保存 |
ESC |
取消框选 |
不传参数时自动截取鼠标所在屏幕（F2、F3 均如此）；也可传 1、2、3… 按 mss 显示器索引指定屏幕（启动时会在日志中列出各屏幕的索引）。图片保存到指定目录，文件名按已有编号自动顺延（如已有
1.png则保存为2.png），可直接用于识别自测或模板训练。
- 热键无响应：请确认程序已在运行且未被最小化至托盘；若游戏以管理员身份运行，需以相同权限启动本程序；若被杀毒软件拦截，请将程序加入白名单。
- 识别为 0 张或出现
?：框选区域太小或牌面显示过小，建议把图片/窗口缩放到 100% 以上再识别；?表示该槽位未能识别，请重新框选更完整的牌行区域后按 F1 刷新。 - 识别数量不是 13~14 张：框选时请尽量只包含一行牌面，避免把相邻牌、背景或其他区域一起框入。
- 切牌建议的原理：程序对每张候选牌计算打掉后的向听数与有效进张（摸到后向听下降的牌，按 4−手牌持有计剩余张数），优先向听更低、进张更多，红5 在同等条件下保留；听牌时显示和牌张。
仓库自带 PyInstaller 配置（单目录模式、关闭 UPX，启动速度与源码运行相当）：
pip install pyinstaller
python -m PyInstaller --noconfirm --clean MahjongHelper.spec产物位于 dist/MahjongHelper/，将整个目录压缩后即可分发。
main.py 主程序：界面、热键、识别线程
vision.py 图像识别：区域提取、分档对齐、模板匹配
template_manager.py 模板加载、矩阵预计算、样本管理、模板重建
logic.py 日麻切牌建议（向听数 + 有效进张 + 红5 保留）
debug_capture.py 截图工具 GUI：自定义热键与保存目录，F2 全屏 / F3 框选保存
templates/ 37 张牌面模板（0.png ~ 36.png，含 34~36 红5万/索/筒）
template_packs/ 模板包仓库：按游戏/皮肤组织（如 雀魂默认/templates），供不同牌面皮肤切换
MahjongHelper.spec PyInstaller 打包配置
本项目采用 MIT License，详情见 LICENSE。
感谢开源社区的优秀库：PyQt5、OpenCV、NumPy、Pillow、mss、keyboard 等。