How cmusatyalab/openface works
Project type and purpose
• OpenFace is an open-source face-recognition library and toolkit. It provides:
• A core Python API (openface/) wrapping Torch neural nets for feature extraction and face alignment
• Command-line utilities (scripts under top level, batch-represent/, conversion/, util/)
• Training pipelines (Lua/Torch scripts under training/)
• Evaluation scripts (evaluation/)
• Demos (Python, Lua, and a real-time web demo under demos/)
• Model management (models/)
File structure
• Top-level directories group by functionality:
• openface/: core library modules (alignment, data loading, neural-net inference)
• batch-represent/, conversion/, util/: data-processing and utility scripts
• training/: Torch training pipelines and configurations
• evaluation/: accuracy-evaluation suites on LFW and other benchmarks
• demos/: interactive and programmatic demos, including demos/web (static assets, JS/CSS, Python websocket server)
• models/: pretrained model definitions and scripts to fetch them
• Config files: setup.py, requirements.txt, Dockerfiles, CI configs, docs in api-docs/, docs/.
Readme insights
• Emphasizes modularity: library + demos + training + evaluation
• Highlights dependencies: Python, Torch, dlib, web stack (WebSocket)
a. Main components
• Core Library Layer (Python modules in openface/)
• Model Layer (Torch models in models/)
• CLI & Batch Tools Layer (batch-represent/, conversion scripts, util scripts)
• Training Layer (Lua/Torch training scripts in training/)
• Evaluation Layer (Python/Lua scripts in evaluation/)
• Demo Layer
• Local Demos (Python/Lua scripts under demos/*.py and demos/vis-outputs.lua)
• Web Demo (Front-end: HTML/JS/CSS; Back-end: Python WebSocket server)
• Data Layer (datasets fetched/processed under data/)
• External Services/Dependencies:
• dlib (face landmark detection)
• Torch (neural-network runtime)
• Python packages (NumPy, SciPy, Flask or similar for web demo)
b. Relationships & interactions
• CLI/Batch Tools → import Core Library → load models from Model Layer → run inference → write embeddings
• Training Layer → import Core Library modules → consume processed data (Data Layer) → train and export models back to Model Layer
• Evaluation Layer → load Core Library + Model Layer → run benchmarks on datasets → produce accuracy reports
• Local Demos → orchestrate Core Library + Model Layer → show results on images or webcam
• Web Demo Front-end ↔ Web Demo Back-end → uses WebSocket for real-time inference → back-end calls Core Library + Model Layer
• Data Layer is shared by Training, Evaluation, and Conversion scripts
c. Architectural patterns/design principles
• Modular layering: clear separation between core inference library, training, evaluation, and demos
• Reuse of Core Library across tools, demos, training, and evaluation
• Plug-in model definitions: Model Layer uses .def.lua files to configure network topology
• Microservice style in web demo: lightweight Python server exposing inference over WebSockets
d. Key technologies/frameworks
• Python 2/3, Torch7 (Lua)
• dlib for facial landmark detection
• WebSocket server (Python) + static front-end (HTML/CSS/JS)
• Docker for containerized builds
• Continuous Integration via Travis, documentation via ReadTheDocs
Important note
• Every module group as a component. Don’t omit conversion/, util/, or evaluation/. Each has a role in the overall architecture.