# DLMask

**Repository Path**: DragonCodingPlus/dlmask

## Basic Information

- **Project Name**: DLMask
- **Description**: 视频处理，为人物添加面部马赛克。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-06
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DLMask — 视频人脸马赛克

基于 YOLOv8 的桌面端视频人脸马赛克工具。选择视频后自动检测其中所有人脸，支持自定义马赛克粒度，可实时预览效果并导出处理后的视频。

## 功能

- **自动人脸检测** — 基于 Ultralytics YOLOv8m 模型，自动识别视频每一帧中的人脸
- **实时预览播放** — 边播边检测，跳帧优化保持 30fps 流畅度
- **马赛克粒度调节** — 支持 4～40px 马赛克网格大小，实时调整
- **多视角追踪** — 基于 IoU + 质心距离 + 速度预测的多帧人脸追踪，支持人脸离开后重入识别
- **GPU 加速** — 自动利用 Apple Silicon MPS（Metal Performance Shaders）加速推理
- **运动补偿** — 检测阶段使用质心-速度预测模型，减少相邻帧之间的 bbox 抖动
- **跨平台打包** — 支持 macOS (.app) 和 Windows (.exe) 独立可执行文件

## 效果预览

```
  ┌─────────────────────────────────────┐
  │  📁 选择视频   my_video.mp4         │
  ├─────────────────────────────────────┤
  │                                     │
  │      ┌───────────────────┐          │
  │      │                   │          │
  │      │   视频预览区域      │          │
  │      │                   │          │
  │      │   ████████████    │          │
  │      │   ██ 马赛克 ██    │          │
  │      │   ████████████    │          │
  │      └───────────────────┘          │
  │  ◀═══ SeekBar ═══════════▶          │
  │  ▶ 播放   00:42 / 03:15             │
  ├─────────────────────────────────────┤
  │  马赛克: ──■── 16px    ⚡ 导出视频   │
  │  [░░░░░░░░░░░░░░░] 45%              │
  └─────────────────────────────────────┘
```

## 快速开始

### 环境要求

- Python 3.10+
- macOS 13+（Apple Silicon 或 Intel）或 Windows 10+
- 安装以下系统依赖（仅 Windows 需要额外步骤；macOS 通常无需额外操作）

### 安装

```bash
# 克隆仓库
git clone <repo-url>
cd DLMask

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate   # macOS
# venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

### 运行

```bash
python3 main.py
```

首次运行时，程序会自动从镜像下载人脸检测模型（~50MB）到 `~/.cache/ultralytics/`。下载后模型会被缓存，后续启动无需网络。

模型下载镜像地址：<https://hf-mirror.com/outfly/face_yolov8m>

### 使用流程

1. 启动程序，等待状态栏显示 **"模型就绪"**
2. 点击 **"选择视频"**，选取 MP4 / AVI / MOV / MKV 文件
3. 视频加载后自动开始播放，人脸区域会实时显示蓝色检测框
4. 通过 **马赛克滑块** 调整网格大小（4～40px）
5. 点击 **"导出视频"** 开始处理，进度条显示完成百分比
6. 导出完成后在原文件同目录生成 `*_masked.mp4` 文件

## 项目结构

```
DLMask/
├── main.py                  # 入口，设置 sys.path 后启动 GUI
├── build.py                 # PyInstaller 打包脚本（macOS / Windows）
├── requirements.txt         # Python 依赖
├── runtime_hook_cv2.py      # PyInstaller cv2 运行时钩子
├── README.md
├── src/
│   ├── __init__.py
│   ├── app.py               # GUI 主窗口（CustomTkinter）
│   ├── config.py            # 全局配置常量
│   ├── detector.py          # FaceDetector — YOLO 人脸检测封装
│   ├── mosaic.py            # MosaicEngine — 马赛克绘制引擎
│   ├── tracker.py           # FaceTracker — 多帧人脸追踪
│   └── video_processor.py   # VideoProcessor — 视频读写与处理流水线
└── resources/               # 打包资源（构建时生成）
    └── face_yolov8m.pt
