AirAware | Face Mask Detection System 😷✨

A real-time face mask detection system that can identify whether a person is wearing a mask, not wearing a mask, or wearing a mask incorrectly using computer vision and deep learning.

---

🚀 Features

• 🕒 Real-time Detection: Works with webcam for live mask detection
• 👥 Multiple Face Support: Detects and classifies multiple faces simultaneously
• 🟢🟡🔴 Three-Class Classification:
  • 🟢 with_mask: Person is wearing a mask correctly
  • 🔴 without_mask: Person is not wearing a mask
  • 🟡 mask_weared_incorrect: Person is wearing a mask incorrectly
• 📈 High Accuracy: CNN-based model with data augmentation
• 🖥️ User-Friendly Interface: Real-time statistics and visual feedback
• 📸 Screenshot Capability: Save detection results as images

---

🖥️ System Requirements

• 🐍 Python 3.7 or higher
• 🎥 Webcam (for real-time detection)
• 💾 Sufficient RAM (4GB+ recommended for training)
• ⚡ GPU (optional, for faster training)

---

⚙️ Installation

1. Clone or download this repository

   git clone https://github.com/HexCrystal69/AirAware.git

2. Install dependencies:

   pip install -r requirements.txt

3. Verify installation:

   python -c "import tensorflow, cv2, numpy; print('All dependencies installed successfully!')"

---

🗂️ Dataset Structure

The system expects the following dataset structure:

data/
├── images/
│   ├── maksssksksss0.png
│   ├── maksssksksss1.png
│   └── ... (all PNG images)
└── annotations/
    ├── maksssksksss0.xml
    ├── maksssksksss1.xml
    └── ... (corresponding XML annotations)

---

🛠️ Usage

1️⃣ Training the Model

To train the mask detection model:

python train.py

This will:

• 📥 Load and preprocess the dataset from data/ folder
• 🏗️ Create a CNN model with data augmentation
• 🏃 Train the model with early stopping and learning rate scheduling
• 💾 Save the best model as mask_detector_model.h5
• 🖼️ Generate training plots (training_history.png)
• 📊 Create a confusion matrix (confusion_matrix.png)
• 📝 Print evaluation metrics

Training Parameters:

• ⏳ Epochs: 50 (with early stopping)
• 📦 Batch Size: 32
• 🚦 Learning Rate: 0.001 (with reduction on plateau)
• 🔄 Data Augmentation: Rotation, shifts, flips, zoom, brightness

---

2️⃣ Real-time Detection

To run real-time mask detection with your webcam:

python run_detection.py

Advanced Options:

# Use a different model file
python run_detection.py --model my_custom_model.h5

# Use a different camera (if you have multiple cameras)
python run_detection.py --camera 1

# Adjust confidence threshold
python run_detection.py --confidence 0.8

# Hide FPS and statistics display
python run_detection.py --no-fps

Real-time Controls:

• 🅀 q: Quit detection
• 💾 s: Save screenshot
• ℹ️ h: Show help

---

3️⃣ Image-based Detection

To test the system on a single image:

python src/mask_classifier.py

Then enter the path to your image when prompted.

---

🧠 Model Architecture

The CNN model consists of:

• 🧱 4 Convolutional Blocks with increasing filters (32→64→128→256)
• 🧪 Batch Normalization for stable training
• 🏊 MaxPooling for dimension reduction
• 🛡️ Dropout for regularization
• 🏢 Dense Layers (512→256→3) for classification
• 🧮 Softmax activation for multi-class output

---

📊 Performance

The system typically achieves:

• 🏆 Training Accuracy: 95%+
• 🥈 Validation Accuracy: 90%+
• ⚡ Real-time FPS: 15-30 FPS (depending on hardware)
• 👨‍👩‍👧‍👦 Face Detection: Works with multiple faces simultaneously

---

📁 File Structure

Face Mask Detection System/
├── data/                          # Dataset folder
│   ├── images/                    # PNG images
│   └── annotations/               # XML annotations
├── src/                          # Source code
│   ├── realtime_detection.py     # Real-time detection
│   ├── mask_classifier.py        # Image-based detection
│   ├── face_detector.py          # Face detection utilities
│   └── utils.py                  # Data loading and utilities
├── train.py                      # Complete training script
├── run_detection.py              # Simple detection launcher
├── requirements.txt              # Python dependencies
└── README.md                     # This file

---

🛑 Troubleshooting

⚠️ Common Issues

1. ❌ "Model file not found"

   • Make sure you've trained the model first using python train.py

2. 📷 "Could not open camera"

   • Check if your webcam is connected and not being used by another application
   • Try different camera indices: --camera 1, --camera 2, etc.

3. 🖼️ "No images found in dataset"

   • Ensure your dataset is in the correct structure under data/ folder
   • Check that images are in PNG format

4. 🐢 Low FPS

   • Close other applications using the camera
   • Reduce image resolution in the code
   • Use a GPU for faster inference

5. 🎯 Poor detection accuracy

   • Retrain the model with more data
   • Adjust confidence threshold
   • Ensure good lighting conditions

💡 Performance Tips

• 🔆 For better accuracy: Use good lighting and face the camera directly
• 🚀 For faster processing: Close unnecessary applications
• 👀 For multiple faces: Ensure all faces are clearly visible
• 🖥️ For training: Use GPU acceleration if available

---

🛠️ Customization

➕ Adding New Classes

To add new mask types, modify src/utils.py:

CLASSES = ['with_mask', 'without_mask', 'mask_weared_incorrect', 'new_mask_type']

🏗️ Adjusting Model Architecture

Modify the create_model() function in src/train_model.py to change the CNN architecture.

🎛️ Changing Detection Parameters

Adjust face detection parameters in src/face_detector.py:

faces = detect_faces(frame, scaleFactor=1.1, minNeighbors=5)

---

🤝 Contributing

Feel free to contribute to this project by:

• 🐞 Reporting bugs
• 💡 Suggesting new features
• 📝 Improving documentation
• ⚡ Optimizing performance

---

📄 License

This project is open source and available under the MIT License.

---

🙏 Acknowledgments

• 📚 Dataset: Face Mask Detection Dataset
• 👁️ Face Detection: OpenCV Haar Cascades
• 🧠 Deep Learning Framework: TensorFlow/Keras
• 🖼️ Computer Vision: OpenCV