憨憨美瞳面诊体验馆 是一款专为美瞳零售门店、眼镜连锁店及线上新零售场景打造的专业级 AI 智能美瞳试戴与数字化客户管理系统。项目基于 Python 3.10 开发，深度融合了 PyQt5 图形界面框架、OpenCV 图像处理引擎以及 Google MediaPipe 高精度计算机视觉框架，旨在通过前沿的视觉技术升级传统美瞳的选购与试戴体验。
- 核心语言：Python 3.10
- 图形界面 (GUI)：PyQt5（采用现代深色科技感 UI 风格，支持高分屏自适应）
- 计算机视觉与深度学习：
- MediaPipe Face Mesh：用于高精度人脸检测、468 点 3D 面部网格捕捉及虹膜精确定位。
- OpenCV (
cv2)：负责视频流采集、图像矩阵变换、图层透明度合成（Alpha Blending）及高斯模糊边缘柔化。
- 数据存储与持久化：
- JSON 格式存储客户试戴历史记录。
- NumPy (
.npy) 存储人脸低维特征向量（Embedding），用于老顾客无感智能识别。
- 打包分发：PyInstaller（支持单文件
.exe独立绿色运行，内置图标与图像素材打包）。
- 高精度网格捕捉：精准锁定左右眼瞳孔中心点及眼裂边缘边界。
- 智能平滑防抖算法：引入时序加权平滑机制，有效解决视频流中的轻微抖动和闪烁现象，让美瞳纹理如同原生般紧密贴合眼球转动。
- 余弦径向边缘渐变（Soft Alpha Mask）：独创的动态半径渐变与高斯模糊边缘算法，彻底消除了传统贴图生硬的“塑料感”，呈现出极具通透感和真实感的水光高光效果。
- 姿态校验：具备人脸侧偏、过度仰头俯视过滤功能，保证视觉呈现的专业度。
- 双通道采集源：支持实时摄像头动态试戴、本地自拍照静态试戴。
- 一键批量导入素材文件夹：全面支持
.png、.jpg、.jpeg、.webp（包括所有大小写形式）的文件夹批量导入，商家可一键上新和展示新品。 - 预设与自定义款式切换：内置经典热销及动漫写轮眼款式，具备分类筛选器（自然款、混血款、浅瞳、深瞳）及详细的产品参数卡展示（直径、基弧、含水量、价格、描述）。
- 全方位微调参数：支持自由控制透明度 (Alpha)、缩放比例 (Scale)、单双眼独立控制及“原图对比”。
- 环境光与色温调节：提供色温（Temperature）、亮度（Brightness）滑块，并内置四大预设场景（Natural 自然光、Warm Light 暖光、Cold Light 冷光、Night 夜间）。
- AI 老顾客无感识别：自动提取顾客的面部特征向量与本地数据库比对，自动弹出专属欢迎标语。
- 客户独立文件夹档案库：设立密码保护机制（管理密码
123456），自动为每位顾客建立独立文件夹，归档特征文件、历史记录及多张高清试戴效果截图。 - 带水印成品导出：确认保存时，自动在试戴效果图右下角合成“憨憨美瞳面诊体验馆”专属品牌水印。
myproject/
│
├── app18.py # 系统主程序源码（包含 UI 界面、视觉引擎、业务逻辑）
├── pictures/ # 核心图标及默认动漫美瞳素材文件夹
│ ├── hanhan.jpg # 窗口软件 Logo
│ ├── hanhan2.jpg # 店长形象卡通头像
│ ├── kakaxi.png # 卡卡西写轮眼素材
│ ├── zuozhu.png # 佐助万花筒素材
│ └── you.jpg # 宇智波鼬写轮眼素材
├── Customer Profile/ # 客户专属档案数据库（运行时自动生成）
│ └── 某某顾客/ # 顾客独立文件夹
│ ├── face_feature.npy # 人脸特征向量文件
│ ├── history.json # history 历史记录清单
│ └── *.png # 历史保存的高清带水印效果图
└── README.md # 项目说明文档
四、项目设计与开发过程中遇到的问题及解决方案
1. 虹膜贴合时的抖动与“塑料感”问题
问题描述：早期使用简单的固定坐标贴图时，由于视频流中人脸有微小的晃动，美瞳图案会出现严重的闪烁和抖动；且贴图边缘生硬，缺乏真实眼球的通透感和水光感。
解决方案：
引入时序加权平滑算法，对每一帧捕获的虹膜坐标进行缓冲与加权平均，过滤掉高频抖动。
采用余弦径向边缘渐变与动态高斯模糊算法，使美瞳边缘与真实眼球自然融合，呈现出逼真的通透高光。
2. 多源图像与异形素材兼容性问题
问题描述：商家在批量导入本地图片文件夹时，图片后缀格式各异（如大写的 .JPG、.PNG，或者现代网络常见的 .webp格式），导致部分素材无法被正确识别和加载。
解决方案：
重构了图像加载与文件扫描逻辑，支持不区分大小写的多种常见图像格式后缀匹配。
针对 .webp 格式引入了专属解码适配，确保任何外部素材拖入或文件夹批量导入时都能稳定解析。
3. 眨眼与半眯眼时的“眼皮穿帮”问题（眼皮覆盖遮挡）
问题描述：在早期版本中，美瞳图案仅根据瞳孔中心进行圆形贴图。当顾客闭眼、眨眼或者正常眨动眼睑时，上下眼睑无法遮挡美瞳，导致美瞳图案直接“透视”盖在眼皮上方，出现严重的穿帮和违和感。
解决方案：
提取 MediaPipe 提供的上下眼睑轮廓关键点（左眼 16 个特征点、右眼 16 个特征点）。
在每一帧渲染时，利用 `cv2.fillPoly` 动态生成当前帧的**眼睑遮挡掩膜 (Eyelid Mask)**。
在将美瞳纹理贴合到眼球前，先与该眼睑掩膜进行像素级相乘。当顾客眨眼或闭眼时，眼皮区域的Alpha通道自动归零，完美实现了“眼皮盖住美瞳”的真实物理遮挡效果。
4. 老顾客无感识别与隐私安全平衡
问题描述：系统需要自动识别老顾客并调取其历史喜好，但又不能让顾客每次都手动登录或录入繁琐的个人信息。
解决方案：
采用 Face Embedding（人脸特征向量）** 技术，在试戴时自动提取并比对本地数据库中的低维特征矩阵，实现“无感静默识别”。
针对客户档案数据库引入了**独立文件夹加密机制**（访问管理密码 `123456`），严格保护消费者个人隐私数据不被泄露。
5. 依赖库与模型文件打包后丢失（PyInstaller 报错）
问题描述：在本地开发环境运行一切正常，但通过 PyInstaller 打包成独立 `.exe` 可执行程序后，双击运行常出现找不到 MediaPipe 内部模型文件或软件 Logo 图片崩溃的现象。
解决方案：
在打包命令中显式添加 `--add-data "pictures;pictures"` 将本地静态资源目录整体嵌入。
使用 `--collect-all mediapipe` 参数，确保深度学习框架底层依赖的动态链接库与模型被完整收集进最终的可执行文件中。
- 安装 Python 3.10 * 访问 Python 官方网站或通过包管理器下载并安装 Python 3.10 版本。 * 安装时请勾选 "Add Python to PATH"（将 Python 添加到系统环境变量），以便在终端中直接使用
python和pip命令。
本项目依赖于计算机视觉、图形界面及矩阵运算等第三方库。在激活虚拟环境后，执行以下 pip 安装命令：
Bash
pip install opencv-python mediapipe PyQt5 numpy
- 版本说明：
opencv-python：用于处理摄像头视频流、矩阵变换以及图层混合。mediapipe：提供高精度的 Face Mesh（人脸面部网格）及虹膜检测模型。PyQt5：构建整体深色科技感图形交互界面。numpy：负责底层数学计算、特征向量（Embedding）矩阵距离计算及多维数组处理。
