Facemind: A PyQt5 and Mediapipe App That Reads Mental Health from Facial Landmarks

What Facemind Solves and Who It Targets

Facemind addresses a narrow problem: turning a webcam feed into a real-time mental health estimate using facial landmarks. The README says the application uses computer vision and machine learning to analyze mental health based on facial expressions, with a login system and real-time analysis. The target audience is clear from the project's own words: it was built as a delegation for a competition paper, authored by two people. This is not a tool for clinicians or for production mental health screening. It is a demonstration of a pipeline, aimed at judges or reviewers who want to see a working interface, not a validated medical device. If you need a reliable mental health assessment, Facemind is the wrong starting point because the README gives no evidence that the analysis is grounded in clinical research.

The Architecture: OpenCV, Mediapipe, and PyQt5 in One Loop

The repository layout and README reveal a stack that is common for desktop computer vision experiments. OpenCV captures video frames, Mediapipe extracts facial landmarks, and PyQt5 renders the interface. The data flow is typical: each frame from the camera is passed to Mediapipe's face mesh model, which returns 468 landmarks in 3D space. Those landmarks are then fed into some analysis logic that produces a mental health label or score, which the PyQt5 window displays. The README mentions 'real-time mental health analysis through facial landmarks', so the loop is frame-by-frame, not batch processing. One detail stands out: the README lists selenium as a dependency, which is unusual for a desktop CV app. Selenium is a browser automation tool, so either the app scrapes something or the dependency is leftover from an earlier version. The README does not explain it, and that is a sign of incomplete documentation.

Running Facemind: Docker Pull, Not pip Install

The README's installation section is oddly short. It lists required packages: opencv-python, numpy, mediapipe, selenium, PyQt5, and pandas. Then it gives a single command to install missing dependencies: docker pull ghcr.io/galihru/mental_health_app:latest. That is a Docker image pull, not a pip command. The repository name is facemind, but the Docker image is named mental_health_app, which is a mismatch you should note. The README does not show how to run the app after pulling the image, nor does it show a command to launch the PyQt5 window. There is no mention of a requirements.txt, a setup.py, or a CLI entry point. If you want to run it from source, you would need to clone the repo and install the listed packages manually, then run the main script, but the README does not name that script. This is a real friction point for anyone trying to evaluate the project quickly.

The Core Problem: No Evidence of a Mental Health Model

The biggest limitation is that the README never explains how facial landmarks become a mental health assessment. It says the app analyzes mental health, but it does not specify the algorithm, the model, or the mapping from landmark coordinates to a psychological state. Is it a rule-based heuristic, like measuring eyebrow distance for stress? Or a trained classifier? The README is silent. The word 'machine learning' appears, but no training data, no model file, and no accuracy numbers are mentioned. For any serious evaluation, this is a dealbreaker. You cannot trust an output you do not understand. The lack of validation means the app could be assigning random labels for all the evidence provided. If you are considering this for a research project, you must inspect the source code to see what the analysis function actually computes. The documentation gives you no basis to believe the mental health readings are meaningful.

A Competition Paper Prototype, Not a Maintained Library

The release history shows two tags, v1.0 and v1.1, both dated 2025-01-15, the same day as the last push. That suggests a single burst of work, likely tied to the competition deadline. The repository is not archived, but with only two releases on one day, there is no sign of ongoing maintenance. The README is sparse, with no usage examples beyond the Docker pull, no API documentation, and no contribution guidelines. The license is Apache-2.0, which is permissive and allows reuse, but the project is presented as a paper submission, not a community project. For an engineer evaluating adoption, this means you should expect to read the source yourself and maintain it yourself. There is no community to answer questions, and the documentation will not help you debug. The Apache-2.0 license does give you freedom to modify and redistribute, but it does not compensate for the lack of support.

Alternative Approaches: Rule-Based Heuristics vs. Trained Models

If you need to analyze facial expressions for mental health signals, there are different paths. One alternative is to skip the mental health label entirely and use Mediapipe's facial landmarks directly for specific, measurable cues like eye blink rate or head pose, which have documented correlations with fatigue or attention. That approach is more transparent because you control the mapping. Another alternative is to use a trained emotion recognition model, such as a convolutional neural network trained on datasets like FER2013, which outputs discrete emotions (happy, sad, angry) rather than a mental health score. The difference is that Facemind claims to output a mental health assessment, which implies a higher-level inference, but it does not show the model. A rule-based system gives you explainability, while a trained model gives you statistical grounding. Facemind sits in between, claiming the latter without proving it. For a competition, the visual demo may be enough, but for any real use, you need a tool that either explains its rules or shows its training data.

Maintenance and Upgrade Costs

The maintenance cost for Facemind is low in terms of dependencies, because OpenCV, Mediapipe, and PyQt5 are all stable, well-maintained libraries. The risk is in the custom analysis code, which is undocumented. If the underlying libraries update their APIs, such as Mediapipe's landmark indexing or PyQt5's signal handling, you will need to debug without a guide. The Docker image, ghcr.io/galihru/mental_health_app:latest, is a convenience, but it pins a specific environment, and you have no idea when or if it will be updated. The license, Apache-2.0, permits you to fork and patch, which is a positive. However, the project's purpose as a competition paper means the authors likely have no incentive to maintain it after the event. You should budget time to read every line of the analysis module and to write your own tests, because the README gives you no baseline for correctness. The upgrade cost is not about the stack; it is about understanding what the code actually does.

Editorial conclusion

Adopt Facemind if you are a student or researcher building a prototype for a competition paper and need a working example of facial landmark extraction with a PyQt5 GUI. Do not use it for clinical diagnosis or any real mental health assessment, as the documentation provides no validation, accuracy metrics, or clinical basis. Before integrating it, verify the actual analysis logic in the source code, confirm the claimed mental health mapping is more than a label, and check the Docker image and dependencies for compatibility with your Python environment. The project is a proof of concept, not a reliable tool, and its value is limited to demonstrating a pipeline.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes