# openharmony-snap

**Repository Path**: gerecoc/openharmony-snap

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HDC Snap Cast - HarmonyOS 设备投屏工具

基于 HDC (HarmonyOS Device Connector) 的截图投屏脚本，支持鼠标和键盘反控设备。

---

## 目录结构

```
snap/
├── run_snap.bat              # 主启动脚本（双击这个）
├── README.md                 # 本文档
└── runtime/
    ├── bin/
    │   ├── hdc.exe           # HarmonyOS hdc 工具
    │   └── libusb_shared.dll # hdc 依赖库
    ├── scripts/
    │   └── snap.py           # Python 投屏主程序
    ├── requirements.txt      # Python 依赖列表
    ├── setup_env.bat         # 手动设置环境脚本（可选）
    ├── run.bat               # runtime 目录下的启动脚本
    └── .venv/                # Python 虚拟环境（自动生成）
```

---

## 使用方法

### 快速开始

1. 确保已安装 **Python 3.7+**
2. 用 USB 连接 HarmonyOS 设备
3. **双击 `run_snap.bat`**

*注意：hdc 工具已包含在 runtime\bin\ 目录中，无需单独安装配置*

### 操作说明

- 鼠标左键/右键点击 → 设备对应点击
- 鼠标拖拽 → 设备拖拽滑动
- 鼠标滚轮 → 设备滚动
- 键盘输入 → 设备输入
- 按 ESC 或关闭窗口 → 退出程序

---

## run_snap.bat 执行流程

### 1. 环境检测与安装（仅首次运行）

双击 `run_snap.bat` 后，脚本依次检查：

| 检查项 | 检测内容 | 不存在时的处理 |
|--------|----------|----------------|
| `runtime/scripts/snap.py` | 主程序是否存在 | 报错退出 |
| `runtime/.venv/` | 虚拟环境是否存在 | **自动创建虚拟环境** |
| Python | 系统是否有 Python 3.7+ | 报错提示安装 Python |

#### 自动创建虚拟环境的步骤：

```batch
1. 使用系统 Python 执行: python -m venv runtime\.venv
2. 激活虚拟环境: call runtime\.venv\Scripts\activate.bat
3. 安装依赖: pip install -r runtime\requirements.txt
```

#### 安装的依赖：

- `opencv-python>=4.5.0` - 用于图像显示和窗口管理
- `numpy>=1.19.0` - 用于图像处理的数值计算

---

### 2. 启动前检查

| 检查项 | 说明 |
|--------|------|
| `runtime\bin\hdc.exe` | 检测自带的 hdc 是否存在 |
| `hdc list targets` | 使用自带的 hdc 检测设备连接 |

---

### 3. 运行时使用的环境

**关键点：完全独立，不依赖用户系统环境！**

| 组件 | 路径 | 说明 |
|------|------|------|
| Python | `runtime\.venv\Scripts\python.exe` | 独立虚拟环境 |
| 依赖库 | `runtime\.venv\Lib\site-packages\` | opencv, numpy 等 |
| hdc | `runtime\bin\hdc.exe` | 自带 hdc 工具 |

这样设计的好处：
- 不依赖用户系统的 Python 版本
- 不依赖用户系统的 HarmonyOS SDK/hdc
- 不污染用户系统环境
- 可以打包成完全独立的工具包分发

---

## snap.py 执行逻辑

### 核心类：`HdcSnapCast`

### 1. 初始化 (`__init__`)

```
- 创建本地临时目录（默认 .snap_frames）
- 初始化线程锁（用于最新帧数据同步）
- 设置渲染区域映射（用于窗口缩放后坐标转换）
```

### 2. 抓帧线程 (`_capture_loop`)

后台独立线程运行，按指定间隔不断抓帧：

```
循环:
  ├─ 执行 hdc shell snapshot_display  (设备侧截图)
  ├─ 解析输出获取截图的远程路径
  ├─ hdc file recv 拉取图片到本地
  ├─ cv2.imdecode 解码为 OpenCV 图像
  ├─ 更新 self.latest_frame  (加锁保护)
  ├─ 如果开启 cleanup-local，删除本地文件
  └─ 等待 interval_ms 后下一帧
