# ezgo - 宇树Go2机器狗Python控制库

[![PyPI version](https://badge.fury.io/py/ezgo.svg)](https://badge.fury.io/py/ezgo)
[![Python versions](https://img.shields.io/pypi/pyversions/ezgo.svg)](https://pypi.org/project/ezgo/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

ezgo 是一个用于控制宇树Go2机器狗的Python库，提供了简单易用的API接口，支持运动控制、视频流获取、UI界面等功能。

## 功能特性

- 🤖 **运动控制**: 支持前进、后退、转向、舞蹈等多种动作
- 📹 **视频流**: 实时获取机器狗摄像头画面
- 🎮 **状态管理**: 智能状态检测和动作切换
- 🖥️ **UI界面**: 提供简单的图形界面用于显示和控制
- 🔧 **易于集成**: 简洁的API设计，便于快速开发

## 安装

### 使用pip安装

```bash
pip install ezgo
```

### 从源码安装

```bash
git clone https://github.com/your-username/ezgo.git
cd ezgo
pip install -e .
```

## 系统要求

在安装 ezgo 之前，请确保您的系统已安装以下依赖：

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install python3-opencv python3-numpy python3-pil

# CentOS/RHEL
sudo yum install opencv-python numpy Pillow

# macOS
brew install opencv

# Windows
# 请使用 pip 安装或下载预编译的二进制包
pip install opencv-python numpy Pillow
```

**注意**: ezgo 不会自动安装这些依赖，因为它们可能需要系统级安装或特定配置。

## 快速开始

### 基本使用

```python
from ezgo import Go2

# 初始化Go2控制器
go2 = Go2(interface="enx00e0986113a6")  # 替换为你的网卡接口

# 初始化连接
if go2.init():
    print("连接成功！")
    
    # 基本动作
    go2.StandUp()        # 站立
    go2.Forward(0.3, 2)  # 向前移动2秒
    go2.TurnLeft(0.5, 1) # 左转1秒
    go2.Hello()          # 打招呼
    go2.Damp()           # 进入阻尼状态
else:
    print("连接失败！")
```

### 视频流使用

```python
import cv2
from ezgo import Go2

# 初始化
go2 = Go2()
if go2.init():
    print("开始获取视频流...")
    
    while True:
        frame = go2.read_image()
        if frame is not None:
            cv2.imshow('Go2 Camera', frame)
            
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
    
    cv2.destroyAllWindows()
```

### UI界面使用

```python
from ezgo.ui import APP
from ezgo.camera import Camera
import time

# 创建UI应用
app = APP(title="Go2控制面板", width=480, height=800)

# 创建摄像头
camera = Camera(index=0)
camera.open_camera()

# 更新界面
while app.is_running:
    try:
        # 获取摄像头图像
        frame = camera.read_cv2_image()
        image_tk = camera.cv2_to_tk(frame)
        app.set_image(image_tk)
        app.set_text("系统运行正常")
        
        app.update()
        time.sleep(0.03)  # 约30FPS
    except Exception as e:
        print(f"更新界面出错: {e}")
        break

app.mainloop()
```

## API 文档

### Go2 类

主要的机器狗控制类，提供以下方法：

#### 运动控制
- `StandUp()` - 站立
- `StandDown()` - 蹲下
- `Sit()` - 坐下
- `Damp()` - 进入阻尼状态
- `BalanceStand()` - 平衡站立
- `StopMove()` - 停止移动

#### 移动控制
- `Move(vx, vy, vyaw)` - 移动控制
- `Forward(speed, duration)` - 向前移动
- `Backward(speed, duration)` - 向后移动
- `Left(speed, duration)` - 向左移动
- `Right(speed, duration)` - 向右移动
- `TurnLeft(speed, duration)` - 左转
- `TurnRight(speed, duration)` - 右转

#### 动作控制
- `Hello()` - 打招呼
- `Stretch()` - 伸懒腰
- `Content()` - 开心
- `Heart()` - 比心
- `Scrape()` - 拜年作揖
- `Dance1()` - 舞蹈1
- `Dance2()` - 舞蹈2
- `FrontJump()` - 前跳
- `FrontPounce()` - 向前扑人

#### 视频控制
- `read_image()` - 获取一帧图像
- `open_video(width, height)` - 打开视频流

### Camera 类

摄像头控制类，提供以下方法：
- `open_camera()` - 打开摄像头
- `read_cv2_image()` - 读取OpenCV格式图像
- `read_pil_image()` - 读取PIL格式图像
- `cv2_to_tk(frame)` - 转换为Tkinter格式
- `resize(frame, size)` - 调整图像尺寸
- `crop_to_square(frame)` - 裁剪为正方形

### APP 类

UI界面类，基于Tkinter：
- `set_image(image)` - 设置显示图像
- `set_text(text)` - 设置显示文字

## 项目结构

```
ezgo/
├── src/
│   ├── __init__.py      # 包初始化文件
│   ├── go2.py          # Go2机器狗控制类
│   ├── camera.py       # 摄像头控制类
│   └── ui.py           # UI界面类
├── pyproject.toml      # 现代Python项目配置
├── README.md          # 项目文档
├── LICENSE            # 开源协议
├── quick_update.py    # 快速更新脚本
└── .pypirc           # PyPI配置文件
```

## 开发指南

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/your-username/ezgo.git
cd ezgo

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

# 运行测试
python -m pytest tests/
```

### 发布新版本

```bash
# 更新补丁版本
python quick_update.py patch

# 更新次版本
python quick_update.py minor

# 更新主版本
python quick_update.py major

# 发布到PyPI
python quick_update.py publish
```

## 常见问题

### Q: 连接机器狗失败怎么办？
A: 请检查网络连接，确保机器狗IP (192.168.123.161) 可以ping通，并确认网卡接口名称正确。

### Q: 视频流无法打开？
A: 请检查GStreamer是否正确安装，以及网卡多播配置是否正确。

### Q: 某些动作无法执行？
A: 请检查机器狗当前状态，某些动作需要在特定状态下才能执行。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 更新日志

### v0.0.1 (2024-01-01)
- 初始版本发布
- 基本运动控制功能
- 视频流获取功能
- UI界面功能