Software_Architecture/distance-judgement/CAMERA_ORIENTATION_GUIDE.md

# 摄像头朝向自动配置功能指南 🧭

## 功能概述

本系统现在支持自动获取设备位置和朝向，将本地摄像头设置为面朝使用者，实现智能的摄像头配置。

## 🎯 主要功能

### 1. 自动GPS定位
- **Windows系统**: 使用Windows Location API获取精确GPS位置
- **其他系统**: 使用IP地理定位作为备选方案
- **精度**: GPS可达10米内，IP定位约10公里

### 2. 设备朝向检测  
- **桌面设备**: 使用默认朝向算法（假设用户面向屏幕）
- **移动设备**: 支持陀螺仪和磁力计朝向检测
- **智能计算**: 自动计算摄像头应该面向用户的角度

### 3. 自动配置应用
- **实时更新**: 自动更新配置文件和运行时参数
- **地图同步**: 自动更新地图上的摄像头位置标记
- **即时生效**: 配置立即应用到距离计算和人员定位

## 🚀 使用方法

### 方法一：启动时自动配置

```bash
python main_web.py
```

系统会检测到默认配置并询问是否自动配置：
```
🤖 检测到摄像头使用默认配置
   是否要自动配置摄像头位置和朝向？
   • 输入 'y' - 立即自动配置
   • 输入 'n' - 跳过，使用Web界面配置
   • 直接回车 - 跳过自动配置

🔧 请选择 (y/n/回车): y
```

### 方法二：独立配置工具

```bash
# 完整自动配置
python tools/auto_configure_camera.py

# 仅测试GPS功能
python tools/auto_configure_camera.py --test-gps

# 仅测试朝向功能  
python tools/auto_configure_camera.py --test-heading
```

### 方法三：Web界面配置

1. 启动Web服务器：`python main_web.py`
2. 打开浏览器访问 `https://127.0.0.1:5000`
3. 在"🧭 自动位置配置"面板中：
   - 点击"📍 获取位置"按钮
   - 点击"🧭 获取朝向"按钮  
   - 点击"🤖 自动配置摄像头"按钮

## 📱 Web界面功能详解

### GPS位置获取
```javascript
// 使用浏览器Geolocation API
navigator.geolocation.getCurrentPosition()
```

**支持的浏览器**：
- ✅ Chrome/Edge (推荐)
- ✅ Firefox  
- ✅ Safari
- ❌ IE (不支持)

**权限要求**：
- 首次使用需要授权位置权限
- HTTPS环境下精度更高
- 室外环境GPS信号更好

### 设备朝向检测
```javascript  
// 使用设备朝向API
window.addEventListener('deviceorientation', handleOrientation)
```

**支持情况**：
- 📱 **移动设备**: 完全支持（手机、平板）
- 💻 **桌面设备**: 有限支持（使用算法估算）  
- 🍎 **iOS 13+**: 需要明确请求权限

## ⚙️ 技术实现

### 后端模块

#### 1. OrientationDetector (`src/orientation_detector.py`)
- GPS位置获取（多平台支持）
- 设备朝向检测  
- 摄像头朝向计算
- 配置文件更新

#### 2. WebOrientationDetector (`src/web_orientation_detector.py`)  
- Web API接口
- 前后端数据同步
- 实时状态管理

### 前端功能

#### JavaScript函数
- `requestGPSPermission()` - GPS权限请求
- `requestOrientationPermission()` - 朝向权限请求  
- `autoConfigureCamera()` - 自动配置执行
- `manualConfiguration()` - 手动配置入口

#### API接口
- `POST /api/orientation/auto_configure` - 自动配置
- `POST /api/orientation/update_location` - 更新GPS
- `POST /api/orientation/update_heading` - 更新朝向
- `GET /api/orientation/get_status` - 获取状态

## 🔧 配置原理

### 朝向计算逻辑

```python
def calculate_camera_heading_facing_user(self, user_heading: float) -> float:
    """
    计算摄像头朝向用户的角度
    摄像头朝向 = (用户朝向 + 180°) % 360°
    """
    camera_heading = (user_heading + 180) % 360
    return camera_heading
```

### 坐标转换

```python
def calculate_person_position(self, pixel_x, pixel_y, distance, frame_width, frame_height):
    """
    基于摄像头位置、朝向和距离计算人员GPS坐标
    使用球面几何学进行精确计算
    """
    # 像素到角度转换
    horizontal_angle_per_pixel = self.camera_fov / frame_width
    horizontal_offset_degrees = (pixel_x - center_x) * horizontal_angle_per_pixel
    
    # 计算实际方位角
    person_bearing = (self.camera_heading + horizontal_offset_degrees) % 360
    
    # 球面坐标计算
    person_lat, person_lng = self._calculate_destination_point(
        self.camera_lat, self.camera_lng, distance, person_bearing
    )
```

## 📋 系统要求

### 环境要求
- Python 3.7+
- 现代Web浏览器
- 网络连接（GPS定位需要）

### Windows特别要求
```bash
# 安装Windows位置服务支持
pip install winrt-runtime winrt-Windows.Devices.Geolocation
```

### 移动设备要求
- HTTPS访问（GPS权限要求）
- 现代移动浏览器
- 设备朝向传感器支持

## 🔍 故障排除

### GPS获取失败
**常见原因**：
- 位置权限被拒绝
- 网络连接问题  
- GPS信号不佳

**解决方案**：
1. 检查浏览器位置权限设置
2. 移动到室外或窗边
3. 使用IP定位作为备选
4. 手动输入坐标

### 朝向检测失败
**常见原因**：
- 设备不支持朝向传感器
- 浏览器兼容性问题
- 权限被拒绝

**解决方案**：
1. 使用支持的移动设备
2. 更新到现代浏览器
3. 允许设备朝向权限
4. 使用手动配置

### 配置不生效
**可能原因**：
- 配置文件写入失败
- 权限不足
- 模块导入错误

**解决方案**：
1. 检查文件写入权限
2. 重启应用程序
3. 查看控制台错误信息

## 💡 使用建议

### 最佳实践
1. **首次配置**: 使用Web界面进行配置，可视化效果更好
2. **定期更新**: 位置变化时重新配置
3. **精度要求**: GPS环境下精度更高，室内可用IP定位
4. **设备选择**: 移动设备朝向检测更准确

### 注意事项
1. **隐私保护**: GPS数据仅用于本地配置，不会上传
2. **网络要求**: 初次配置需要网络连接
3. **兼容性**: 老旧浏览器可能不支持某些功能
4. **精度限制**: 桌面设备朝向检测精度有限

## 📚 相关文档

- [MAP_USAGE_GUIDE.md](MAP_USAGE_GUIDE.md) - 地图功能使用指南
- [MOBILE_GUIDE.md](MOBILE_GUIDE.md) - 移动端使用指南  
- [HTTPS_SETUP.md](HTTPS_SETUP.md) - HTTPS配置指南

---

🎯 **快速开始**: 运行 `python main_web.py`，选择自动配置，享受智能的摄像头定位体验！