# EyeGazeTrackingSystem **Repository Path**: Junjiagit/EyeGazeTrackingSystem ## Basic Information - **Project Name**: EyeGazeTrackingSystem - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-16 - **Last Updated**: 2026-01-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 基于MediaPipe的眼睛注视跟踪系统 ## 模块功能与使用说明报告 **作者**：技术导师 Copilot (@mosivez) **日期**：2025年5月5日 **版本**：V1.0 ## 目录 1. [系统概述](#1-系统概述) 2. [模块功能详解](#2-模块功能详解) 3. [系统架构说明](#3-系统架构说明) 4. [安装与配置](#4-安装与配置) 5. [使用指南](#5-使用指南) 6. [评估与测试](#6-评估与测试) 7. [常见问题与解决方案](#7-常见问题与解决方案) 8. [进一步优化建议](#8-进一步优化建议) --- ## 1. 系统概述 ### 1.1 系统介绍 本系统是一个基于MediaPipe面部检测技术的眼睛注视跟踪系统，能够实时检测用户面部和眼睛位置，分析虹膜相对位置和头部姿态，最终预测用户屏幕注视点位置。系统通过多模块化设计，包含了完整的校准、训练、评估和预测流程，提供了灵活的配置选项和详尽的评估报告功能。 ### 1.2 系统特点 - **模块化设计**：各功能独立封装，便于维护和扩展 - **基于MediaPipe**：利用先进的面部检测技术，稳定可靠 - **多模型支持**：支持SVR、随机森林和神经网络多种机器学习模型 - **完整评估体系**：提供详细的性能评估指标和可视化报告 - **配置化管理**：通过YAML配置文件实现参数灵活调整 - **实时处理**：使用卡尔曼滤波平滑数据，提高预测稳定性 ### 1.3 系统流程 1. **校准阶段**：用户注视屏幕不同位置，系统收集眼睛特征数据 2. **训练阶段**：基于校准数据训练机器学习模型 3. **评估阶段**：测试系统在不同屏幕位置的预测准确性 4. **预测阶段**：实时预测用户注视点位置 --- ## 2. 模块功能详解 ### 2.1 配置模块 `config.py` 配置管理模块负责加载和管理系统参数配置。 **主要功能**: - 加载YAML格式的配置文件 - 提供默认配置 - 递归更新配置项 - 转换特殊配置为NumPy格式 - 提供统一的配置访问接口 **关键类**: - `ConfigManager`: 配置管理器，处理配置的加载和访问 ### 2.2 眼睛检测模块 `eye_detector.py` 负责检测面部关键点、眼睛和虹膜位置。 **主要功能**: - 初始化MediaPipe面部网格检测器 - 检测眼睛角点和中心点 - 检测虹膜中心点 - 计算虹膜相对眼睛中心的偏移 **关键类和数据结构**: - `EyeDetector`: 眼睛检测主类 - `EyePoint`: 存储眼睛关键点的数据结构 ### 2.3 头部姿态估计模块 `pose_estimator.py` 估计头部三维姿态，用于视线方向计算。 **主要功能**: - 解算PnP问题，估计头部旋转和平移 - 计算视线方向向量 - 将三维视线投影到屏幕平面 **关键类和数据结构**: - `PoseEstimator`: 姿态估计器 - `HeadPose`: 头部姿态数据结构 ### 2.4 卡尔曼滤波模块 `kalman_filter.py` 对检测数据进行滤波处理，减少抖动，提高稳定性。 **主要功能**: - 初始化姿态和偏移的卡尔曼滤波器 - 对头部姿态数据进行滤波 - 对眼睛偏移数据进行滤波 - 限制预测点移动速度，避免跳变 **关键类和数据结构**: - `KalmanFilterManager`: 卡尔曼滤波管理器 - `FilteredData`: 滤波后数据的结构体 ### 2.5 注视点映射模块 `gaze_mapper.py` 将特征向量映射到屏幕坐标的机器学习模型。 **主要功能**: - 创建和训练不同类型的模型 - 预测注视点位置 - 保存和加载模型 - 数据增强（扩充校准点） **支持的模型类型**: - SVR (Support Vector Regression) - 随机森林 (Random Forest) - 神经网络 (Neural Network) ### 2.6 校准模块 `calibration.py` 负责系统校准流程。 **主要功能**: - 生成校准点位置 - 处理校准步骤 - 收集校准数据 - 绘制校准界面 **关键类**: - `CalibrationManager`: 校准流程管理器 ### 2.7 评估模块 `evaluation.py` 负责系统性能评估和报告生成。 **主要功能**: - 处理评估流程 - 计算评估指标（误差、标准差、完整度） - 区域性能分析 - 时间序列分析 - 方向误差分析 - 可视化评估结果 - 生成HTML评估报告 **关键类**: - `EvaluationManager`: 评估流程管理器 ### 2.8 可视化模块 `visualization.py` 负责系统的视觉反馈和结果可视化。 **主要功能**: - 绘制调试信息 - 创建主显示屏 - 绘制头部姿态和视线方向 - 生成评估结果可视化 **关键类**: - `Visualizer`: 可视化工具类 ### 2.9 主程序模块 `main.py` 整合所有模块，实现完整系统功能。 **主要功能**: - 初始化和管理各个模块 - 处理摄像头输入 - 协调校准、训练、评估和预测流程 - 处理用户输入和交互 - 保存结果和生成报告 **关键类**: - `EyeTrackingSystem`: 眼动追踪系统主类 --- ## 3. 系统架构说明 ### 3.1 架构设计 系统采用模块化架构设计，各个功能模块相互独立，通过明确的接口进行通信。中心是主程序模块，它协调各个功能模块的工作流程。 ``` ┌─── eye_detector.py ───┐ │ │ ▼ │ ┌─────────────┐ ┌─────────────────┐ ┌────────────┐ │ config.py │◄─┤ main.py │◄─┤ pose_estimator.py └─────────────┘ └─────────────────┘ └────────────┘ ▲ ▲ │ ▲ ▲ │ │ │ │ │ ┌────┴────────┐ ┌──────┘ │ └────────┐ ┌────┴─────────┐ │ gaze_mapper.py │ │ calibration.py │ │ kalman_filter.py │ └──────────────┘ └──────────────┘ └──────────────┘ │ ┌──────────┴───────────┐ │ │ ┌───────┴─────────┐ ┌─────────┴────────┐ │ evaluation.py │ │ visualization.py │ └─────────────────┘ └──────────────────┘ ``` ### 3.2 数据流 1. `config.py` 初始化系统配置 2. `main.py` 读取摄像头图像 3. `eye_detector.py` 检测眼睛位置和虹膜 4. `pose_estimator.py` 估计头部姿态 5. `kalman_filter.py` 平滑处理数据 6. `gaze_mapper.py` 映射到屏幕坐标 7. `visualization.py` 提供视觉反馈 8. `calibration.py`/`evaluation.py` 根据当前模式处理特定流程 ### 3.3 扩展性设计 - **配置驱动**: 大多数参数通过配置文件设置，无需修改代码 - **模型可插拔**: 支持不同类型的机器学习模型，可轻松添加新模型 - **评估框架**: 提供标准化评估流程，便于比较不同配置的性能 - **可视化分离**: 显示逻辑与核心功能分离，便于定制界面 --- ## 4. 安装与配置 ### 4.1 系统要求 - **操作系统**: Windows 10/11, macOS, Linux - **Python版本**: Python 3.7+ - **摄像头**: 支持OpenCV的摄像头设备 ### 4.2 依赖库 ``` opencv-python>=4.5.0 mediapipe>=0.8.9 numpy>=1.19.0 scikit-learn>=0.24.0 matplotlib>=3.3.0 pyyaml>=5.1 seaborn>=0.11.0 pandas>=1.1.0 ``` ### 4.3 安装步骤 1. 克隆或下载项目代码 2. 安装依赖: ```bash pip install -r requirements.txt ``` 3. 生成默认配置文件: ```bash python main.py --generate-config ``` 4. 根据需要修改配置文件 `config.yml` ### 4.4 配置说明 配置文件 `config.yml` 包含以下主要部分: - **camera**: 摄像头配置 - **mediapipe**: MediaPipe面部网格参数 - **calibration**: 校准点数量和位置 - **evaluation**: 评估点数量和每点录制帧数 - **model**: 机器学习模型类型和参数 - **filtering**: 卡尔曼滤波参数 - **visualization**: 可视化选项 - **system**: 系统级参数 --- ## 5. 使用指南 ### 5.1 基本操作 1. **启动系统**: ```bash python main.py ``` 2. **选择配置文件**: ```bash python main.py --config custom_config.yml ``` ### 5.2 校准流程 1. 系统启动后，默认进入校准模式 2. 屏幕上会显示绿色校准点，请注视该点 3. 注视点后按空格键确认采集 4. 校准点会变为红色，表示该点数据已采集 5. 完成所有校准点后，系统自动进入训练模式 ### 5.3 评估流程 1. 训练完成后，系统自动进入评估模式 2. 屏幕上会显示白色评估点，请注视该点 3. 注视点后按R键开始录制 4. 录制过程中点会变为黄色 5. 完成所有评估点后，系统自动进入预测模式并生成评估报告 ### 5.4 预测模式 1. 在预测模式下，屏幕上会显示红色点表示预测的注视位置 2. 可以自由移动视线，观察系统跟踪效果 3. 按Q键退出系统 4. 按S键保存当前评估结果 5. 按R键重新开始校准 ### 5.5 结果报告 系统会在 `results` 目录下生成评估结果，包括: - 原始数据 (`raw_data.json`) - 评估指标 (`metrics.json`) - 时间序列分析 (`temporal_analysis.json`) - 方向误差分析 (`directional_analysis.json`) - 可视化图表 (位于 `visualizations` 子目录) - HTML评估报告 (`report.html`) --- ## 6. 评估与测试 ### 6.1 评估指标说明 - **平均误差**: 预测点与目标点间的平均欧氏距离(像素) - **标准差**: 误差的标准偏差，反映稳定性 - **完整度**: 有效预测帧数占预期帧数的比例 - **区域性能**: 屏幕不同区域的预测精度 - **方向误差**: 水平与垂直方向上的误差对比 ### 6.2 评估结果解读 HTML评估报告提供了多种可视化结果: - **准确度散点图**: 显示预测点与目标点的空间关系 - **准确度热力图**: 展示不同屏幕区域的误差分布 - **误差箱型图**: 每个评估点的误差统计分布 - **方向误差对比图**: 水平和垂直方向误差的比较 - **时间序列稳定性图**: 误差随时间的变化趋势 ### 6.3 系统表现评估 典型性能指标值范围： - **理想情况**: 平均误差 < 30像素 - **可接受范围**: 平均误差 30-60像素 - **需改进**: 平均误差 > 60像素 影响因素： - 校准点数量和分布 - 用户头部运动 - 摄像头分辨率和帧率 - 环境光线条件 --- ## 7. 常见问题与解决方案 ### 7.1 校准问题 **问题**: 校准过程中无法捕获数据 **解决方案**: - 检查摄像头是否正常工作 - 确保面部在摄像头视野内 - 调整光线，避免过亮或过暗 - 确保眼睛睁开并可见 **问题**: 校准后预测准确度低 **解决方案**: - 增加校准点数量 - 校准时保持头部相对稳定 - 尝试启用数据增强选项 - 确保校准点覆盖整个屏幕范围 ### 7.2 检测问题 **问题**: 系统无法检测到面部 **解决方案**: - 确保光线充足 - 调整摄像头角度 - 不要佩戴深色墨镜 - 检查MediaPipe版本是否兼容 **问题**: 虹膜检测不稳定 **解决方案**: - 增加卡尔曼滤波的过程噪声参数 - 减少眼睛-摄像头距离 - 避免低光环境 - 更新到支持虹膜检测的MediaPipe版本 ### 7.3 性能问题 **问题**: 系统运行缓慢 **解决方案**: - 降低摄像头分辨率 - 减少评估点的记录帧数 - 关闭不必要的可视化选项 - 在更高性能的设备上运行 **问题**: 预测点跳动剧烈 **解决方案**: - 增大 `prediction_max_speed` 参数 - 增加卡尔曼滤波的测量噪声参数 - 确保摄像头固定牢固 - 训练时增加数据样本数量 --- ## 8. 进一步优化建议 ### 8.1 模型优化 - **多模型集成**: 结合不同类型模型的预测结果 - **个性化适应**: 添加用户适应性学习机制 - **学习率调整**: 实现动态学习率以适应不同用户 - **迁移学习**: 使用预训练模型加速校准过程 ### 8.2 功能扩展 - **眨眼检测**: 添加眨眼识别作为交互触发 - **多用户配置**: 支持多用户配置文件切换 - **眼动轨迹分析**: 记录和分析注视轨迹 - **深度估计**: 增加Z轴估计，支持3D交互 ### 8.3 评估完善 - **疲劳度评估**: 长时间使用后的性能变化 - **跨设备测试**: 在不同摄像头设备上的表现 - **用户体验评分**: 添加用户感知评分系统 - **延迟分析**: 各处理阶段的时间消耗分析 ### 8.4 系统集成 - **GUI界面**: 添加图形用户界面进行配置 - **外部应用集成**: 提供API与其他应用对接 - **实时检修**: 运行时系统状态监控和报告 - **云端支持**: 添加远程校准模型的存取功能 --- 感谢您使用基于MediaPipe的眼睛注视跟踪系统。如有任何问题或建议，请联系技术支持团队。 祝您使用愉快！