nischi/mmm-face-reco-dnn

<explanation>

1. Project Type and Purpose

- This is a MagicMirror² module (JavaScript/Node.js front‑end + Node helper) that uses Python scripts (face_recognition, OpenCV, dlib) to detect and recognize faces via a Raspberry Pi camera.

- Purpose: show/hide MagicMirror modules based on who is in front of the mirror.

2. Main Components

A. MagicMirror² Core

• Hosts all modules, renders the UI, handles notifications bus.

B. MMM‑Face‑Reco‑DNN Front‑End (MMM‑Face‑Reco‑DNN.js)

• Configures display classes and handles incoming notifications (USERS_LOGIN, USERS_LOGOUT).

C. Node Helper (node_helper.js)

• Periodically triggers face recognition (checkInterval).

• Spawns Python processes for detection/encoding.

• Sends results back to MagicMirror via notifications.

D. Python Face‑Recognition Engine

• Scripts in tools/ (encode.py, recognition.py, takesPictures.py).

• Uses libraries: face_recognition, OpenCV (picamera2), dlib, numpy.

• Reads/writes: dataset/ (input images), model/haarcascade_frontalface_default.xml, model/encodings.pickle.

E. Hardware & Environment

• Raspberry Pi camera (via picamera2).

• Python virtual environment or system Python with required libraries.

F. Data Stores

• dataset/ (user subfolders with images).

• model/encodings.pickle (embeddings).

• Haar cascade XML (face detection).

3. Relationships & Data Flow

1. Front‑End sets checkInterval → Node Helper

2. Node Helper → (child_process) → Python recognition.py

3. Python script:

– Grabs image from Pi camera

– Detects faces (Haar or DNN)

– Computes embeddings, compares to encodings.pickle

– Returns list of recognized / unknown faces

4. Node Helper receives results → emits MagicMirror notifications (USERS_LOGIN, USERS_LOGOUT) → Front‑End

5. Front‑End updates module classes (known/unknown/noface) → MagicMirror² shows/hides modules

4. Architectural Patterns & Design Principles

- Modular separation: UI layer (JS) / orchestration (Node) / compute engine (Python).

- IPC via child processes and MagicMirror notification bus.

- Configuration-driven: model paths, detection method, classes.

- Extensibility: tools/ scripts for dataset management and encoding.

5. Diagramming Guidelines

a. Use distinct shapes/colors for each layer:

– Blue rectangles: MagicMirror Core + Front‑End

– Green rectangles: Node Helper

– Orange rectangles: Python Engine & tools

– Gray cylinders: Data stores (dataset, encodings.pickle, Haar XML)

– Icon for Pi camera hardware

b. Draw directional arrows to show:

– Front‑End → Node Helper (trigger checks)

– Node Helper → Python scripts (spawn, request)

– Python → Data stores (read/write)

– Python → Node Helper (results)

– Node Helper → Front‑End (notifications)

– Front‑End → MagicMirror Core (UI updates)

c. Annotate technologies on each component:

– Front‑End: JavaScript, Electron, MagicMirror² module API

– Node Helper: Node.js, child_process API

– Python Engine: face_recognition, OpenCV, dlib, numpy, picamera2

d. Highlight key patterns:

– Parent‑child process boundary between Node and Python

– Pub/Sub via MagicMirror notifications

6. Tailoring for This Project

- Emphasize the two‑language split (JS vs. Python).

- Show where model files live and when encode.py is used offline (toolchain).

- Show the camera as an external input.

7. Essential Elements to Include

– Clear labels for each box/component

– Arrowheads for data/control flow

– Color coding (e.g., compute vs. storage vs. UI)

– Legend for shapes/colors

– Note configuration inputs (config.js parameters)

By following this structure, your diagram will clearly separate the UI layer, orchestration layer, compute layer, data stores, and hardware, making the end‑to‑end face‑recognition flow and module interaction crystal‑clear.