FaceHalo - Face Mouse Controller

中文文档

FaceHalo is a face-controlled mouse system that allows you to control your computer hands-free using facial gestures and head movements.

Features

• 🖱️ Mouse Control: Control cursor position with head movements
• 👁️ Blink Detection: Detects eye blinks and closures
• 👄 Mouth Gestures: Detects mouth opening for actions
• 🎨 Multiple Display Modes: Black curtain, white curtain, or camera view
• ⚙️ Adjustable Sensitivity: Customize X/Y axis sensitivity and dead zone
• 🪞 Mirror Mode: Flip video horizontally for natural interaction

Action Bindings

Action	Trigger	Binding Status
Double Click	Quick mouth open (Ratio > 0.3, 3 frames)	✅ Bound
End Drag	Long mouth open 0.6s (20 frames)	✅ Bound
Blink	Eye blink (EAR < 0.2, 3 frames)	👁️ Display only
Long Eye Close	Eye closed 0.5s (15 frames)	👁️ Display only
Long Mouth Open	Mouth open 0.6s (20 frames)	👁️ Display only

Note: Actions marked as "Display only" are recognized but do not trigger mouse operations to prevent accidental triggers.

Requirements

• Python 3.8+
• Webcam
• Windows / macOS / Linux

Installation

1. Clone the repository:

git clone https://github.com/yourusername/FaceHalo.git
cd FaceHalo

2. Create a virtual environment (recommended):

python -m venv .venv

3. Activate the virtual environment:

• Windows:

.venv\Scripts\activate

• macOS/Linux:

source .venv/bin/activate

4. Install dependencies:

pip install -r requirements.txt

Usage

GUI Version (Recommended)

Run the UI version with full settings:

python face_mouse_ui.py

Or use the batch file (Windows):

run_ui.bat

Command Line Version

Run the command line version:

python face_mouse_controller.py

Select mode:

• 1. Standard mode (recommended): Uses calibration center point
• 2. Simple mode: Uses screen center with dead zone

Controls

Hotkey	Function
C	Calibrate center position
L	Toggle landmarks display
I	Toggle info display
Q	Quit

GUI Settings

• Background Mode: Choose between black curtain, white curtain, or camera view
• Sensitivity: Adjust X/Y axis sensitivity (0.5 - 3.0)
• Dead Zone: Set dead zone to prevent jitter (0.0 - 0.5)
• Mirror Mode: Flip video horizontally
• Show Landmarks: Toggle facial landmark display

How It Works

1. Face Detection: Uses MediaPipe Face Mesh to detect 468 facial landmarks
2. Head Pose: Calculates head position relative to calibration center
3. Mouse Movement: Maps head position to screen coordinates
4. Gesture Recognition: Detects eye blinks and mouth openings
5. Action Execution: Triggers mouse actions based on recognized gestures

Project Structure

FaceHalo/
├── face_mouse_controller.py    # Command line version
├── face_mouse_ui.py            # GUI version (PyQt6)
├── requirements.txt            # Python dependencies
├── run.bat                     # Windows batch file (CLI)
├── run_ui.bat                  # Windows batch file (GUI)
├── models/                     # Face landmark model (auto-downloaded)
├── README.md                   # English documentation
├── README_CN.md                # Chinese documentation
└── .gitignore                  # Git ignore file

Troubleshooting

Camera not detected

• Ensure your webcam is connected and not in use by other applications
• Try changing the camera index in the code (default is 0)

Face not detected

• Ensure good lighting conditions
• Face the camera directly
• Try calibrating the center position (press C or click "Calibrate")

Cursor too sensitive/jittery

• Increase the dead zone value
• Decrease sensitivity
• Enable smoothing (built-in 5-frame averaging)

Actions triggering accidentally

• Only essential actions (double click, end drag) are bound to mouse operations
• Other actions are recognized but do not trigger mouse actions

Safety Notes

• ⚠️ Failsafe: Move mouse to screen corner to emergency stop
• ⚠️ Keep your face visible to the camera at all times
• ⚠️ Take regular breaks to avoid eye strain

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• MediaPipe for face landmark detection
• PyQt6 for the GUI
• PyAutoGUI for mouse control

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Made with ❤️ by [Your Name]