> ## Documentation Index
> Fetch the complete documentation index at: https://jmail.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# photo_faces()

> 下载用于将照片与人物关联的人脸边界框数据

```python theme={null}
client.photo_faces() -> pd.DataFrame
```

下载人脸边界框数据，将照片中检测到的人脸与已识别人物关联起来。

## 返回值

包含人脸检测数据的 `pd.DataFrame`。

## 示例

```python theme={null}
from jmail import JmailClient

client = JmailClient()
faces = client.photo_faces()
people = client.people()

# 连接数据以获取人员姓名
import pandas as pd
merged = faces.merge(people[["id", "name"]], left_on="person_id", right_on="id", suffixes=("", "_person"))
print(merged.groupby("name").size().sort_values(ascending=False).head(20))
```

## 列

| 列名 | 类型 | 描述 |
| - | - | - |
| `id` | int | 人脸检测的唯一 ID |
| `photo_id` | int | 指向 photos 表的外键 |
| `person_id` | int | 指向 people 表的外键 |
| `bbox_left` | float | 边界框左边缘（归一化到 0–1） |
| `bbox_top` | float | 边界框上边缘（归一化到 0–1） |
| `bbox_width` | float | 边界框宽度（归一化到 0–1） |
| `bbox_height` | float | 边界框高度（归一化到 0–1） |
| `confidence` | float | 检测置信度得分 |

## 直接链接

```
https://data.jmail.world/v1/photo_faces.parquet
https://data.jmail.world/v1/photo_faces.ndjson.gz
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.