edgeface-knn 2.0.0__tar.gz

edgeface_knn-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saksham Bajaj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgeface_knn-2.0.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: edgeface-knn
+Version: 2.0.0
+Summary: Real-time CPU face recognition pipeline using classical ML, refactored from an embedded Raspberry Pi deployment into an installable modular package.
+Author: Saksham Bajaj
+License: MIT
+Project-URL: Homepage, https://github.com/SakshamBjj/edge-face-recognition-v2
+Project-URL: Source, https://github.com/SakshamBjj/edge-face-recognition-v2
+Project-URL: Tracker, https://github.com/SakshamBjj/edge-face-recognition-v2/issues
+Keywords: face recognition,computer vision,opencv,edge ml,classical machine learning
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.5
+Requires-Dist: numpy>=1.21
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: pyyaml>=5.4
+Dynamic: license-file
+
+# Edge Face Recognition (CPU-Only)
+
+> ⚠️ Repository name contains `v2` to indicate the refactored codebase.  
+> The installable Python package remains `edge-face-recognition` (no v2) to preserve upgrade compatibility.
+
+Real-time face recognition designed for CPU-only environments — laptops, embedded systems, and Raspberry-Pi-class devices.
+
+Classical computer vision pipeline (Haar Cascade + KNN) engineered for deterministic low-latency inference without GPUs or deep learning frameworks.
+
+**Latency:** ~40 ms per processed frame
+**Effective throughput:** ~15 FPS (frame-skipped real-time UX)
+
+> Originally built as a Raspberry Pi prototype (Sept 2024).
+> Refactored into a modular installable Python package (Dec 2025).
+
+---
+
+## What this project is
+
+A lightweight identity recognition system intended for:
+
+* Attendance systems
+* Lab / hostel / office access logging
+* Offline environments
+* Edge devices with no GPU
+* Privacy-sensitive deployments (no cloud inference)
+
+The system prioritizes **correct identification over aggressive guessing** — unknown faces are rejected instead of force-matched.
+
+---
+
+## Installation
+
+> ⚠️ **WSL note:**
+> The project can be developed and packaged inside WSL, but webcam capture must be run using native Windows Python.
+> WSL does not expose camera devices to OpenCV.
+
+---
+
+### Option A — Development setup (WSL recommended)
+
+Use this if you are modifying code or building the package.
+
+```bash
+git clone https://github.com/SakshamBjj/edge-face-recognition-v2.git
+cd edge-face-recognition-v2
+pip install -e .
+```
+
+Verify CLI:
+
+```bash
+edge-face --help
+```
+
+---
+
+### Option B — Usage setup (Windows / native OS)
+
+For actual face collection and recognition:
+
+```bash
+pip install edgeface-knn
+```
+
+---
+
+## Running the Application
+
+> Run the following commands from **Windows terminal (PowerShell / CMD)**, not WSL.
+
+---
+
+### 1) Register people
+
+```bash
+edge-face collect --name Alice
+edge-face collect --name Bob
+```
+
+Captures 100 samples per person via webcam automatically.
+
+---
+
+### 2) Run recognition
+
+```bash
+edge-face run
+```
+
+Controls:
+
+| Key | Action         |
+| --- | -------------- |
+| `o` | Log attendance |
+| `q` | Quit           |
+
+Logs saved to:
+
+```
+attendance/YYYY-MM-DD.csv
+```
+
+---
+
+### 3) Optional configuration
+
+Override default parameters:
+
+```bash
+edge-face run --config configs/my_config.yaml
+```
+
+---
+
+## Why this split exists
+
+WSL is a virtualized Linux environment and does not provide direct access to webcam hardware.
+The package itself is OS-independent, but real-time capture requires native OS execution.
+
+Typical workflow:
+
+| Task                    | Environment |
+| ----------------------- | ----------- |
+| Development / packaging | WSL         |
+| Face collection         | Windows     |
+| Real-time recognition   | Windows     |
+
+---
+
+## Runtime Pipeline
+
+```
+Camera (30 FPS)
+ → Grayscale conversion
+ → Haar Cascade detection (~20 ms)
+ → Crop + resize (50×50)
+ → Flatten vector
+ → KNN classification (~15 ms)
+ → Confidence scoring
+ → Unknown rejection
+ → Overlay + logging
+```
+
+Frame skipping processes every 2nd frame to maintain smooth real-time UX.
+
+---
+
+## Unknown Face Handling
+
+The system favors **precision over recall**.
+
+Instead of always predicting a nearest neighbor:
+
+| Confidence  | Result            |
+| ----------- | ----------------- |
+| ≥ threshold | Person identified |
+| < threshold | Marked “Unknown”  |
+
+Prevents the most serious failure in face recognition systems: logging the wrong person.
+
+---
+
+## Why Classical ML instead of Deep Learning?
+
+| Factor        | This Project (KNN)  | CNN Face Recognition |
+| ------------- | ------------------- | -------------------- |
+| Model size    | <1 MB               | ~90 MB               |
+| CPU inference | ~40 ms              | ~300 ms              |
+| GPU required  | No                  | Yes                  |
+| Training data | ~100 samples/person | 1000+ samples/person |
+
+**Design goal:** predictable latency on CPU hardware
+—not maximum accuracy on servers.
+
+Deep learning was prototyped but exceeded real-time limits without GPU acceleration.
+
+---
+
+## Performance
+
+### Accuracy (typical indoor lighting)
+
+| Condition    | Accuracy |
+| ------------ | -------- |
+| Frontal face | ~95%     |
+| Glasses      | ~90%     |
+| Mask         | ~75%     |
+| ±30° angle   | ~70%     |
+
+### Latency
+
+| Stage          | Time       |
+| -------------- | ---------- |
+| Detection      | 20 ms      |
+| Preprocess     | 5 ms       |
+| Classification | 15 ms      |
+| **Total**      | **~40 ms** |
+
+---
+
+## Known Limitations
+
+1. Low lighting reduces detection reliability
+2. Side profiles (>30°) often not detected
+3. Performance degrades beyond ~100 identities (KNN O(n))
+4. Not spoof-proof (photo attacks possible)
+
+---
+
+## Package Layout
+
+```
+edge-face-recognition-v2/
+├── configs/default.yaml
+├── src/edge_face/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── config.py
+│   ├── detector.py
+│   ├── dataset.py
+│   ├── model.py
+│   └── pipeline.py
+├── scripts/collect_faces.py
+├── data/              (generated)
+└── attendance/        (generated)
+```
+
+---
+
+## Engineering Tradeoffs
+
+| Decision          | Reason                         | Cost                        |
+| ----------------- | ------------------------------ | --------------------------- |
+| Haar Cascade      | 20 ms detection                | Angle robustness            |
+| Raw pixels        | No feature extraction overhead | Less compact representation |
+| KNN               | No training step               | Scaling limits              |
+| Frame skipping    | Real-time UX                   | Slight temporal jitter      |
+| Unknown rejection | Avoid false positives          | Occasional false negatives  |
+
+---
+
+## Project Evolution
+
+| Version | Focus                                 |
+| ------- | ------------------------------------- |
+| v1      | Embedded Raspberry Pi prototype       |
+| v2      | Installable reusable software package |
+
+Archived prototype available in repository history.
+
+---
+
+## What this demonstrates
+
+* Designing ML systems under hardware constraints
+* Latency-driven model selection
+* Converting prototype code into a distributable tool
+* Building CLI-driven reproducible workflows
+
+---
+
+## References
+
+* Viola-Jones Face Detection
+* OpenCV face recognition documentation
+* scikit-learn KNN implementation
+
+---
+
+**Author:** Saksham Bajaj
+**License:** MIT

