MahjongBot 🤖

智能麻将机器人 - 基于 YOLO 视觉识别和机械臂控制的远程打麻将系统，支持双摄像头实时检测、自动出牌和云端交互。

✨ 核心特性

🎯 精准识别

• YOLO 视觉检测: 支持 34 种国标麻将牌面识别
• 双摄像头架构: 前置摄像头检测手牌，顶置摄像头推流给用户
• 实时检测: 低延迟视觉处理，支持 ROI 区域过滤

🤖 智能控制

• 5DOF 机械臂: 精确的逆运动学控制
• 自动出牌: 根据视觉检测结果智能选择和抓取麻将牌
• 坐标转换: 图像坐标到机械臂坐标的精确标定

🌐 云端交互

• 腾讯云 TRTC: 实时音视频通话
• MQTT 桥接: 云服务器与机器人本地通信
• Flask Web 服务器: 用户友好的远程控制界面

🔧 技术栈

• 语言: Python 3.11+
• 视觉: Ultralytics YOLO, OpenCV
• 通信: ZeroMQ, MQTT, WebSocket
• 硬件: 飞特舵机, 双摄像头
• 云服务: 腾讯云 TRTC

🚀 快速开始

环境要求

• Python 3.11+
• Windows/Linux/macOS
• 摄像头设备
• 机械臂硬件 (可选，用于实际控制)

安装依赖

# 克隆项目
git clone https://github.com/yourusername/mahjongbot.git
cd mahjongbot

# 安装依赖
pip install -r requirements.txt

配置设置

1. 编辑配置文件 (software/src/configs/config.py):

@dataclass
class MahjongConfig:
    # 摄像头配置
    front_camera_device_id: int = 0
    top_camera_device_id: int = 1

    # 检测配置
    detector_roi_enabled: bool = True
    detector_roi_x: int = 100
    detector_roi_y: int = 200
    detector_roi_width: int = 800
    detector_roi_height: int = 400

    # MQTT 配置
    mqtt_broker: str = "your-mqtt-broker.com"
    mqtt_username: str = "your-username"
    mqtt_password: str = "your-password"

2. 下载模型:

cd software
python tools/download_models.py

启动系统

# 一键启动所有服务
cd software
python start_system.py

# 或分别启动
# 1. 视觉服务
python -m services.vision_service --device 0

# 2. 机械臂服务
python -m services.motion_service.arm_service

# 3. 麻将机器人桥接服务
python -m applications.mahjong_bot.robot_bridge_server --host 0.0.0.0 --port 5200

访问控制界面

打开浏览器访问: http://localhost:5200

• 实时视频流: 双摄像头画面
• 牌面检测: 自动识别和显示麻将牌
• 远程出牌: 点击牌面执行自动出牌
• 状态监控: 系统状态和检测结果

📖 使用指南

基本操作

1. 启动服务: 运行 start_system.py
2. 连接摄像头: 确保前置和顶置摄像头正常工作
3. 标定坐标: 使用 calibration_tool.py 进行图像到机械臂坐标转换
4. 开始游戏: 通过 Web 界面进行远程打麻将

高级功能

• ROI 设置: 在配置中启用和调整检测区域
• 多臂协同: 支持双机械臂同时操作
• 云端部署: 通过 MQTT 实现远程控制

测试工具

# 交互式测试
python -m tests.test_interactive_arm

# 检测测试
python -m tests.test_mahjong_detection

# 坐标标定
python tools/calibration_tool.py

🏗️ 系统架构

整体架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   云服务器      │    │   MQTT 桥接      │    │   本地机器人     │
│                 │    │                 │    │                 │
│  Flask Web      │◄──►│  Robot Bridge   │◄──►│  YOLO 检测      │
│  TRTC UserSig   │    │  Server         │    │  机械臂控制     │
│  控制界面       │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
       │                       │                       │
       ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   用户浏览器     │    │   MQTT 消息      │    │   硬件控制      │
│   实时视频       │    │   指令传递       │    │   舵机驱动      │
│   远程操作       │    │                 │    │   摄像头采集     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

软件分层架构

┌─────────────────────────────────────────────────────────────────┐
│                      RobotBridgeService                          │
│                    (协调层 - robot_bridge_server.py)              │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐  │
│  │ GameStateManager│    │ ArmController   │    │ ArmController│ │
│  │ (手牌状态管理)   │    │ (机械臂1控制)    │    │ (机械臂2控制)│ │
│  └────────┬────────┘    └────────┬────────┘    └──────┬──────┘  │
└───────────┼──────────────────────┼────────────────────┼─────────┘
            │                      │                    │
┌───────────▼──────────────────────▼────────────────────▼─────────┐
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  业务逻辑层 (game_state_manager.py)                      │  │
│  │  - 手牌状态管理 (选牌、出牌记录、位置映射)                │  │
│  │  - 虚拟牌与物理牌映射                                    │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  运动控制层 (arm_controller.py)                          │  │
│  │  - 坐标转换 (image_to_arm_coords)                        │  │
│  │  - 运动规划 (pick_and_place, push_tile)                  │  │
│  │  - 动作执行 (纯机械臂控制，无状态管理)                    │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  基础能力层                                              │  │
│  │  - detector.py: YOLO 检测，提供 bbox/center/bottom_center│  │
│  │  - coordinate_transformer.py: 透视变换、坐标映射         │  │
│  │  - motion_planner.py: 逆运动学、动作序列规划             │  │
│  │  - arm_client.py: 机械臂通信客户端                     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

架构设计原则

层级	文件	职责	关键方法/属性
数据层	detector.py	牌的检测数据	bbox, center, bottom_center
业务逻辑层	game_state_manager.py	手牌状态管理	initialize_hand(), select_tile(), discard_selected()
运动控制层	arm_controller.py	纯机械臂运动	pick_and_place(x,y), push_tile(x,y)
协调层	robot_bridge_server.py	整合流程	管理 GameStateManager + ArmController

开发环境设置

# 安装开发依赖
pip install -e .

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Ultralytics YOLO - 强大的目标检测框架
• ZeroMQ - 高性能异步消息库
• 腾讯云 TRTC - 实时音视频通信服务

---

⭐ 如果这个项目对你有帮助，请给我们一个 Star！