Add face recognition and motion detection

.gitignore

@@ -0,0 +1,11 @@
+# Snapshots and caches
+snapshots/
+known_faces/encodings.pkl
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Optional: uncomment to avoid committing face photos
+# known_faces/*.jpg
+# known_faces/*.jpeg
+# known_faces/*.png

README.md

@@ -9,4 +9,63 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Smartdoor — Detection, face recognition & motion
+
+Object detection with **YOLOv8n** (person, dog, cat, etc.), optional **face recognition** (e.g. "Danny is at the door"), and **motion-only** mode to save CPU.
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+# Camera
+python main.py
+# With face recognition (add photos in known_faces/ as name.jpg)
+python main.py --known-faces known_faces
+# Only run detection when motion (saves CPU)
+python main.py --motion-only
+# Video file + snapshots
+python main.py --source video.mp4 --snapshots .
+```
+
+## Face recognition
+
+Put one image per person in `known_faces/` named by the label you want (e.g. `danny.jpg`). Use a clear front-facing face. Encodings are cached in `known_faces/encodings.pkl`.
+
+## Structure
+
+- `detector/` — YOLOv8n object detection (boxes + labels)
+- `recognizer/` — face recognition (match known people)
+- `notifier/` — log, print, snapshot
+- `motion.py` — motion detection (optional trigger)
+- `main.py` — camera/video pipeline
+- `app.py` — Gradio demo for Hugging Face Spaces
+
+## Push to Hugging Face
+
+1. Create a Space at [huggingface.co/spaces](https://huggingface.co/spaces) (e.g. **Gradio** SDK).
+2. Clone your Space and add this repo’s files, or push from an existing clone:
+
+```bash
+cd smartdoor
+git remote add space https://huggingface.co/spaces/YOUR_USERNAME/smartdoor   # if not already
+git add .
+git commit -m "Add face recognition and motion detection"
+git push space main
+```
+
+3. If the Space repo was created empty, you can also use the HF CLI:
+
+```bash
+pip install huggingface_hub
+huggingface-cli login
+git clone https://huggingface.co/spaces/YOUR_USERNAME/smartdoor
+cp -r smartdoor/* smartdoor/.gitignore smartdoor/README.md smartdoor/requirements.txt ./smartdoor/  # copy app, etc.
+cd smartdoor
+git add .
+git commit -m "Add face recognition and motion"
+git push origin main
+```
+
+**Note:** The Gradio Space runs `app.py`; face recognition works if you add images under `known_faces/` in the Space (e.g. via the Files UI or at build time).
+
+Configuration reference: https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,80 @@
+"""
+Gradio app for Smartdoor — upload image, run detection + optional face recognition.
+"""
+
+import gradio as gr
+from pathlib import Path
+import sys
+import cv2
+import numpy as np
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from detector import Detector
+
+try:
+    from recognizer import FaceRecognizer
+    _recognizer = None
+    _known = Path(__file__).resolve().parent / "known_faces"
+    if _known.exists():
+        _recognizer = FaceRecognizer(_known)
+        if not _recognizer.is_available:
+            _recognizer = None
+except Exception:
+    _recognizer = None
+
+detector = Detector("yolov8n.pt")
+
+
+def run_detection(image):
+    if image is None:
+        return None, ""
+    if isinstance(image, np.ndarray):
+        frame = cv2.cvtColor(image, cv2.COLOR_RGB2BGR) if image.ndim == 3 else image
+    else:
+        frame = cv2.cvtColor(np.array(image), cv2.COLOR_RGB2BGR)
+    detections = detector.detect(frame, conf_threshold=0.25)
+    annotated = detector.annotate_frame(frame, detections)
+    lines = []
+    person_names = []
+    face_results = []
+    if _recognizer is not None and _recognizer.is_available:
+        person_boxes = [d.xyxy for d in detections if detector.is_person(d.label)]
+        if person_boxes:
+            face_results = _recognizer.recognize_faces_in_frame(frame, person_boxes)
+            person_names = [r[1] for r in face_results]
+    person_idx = 0
+    for d in detections:
+        if detector.is_person(d.label):
+            name = person_names[person_idx] if person_idx < len(person_names) else None
+            lines.append("{} is at the door".format(name) if name else "Person detected")
+            person_idx += 1
+        elif detector.is_animal(d.label):
+            lines.append("{} detected".format(d.label))
+        else:
+            lines.append("{} detected".format(d.label))
+    for (fx1, fy1, fx2, fy2), name in face_results:
+        if name:
+            cv2.rectangle(annotated, (fx1, fy1), (fx2, fy2), (255, 0, 0), 2)
+            cv2.putText(
+                annotated, name, (fx1, fy1 - 8),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2, cv2.LINE_AA
+            )
+    text = "\n".join(lines) if lines else "No person/animal detected"
+    annotated_rgb = cv2.cvtColor(annotated, cv2.COLOR_BGR2RGB)
+    return annotated_rgb, text
+
+
+with gr.Blocks(title="Smartdoor — Detection & Faces") as app:
+    gr.Markdown(
+        "# Smartdoor — Object detection & face recognition\n"
+        "Upload an image. Add photos in `known_faces/` as `name.jpg` to recognize people."
+    )
+    with gr.Row():
+        inp = gr.Image(label="Upload or paste image", type="numpy")
+        out_img = gr.Image(label="Detections")
+    out_text = gr.Textbox(label="Detected", lines=4)
+    btn = gr.Button("Detect")
+    btn.click(fn=run_detection, inputs=inp, outputs=[out_img, out_text])
+
+if __name__ == "__main__":
+    app.launch()

detector/__init__.py

@@ -0,0 +1,3 @@
+from .detector import Detector, Detection
+
+__all__ = ["Detector", "Detection"]

detector/detector.py

@@ -0,0 +1,70 @@
+"""
+Object detection using YOLOv8n (nano). CPU-friendly, no face recognition.
+Returns bounding boxes + labels for person, dog, cat, etc.
+"""
+
+from dataclasses import dataclass
+from typing import List, Tuple
+
+import cv2
+from ultralytics import YOLO
+
+
+# Classes we care about for door / animal use case
+PERSON_LABEL = "person"
+ANIMAL_LABELS = frozenset({"dog", "cat", "bird", "horse", "sheep", "cow", "bear"})
+
+
+@dataclass
+class Detection:
+    """Single detection: label + bbox (xyxy)."""
+    label: str
+    confidence: float
+    xyxy: Tuple[float, float, float, float]  # x1, y1, x2, y2
+
+
+class Detector:
+    """
+    YOLOv8n-based detector. Load once, run on frames.
+    """
+
+    def __init__(self, model_path: str = "yolov8n.pt"):
+        self.model = YOLO(model_path)
+        self.names = self.model.names
+
+    def detect(self, frame, conf_threshold: float = 0.25) -> List[Detection]:
+        """
+        Run detection on a BGR frame (e.g. from cv2).
+        Returns list of Detection with label, confidence, bbox.
+        """
+        results = self.model(frame, conf=conf_threshold, verbose=False)
+        out = []
+        for r in results:
+            if r.boxes is None:
+                continue
+            for box in r.boxes:
+                cls_id = int(box.cls[0])
+                label = self.names[cls_id]
+                conf = float(box.conf[0])
+                xyxy = tuple(map(float, box.xyxy[0]))
+                out.append(Detection(label=label, confidence=conf, xyxy=xyxy))
+        return out
+
+    def is_person(self, label: str) -> bool:
+        return label == PERSON_LABEL
+
+    def is_animal(self, label: str) -> bool:
+        return label in ANIMAL_LABELS
+
+    def annotate_frame(self, frame, detections: List[Detection]):
+        """Draw bounding boxes and labels on a copy of the frame."""
+        annotated = frame.copy()
+        for d in detections:
+            x1, y1, x2, y2 = map(int, d.xyxy)
+            cv2.rectangle(annotated, (x1, y1), (x2, y2), (0, 255, 0), 2)
+            text = "{} {:.2f}".format(d.label, d.confidence)
+            cv2.putText(
+                annotated, text, (x1, y1 - 8),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1, cv2.LINE_AA
+            )
+        return annotated

known_faces/README.md

@@ -0,0 +1,8 @@
+# Known faces (face recognition)
+
+Add one image per person, named by the label you want announced:
+
+- `danny.jpg` → "Danny is at the door"
+- `jane.jpg` → "Jane is at the door"
+
+Use a clear front-facing face photo. On first run, encodings are computed and cached in `encodings.pkl`.

main.py

@@ -0,0 +1,147 @@
+"""
+Smartdoor — object detection, optional face recognition and motion trigger.
+Pipeline: (optional motion) → capture frame → detection → face recognition for persons → notify → draw.
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+import cv2
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from detector import Detector
+from notifier import Notifier
+from motion import MotionDetector
+
+try:
+    from recognizer import FaceRecognizer
+except ImportError:
+    FaceRecognizer = None
+
+
+def setup_logging(level=logging.INFO):
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+
+def run(
+    source=0,
+    conf=0.25,
+    snapshot_dir=None,
+    no_show=False,
+    motion_only=False,
+    known_faces_dir=None,
+):
+    setup_logging()
+    detector = Detector("yolov8n.pt")
+    notifier = Notifier(log_to_console=True, snapshot_dir=snapshot_dir)
+
+    recognizer = None
+    if known_faces_dir and Path(known_faces_dir).exists() and FaceRecognizer is not None:
+        recognizer = FaceRecognizer(Path(known_faces_dir))
+        if recognizer.is_available:
+            logging.info("Face recognition enabled for %s", known_faces_dir)
+        else:
+            recognizer = None
+
+    motion = MotionDetector(threshold=25.0, min_area=500) if motion_only else None
+
+    cap = cv2.VideoCapture(source)
+    if not cap.isOpened():
+        logging.error("Could not open video source: %s", source)
+        return 1
+
+    try:
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+
+            if motion is not None and not motion.has_motion(frame):
+                if not no_show:
+                    cv2.imshow("Smartdoor — Detection", frame)
+                    if cv2.waitKey(1) == 27:
+                        break
+                continue
+
+            detections = detector.detect(frame, conf_threshold=conf)
+            person_names = []
+            face_results = []
+            if recognizer is not None and recognizer.is_available:
+                person_boxes = [d.xyxy for d in detections if detector.is_person(d.label)]
+                if person_boxes:
+                    face_results = recognizer.recognize_faces_in_frame(frame, person_boxes)
+                    person_names = [(i, face_results[i][1]) for i in range(len(face_results))]
+
+            notifier.on_detections(frame, detections, detector, person_names=person_names)
+            annotated = detector.annotate_frame(frame, detections)
+
+            if recognizer is not None and face_results:
+                for (fx1, fy1, fx2, fy2), name in face_results:
+                    if name:
+                        cv2.rectangle(annotated, (fx1, fy1), (fx2, fy2), (255, 0, 0), 2)
+                        cv2.putText(
+                            annotated, name, (fx1, fy1 - 8),
+                            cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2, cv2.LINE_AA
+                        )
+
+            if not no_show:
+                cv2.imshow("Smartdoor — Detection", annotated)
+                if cv2.waitKey(1) == 27:
+                    break
+    finally:
+        cap.release()
+        cv2.destroyAllWindows()
+
+    return 0
+
+
+def main():
+    p = argparse.ArgumentParser(
+        description="Smartdoor: object detection, face recognition, motion trigger"
+    )
+    p.add_argument(
+        "--source",
+        default=0,
+        help="Camera index (default 0) or path to video file",
+    )
+    p.add_argument("--conf", type=float, default=0.25, help="Confidence threshold")
+    p.add_argument(
+        "--snapshots",
+        type=Path,
+        default=None,
+        help="Directory to save snapshots when person/animal detected",
+    )
+    p.add_argument("--no-show", action="store_true", help="Do not show OpenCV window")
+    p.add_argument(
+        "--motion-only",
+        action="store_true",
+        help="Only run detection when motion is detected (saves CPU)",
+    )
+    p.add_argument(
+        "--known-faces",
+        type=Path,
+        default=None,
+        help="Folder with known face images (name.jpg); enables face recognition",
+    )
+    args = p.parse_args()
+
+    source = int(args.source) if str(args.source).isdigit() else args.source
+    sys.exit(run(
+        source=source,
+        conf=args.conf,
+        snapshot_dir=args.snapshots,
+        no_show=args.no_show,
+        motion_only=args.motion_only,
+        known_faces_dir=args.known_faces,
+    ))
+
+
+if __name__ == "__main__":
+    main()

models/.gitkeep

@@ -0,0 +1,2 @@
+# Custom models later (e.g. fine-tuned animal classifier).
+# YOLOv8n is loaded via ultralytics from cache.

motion.py

@@ -0,0 +1,40 @@
+"""
+Simple motion detection: frame difference above threshold.
+Use to only run detection when there's movement (saves CPU).
+"""
+
+import cv2
+import numpy as np
+from typing import Optional
+
+
+class MotionDetector:
+    def __init__(self, threshold: float = 25.0, min_area: int = 500):
+        """
+        threshold: mean absolute difference above this → motion
+        min_area: minimum contour area to count as motion (noise filter)
+        """
+        self.threshold = threshold
+        self.min_area = min_area
+        self._prev_gray: Optional[np.ndarray] = None
+
+    def has_motion(self, frame) -> bool:
+        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        gray = cv2.GaussianBlur(gray, (21, 21), 0)
+        if self._prev_gray is None:
+            self._prev_gray = gray
+            return True  # First frame: assume motion so we run detection
+        diff = cv2.absdiff(self._prev_gray, gray)
+        self._prev_gray = gray
+        mean_diff = np.mean(diff)
+        if mean_diff < self.threshold:
+            return False
+        thresh = cv2.threshold(diff, 25, 255, cv2.THRESH_BINARY)[1]
+        thresh = cv2.dilate(thresh, None, iterations=2)
+        contours, _ = cv2.findContours(
+            thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
+        for c in contours:
+            if cv2.contourArea(c) >= self.min_area:
+                return True
+        return False

notifier/notifier.py

@@ -0,0 +1,72 @@
+"""
+Notify on detections: print, log, and save snapshots.
+Later: voice (pyttsx3 / gTTS).
+"""
+
+import logging
+from pathlib import Path
+from datetime import datetime
+from typing import List
+
+import cv2
+
+# Optional: from detector import Detection
+# We accept generic dict/list to avoid circular imports; main passes Detection-like objects.
+
+
+def _ensure_snapshots_dir(base_dir: Path) -> Path:
+    d = base_dir / "snapshots"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+class Notifier:
+    """
+    Log and snapshot on person/animal detections.
+    """
+
+    def __init__(self, log_to_console: bool = True, snapshot_dir: Path = None):
+        self.log_to_console = log_to_console
+        self.snapshot_dir = snapshot_dir
+        self._logger = logging.getLogger("smartdoor.notifier")
+        if snapshot_dir is not None:
+            self._snap_dir = _ensure_snapshots_dir(snapshot_dir)
+        else:
+            self._snap_dir = None
+
+    def on_detections(self, frame, detections: List, detector, person_names=None) -> None:
+        """
+        For each detection: print/log label; if person or animal, optionally save snapshot.
+        person_names: optional list of (person_detection_index, name) from face recognizer.
+        """
+        person_names = person_names or []
+        name_by_index = dict(person_names)
+        idx = 0
+        for d in detections:
+            label = d.label
+            if detector.is_person(label):
+                name = name_by_index.get(idx)
+                msg = "{} is at the door".format(name) if name else "Person detected"
+                idx += 1
+            elif detector.is_animal(label):
+                msg = "{} detected".format(label)
+            else:
+                msg = "{} detected".format(label)
+
+            if self.log_to_console:
+                print(msg)
+            self._logger.info(msg)
+
+            if self._snap_dir is not None and (
+                detector.is_person(label) or detector.is_animal(label)
+            ):
+                self._save_snapshot(frame, label)
+
+    def _save_snapshot(self, frame, label: str) -> None:
+        if self._snap_dir is None:
+            return
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        name = f"{ts}_{label}.jpg"
+        path = self._snap_dir / name
+        cv2.imwrite(str(path), frame)
+        self._logger.info("Snapshot saved: %s", path)

recognizer/__init__.py

@@ -0,0 +1,3 @@
+from .recognizer import FaceRecognizer, HAS_FACE_RECOGNITION
+
+__all__ = ["FaceRecognizer", "HAS_FACE_RECOGNITION"]

recognizer/recognizer.py

@@ -0,0 +1,131 @@
+"""
+Face recognition: crop face from person bbox, embed, match known people.
+Known faces: put images in known_faces/ as name.jpg (e.g. danny.jpg).
+Encodings cached in known_faces/encodings.pkl.
+"""
+
+from pathlib import Path
+from typing import List, Optional, Tuple
+import pickle
+import logging
+
+import cv2
+import numpy as np
+
+try:
+    import face_recognition
+    HAS_FACE_RECOGNITION = True
+except ImportError:
+    HAS_FACE_RECOGNITION = False
+
+logger = logging.getLogger("smartdoor.recognizer")
+
+DEFAULT_TOLERANCE = 0.5
+
+
+class FaceRecognizer:
+    def __init__(self, known_faces_dir, tolerance=DEFAULT_TOLERANCE):
+        self.known_faces_dir = Path(known_faces_dir)
+        self.tolerance = tolerance
+        self._encodings_by_name = {}
+        self._loaded = False
+        self._load_known_faces()
+
+    def _load_known_faces(self):
+        if not HAS_FACE_RECOGNITION:
+            logger.warning("face_recognition not installed; face recognition disabled")
+            return
+        cache = self.known_faces_dir / "encodings.pkl"
+        if cache.exists():
+            try:
+                with open(cache, "rb") as f:
+                    self._encodings_by_name = pickle.load(f)
+                self._loaded = True
+                logger.info("Loaded %d known people from cache", len(self._encodings_by_name))
+                return
+            except Exception as e:
+                logger.warning("Could not load encodings cache: %s", e)
+        self._encodings_by_name = {}
+        for path in self.known_faces_dir.glob("*.jpg"):
+            name = path.stem
+            encodings = self._encode_image(path)
+            if encodings:
+                self._encodings_by_name[name] = encodings
+                logger.info("Registered %s from %s", name, path.name)
+        if self._encodings_by_name:
+            self.known_faces_dir.mkdir(parents=True, exist_ok=True)
+            try:
+                with open(cache, "wb") as f:
+                    pickle.dump(self._encodings_by_name, f)
+            except Exception as e:
+                logger.warning("Could not save encodings cache: %s", e)
+        self._loaded = bool(self._encodings_by_name)
+
+    def _encode_image(self, path):
+        if not HAS_FACE_RECOGNITION:
+            return []
+        img = face_recognition.load_image_file(str(path))
+        encodings = face_recognition.face_encodings(img)
+        return list(encodings)
+
+    def _encode_bgr(self, bgr_frame):
+        if not HAS_FACE_RECOGNITION:
+            return []
+        rgb = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2RGB)
+        encodings = face_recognition.face_encodings(rgb)
+        return list(encodings)
+
+    def recognize_face(self, face_crop_bgr):
+        if not HAS_FACE_RECOGNITION or not self._encodings_by_name:
+            return None
+        encodings = self._encode_bgr(face_crop_bgr)
+        if not encodings:
+            return None
+        query = encodings[0]
+        for name, known_list in self._encodings_by_name.items():
+            matches = face_recognition.compare_faces(
+                known_list, query, tolerance=self.tolerance
+            )
+            if any(matches):
+                return name
+        return None
+
+    def recognize_faces_in_frame(self, frame_bgr, person_boxes):
+        results = []
+        if not HAS_FACE_RECOGNITION or not self._encodings_by_name:
+            return results
+        for (x1, y1, x2, y2) in person_boxes:
+            x1, y1, x2, y2 = int(x1), int(y1), int(x2), int(y2)
+            h, w = frame_bgr.shape[:2]
+            pad = 0.1
+            pw = int((x2 - x1) * pad)
+            ph = int((y2 - y1) * pad)
+            x1 = max(0, x1 - pw)
+            y1 = max(0, y1 - ph)
+            x2 = min(w, x2 + pw)
+            y2 = min(h, y2 + ph)
+            crop = frame_bgr[y1:y2, x1:x2]
+            if crop.size == 0:
+                results.append(((x1, y1, x2, y2), None))
+                continue
+            rgb_crop = cv2.cvtColor(crop, cv2.COLOR_BGR2RGB)
+            face_locs = face_recognition.face_locations(rgb_crop, model="hog")
+            if not face_locs:
+                results.append(((x1, y1, x2, y2), None))
+                continue
+            t, r, b, l = face_locs[0]
+            face_crop = crop[t:b, l:r]
+            if face_crop.size == 0:
+                results.append(((x1, y1, x2, y2), None))
+                continue
+            name = self.recognize_face(face_crop)
+            fx1 = x1 + l
+            fy1 = y1 + t
+            fx2 = x1 + r
+            fy2 = y1 + b
+            results.append(((fx1, fy1, fx2, fy2), name))
+        return results
+
+    @property
+    def is_available(self):
+        return HAS_FACE_RECOGNITION and self._loaded

requirements.txt

@@ -0,0 +1,4 @@
+ultralytics>=8.0.0
+opencv-python>=4.8.0
+gradio>=4.0.0
+face_recognition>=1.3.0