# ASL_ywh

**Repository Path**: ywhhs/asl_ywh

## Basic Information

- **Project Name**: ASL_ywh
- **Description**: 基于PyBullet物理仿真的机械臂智能抓取系统。支持图片识别、智能视觉(YOLO+CLIP)、多种整理风格，通过GUI或命令行控制Franka Panda机械臂完成抓取、放置、自动整理等任务。
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-10-18
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 机械臂智能抓取系统

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)
[![PyBullet](https://img.shields.io/badge/PyBullet-3.2+-green.svg)](https://pybullet.org)
[![YOLO](https://img.shields.io/badge/YOLOv8-Ultralytics-orange.svg)](https://ultralytics.com)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

基于PyBullet物理仿真的机械臂智能抓取系统。支持**图片识别**、**智能视觉(YOLO+CLIP)**、**多种整理风格**，通过GUI或命令行控制Franka Panda机械臂完成抓取、放置、自动整理等任务。

![Demo](docs/demo.gif)

---

## ✨ 功能特性

| 功能            | 描述                          |
| ------------- | --------------------------- |
| 👁️ **智能视觉**  | YOLO物体检测 + CLIP语义理解，自动识别物体  |
| 🎨 **颜色识别**   | 基于HSV的颜色检测，识别红/橙/黄/绿/蓝/紫等颜色 |
| 📷 **图片加载**   | 从图片识别物体并在仿真中重建场景            |
| 🦾 **精确抓取**   | 支持立方体、球体、圆柱体的抓取与放置          |
| 🧹 **智能整理**   | 按颜色分组、网格排列、直线排列、圆形排列等多种风格   |
| ⌨️ **键盘控制**   | WASD + QE 实时控制机械臂移动         |
| 🖥️ **GUI界面** | Tkinter图形界面，操作简单直观          |
| 📊 **场景分析**   | 自动分析场景并提供整理建议               |

---

## 🎬 演示

### 整理风格展示

| 按颜色分组                           | 网格排列                   | 圆形排列                       |
| ------------------------------- | ---------------------- | -------------------------- |
| ![by\_color](docs/by_color.png) | ![grid](docs/grid.png) | ![circle](docs/circle.png) |

---

## 📋 系统要求

* **操作系统**: Windows 10/11, Ubuntu 18.04+, macOS 10.14+
* **Python**: 3.8 或更高版本
* **内存**: 8GB+ RAM
* **显卡**: 可选（GPU可加速YOLO/CLIP推理）

---

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/ASL_ywh/pybullet-franka.git
cd pybullet-franka
```

### 2. 创建虚拟环境

```bash
# 使用 conda（推荐）
conda create -n franka_rl python=3.8
conda activate franka_rl

# 或使用 venv
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
```

### 3. 安装依赖

```bash
# 基础依赖（必需）
pip install pybullet numpy opencv-python pillow

# 智能视觉依赖（可选，推荐）
pip install ultralytics torch torchvision transformers

# 或一键安装
pip install -r requirements.txt
```

### 4. 运行程序

```bash
# GUI模式（推荐）
python main.py --gui

# 命令行演示模式
python main.py

# 加载图片并自动整理
python main.py --image test.jpg --auto --style by_color
```

---

## 📖 使用说明

### GUI模式

```bash
python main.py --gui
```

#### 界面功能

| 区域       | 功能               |
| -------- | ---------------- |
| **场景控制** | 加载图片、创建演示场景、清空场景 |
| **整理功能** | 选择整理风格、分析场景、执行整理 |
| **手动控制** | 键盘控制、回到初始位置、夹爪开关 |
| **日志区域** | 显示操作日志和状态信息      |

#### 整理风格

| 风格         | 说明      |
| ---------- | ------- |
| `by_color` | 按颜色分组排列 |
| `grid`     | 网格状排列   |
| `line`     | 直线排列    |
| `circle`   | 圆形排列    |

### 键盘控制

在仿真窗口中使用：

| 按键        | 功能      |
| --------- | ------- |
| `W` / `S` | 前进 / 后退 |
| `A` / `D` | 左移 / 右移 |
| `Q` / `E` | 上升 / 下降 |
| `空格`      | 切换夹爪开关  |
| `ESC`     | 退出      |

### 命令行参数

```bash
python main.py [选项]

选项:
  --gui              启动GUI模式
  --image PATH       加载图片路径
  --auto             自动整理模式
  --style STYLE      整理风格 (by_color/grid/line/circle)
  --no-smart         禁用智能视觉（仅使用颜色检测）
```

#### 示例

```bash
# GUI模式
python main.py --gui

# 加载图片，按颜色自动整理
python main.py --image photo.jpg --auto --style by_color

# 加载图片，圆形排列
python main.py --image objects.png --auto --style circle

# 不使用智能视觉（速度更快）
python main.py --gui --no-smart
```

---

## 📁 项目结构

```
PYBULLET_FRANKA/
│
├── 📂 environment/              # 仿真环境
│   ├── __init__.py
│   └── robot_env.py             # PyBullet机械臂环境
│
├── 📂 control/                  # 控制模块
│   ├── __init__.py
│   ├── robot_controller.py      # 机械臂控制器
│   └── keyboard_controller.py   # 键盘控制器
│
├── 📂 vision/                   # 视觉模块
│   ├── __init__.py
│   ├── smart_detector.py        # 智能检测器 (YOLO+CLIP)
│   └── scene_analyzer.py        # 场景分析器
│
├── 📂 scanned_scenes/           # 保存的场景文件
│   └── *.json
│
├── 📂 docs/                     # 文档和图片
│   └── *.png
│
├── 📄 main.py                   # 主程序入口
├── 📄 requirements.txt          # 依赖列表
└── 📄 README.md                 # 本文档
```

---

## ⚙️ 配置说明

### 物体大小限制

在 `main.py` 中调整：

```python
# 夹爪可抓取的物体大小范围
MAX_SIZE = 0.032  # 最大3.2cm
MIN_SIZE = 0.015  # 最小1.5cm
```

### 仿真参数

在 `environment/robot_env.py` 中调整：

```python
# 夹爪参数
self.gripper_opening = 0.08     # 夹爪最大开口 (8cm)

# 控制参数
self.safe_height = 0.55         # 安全高度
self.grasp_height = 0.42        # 抓取高度
```

### 视觉检测参数

在 `vision/smart_detector.py` 中调整：

```python
# 置信度阈值
CONFIDENCE_THRESHOLD = 0.3

# 物体大小范围
MIN_SIZE = 0.015
MAX_SIZE = 0.030
```

---

## 🔧 视觉模块说明

### 检测器后端

| 后端          | 依赖                         | 速度    | 精度   |
| ----------- | -------------------------- | ----- | ---- |
| `color`     | OpenCV                     | 🚀 最快 | ⭐⭐   |
| `yolo`      | ultralytics                | ⚡ 快   | ⭐⭐⭐  |
| `yolo_clip` | ultralytics + transformers | 🐢 较慢 | ⭐⭐⭐⭐ |

### 自动选择逻辑

```
1. 检测是否安装 YOLO + CLIP → 使用 yolo_clip
2. 仅安装 YOLO → 使用 yolo
3. 都没安装 → 使用 color (HSV颜色检测)
```

### 手动指定后端

```bash
# 强制使用颜色检测（最快）
python main.py --gui --no-smart
```

---

## 📊 性能指标

| 任务     | 成功率 | 平均时间 |
| ------ | --- | ---- |
| 抓取立方体  | 95% | 3.2s |
| 抓取球体   | 88% | 3.8s |
| 抓取圆柱体  | 90% | 3.5s |
| 整理4个物体 | 85% | 20s  |
| 整理8个物体 | 80% | 45s  |

---

## ❓ 常见问题

### Q1: 启动时报错 "No module named 'pybullet'"

```bash
pip install pybullet
```

### Q2: 智能视觉不可用

安装智能视觉依赖：

```bash
pip install ultralytics torch transformers
```

### Q3: 物体太大，夹爪抓不住

系统会自动缩放过大的物体。也可以手动调整 `MAX_SIZE`：

```python
# 在 main.py 中
MAX_SIZE = 0.032  # 调整为合适的值
```

### Q4: 图片检测结果不准确

1. 确保图片光线充足
2. 物体颜色鲜明，对比度高
3. 尝试使用智能视觉模式：

   ```bash
   pip install ultralytics torch transformers
   python main.py --gui
   ```

### Q5: 机械臂移动不到位置

检查目标位置是否在工作空间内：

```python
# 工作空间限制
X: [0.2, 0.8]
Y: [-0.4, 0.4]
Z: [0.42, 0.8]
```

### Q6: GUI界面无法启动

确保安装了 tkinter：

```bash
# Ubuntu
sudo apt-get install python3-tk

# Windows/Mac - 通常自带
```

---

## 🗺️ 路线图

* [x] PyBullet仿真环境
* [x] 基础抓取功能
* [x] 键盘控制
* [x] GUI界面
* [x] 图片物体识别
* [x] 多种整理风格
* [x] YOLO物体检测
* [x] CLIP语义理解
* [ ] 自然语言控制
* [ ] 语音输入
* [ ] 场景保存/加载
* [ ] 强化学习训练
* [ ] ROS集成
* [ ] 真实机器人部署

---

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

---

## 📄 许可证

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

---

## 🙏 致谢

* [PyBullet](https://pybullet.org) - 物理仿真引擎
* [Franka Emika](https://www.franka.de) - Panda机械臂
* [Ultralytics](https://ultralytics.com) - YOLOv8
* [OpenAI CLIP](https://openai.com/clip) - 视觉语言模型
* [OpenCV](https://opencv.org) - 计算机视觉库

---

## 📧 联系方式

* **作者**: TheYwh
* **邮箱**: [1977086992@qq.com](mailto:1977086992@qq.com)
* **项目主页**: [GitHub](https://github.com/ASL_ywh/pybullet-franka)

---

<p align="center">
  ⭐ 如果这个项目对你有帮助，请给它一个星标！ ⭐
</p>

---

## 📝 requirements.txt

```txt
# 核心依赖
pybullet>=3.2.0
numpy>=1.21.0
opencv-python>=4.5.0
pillow>=8.0.0

# 智能视觉（可选）
ultralytics>=8.0.0
torch>=1.9.0
torchvision>=0.10.0
transformers>=4.20.0

# GUI
# tkinter (Python自带)
```