# HandSnap

**Repository Path**: lhy159/hand-snap

## Basic Information

- **Project Name**: HandSnap
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能手势交互相机 (HandSnap)

> 基于 OpenCV + MediaPipe Hands 的实时手势识别视觉应用

---

## 目录

- [功能概述](#功能概述)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [环境搭建（详细）](#环境搭建详细)
- [编译指令](#编译指令)
- [运行说明](#运行说明)
- [手势操作指南](#手势操作指南)
- [目录结构](#目录结构)
- [便携式部署指南](#便携式部署指南)
- [常见问题](#常见问题)

---

## 功能概述

智能手势交互相机是一款基于计算机视觉的实时手势识别应用，通过摄像头捕捉用户的手势动作，实现以下功能：

| 手势 | 动作 | 功能 |
|:---:|------|------|
| ✌ **剪刀手** (V-Sign) | 食指和中指伸直成 V 字形 | 2 秒倒计时后自动拍照 |
| ✊ **握拳** (Fist) | 四指弯曲握拳 | 2 秒倒计时后开始/停止录像 |
| 👆 **双指并拢滑动** | 食指中指并拢左右滑动 | 切换画面滤镜 |

### 滤镜效果

| 滤镜 | 效果描述 |
|------|---------|
| 原图 | 无处理，原始画面 |
| 灰度 | 黑白灰度效果 |
| 边缘检测 | Canny 边缘检测，线条风格 |
| 复古色调 | 暖色调 + 暗角效果 |

### 交互特性

- **防误触机制**：手势需连续 5 帧确认，避免误触发
- **2 秒倒计时**：拍照和录像操作前有 2 秒倒计时提示，用户可取消
- **实时状态面板**：屏幕显示当前模式、滤镜、检测到的手势
- **录像计时器**：录像中实时显示录制时长

---

## 环境要求

### 必需工具

| 工具 | 最低版本 | 用途 |
|------|---------|------|
| GCC / Clang | GCC 9+ / Clang 12+ | C++17 编译器 |
| CMake | 3.16+ | 构建系统 |
| Git | 任意 | 源码下载 |
| Bazel / Bazelisk | 6.x+ | MediaPipe 构建 |
| Python 3 | 3.8+ | MediaPipe 构建辅助 |

### 操作系统

- Ubuntu 20.04 / 22.04 / 24.04（推荐）
- 其他 Linux 发行版（需自行调整依赖）

### 硬件

- 摄像头（USB 摄像头或笔记本内置摄像头）
- 建议 4GB+ 内存（MediaPipe 构建需要）

---

## 快速开始

```bash
# 1. 安装基础工具（仅首次需要）
sudo apt-get install -y build-essential cmake git python3 python3-pip

# 2. 安装 Bazelisk（MediaPipe 构建工具）
sudo npm install -g @bazel/bazelisk
# 如果没有 npm，也可以用：
# wget https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64
# chmod +x bazelisk-linux-amd64 && sudo mv bazelisk-linux-amd64 /usr/local/bin/bazel

# 3. 一键构建所有依赖
bash scripts/setup.sh all

# 4. 编译项目
cd code && cmake -B build && cmake --build build

# 5. 运行
./build/hand_snap
```

---

## 环境搭建（详细）

### 方案 A：自动构建（推荐，需要网络）

运行项目提供的自动化脚本，下载并编译 OpenCV 和 MediaPipe：

```bash
# 构建所有依赖（OpenCV + MediaPipe + 模型）
bash scripts/setup.sh all

# 或分步构建：
bash scripts/setup.sh opencv      # 仅构建 OpenCV
bash scripts/setup.sh mediapipe   # 仅构建 MediaPipe
bash scripts/setup.sh models      # 仅下载模型文件
```

脚本会自动将依赖安装到 `third_party/install/` 目录。

### 方案 B：手动配置（离线环境）

如果无法联网，或需要手动管理依赖：

#### B.1 准备 OpenCV

```bash
# 在联网机器上编译好 OpenCV，然后复制到目标机器
# 编译后的文件结构：
third_party/install/
├── include/opencv4/    # OpenCV 头文件
├── lib/                 # libopencv_*.so
└── lib/cmake/opencv4/   # OpenCV CMake 配置
```

#### B.2 准备 MediaPipe

MediaPipe 的 C++ 库构建较为复杂，建议在联网机器上使用 Bazel 构建后，复制以下文件：

```bash
# 从构建好的 MediaPipe 项目中复制
# 头文件：
third_party/install/include/mediapipe/   # 所有 .h 头文件

# 库文件：
third_party/install/lib/                 # 所有 .so 和 .a 文件

# 第三方依赖头文件（MediaPipe 构建时自动下载的）：
third_party/install/include/absl/         # Abseil
third_party/install/include/flatbuffers/  # FlatBuffers
third_party/install/include/opencv4/      # OpenCV（MediaPipe 自带）
```

#### B.3 准备模型文件

```bash
# 下载手部关键点检测模型
mkdir -p models
wget https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task \
    -O models/hand_landmarker.task
```

---

## 编译指令

### 标准编译（两条指令）

```bash
# 生成构建系统文件
cmake -B build

# 执行编译
cmake --build build
```

### 指定依赖路径编译

```bash
cmake -B build \
    -DOPENCV_ROOT=/path/to/opencv \
    -DMEDIAPIPE_ROOT=/path/to/mediapipe

cmake --build build
```

### Release 模式编译

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

### 编译产物

编译成功后在 `code/build/` 目录下生成 `hand_snap` 可执行文件。

---

## 运行说明

```bash
# 基本运行（使用默认摄像头和参数）
./code/build/hand_snap

# 指定摄像头 ID（多摄像头时）
./code/build/hand_snap 1

# 指定模型路径和输出目录
./code/build/hand_snap 0 ../models/hand_landmarker.task ./my_photos

# 参数说明：
#   参数1: 摄像头 ID（默认 0）
#   参数2: 模型文件路径（默认 ../models/hand_landmarker.task）
#   参数3: 照片/视频输出目录（默认 ./output）
```

### 快捷键

| 按键 | 功能 |
|------|------|
| Q / ESC | 退出程序 |
| F | 手动切换滤镜（调试用） |

---

## 手势操作指南

### 1. 拍照（剪刀手 ✌）

1. 面对摄像头，伸出食指和中指成 V 字形
2. 保持手势，无名指和小指弯曲
3. 屏幕出现 2 秒倒计时圆环
4. 倒计时结束，自动拍照
5. 照片保存在 `output/` 目录下

> **取消**：在倒计时期间改变手势即可取消拍照。

### 2. 录像（握拳 ✊）

1. 面对摄像头，四指弯曲握拳
2. 保持手势，屏幕出现 2 秒倒计时圆环
3. 倒计时结束，开始录像（屏幕左上角显示红色 REC 指示灯）
4. 再次握拳，经过 2 秒倒计时后停止录像
5. 视频保存在 `output/` 目录下

> **取消**：在倒计时期间改变手势即可取消开始/停止录像。

### 3. 切换滤镜（双指并拢滑动 👆）

1. 食指和中指伸直并拢
2. 保持并拢状态，向左或向右滑动
3. 滤镜立即切换（无需倒计时）
4. 屏幕左上角面板显示当前滤镜名称

---

## 目录结构

```
HandSnap1.0/
├── README.md                        # 项目说明（本文件）
├── code/                            # 源代码目录
│   ├── CMakeLists.txt               # CMake 构建配置
│   ├── main.cpp                     # 主程序：状态机、UI、MediaPipe 集成
│   ├── gesture_recognizer.h         # 手势识别器头文件：关键点定义、接口
│   ├── gesture_recognizer.cpp       # 手势识别算法实现：V-Sign、Fist、Swipe
│   ├── camera_controller.h          # 摄像头控制器头文件
│   ├── camera_controller.cpp        # 摄像头控制：拍照、录像功能
│   └── build/                       # 编译输出目录（自动生成）
│       └── hand_snap                # 可执行文件
├── scripts/                         # 辅助脚本
│   └── setup.sh                     # 便携式依赖构建脚本
├── third_party/                     # 第三方依赖（自动生成）
│   ├── build/                       # 源码和构建中间文件
│   └── install/                     # 编译产物安装目录
│       ├── include/                 # 头文件
│       ├── lib/                     # 库文件
│       └── bin/                     # 可执行文件
├── models/                          # AI 模型文件
│   └── hand_landmarker.task         # MediaPipe 手部关键点模型
├── output/                          # 照片/视频输出目录（自动生成）
├── docs/                            # 文档目录
│   ├── 项目设计说明书.md             # 项目设计文档
│   └── AI对话记录.md                # AI 问答记录
└── 项目设计说明书书写模板.md          # 模板文件（参考用）
```

---

## 便携式部署指南

### 场景：将项目复制到另一台纯净 Ubuntu 机器

**前提条件**：目标机器已安装基础编译工具（build-essential、cmake、git、python3、bazel）。

**步骤：**

```bash
# 1. 复制整个项目文件夹到目标机器
scp -r HandSnap1.0/ user@target-machine:/home/user/

# 2. 在目标机器上安装基础工具（仅首次）
sudo apt-get install -y build-essential cmake git python3 python3-pip
sudo npm install -g @bazel/bazelisk

# 3. 运行依赖构建脚本
cd /home/user/HandSnap1.0
bash scripts/setup.sh all

# 4. 编译项目
cd code && cmake -B build && cmake --build build

# 5. 运行
./build/hand_snap
```

### 场景：离线环境部署

如果目标机器无法联网：

1. 在联网机器上执行 `bash scripts/setup.sh all` 完成所有依赖构建
2. 将整个 `HandSnap1.0/` 文件夹（包括 `third_party/` 和 `models/`）复制到目标机器
3. 在目标机器上直接编译：

```bash
cd code && cmake -B build && cmake --build build
```

---

## 常见问题

### Q1: 摄像头打不开？

```bash
# 检查摄像头设备
ls /dev/video*
# 检查权限
groups $USER | grep video
# 如果不在 video 组中
sudo usermod -a -G video $USER
# 重新登录后生效
```

### Q2: MediaPipe 构建失败？

MediaPipe 对 Bazel 版本有特定要求。建议使用 Bazelisk 自动管理 Bazel 版本：

```bash
sudo npm install -g @bazel/bazelisk
```

### Q3: 编译时找不到 OpenCV？

```bash
# 指定 OpenCV 路径
cmake -B build -DOPENCV_ROOT=/path/to/opencv/install
cmake --build build
```

### Q4: 运行时找不到 .so 文件？

```bash
# 将本项目依赖库路径加入 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$(pwd)/../third_party/install/lib:$LD_LIBRARY_PATH
./build/hand_snap
```

### Q5: 手势识别不灵敏？

- 确保手掌在摄像头画面中清晰可见
- 保持适当距离（30-80cm）
- 避免背景中有类似手部形状的物体
- 确保光照充足
- 可以调整 `gesture_recognizer.cpp` 中的阈值参数

### Q6: 如何添加新的手势？

1. 在 `gesture_recognizer.h` 的 `GestureType` 枚举中添加新手势
2. 在 `gesture_recognizer.cpp` 中实现判断函数
3. 在 `recognize()` 函数中添加检测逻辑
4. 在 `main.cpp` 的状态机中添加对应的处理

---

## 技术栈

| 组件 | 技术 |
|------|------|
| 语言 | C++17 |
| 构建 | CMake 3.16+ |
| 计算机视觉 | OpenCV 4.x |
| 手部关键点检测 | MediaPipe Hands (Tasks API) |
| 深度学习框架 | TensorFlow Lite (MediaPipe 内置) |
| 编译器 | GCC 9+ / Clang 12+ |