```

### 3. 显示与事件循环 (主线程 `run`)

```
循环:
  ├─ 检测窗口是否被用户关闭 (WND_PROP_VISIBLE)
  ├─ 从 self.latest_frame 获取最新帧
  ├─ _build_display_frame():
  │   ├─ 获取窗口大小
  │   ├─ 按比例缩放画面保持 aspect ratio
  │   ├─ 居中绘制到画布
  │   └─ 记录显示区域映射（用于坐标转换）
  ├─ cv2.imshow 显示画面
  ├─ cv2.waitKeyEx 等待键盘/鼠标事件
  └─ 退出条件: ESC 键 或 窗口关闭
```

### 4. 鼠标事件处理 (`_mouse_callback`)

| 事件 | 执行操作 |
|------|----------|
| `LBUTTONDOWN` | 记录按下位置 |
| `LBUTTONUP` | 按下=释放位置 → `_inject_click`，否则 → `_inject_drag` |
| `RBUTTONDOWN`/`UP` | 同左键，但发送右键点击 |
| `MOUSEWHEEL` | 调用 `_inject_scroll` |

### 5. 坐标转换 (`_to_device_coords`)

将窗口鼠标坐标转换为设备实际坐标：
```
窗口坐标 → 渲染区域内相对坐标 → 按比例映射 → 设备坐标
```

### 6. 反控命令注入 (`_send_uinput`)

通过 `hdc shell uinput` 命令向设备注入输入事件：

| 函数 | uinput 命令 | 说明 |
|------|-------------|------|
| `_inject_click` | `-M -m x y -d btn` / `-u btn` | 按下+释放 |
| `_inject_drag` | `-M -g x1 y1 x2 y2 duration` | 拖拽手势 |
| `_inject_scroll` | `-T -m x y x y+delta 300` | 触摸滑动 |
| `_inject_key` | `-K -d keycode` / `-u keycode` | 按键 |

### 7. 键码映射 (`_map_key_to_linux_uinput`)

将 OpenCV 的 `waitKeyEx` 键值转换为 Linux  input 子系统键码：
- 字母 a-z → 对应键码
- 数字 0-9 → 对应键码
- 特殊键（ESC/Enter/Backspace/方向键/F1-F12等）→ 对应键码

---

## 命令行参数 (snap.py)

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--hdc` | `hdc` | hdc 可执行文件路径 |
| `-t, --serial` | - | 设备序列号（多设备时指定） |
| `--snapshot-cmd` | `snapshot_display` | 设备侧截图命令 |
| `--interval-ms` | `100` | 抓帧周期(ms)，越小越流畅 |
| `--output-dir` | `./.snap_frames` | 本地临时图片目录 |
| `--cleanup-local` | - | 每次显示后删除本地帧文件 |
| `--command-timeout` | `6` | hdc 命令超时(秒) |
| `--drag-duration-ms` | `200` | 拖拽事件持续时间(ms) |

---

## 环境要求

### 用户系统需要安装

- **Python 3.7 或更高版本**（仅首次运行时用于创建虚拟环境）
- **USB 连接的 HarmonyOS 设备**

### 工具包自带

- **hdc.exe** - 在 `runtime\bin\` 目录
- **libusb_shared.dll** - hdc 依赖库

### 工具包内部使用（自动安装）

- Python 虚拟环境：`runtime\.venv\`
- opencv-python
- numpy

---

## 打包分发说明

可以将整个 `snap/` 目录打包成 zip 分发：

```
snap.zip
└── snap/
    ├── run_snap.bat
    ├── README.md
    └── runtime/
        ├── scripts/snap.py
        ├── requirements.txt
        ├── setup_env.bat
        └── run.bat
        (注意：不要打包 .venv 目录，让用户首次运行自动创建)
```

用户使用时：
1. 解压 zip
2. 双击 run_snap.bat
3. 等待首次自动安装环境
4. 开始使用