Folders and files
A lightweight face recognition module based on OpenCV LBPH (Local Binary Patterns Histograms).
Use it via the interactive CLI or embed it directly as a Python API in your own project.
- Register faces from camera or image files / folders
- Train the LBPH recognition model
- Detect & recognize faces real-time from camera or from image files
- Manage registered users (list, delete)
- Clean Python API — one class, zero boilerplate
- Customizable window titles via app_name
- Python 3.10+
- opencv-contrib-python >= 4.8.0
- numpy >= 1.24.0
pip install facerecog-lbphgit clone https://github.com/AlulCode45/FaceRecon-Module.git
cd FaceRecon-Module
pip install -r requirements.txtImportant: Use opencv-contrib-python, not opencv-python.
The cv2.face.LBPHFaceRecognizer module is only available in the contrib build.
When you use this module, it will automatically create the following in your working directory:
your-project/ ├── facerecog/ ← this repo (if using from source) │ ├── facerecog/ ← the Python package │ ├── example.py ← standalone CLI demo │ ├── pyproject.toml │ └── README.md ├── dataset/ ← auto created: face photos per person ├── trainer/ ← auto created: trained model output └── labels.json ← auto created: ID → name mapping
Run the built-in CLI demo:
python example.pyMenu:
==============================================
FACE RECOGNITION SYSTEM
==============================================
[1] Register — Register face via camera
[2] Train — Train the model
[3] Detect — Real-time face detection
[4] List — List registered users
[5] Delete — Delete a user
[6] Detect — Detect face from image
[7] Register — Register face from image
[0] Exit
==============================================
[1] or [7] Register → [2] Train → [3] or [6] Detect
from facerecog import FaceRecog
fr = FaceRecog()fr = FaceRecog(
threshold=75, # LBPH confidence: lower = stricter match (default 75)
max_photos=40, # photos captured per camera session (default 40)
camera_index=0, # camera device index (default 0)
app_name="My App", # label in OpenCV window titles (default "Face Recognition")
)Via camera:
saved = fr.register_from_camera("Alice")
print(f"{saved} photos saved")Via single image file:
saved = fr.register_from_image("Alice", "/path/to/alice.jpg")Via folder containing multiple images:
saved = fr.register_from_image("Alice", "/path/to/alice_photos/")Supported formats: .jpg, .jpeg, .png, .bmp, .webp
Overwrite / append:
# Replace existing data
fr.register_from_image("Alice", "/photos/", overwrite=True)
# Add to existing data (default)
fr.register_from_image("Alice", "/photos/", append=True)info = fr.train()
print(info)
# {"total_images": 80, "total_persons": 2, "model_path": "trainer/trainer.yml"}Must be re-run whenever faces are added or deleted.
Real-time from camera:
fr.detect_camera()
# Close with q, Esc, or click X on the windowFrom image file (with result window):
result = fr.detect_image("photo.jpg", show=True)From image file (data only, no window):
result = fr.detect_image("photo.jpg", show=False)
print(f"Faces found: {result.total_faces}")
for face in result.faces:
print(face.name) # person name / "Unknown"
print(face.recognized) # True / False
print(face.score) # confidence percentage (0–100)
print(face.confidence) # raw LBPH value (lower = more confident)
print(face.x, face.y, face.w, face.h) # bounding boxCheck if a face is recognized:
result = fr.detect_image("photo.jpg", show=False)
for face in result.faces:
if face.recognized:
print(f"Recognized: {face.name} ({face.score}%)")
else:
print("Unknown face")List all users:
users = fr.list_users()
for u in users:
print(u["id"], u["name"], u["photos"])
# 1 Alice 40
# 2 Bob 35Delete a user:
info = fr.delete_user("Alice")
print(info)
# {"id": 1, "name": "Alice", "photos_deleted": 40}After deleting, call fr.train() again to update the model.
print(fr)
# FaceRecog(app_name='Face Recognition', users=2, threshold=75, max_photos=40)from facerecog import FaceRecog
fr = FaceRecog(threshold=70, app_name="Security System")
# 1. Register people from photo folders
fr.register_from_image("Alice", "./photos/alice/")
fr.register_from_image("Bob", "./photos/bob/")
# 2. Train the model
info = fr.train()
print(f"Done: {info['total_images']} images, {info['total_persons']} people")
# 3. Detect faces in a group photo
result = fr.detect_image("group.jpg", show=True)
for face in result.faces:
status = f"{face.name} ({face.score}%)" if face.recognized else "Unknown"
print(f"Face at ({face.x},{face.y}): {status}")
# 4. Real-time detection
fr.detect_camera()- dataset/, trainer/, and labels.json are created in your current working directory — not inside the module folder.
- More training photos = better accuracy.
- If the camera is not detected, try camera_index=1 or camera_index=2.
- Use clear, well-lit, front-facing photos for best results.
- The app_name parameter sets the title of all OpenCV windows — useful when integrating into a larger app.
MIT