人脸识别系统 (Face Recognition System)

English Version Below

📑 关于本项目 (About)

欢迎查看本项目！这是一个基于 Python 的人脸识别 C/S 系统开源项目。如果你的需求是搭建一套能够运行人脸检测、特征提取、特征入库与身份匹配的人脸识别系统，你可以直接 Fork 或是 Clone 本仓库进行调用与二次开发。

本项目主要具备以下特性：

• 核心算法：集成 YOLOv5-face 进行高精度人脸特征定位，同时结合传统/深度特征提取方法捕获人脸特征信息。
• 数据交互：使用轻量级的 SQLite 数据库完成特征和身份信息的数据读写、更新及管理。
• 客户端交互：通过 PyQt5 提供可交互的前端界面，支持班级照片的批量入库、单张照片验证及合照多人同时识别。
• 开发模式：开发过程中引入了 Vibecoding（AI 辅助编程）快速完成工程界面的搭建，同时保留了对系统架构与核心算法流程的精细人工设计与打磨。

⚠️ 隐私声明： 出于隐私保护，本开源仓库不包含任何真实的班级人员数据和预训练大模型权重。你可以非常方便地使用自己的测试照片来运行系统库。

🚀 如何开始 (Getting Started)

1. 克隆/Fork 仓库

你可以 Fork 这个仓库到你的 GitHub，或者直接将其 Clone 到本地：

git clone https://github.com/plumqm/face-recognition.git
cd face-recognition

2. 安装依赖

运行本项目需要一些基础的机器视觉和机器学习库，请确保你已经安装了所需环境（推荐使用虚拟环境）：

pip install opencv-python face_recognition dlib PyQt5 numpy

3. 如何使用你自己的照片运行代码

为了方便大家直接调用而不需要去满篇找代码修改真实路径，本项目已将照片读取路径提取为环境变量。你不需要修改任何源代码，只需在运行代码前设置以下环境变量即可：

• PHOTO_DIR：存放所有人脸照片的目录路径（通常用于批量录入、训练库或比对）。
• TEST_IMAGE_PATH：单张测试照片的具体路径（用于运行单张测试脚本）。

平台设置示例

Windows (PowerShell):

# 设置环境变量
$env:PHOTO_DIR="D:\your\custom\photos\dir"
$env:TEST_IMAGE_PATH="D:\your\custom\test.jpg"

# 运行你的目标脚本，例如：
python project/1/set_table.py

Windows (CMD):

set PHOTO_DIR=D:\your\custom\photos\dir
set TEST_IMAGE_PATH=D:\your\custom\test.jpg
python project/1/set_table.py

Linux / macOS:

export PHOTO_DIR="/path/to/your/photos"
export TEST_IMAGE_PATH="/path/to/your/test.jpg"
python project/1/set_table.py

4. 项目结构简介

• project/1, project/2, project/3, project/4 等目录包含了项目的不同阶段和不同变体的代码。
• 核心代码通常包含：数据库初始化 (set_table.py)、特征提取 (计算特征值并存入数据库.py)、前台界面测试等。具体可进入项目子文件查看。

---

English Version

📑 About This Project

Welcome to this project! This is an open-source Python-based Face Recognition Client/Server (C/S) system. The core workflow covers face detection, feature extraction, database feature enrollment, and identity matching. If you are looking to build and deploy a facial recognition system, you can easily Fork or Clone this repository for direct usage or secondary customization.

Key project features include:

• Core Algorithms: Integrates YOLOv5-face for high-precision face detection and utilizes traditional/deep learning feature extraction routines.
• Data Management: Employs lightweight SQLite to handle database operations for facial features and individual identities.
• Interactive UI: Provides a graphical client interface built with PyQt5, supporting batch photo enrollment, single image recognition, and group photo multi-face recognition.
• Development Paradigm: Built utilizing Vibecoding (AI-assisted programming) to rapidly scaffold UI and repetitive codebase elements, while the core architecture and algorithmic pipelines are carefully hand-crafted and optimized.

⚠️ Privacy Disclaimer: For privacy reasons, this open-source repository does not contain any real class photo datasets or specific pre-trained bulk weight models. You can seamlessly plug in your own image datasets to safely run and test the code (see usage instructions below).

🚀 Getting Started

1. Clone / Fork the Repository

You can Fork this repository to your own GitHub account or simply clone it to your local machine:

git clone https://github.com/plumqm/face-recognition.git
cd face-recognition

2. Install Dependencies

This project requires foundational computer vision libraries. Please ensure your environment is set up (virtual environments are recommended):

pip install opencv-python face_recognition dlib PyQt5 numpy

3. How to Run the Code with Your Own Photos

To make it entirely plug-and-play without the need to modify source code to change hardcoded paths, this project uses Environment Variables for I/O paths. You do not need to modify the Python files.

Simply set the following environment variables before running the scripts:

• PHOTO_DIR: The directory containing the face photos (used for bulk enrollment/training).
• TEST_IMAGE_PATH: The exact file path to a single test photo (used generally for single-image test scripts).

Examples by Platform

Windows (PowerShell):

# Set Environment Variables
$env:PHOTO_DIR="C:\path\to\your\photos\dir"
$env:TEST_IMAGE_PATH="C:\path\to\your\test.jpg"

# Run your target script, e.g.:
python project/1/set_table.py

Windows (CMD):

set PHOTO_DIR=C:\path\to\your\photos\dir
set TEST_IMAGE_PATH=C:\path\to\your\test.jpg
python project/1/set_table.py

Linux / macOS:

export PHOTO_DIR="/path/to/your/photos"
export TEST_IMAGE_PATH="/path/to/your/test.jpg"
python project/1/set_table.py

4. Project Structure Overview

• Directories like project/1, project/2, project/3, and project/4 contain scripts from different stages and variants of the system.
• Key scripts typically involve database initialization (set_table.py), feature extraction to database (计算特征值并存入数据库.py), and UI tests. Feel free to explore specific subfolders based on your requirements.