Software_Architecture/distance-judgement/CAMERA_ORIENTATION_GUIDE.md

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

功能概述

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

🎯 主要功能

1. 自动GPS定位

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

2. 设备朝向检测

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

3. 自动配置应用

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

🚀 使用方法

方法一：启动时自动配置

python main_web.py

系统会检测到默认配置并询问是否自动配置：

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

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

方法二：独立配置工具

# 完整自动配置
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位置获取

// 使用浏览器Geolocation API
navigator.geolocation.getCurrentPosition()

支持的浏览器：

• ✅ Chrome/Edge (推荐)
• ✅ Firefox
• ✅ Safari
• ❌ IE (不支持)

权限要求：

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

设备朝向检测

// 使用设备朝向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 - 获取状态

🔧 配置原理

朝向计算逻辑

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

坐标转换

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特别要求

# 安装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 - 地图功能使用指南
• MOBILE_GUIDE.md - 移动端使用指南
• HTTPS_SETUP.md - HTTPS配置指南

---

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