230 lines
8.8 KiB
Markdown
230 lines
8.8 KiB
Markdown
# 人体姿态估计接口
|
||
|
||
本文档描述了人体姿态估计（Human Pose Estimation, HPE）服务的 HTTP API 接口规范。
|
||
|
||
## 目录
|
||
|
||
- [人体姿态估计接口](#人体姿态估计接口)
|
||
- [目录](#目录)
|
||
- [服务概述](#服务概述)
|
||
- [接口说明](#接口说明)
|
||
- [请求](#请求)
|
||
- [请求头](#请求头)
|
||
- [响应](#响应)
|
||
- [成功响应](#成功响应)
|
||
- [响应体示例](#响应体示例)
|
||
- [错误码](#错误码)
|
||
- [错误响应示例](#错误响应示例)
|
||
- [响应数据结构](#响应数据结构)
|
||
- [关键点定义](#关键点定义)
|
||
- [骨骼连接定义](#骨骼连接定义)
|
||
- [可视化示例](#可视化示例)
|
||
- [使用示例](#使用示例)
|
||
- [Python 示例](#python-示例)
|
||
- [Bash/cURL 示例](#bashcurl-示例)
|
||
- [cURL 快速示例](#curl-快速示例)
|
||
- [注意事项](#注意事项)
|
||
|
||
---
|
||
|
||
## 服务概述
|
||
|
||
HPE 服务提供基于深度学习的人体姿态估计能力，可从输入图像中检测人体并识别 133 个关键点（全身姿态，包含身体、手部及面部关键点）。
|
||
|
||
- **服务端点**：`https://api.pose.weihua-iot.cn/hpe`
|
||
|
||
---
|
||
|
||
## 接口说明
|
||
|
||
### 请求
|
||
|
||
| 属性 | 说明 |
|
||
| ------------------ | --------------------------- |
|
||
| **URL** | `/hpe` |
|
||
| **方法** | `POST` |
|
||
| **Content-Type** | `image/jpeg` 或 `image/png` |
|
||
| **请求体** | 原始图像二进制数据 |
|
||
| **最大请求体大小** | 10 MB |
|
||
| **超时时间** | 30 秒 |
|
||
|
||
#### 请求头
|
||
|
||
| 名称 | 必填 | 说明 |
|
||
| ---------------- | ---- | ---------------------------------- |
|
||
| `Content-Type` | 是 | 必须为 `image/jpeg` 或 `image/png` |
|
||
| `Content-Length` | 否 | 请求体字节数（推荐提供） |
|
||
|
||
### 响应
|
||
|
||
#### 成功响应
|
||
|
||
| HTTP 状态码 | Content-Type | 说明 |
|
||
| ----------- | ------------------ | ------------------------------ |
|
||
| `200` | `application/json` | 检测到姿态，返回 JSON 数据 |
|
||
| `200` | 无内容 | 未检测到人体姿态，返回空响应体 |
|
||
|
||
#### 响应体示例
|
||
|
||
```json
|
||
{
|
||
"frame_index": 0,
|
||
"reference_size": [1920, 1080],
|
||
"bbox": [[100, 150, 400, 800], [500, 200, 750, 850]],
|
||
"bbox_confidence": [0.95, 0.87],
|
||
"keypoints": [
|
||
[[x1, y1], [x2, y2], ...],
|
||
[[x1, y1], [x2, y2], ...]
|
||
],
|
||
"keypoints_confidence": [
|
||
[0.9, 0.85, ...],
|
||
[0.88, 0.92, ...]
|
||
]
|
||
}
|
||
```
|
||
|
||
### 错误码
|
||
|
||
| HTTP 状态码 | 错误类型 | 说明 |
|
||
| ----------- | ---------------------- | --------------------------------------------- |
|
||
| `400` | Bad Request | 请求体为空或图像解码失败 |
|
||
| `408` | Request Timeout | 推理超时（超过 30 秒） |
|
||
| `413` | Payload Too Large | 请求体超过 10 MB 限制 |
|
||
| `415` | Unsupported Media Type | Content-Type 不是 `image/jpeg` 或 `image/png` |
|
||
| `503` | Service Unavailable | 服务过载，请求队列已满（最大 16 个请求） |
|
||
|
||
#### 错误响应示例
|
||
|
||
```json
|
||
{
|
||
"error": "Unsupported Media Type",
|
||
"detail": "Expected Content-Type: image/jpeg or image/png, got: text/plain"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 响应数据结构
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| ---------------------- | ------------------------------- | -------------------------------------------------------------------------------- |
|
||
| `frame_index` | `int` | 帧索引，HTTP 接口始终返回 `0` |
|
||
| `reference_size` | `[int, int]` | 输入图像尺寸，格式为 `[宽度, 高度]` |
|
||
| `bbox` | `[[x1, y1, x2, y2], ...]` | 检测到的人体边界框列表，每个边界框包含左上角 `(x1, y1)` 和右下角 `(x2, y2)` 坐标 |
|
||
| `bbox_confidence` | `[float, ...]` 或 `null` | 每个边界框的置信度分数（0-1），可能为空 |
|
||
| `keypoints` | `[[[x, y], ...], ...]` | 每个检测到的人体的 133 个关键点坐标列表 |
|
||
| `keypoints_confidence` | `[[float, ...], ...]` 或 `null` | 每个关键点的置信度分数（0-1），可能为空 |
|
||
|
||
---
|
||
|
||
## 关键点定义
|
||
|
||
本服务使用 COCO WholeBody 格式，共包含 133 个关键点：
|
||
|
||
| 索引范围 | 数量 | 描述 |
|
||
| -------- | ---- | -------------------------------------------------------------------- |
|
||
| 0-16 | 17 | 身体关键点（鼻子、眼睛、耳朵、肩膀、肘部、手腕、髋部、膝盖、脚踝等） |
|
||
| 17-22 | 6 | 脚部关键点 |
|
||
| 23-90 | 68 | 面部关键点 |
|
||
| 91-111 | 21 | 左手关键点 |
|
||
| 112-132 | 21 | 右手关键点 |
|
||
|
||
|
||
|
||
### 骨骼连接定义
|
||
|
||
关键点之间通过骨骼（Bone）连接形成人体骨架结构。主要骨骼连接如下：
|
||
|
||
| 部位 | 连接关系（0-based 索引） |
|
||
| ---- | ------------------------------------------------ |
|
||
| 腿部 | (15, 13), (13, 11), (16, 14), (14, 12), (11, 12) |
|
||
| 躯干 | (5, 11), (6, 12), (5, 6) |
|
||
| 手臂 | (5, 7), (7, 9), (6, 8), (8, 10) |
|
||
| 头部 | (1, 2), (0, 1), (0, 2), (1, 3), (2, 4) |
|
||
| 左脚 | (15, 17), (15, 18), (15, 19) |
|
||
| 右脚 | (16, 20), (16, 21), (16, 22) |
|
||
| 左手 | 手腕(91)连接至各指根，每指4个关节依次连接 |
|
||
| 右手 | 手腕(112)连接至各指根，每指4个关节依次连接 |
|
||
|
||
### 可视化示例
|
||
|
||
项目提供了完整的可视化脚本 [scripts/vis_whole_body.py](scripts/vis_whole_body.py)，包含：
|
||
|
||
- **关键点定义**：`body_landmarks`、`foot_landmarks`、`face_landmarks`、`hand_landmarks` 字典，包含每个关键点的索引、名称和颜色
|
||
- **骨骼定义**：`body_bones`、`hand_bones` 列表，定义了关键点之间的连接关系
|
||
- **可视化函数**：
|
||
- `visualize_whole_body()` - 可视化单人 133 个关键点
|
||
- `visualize_17_keypoints()` - 仅可视化 17 个身体关键点
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
完整的客户端示例代码位于 [scripts](scripts/) 目录下。
|
||
|
||
### Python 示例
|
||
|
||
参见 [scripts/client_example.py](scripts/client_example.py)。
|
||
|
||
该脚本使用 [PEP 723](https://peps.python.org/pep-0723/) 内联脚本元数据，可通过 [uv](https://docs.astral.sh/uv/) 直接运行，无需手动安装依赖：
|
||
|
||
```bash
|
||
# 使用 uv 直接运行（自动安装依赖）
|
||
uv run scripts/client_example.py figures/sample.jpg
|
||
|
||
# 指定自定义 URL
|
||
uv run scripts/client_example.py figures/sample.jpg --url https://api.pose.weihua-iot.cn/hpe
|
||
|
||
# 或使用传统方式（需先安装 httpx）
|
||
pip install httpx
|
||
python scripts/client_example.py figures/sample.jpg
|
||
```
|
||
|
||
### Bash/cURL 示例
|
||
|
||
参见 [scripts/client_example.sh](scripts/client_example.sh)。
|
||
|
||
```bash
|
||
# 赋予执行权限
|
||
chmod +x scripts/client_example.sh
|
||
|
||
# 发送图像
|
||
./scripts/client_example.sh figures/sample.jpg
|
||
|
||
# 指定自定义 URL
|
||
./scripts/client_example.sh figures/sample.jpg https://api.pose.weihua-iot.cn/hpe
|
||
```
|
||
|
||
### cURL 快速示例
|
||
|
||
```bash
|
||
# 发送 JPEG 图像
|
||
curl -X POST \
|
||
-H "Content-Type: image/jpeg" \
|
||
--data-binary @figures/sample.jpg \
|
||
https://api.pose.weihua-iot.cn/hpe
|
||
|
||
# 发送 PNG 图像并使用 jq 格式化输出
|
||
curl -s -X POST \
|
||
-H "Content-Type: image/png" \
|
||
--data-binary @figures/sample.png \
|
||
https://api.pose.weihua-iot.cn/hpe | jq .
|
||
|
||
# 将结果保存到文件
|
||
curl -X POST \
|
||
-H "Content-Type: image/jpeg" \
|
||
--data-binary @figures/sample.jpg \
|
||
-o result.json \
|
||
https://api.pose.weihua-iot.cn/hpe
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **图像格式**：仅支持 JPEG 和 PNG 格式，其他格式将返回 415 错误。
|
||
2. **图像大小**：请确保图像文件不超过 10 MB，否则将返回 413 错误。
|
||
3. **并发限制**：服务最多同时处理 16 个请求，超出后将返回 503 错误。
|
||
4. **超时处理**：单次推理最长等待 30 秒，超时将返回 408 错误。
|
||
5. **空结果处理**：当未检测到人体时，服务返回 HTTP 200 但响应体为空，请在客户端代码中正确处理此情况。
|