# face-recognition

**Repository Path**: lotee/face-recognition

## Basic Information

- **Project Name**: face-recognition
- **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-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# 人脸识别系统 (Face Recognition System)

[English Version Below](#english-version)

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

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

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

## 🚀 如何开始 (Getting Started)

### 1. 克隆/Fork 仓库
你可以 Fork 这个仓库到你的 GitHub，或者直接将其 Clone 到本地：
```bash
git clone https://github.com/plumqm/face-recognition.git
cd face-recognition
```

### 2. 安装依赖
运行本项目需要一些基础的机器视觉和机器学习库，请确保你已经安装了所需环境（推荐使用虚拟环境）：
```bash
pip install opencv-python face_recognition dlib PyQt5 numpy
```

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

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

#### 平台设置示例

**Windows (PowerShell):**
```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):**
```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:**
```bash
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`)、前台界面测试等。具体可进入项目子文件查看。

---
<br>

<a name="english-version"></a>
# 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:
```bash
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):
```bash
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):**
```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):**
```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:**
```bash
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.