edgeface_knn-2.0.0/README.md

@@ -0,0 +1,272 @@
+# Edge Face Recognition (CPU-Only)
+
+> ⚠️ Repository name contains `v2` to indicate the refactored codebase.  
+> The installable Python package remains `edge-face-recognition` (no v2) to preserve upgrade compatibility.
+
+Real-time face recognition designed for CPU-only environments — laptops, embedded systems, and Raspberry-Pi-class devices.
+
+Classical computer vision pipeline (Haar Cascade + KNN) engineered for deterministic low-latency inference without GPUs or deep learning frameworks.
+
+**Latency:** ~40 ms per processed frame
+**Effective throughput:** ~15 FPS (frame-skipped real-time UX)
+
+> Originally built as a Raspberry Pi prototype (Sept 2024).
+> Refactored into a modular installable Python package (Dec 2025).
+
+---
+
+## What this project is
+
+A lightweight identity recognition system intended for:
+
+* Attendance systems
+* Lab / hostel / office access logging
+* Offline environments
+* Edge devices with no GPU
+* Privacy-sensitive deployments (no cloud inference)
+
+The system prioritizes **correct identification over aggressive guessing** — unknown faces are rejected instead of force-matched.
+
+---
+
+## Installation
+
+> ⚠️ **WSL note:**
+> The project can be developed and packaged inside WSL, but webcam capture must be run using native Windows Python.
+> WSL does not expose camera devices to OpenCV.
+
+---
+
+### Option A — Development setup (WSL recommended)
+
+Use this if you are modifying code or building the package.
+
+```bash
+git clone https://github.com/SakshamBjj/edge-face-recognition-v2.git
+cd edge-face-recognition-v2
+pip install -e .
+```
+
+Verify CLI:
+
+```bash
+edge-face --help
+```
+
+---
+
+### Option B — Usage setup (Windows / native OS)
+
+For actual face collection and recognition:
+
+```bash
+pip install edgeface-knn
+```
+
+---
+
+## Running the Application
+
+> Run the following commands from **Windows terminal (PowerShell / CMD)**, not WSL.
+
+---
+
+### 1) Register people
+
+```bash
+edge-face collect --name Alice
+edge-face collect --name Bob
+```
+
+Captures 100 samples per person via webcam automatically.
+
+---
+
+### 2) Run recognition
+
+```bash
+edge-face run
+```
+
+Controls:
+
+| Key | Action         |
+| --- | -------------- |
+| `o` | Log attendance |
+| `q` | Quit           |
+
+Logs saved to:
+
+```
+attendance/YYYY-MM-DD.csv
+```
+
+---
+
+### 3) Optional configuration
+
+Override default parameters:
+
+```bash
+edge-face run --config configs/my_config.yaml
+```
+
+---
+
+## Why this split exists
+
+WSL is a virtualized Linux environment and does not provide direct access to webcam hardware.
+The package itself is OS-independent, but real-time capture requires native OS execution.
+
+Typical workflow:
+
+| Task                    | Environment |
+| ----------------------- | ----------- |
+| Development / packaging | WSL         |
+| Face collection         | Windows     |
+| Real-time recognition   | Windows     |
+
+---
+
+## Runtime Pipeline
+
+```
+Camera (30 FPS)
+ → Grayscale conversion
+ → Haar Cascade detection (~20 ms)
+ → Crop + resize (50×50)
+ → Flatten vector
+ → KNN classification (~15 ms)
+ → Confidence scoring
+ → Unknown rejection
+ → Overlay + logging
+```
+
+Frame skipping processes every 2nd frame to maintain smooth real-time UX.
+
+---
+
+## Unknown Face Handling
+
+The system favors **precision over recall**.
+
+Instead of always predicting a nearest neighbor:
+
+| Confidence  | Result            |
+| ----------- | ----------------- |
+| ≥ threshold | Person identified |
+| < threshold | Marked “Unknown”  |
+
+Prevents the most serious failure in face recognition systems: logging the wrong person.
+
+---
+
+## Why Classical ML instead of Deep Learning?
+
+| Factor        | This Project (KNN)  | CNN Face Recognition |
+| ------------- | ------------------- | -------------------- |
+| Model size    | <1 MB               | ~90 MB               |
+| CPU inference | ~40 ms              | ~300 ms              |
+| GPU required  | No                  | Yes                  |
+| Training data | ~100 samples/person | 1000+ samples/person |
+
+**Design goal:** predictable latency on CPU hardware
+—not maximum accuracy on servers.
+
+Deep learning was prototyped but exceeded real-time limits without GPU acceleration.
+
+---
+
+## Performance
+
+### Accuracy (typical indoor lighting)
+
+| Condition    | Accuracy |
+| ------------ | -------- |
+| Frontal face | ~95%     |
+| Glasses      | ~90%     |
+| Mask         | ~75%     |
+| ±30° angle   | ~70%     |
+
+### Latency
+
+| Stage          | Time       |
+| -------------- | ---------- |
+| Detection      | 20 ms      |
+| Preprocess     | 5 ms       |
+| Classification | 15 ms      |
+| **Total**      | **~40 ms** |
+
+---
+
+## Known Limitations
+
+1. Low lighting reduces detection reliability
+2. Side profiles (>30°) often not detected
+3. Performance degrades beyond ~100 identities (KNN O(n))
+4. Not spoof-proof (photo attacks possible)
+
+---
+
+## Package Layout
+
+```
+edge-face-recognition-v2/
+├── configs/default.yaml
+├── src/edge_face/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── config.py
+│   ├── detector.py
+│   ├── dataset.py
+│   ├── model.py
+│   └── pipeline.py
+├── scripts/collect_faces.py
+├── data/              (generated)
+└── attendance/        (generated)
+```
+
+---
+
+## Engineering Tradeoffs
+
+| Decision          | Reason                         | Cost                        |
+| ----------------- | ------------------------------ | --------------------------- |
+| Haar Cascade      | 20 ms detection                | Angle robustness            |
+| Raw pixels        | No feature extraction overhead | Less compact representation |
+| KNN               | No training step               | Scaling limits              |
+| Frame skipping    | Real-time UX                   | Slight temporal jitter      |
+| Unknown rejection | Avoid false positives          | Occasional false negatives  |
+
+---
+
+## Project Evolution
+
+| Version | Focus                                 |
+| ------- | ------------------------------------- |
+| v1      | Embedded Raspberry Pi prototype       |
+| v2      | Installable reusable software package |
+
+Archived prototype available in repository history.
+
+---
+
+## What this demonstrates
+
+* Designing ML systems under hardware constraints
+* Latency-driven model selection
+* Converting prototype code into a distributable tool
+* Building CLI-driven reproducible workflows
+
+---
+
+## References
+
+* Viola-Jones Face Detection
+* OpenCV face recognition documentation
+* scikit-learn KNN implementation
+
+---
+
+**Author:** Saksham Bajaj
+**License:** MIT

edgeface_knn-2.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "edgeface-knn"
+version = "2.0.0"
+description = "Real-time CPU face recognition pipeline using classical ML, refactored from an embedded Raspberry Pi deployment into an installable modular package."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+
+authors = [{name = "Saksham Bajaj"}]
+
+keywords = ["face recognition", "computer vision", "opencv", "edge ml", "classical machine learning"]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+
+dependencies = [
+    "opencv-python>=4.5",
+    "numpy>=1.21",
+    "scikit-learn>=1.0",
+    "pyyaml>=5.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/SakshamBjj/edge-face-recognition-v2"
+Source = "https://github.com/SakshamBjj/edge-face-recognition-v2"
+Tracker = "https://github.com/SakshamBjj/edge-face-recognition-v2/issues"
+
+[project.scripts]
+edge-face = "edge_face.cli:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

edgeface_knn-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

edgeface_knn-2.0.0/src/edge_face/__init__.py

@@ -0,0 +1 @@
+"""edge_face — CPU-only real-time face recognition."""