Han 记牌器 · 斗地主记牌器 / Dou Dizhu Card Tracker

English · 使用指南 · 文档目录 · 问题反馈 · 模型训练仓库 · ❤ 赞赏支持

Han Card Tracker 是 Windows 桌面的开源斗地主记牌器。 使用 YOLO 扑克牌目标检测识别游戏窗口，统计本家初始手牌以外尚未打出的牌，并显示上家、本家、下家的出牌历史。项目使用 Python、PySide6 和 PyTorch，支持 CPU/CUDA 推理及自动布局、手动布局。

A Windows Dou Dizhu card counter and playing-card detection application built with Python, YOLO and PySide6. It tracks remaining cards and play history from a visible game window, with automatic layout detection or user-defined regions and packed inference.

使用注意

1. 当前优先使用原图检测。 随附YOLO模型的训练数据全部是游戏原图，尚未充分覆盖本程序生成的拼图，当前拼图检测的识别准确率和稳定性较低。手动布局可在“基本设置 → 手动框选 → 检测方式”切换为原图；自动布局始终整图识别。
2. 框选大小王时必须包含完整的 J、O、K 三个字母。 训练标注覆盖的是这三个字母，不能只框住 J，或只框住 J、O。请给手牌和出牌区域留足空间，让大小王的三个字母都落在框内，否则可能漏检或误识别。
3. 当前 YOLO 模型主要使用《欢乐斗地主》的画面训练。 使用其他斗地主游戏时，由于牌面样式、颜色和界面不同，可能出现识别不准确的情况。

能做什么

功能	当前实现
扑克牌识别	YOLO 检测牌面与坐标，经布局分析分配到对应区域
剩余牌统计	初始手牌扣一次；对手确认出牌扣除，本家出牌只记历史
自动布局	整图推理；底牌横向居中70%、纵向学习高度，其他牌组按相对位置归属
手动布局	自己框选五区，可选择原图检测或两阶段拼图检测
拼图推理	开局前底牌＋手牌，扣手牌后底牌＋三家出牌；严格框内裁剪
尺度调整	初始固定比例，之后按当前单牌检测框学习；画布按所选模型配置固定像素宽高
运行反馈	暂停、置顶、出牌历史、耗时、实际 YOLO 输入预览及原图/标注图保存
界面排列	剩余牌数与出牌记录独立分区，可在基本设置切换上下或左右长条排列
推理后端	CPU 优先 ONNX Runtime；CUDA 优先 TensorRT，失败可回退 PyTorch

当前维护范围是Windows 斗地主。本仓库不提供 Android APK、OCR 文字识别方案或其他牌类游戏的完整支持；也不自动操作游戏。不同软件、皮肤和模式需要实际验证。

下载与版本

• 当前功能以 main 源码与 更新记录 为准。
• Windows发布包分为 CPU版 和 CPU/GPU版，下载入口与使用方法见使用指南。CPU版不包含CUDA运行库，体积较小；CPU/GPU版支持CPU以及兼容CUDA的NVIDIA显卡。请完整解压后运行包内EXE。
• YOLO 权重位于仓库 yolo/weights/<模型目录>/best.pt。训练代码在独立的 yolo-for-han-card-tracker 仓库；不把旧版发布包描述成已提供训练数据集。

从源码启动

需要 Windows 和 Python 3.11（64位）。使用指南先介绍 EXE 使用与常用设置，再给出源码安装步骤。新增模型须在best.pt旁放置model_config.yaml，填写实际训练输入宽高，参考模型放置与尺寸规范。

git clone https://github.com/hey-three/han-card-tracker.git
cd han-card-tracker
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu121
.\.venv\Scripts\python.exe main.py

requirements.txt 固定了 CUDA 12.1 版 PyTorch，不能假定任意 Python 或仅用默认包索引都可安装。上述安装路径遵循 PyTorch 官方旧版本说明，本次文档维护没有重做全新环境安装或升级依赖。

首次使用：

