How limkhashing/face-matching works
Project Type and Purpose
• This is a Python/Flask full-stack application that compares a face provided in a still image against faces extracted from a short video. Its goal is to return a JSON response indicating if the faces match, along with a confidence score.
• The README clarifies its use of various processing techniques (image resizing/compression, frame extraction, rotation fixes, etc.) and the involvement of multiple external software components (e.g., Tesseract, FFMPEG, OpenCV) that are essential parts of the processing pipeline.
File Structure
• Top-Level Components:
• app.py: Likely the entry point for starting the Flask web server.
• Dockerfile, Procfile, Aptfile, .dockerignore, etc.: Indicate the project is containerized and also deployable (Heroku was once supported, now deprecated), ensuring that deployment architectures are considered.
• README.md and requirements.txt: Provide installation and dependency details.
• src directory: Contains the core application logic including subdirectories for OCR tasks (OCR folder), CPBD processing (cpbd folder), and other utilities (face_processing.py, orientation_processing.py, sharpness_processing.py). These handle the image/video processing, face detection/comparison, and possibly pre/post-processing steps.
• static and templates directories: Support the frontend aspects of the web application (e.g., HTML views and assets).
• tests directory: Contains test cases that validate critical components of the application.
Extract Architectural Insights from the README
• The application workflow is clearly explained in the README:
• Upload a picture and a video.
• Resize or compress images if necessary.
• Extract frames from video and pre-process them (rotation, compression).
• Compare the uploaded image against multiple extracted frames.
• Return JSON with matching information.
• Key external technologies include: Face_Recognition Python package, Flask for the web framework, OpenCV & FFMPEG for media processing, and Docker for containerization.
a. Main Components:
• Web Frontend: Represented by the HTML templates and static assets, serving the client interface.
• Flask Web Server (app.py): Acts as the central controller for handling HTTP requests and routing.
• Processing Modules:
• Face Comparison Module (face_processing.py)
• OCR Processing Module (src/OCR/ folder includes crop_morphology.py, ocr_process.py, regex_patterns.py)
• CPBD Module (src/cpbd/) for possibly assessing image sharpness or similar metrics.
• Orientation & Sharpness Processing: Handled by orientation_processing.py and sharpness_processing.py.
• External Dependencies/Services:
• Face_Recognition Library
• OpenCV
• FFMPEG
• Tesseract (external dependency, installed separately)
• Data Flow: Include sample data (illustrated in sample_data/) and illustrate testing (tests directory) if desired.
• Docker Containerization: Note the Dockerfile and related deployment files to recognize that the entire app runs inside a container environment.
b. Relationships and Interactions:
• A user initiates requests via the frontend (browser) to the Flask web server.
• The Flask server (app.py) routes requests to appropriate backend processing modules.
• For an upload request: The image and video files are passed to various processing modules:
• Pre-processing (compression and orientation corrections)
• Frame extraction (possibly via FFMPEG)
• Face detection and matching using the Face_Recognition library
• Processors call helper functions in the OCR and CPBD modules as needed.
• Results (confidence percentage, match status) are compiled and sent back as JSON responses.
c. Architectural Patterns and Design Principles:
• Separation of Concerns: The system separates the concerns of web presentation (static/templates) from business logic and processing (app.py and src/ modules).
• Modular Design: Each processing task (OCR, CPBD, face processing, etc.) is encapsulated in its own module, easing testing and maintainability.
• Containerization: The use of Docker indicates a deployment pattern that encapsulates the application and its dependencies for consistent behavior across environments.
• External Dependency Integration: Clear integration with various libraries and external binaries (FFMPEG, Tesseract) for specialized processing steps.
d. Relevant Technologies, Frameworks, and Libraries:
• Flask for the web server.
• Python libraries: face_recognition, OpenCV.
• External processing software: FFMPEG, Tesseract, and cmake (via Aptfile for installing additional packages).
• Testing frameworks and CI/CD integration (Travis CI, Codecov as seen from the badges).
Elements
• Web UI components (e.g., blue rectangles for HTML/templates),
• Backend modules (e.g., green ovals for processing modules),
• Including notes about the purpose of each module next to its representation.
Detailed Component Breakdown
• Client/User: Browser initiating image and video uploads.
• Frontend Layer: Static files and templates served by Flask.
• Flask Application (app.py): Serves as the entry point, handling HTTP requests/responses.
• Business Logic Modules (inside src/):
• OCR Subsystem: Contains crop_morphology.py, ocr_process.py, regex_patterns.py.
• CPBD Subsystem: Includes cpbd module files (compute.py, octave.py).
• Face Processing: Modules for face_processing, orientation_processing, sharpness_processing.
• Additional Utilities: Constants, delete_files, etc.
• External Dependencies:
• Face_Recognition library
• OpenCV
• FFMPEG and Tesseract (illustrate these as prerequisites or external services).
• Docker Container: Represent the system encapsulated within a Docker container, including configuration files like Dockerfile, and mention the container orchestration potential.