```

### 模块职责

| 模块 | 职责 |
|---|---|
| `app.py` | GUI 主循环：视频选择、播放/暂停、进度条拖动、马赛克调节、导出触发、模型加载覆盖层 |
| `config.py` | 模型路径、检测阈值、马赛克参数、视频编码器、窗口尺寸等全部常量 |
| `detector.py` | 封装 Ultralytics YOLO：加载模型（优先 bundle → 缓存 → 下载）、单帧检测、bbox 绘制 |
| `mosaic.py` | 对指定 bbox 区域执行像素化（缩略图 + 最近邻放大） |
| `tracker.py` | 跨帧人脸匹配：处理阶段用 IoU 匹配，扫描阶段用质心距离 + 速度预测 |
| `video_processor.py` | 逐帧流水线：读取 → 检测 → 马赛克 → 写入，avc1 硬件编码，支持进度回调与取消 |

## 打包（独立可执行文件）

程序使用 PyInstaller 打包为不需要 Python 环境的独立可执行文件。

### macOS

```bash
python3 build.py mac
```

输出：`dist/DLMask.app`（约 1.8 GB，包含模型文件）

### Windows

```bash
python build.py win
```

输出：`dist/DLMask/` 目录（可在其他 Windows 电脑上直接运行）

> **注意**：打包后的程序关闭时会跳过 Python 解释器的 finalization 流程（`os._exit(0)`），以避免 PyInstaller 环境下 tkinter Tcl 回调引发的 SIGSEGV 崩溃。打包应用无持久状态，OS 会正常回收所有资源，不影响使用。

## 技术架构

```
┌─────────────────────────────────────────────────┐
│                    app.py                        │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Toolbar  │  │ Preview  │  │ Bottom Bar    │  │
│  │ 选择视频  │  │ 视频播放   │  │ 马赛克滑块    │  │
│  │ 播放控制  │  │ SeekBar  │  │ 导出按钮+进度  │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│         │            │               │          │
└─────────┼────────────┼───────────────┼──────────┘
          │            │               │
┌─────────┼────────────┼───────────────┼──────────┐
│         ▼            ▼               ▼          │
│  detector.py   video_processor.py               │
│  ┌──────────┐   ┌──────────────────────┐        │
│  │ YOLOv8m  │   │ read→detect→mosaic→  │        │
│  │ + MPS    │   │ write pipeline        │        │
│  └──────────┘   │ + progress_callback   │        │
│        ▲        └──────────────────────┘        │
│        │                 │                      │
│  ┌─────┴─────┐    ┌─────┴──────┐               │
│  │ tracker.py│    │ mosaic.py  │               │
│  │ 跨帧追踪   │    │ 像素化引擎  │               │
│  └───────────┘    └────────────┘               │
└─────────────────────────────────────────────────┘
```

### 性能优化

- **降分辨率检测**：检测前将帧缩放到 640px 宽，推理速度提升 3-5 倍，bbox 检测后再映射回原始坐标
- **跳帧检测**：预览播放时每 3 帧执行一次检测，中间帧复用上次检测结果
- **MPS GPU 加速**：Apple Silicon 上自动将模型迁移到 MPS 后端
- **多缓存机制**：马赛克检测结果缓存 + 跳帧计数，避免重复计算

## 依赖

| 包 | 用途 |
|---|---|
| `ultralytics` | YOLOv8 人脸检测模型 |
| `opencv-python` | 视频 I/O、图像处理、编码输出 |
| `customtkinter` | 现代化暗色主题 GUI 控件 |
| `Pillow` | OpenCV ↔ CTkImage 格式转换 |
| `numpy` | 帧数组操作 |

## 常见问题

**Q: 启动后显示"正在加载模型"很长时间？**

A: 首次加载 PyTorch + YOLO 模型需要 5-15 秒（取决于 CPU/GPU），这是正常的本地加载耗时，不是网络下载。模型文件已打包在应用中。

**Q: 导出视频很慢？**

A: 视频导出是逐帧处理，每帧都要执行 YOLO 推理。对于长视频或高分辨率视频，建议先测试短片段。Apple Silicon Mac 上 MPS 加速会显著提升速度。

**Q: 为什么关闭程序时会出现崩溃报告？**

A: 这是 PyInstaller + tkinter 的已知兼容问题。打包版本已通过 `os._exit(0)` 处理，关闭时跳过 Python finalization，由 OS 回收所有资源。如果仍有崩溃报告，请反馈。

## 了解作者

[作者](http://mjlong123.top/)

[DLMask](http://mjlong123.top/products/dlmask)