1. 打开目标游戏窗口，保持可见且未被遮挡。
2. 在“设置 → 基本设置”新建自动布局，选择游戏窗口并命名保存；或新建手动布局，框选手牌、本家出牌、上家出牌、下家出牌、底牌五区。两种模式分别记住上次使用的布局，点击模式即可切换。
3. 手动布局可在“基本设置 → 手动框选 → 检测方式”选择拼图检测／原图检测。该选择为所有手动布局共用；自动布局始终整图。
4. 建议从开局前启用，观察顶部状态及“实时显示 YOLO 输入”，核对第一次扣牌与后续出牌。

开局与计数规则

• 底牌区连续两帧有任意牌才开局，不比较底牌牌面/张数；第二帧起累计手牌，非空合法手牌按设置连续稳定后只扣一次，不强制17/20张，也不对后来17→20自动补扣。
• 剩余牌数 = 整副牌 − 本家首次确认手牌 − 已确认的对手出牌；不是三位玩家各自剩余张数。
• 底牌缺失立即暂停记录，连续至少 max(3, FRAME_LENGTH) 帧且达到 RESET_TIME 秒后内部结束。旧牌数与历史保留，下一次底牌连续两帧确认开局才刷新。
• 开局前拼图只推理两区，即使底牌未检出也不整图校准。玩家负责框选完整；算法不向框外扩展。

完整业务规则见记牌设计，拼图与自适应见拼图设计。

常见问题

适配 JJ 斗地主或其他窗口吗？ 仓库含 JJ 斗地主样例布局，并验证过少量参考截图；手动五区可用于适配其他窗口，但不是任何版本都可直接使用。自动布局目前面向本家在下、两家在左右的常见画面。

为什么还没开局？ 先检查上方底牌是否落在正确区域并至少识别到一张；非空手牌还需稳定确认。中部翻牌动画不等于上方底牌已到位。

能否保证200毫秒或一直不漏牌？ 不能。采样间隔、模型耗时、整轮耗时不同；截图、模型、皮肤、设备和温度都影响结果。已有验证范围见排查与验证。

如何保存排查材料？ 日常关键事件日志自动按大小轮转；高级设置可开启完整诊断，按局建立目录，后台保存原图、每次YOLO调用输入与标注、牌数/历史和状态前后快照。高级设置可调整全部诊断材料的磁盘额度（默认1 GiB）；空间不足清理已封口旧局，保护当前局。队列/内存拥堵自动暂缓并恢复，缺帧明确记录；磁盘故障暂停并提示，识别继续；自动回放和一键导出尚未实现。

仓库附带维护者当前配置作为起点，窗口标题和框选坐标并非通用。首次使用请在基本设置选择自己的窗口/布局、模型和设备，在高级设置按需启停完整诊断。

赞赏支持

如果这个项目对你有帮助，欢迎通过微信或支付宝二维码自愿赞赏，支持项目维护；也可以点击程序标题栏的爱心，或在“设置”→“赞赏”中查看本地二维码。感谢每一份 Star、问题反馈和代码贡献。

文档与贡献

• 用户：使用指南 · 配置参考 · 排查与验证
• 开发者：架构与数据流 · 自动布局 · 设计决策
• 模型：训练与拼图约定
• 贡献：CONTRIBUTING.md · AGENTS.md · 维护与发布

仓库许可证为 MIT；第三方组件、模型及数据使用各自许可证。使用时遵守目标软件的适用规则。

下一步开发计划

• 改善拼图检测：补充实际拼图训练样本，检查缩放与切片对识别的影响。
• 优先改善地主底牌检测：当前误检和漏检主要集中在底牌区，原图中的底牌目标较小，且地主打出对应底牌后牌面颜色会变淡，需要补充这类训练样本并改进识别稳定性。
• 改善大小王识别，并修复漏检变化造成同一手牌被重复记入历史的问题。
• 推进Android移植，适配手机截图、浮窗和端侧推理；尚未提供安卓APK。

Star 趋势