Software_Architecture/distance-judgement/MAP_USAGE_GUIDE.md

# 地图功能使用指南 🗺️

## 功能概述

本系统集成了高德地图API，可以实时在地图上显示：
- 📷 摄像头位置（蓝色标记）
- 👥 检测到的人员位置（红色标记）
- 📏 每个人员距离摄像头的距离

## 快速开始

### 1. 配置摄像头位置 📍

首先需要设置摄像头的地理位置：

```bash
python setup_camera_location.py
```

按提示输入：
- 摄像头纬度（例：39.9042）
- 摄像头经度（例：116.4074）  
- 摄像头朝向角度（0-360°，0为正北）
- 高德API Key（可选，用于更好的地图体验）

### 2. 启动系统 🚀

```bash
python main.py
```

### 3. 查看地图 🗺️

在检测界面按 `m` 键打开地图，系统会自动在浏览器中显示实时地图。

## 操作说明

### 键盘快捷键

- `q` - 退出程序
- `c` - 距离校准模式
- `r` - 重置为默认参数
- `s` - 保存当前帧截图
- `m` - 打开地图显示 🗺️
- `h` - 设置摄像头朝向 🧭

### 地图界面说明

- 🔵 **蓝色标记** - 摄像头位置
- 🔴 **红色标记** - 检测到的人员位置
- 📊 **信息面板** - 显示系统状态和统计信息
- ⚡ **实时更新** - 地图每3秒自动刷新一次

## 坐标计算原理

系统通过以下步骤计算人员的地理坐标：

1. **像素坐标获取** - 从YOLO检测结果获取人体在画面中的位置
2. **角度计算** - 根据摄像头视场角计算人相对于摄像头中心的角度偏移
3. **方位角计算** - 结合摄像头朝向，计算人相对于正北的绝对角度
4. **地理坐标转换** - 使用球面几何学公式，根据距离和角度计算地理坐标

### 关键参数

- `CAMERA_FOV` - 摄像头视场角（默认60°）
- `CAMERA_HEADING` - 摄像头朝向角度（0°为正北）
- 距离计算基于已校准的距离测量算法

## 高德地图API配置

### 获取API Key

1. 访问 [高德开放平台](https://lbs.amap.com/)
2. 注册并创建应用
3. 获取Web服务API Key
4. 在配置中替换 `your_gaode_api_key_here`

### API使用限制

- 免费配额：每日10万次调用
- 超出配额后可能影响地图加载
- 建议使用自己的API Key以确保稳定服务

## 精度优化建议

### 距离校准 📏

使用 `c` 键进入校准模式：
1. 让一个人站在已知距离处
2. 输入实际距离
3. 系统自动调整计算参数

### 朝向校准 🧭

使用 `h` 键设置准确朝向：
1. 确定摄像头实际朝向（使用指南针）
2. 输入角度（0°为正北，90°为正东）

### 位置校准 📍

确保摄像头GPS坐标准确：
1. 使用手机GPS应用获取精确坐标
2. 运行 `setup_camera_location.py` 更新配置

## 故障排除

### 地图无法打开

1. 检查网络连接
2. 确认高德API Key配置正确
3. 尝试手动访问生成的HTML文件

### 人员位置不准确

1. 重新校准距离参数
2. 检查摄像头朝向设置
3. 确认摄像头GPS坐标准确

### 地图显示异常

1. 刷新浏览器页面
2. 清除浏览器缓存
3. 检查JavaScript控制台错误信息

## 技术细节

### 坐标转换公式

系统使用WGS84坐标系和球面几何学公式：

```python
# 球面距离计算
lat2 = asin(sin(lat1) * cos(d/R) + cos(lat1) * sin(d/R) * cos(bearing))
lng2 = lng1 + atan2(sin(bearing) * sin(d/R) * cos(lat1), cos(d/R) - sin(lat1) * sin(lat2))
```

### 视场角映射

```python
# 像素到角度的转换
horizontal_angle_per_pixel = camera_fov / frame_width
horizontal_offset = (pixel_x - center_x) * horizontal_angle_per_pixel
```

## 系统要求

- Python 3.7+
- OpenCV 4.0+
- 网络连接（地图加载）
- 现代浏览器（Chrome/Firefox/Edge）

## 注意事项

⚠️ **重要提醒**：
- 本系统仅供技术研究使用
- 实际部署需要考虑隐私保护
- GPS坐标精度影响最终定位准确性
- 距离计算基于单目视觉，存在一定误差

## 更新日志

- v1.0.0 - 基础地图显示功能
- v1.1.0 - 添加实时人员位置标记
- v1.2.0 - 优化坐标计算精度
- v1.3.0 - 增加配置工具和用户指南