Deep Dive: Detection Hyperparameters
If you are reading this for the first time, hyperparameters are simply “settings” that you can change to adjust how the AI behaves. In this project, these settings determine the difference between a system that is too sensitive (triggering alarms while you are just blinking) and a system that is too sluggish (failing to wake you up when you are actually falling asleep).
1. Understanding the “Confidence Threshold”
What is it?
When the YOLOv11 model looks at a frame, it doesn’t just say “The eye is closed.” Instead, it says, “I am 85% sure this eye is closed.” That percentage is the Confidence Score.
The confidence_threshold is the “cutoff line.” If the model’s confidence is below this number, the system ignores the detection entirely.
Detailed Impact
- The Default ( or ): The system accepts any detection it is at least half-sure about.
- Setting it Higher (e.g., ): The system becomes “stubborn.” It will only believe the eye is closed if it is absolutely certain. This reduces False Positives (wrongly triggering the alarm).
- Setting it Lower (e.g., ): The system becomes “gullible.” It will react to anything that looks vaguely like a closed eye. This increases False Positives but ensures you never miss a detection.
2. The “Sliding Window” & Drowsiness Threshold
The Concept: What is a Window?
The system doesn’t make a decision based on one single image. Why? Because humans blink! A single frame of closed eyes is just a blink, not drowsiness.
To solve this, we use a Sliding Window (implemented as a deque in the code). Imagine a list that only holds the last 15 frames. As a new frame comes in, the oldest one is pushed out.
The drowsiness_threshold (The Ratio)
This setting determines what percentage of that window must be “closed” to trigger an alarm.
Example with Default ( or ):
- Window Size: 15 frames.
- .
- Result: If 9 or more frames out of the last 15 show closed eyes, the system declares you “Drowsy.”
Detailed Impact
- Higher Threshold (e.g., ): You must keep your eyes closed for a significant portion of the window. The system is more “lenient.”
- Lower Threshold (e.g., ): Even a few slow blinks might trigger the alarm. The system is “strict.”
3. Consecutive Closed Frames
What is it?
While the Ratio (above) looks at the average of the window, the consecutive_closed_threshold looks for a streak.
If you close your eyes and keep them closed for 8 frames in a row, the system triggers an Immediate Alert, regardless of what happened in the rest of the window. This is designed to catch the exact moment someone “nods off.”
Detailed Impact
- Increase this number: The system will ignore longer blinks.
- Decrease this number: The system will react faster to a single, long eye closure.
4. The Notification Cooldown
Why is this necessary?
Computer programs run thousands of times per second. Without a cooldown, if you are drowsy, the system would try to send 30 desktop notifications and play 30 sounds every single second. This would crash your computer and be incredibly annoying.
The notification_cooldown (e.g., 10 seconds) tells the system: “Once you have triggered an alert, wait 10 seconds before you are allowed to alarm the user again.”
Summary Tuning Table for First-Time Users
If you find the system isn’t working quite right, use this table to fix it:
| If the system… | Change this setting | Direction | Why? |
|---|---|---|---|
| Alarms too often (False Alarms) | confidence_threshold | Increase | Forces the AI to be more sure before reacting. |
| Alarms too often (False Alarms) | drowsiness_threshold | Increase | Requires more “closed” evidence over time. |
| Doesn’t alarm when it should | drowsiness_threshold | Decrease | Makes the system more sensitive to closures. |
| Misses long “nods” | consecutive_closed_threshold | Decrease | Triggers the “streak” alert faster. |
| Feels too “spammy” | notification_cooldown | Increase | Gives the user more breathing room between alerts. |
Glossary of Terms for Beginners
- False Positive: When the system says you are drowsy, but you are actually awake.
- True Positive: When the system correctly identifies that you are drowsy.
- Inference: The process of the AI taking an image and making a prediction (Open vs Closed).
- Frame: A single image captured by your webcam (usually 30 frames per second).
- Deque: A special kind of list that automatically removes the oldest item when it gets too full.
Last Updated: 2026-05-03