How tanish-sarkar/real-time-facial-detection works
This is a single-node real-time computer vision + web streaming application:
• Input: Local webcam frames (OpenCV).
• Processing pipeline: grayscale → Haar cascade face detection → Laplacian-variance blur scoring → annotate.
• Output: Live MJPEG stream served by Flask to a browser.
• Side effects (parallel concerns): event-based frame saving (only when blurry) + timestamped logging.
• Real-time frame pipeline (hot path)
• Streaming mechanism (generator-based MJPEG)
• Resource lifecycle (camera ownership in generator)
• Observability + event outputs (logs + saved frames)
• Local filesystem assets (Haar cascade XML)
File-tree-driven architecture mapping (turn directories into components)
You effectively have two entrypoints (two “modes”):
What to extract from README (key runtime behaviors to reflect)
• Generator-based MJPEG streaming (core to Flask integration and performance).
• Camera lifecycle handling (camera opened/owned inside generator to avoid conflicts).
• Event-based frame saving (prevents I/O overload).
• Cooldown logic (avoids repeated captures).
• Defensive programming (avoid silent stream crashes).
• Parallel outputs: “saved and logged in parallel without interrupting the video stream.”
These are architectural concerns, not just implementation details—include them as labeled subcomponents or notes.
Side-effect branches (non-blocking outputs)
From the Decision: BLURRY node, branch to:
• Cooldown Gate (prevents repeated saves)
• If allowed → Frame Saver → saved_frames/blur_YYYYMMDD_HHMMSS.jpg (README mentions this; even if the folder isn’t in your current tree, model it as a filesystem sink).
• Also branch to:
• Event Logger → logs/detections.log
Important: visually indicate these are side effects that must not block the streaming loop. Use:
• a “non-blocking / best-effort” label, or
• a small “async-like” annotation (even if implemented synchronously, the design intent is “don’t interrupt the stream”).
• Browser → Flask: HTTP GET / and /video_feed (or similar)
• Flask → Browser: multipart/x-mixed-replace MJPEG stream
• OpenCV → Asset: loads Haar cascade XML from assets/
• Pipeline → Filesystem:
• append-only logging to logs/detections.log
• conditional image writes to saved_frames/
• “frames (numpy array)” for internal steps
• “JPEG bytes” after encoding
• “MJPEG multipart” for the network response
Architectural patterns/design principles to call out
• Single-process streaming loop with generator producing frames.
• Event-driven side effects (save/log only on blur).
• Backpressure-friendly approach: don’t accumulate frames; process latest frame and stream.
• Separation of concerns:
• Web serving (Flask)
• CV pipeline (OpenCV stages)
• Observability (logging)
• Persistence (frame saving)
• Configuration/assets (Haar XML)
Purpose: “Who talks to what?”
• Browser
• Flask app (on local machine)
• Webcam device
• Local filesystem (assets/logs/saved frames)
Purpose: “What are the major runtime components?”
• Flask server
• MJPEG generator
• CV pipeline components
• Logger + frame saver
• Assets
Purpose: “What happens per frame and when do we save/log?”
Show:
• → process → annotate → encode → yield
• if blur & cooldown ok → save + log
• src/flask_app.py next to the Flask/MJPEG components.
• logs/detections.log next to the logging sink.
What “most detailed” means here (separate into as many components as possible)
• Capture
• Grayscale
• Face detect (asset dependency)
• Blur score
• Threshold decision
• Annotation
• Encoding
• Streaming
Likewise, don’t collapse “output”:
• Streaming output (browser)
• Logging output (file)
• Saved-frame output (folder)