# dlib

**Repository Path**: feifeishuaiguo/dlib

## Basic Information

- **Project Name**: dlib
- **Description**: A toolkit for making real world machine learning and data analysis applications in C++
- **Primary Language**: Unknown
- **License**: BSL-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 340
- **Created**: 2026-05-16
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI美颜滤镜系统

基于InsightFace buffalo_s模型的离线实时视频人像美颜系统，支持磨皮、美白、瘦脸、大眼等功能，提供左右分栏对比的Web视频流服务。

## 功能特性

- **皮肤磨皮**: 基于高斯模糊+蒙版限制，仅作用于皮肤区域，保留五官细节
- **美白提亮**: YCrCb色彩空间调整，冷白皮优化，提升通透感
- **瘦脸**: 基于关键点的局部径向收缩，保护嘴巴区域不变形
- **大眼**: 眼部区域放大，自然不夸张
- **柔光质感**: 增加柔和光泽，提升面部干净度
- **预设方案**: 4套预设（素颜/自然/清新/精致），梯度差异明显
- **左右对比**: Web页面左右分栏显示原图和美颜效果

## 技术栈

- **语言**: Python 3.10+
- **人脸检测**: InsightFace buffalo_s
- **图像处理**: OpenCV 4.x
- **Web服务**: FastAPI + Uvicorn
- **视频流**: MJPEG实时推送

## 项目结构

```
beauty_filter/
├── ai_beauty_engine.py      # AI美颜引擎（人脸检测、蒙版生成、美颜算法）
├── ai_beauty_server.py      # FastAPI服务器（参数配置API、预设切换）
├── web_video_server.py      # Web视频流对比服务（左右分栏对比）
├── dlib_beauty_engine.py    # dlib人脸检测引擎（备用方案）
├── beauty_demo.py           # 图片美颜演示脚本
├── video_beauty_server.py   # 视频美颜服务脚本
├── video_beauty_demo.py     # 视频美颜演示脚本
├── ai_server.py             # AI参数控制服务脚本
├── config.json              # 美颜参数配置文件
├── code/                    # C++源代码（备用方案）
│   ├── CMakeLists.txt
│   ├── include/
│   └── src/
├── models/                  # InsightFace模型文件
│   ├── buffalo_s/
│   └── buffalo_l/
└── docs/                    # 项目文档
    ├── designed.md          # 项目设计文档
    ├── devlog.md            # 开发日志
    ├── perf.md              # 性能优化报告
    └── ai_usage.md          # AI使用说明
```

## 依赖安装

```bash
pip install opencv-python numpy insightface fastapi uvicorn pydantic
```

## 快速开始

### 启动服务

```bash
cd /home/ubt/practice/dlib/beauty_filter
python web_video_server.py "视频文件路径.mp4" 8979
```

### 访问方式

- **对比视频页面**: http://192.168.108.128:8979/compare
- **仅美颜视频**: http://192.168.108.128:8979/bgr
- **健康检查**: http://192.168.108.128:8979/health

### 使用摄像头

```bash
python web_video_server.py "camera" 8979
```

## API接口

### 获取配置
```bash
curl http://192.168.108.128:8979/config
```

### 设置参数
```bash
curl -X POST http://192.168.108.128:8979/config \
    -H "Content-Type: application/json" \
    -d '{
        "whitening_strength": 0.70,
        "smoothing_strength": 0.75,
        "slim_amount_ratio": 0.20,
        "eye_scale": 1.18
    }'
```

### 切换预设
```bash
curl -X POST http://192.168.108.128:8979/preset/精致
```

### 自然语言调参
```bash
curl -X POST http://192.168.108.128:8979/chat \
    -H "Content-Type: application/json" \
    -d '{"query": "美白强一点"}'
```

## 预设方案

| 预设 | 磨皮强度 | 美白强度 | 瘦脸比例 | 大眼比例 |
|------|---------|---------|---------|---------|
| 素颜 | 0.15 | 0.15 | 0.02 | 1.02 |
| 自然 | 0.40 | 0.35 | 0.10 | 1.08 |
| 清新 | 0.55 | 0.50 | 0.14 | 1.12 |
| 精致 | 0.75 | 0.70 | 0.20 | 1.18 |

## 性能指标

| 指标 | 数值 |
|------|------|
| 帧率 | 52.6fps |
| 延迟 | 19ms |
| 人脸检测间隔 | 30帧 |
| 处理分辨率 | 480px |

## 开发说明

### 核心算法流程

1. **人脸检测**: 使用InsightFace buffalo_s检测人脸并提取5个关键点
2. **蒙版生成**: 基于关键点构建椭圆蒙版，仅覆盖皮肤区域
3. **磨皮**: 高斯模糊+蒙版限制，保留五官边缘
4. **美白**: YCrCb色彩空间调整，提升亮度、降低黄色
5. **瘦脸**: cv2.remap实现局部径向收缩
6. **大眼**: cv2.remap实现眼部区域放大
7. **融合**: 标准Alpha混合公式，确保自然过渡

### 缓存机制

- 人脸检测结果缓存：每30帧重新检测
- 蒙版缓存：仅在人脸位置变化或配置变更时重新生成
- 配置哈希缓存：避免重复计算

### 异常保护

- 每个子模块独立try-except
- 异常情况下直接返回原始帧
- 蒙版面积异常时返回原图

## 许可证

MIT License