# Hand AR

**Repository Path**: logicliu/hand-ar

## Basic Information

- **Project Name**: Hand AR
- **Description**: 基于 MediaPipe + OpenCV 的实时手部交互特效项目
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hand AR - 手势反应 3D/多边形可视化

基于 MediaPipe + OpenCV 的实时手部交互特效项目。

## 功能

| 脚本 | 说明 |
|------|------|
| `gesture_poly.py` | 双手指尖多边形特效 — 双手拉开 + 五指张开时，指尖之间生成彩色多边形，支持多种填充样式和贝塞尔曲线边缘 |
| `hand_3d_ar.py` | 掌上 3D 模型 AR 展示 — 五指张开时 3D 模型出现在手掌上，跟随手部移动/旋转，支持甩手切换模型 |

## 快速开始

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

# 2. 下载 MediaPipe 手部关键点模型（首次运行也会自动下载）
# 手动下载: https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task
# 放置到项目根目录

# 3. 运行
python gesture_poly.py   # 双手指尖多边形特效
python hand_3d_ar.py     # 掌上 3D 模型 AR 展示
```

## 操作说明

### gesture_poly.py — 双手指尖多边形

| 按键 | 功能 |
|------|------|
| `Q` | 退出 |
| `B` | 切换直线/贝塞尔曲线多边形 |
| `S` | 切换时间平滑 |
| `D` | 切换调试信息 |

**手势交互：**
- 双手拉开 + 五指张开 → 多边形出现，翻转手掌颜色随之变化
- 双手食指合拢再拉开 → 切换整体填充样式（渐变 → glitch → 反色 → 噪点 → 色调）
- 任意手拇指触碰另一手拇指/食指/中指/无名指再分开 → 切换对应子四边形的独立填充样式

### hand_3d_ar.py — 掌上 3D 模型 AR

| 按键 | 功能 |
|------|------|
| `Q` | 退出 |
| `M` | 切换 3D 模型 |
| `D` | 切换调试信息 |

**手势交互：**
- 五指张开 → 3D 模型出现（带动画）
- 五指并拢 → 3D 模型缩小消失（带动画）
- 将手甩向另一只手 → 模型飞向目标手（带弧线飞行和翻滚动画）

## 3D 模型

将 `.obj`、`.glb`、`.gltf`、`.stl`、`.ply` 等格式的模型文件放入 `models/` 目录，启动时自动扫描加载。当前内置模型：

- 内置：icosphere（二十面球体）、torus（环面）、box（方盒）
- 外部：`crazy-rabbit.glb`、`middle-age-house.obj`

## 项目结构

```
CV-Hand-Detection/
├── gesture_poly.py         # 双手指尖多边形特效
├── hand_3d_ar.py           # 单手掌上 3D 模型 AR 展示
├── models/                 # 外部 3D 模型文件
├── requirements.txt        # Python 依赖
├── hand_landmarker.task    # MediaPipe 手部关键点模型（需下载）
└── README.md
```

## 依赖

- `mediapipe >= 0.10.30` — 手部关键点检测
- `opencv-python >= 4.8.0` — 图像采集与渲染
- `numpy >= 1.24.0` — 数值计算
- `pyrender >= 0.1.45` — 3D 模型离屏渲染
- `trimesh >= 3.21.0` — 3D 模型加载与处理
- `PyOpenGL >= 3.1.6` — OpenGL 绑定
- `fast_simplification >= 0.1.0` — 高面数模型减面