🛡️ Human Detection Security System

AI-powered room monitoring system that detects humans and sends instant Telegram alerts with screenshots when someone enters your room.

✨ Features

• 👤 AI Human Detection - Uses HOG (Histogram of Oriented Gradients) to detect actual humans
• 📸 High-Quality Screenshots - Captures clear images in 1280x720 resolution
• 📱 Telegram Alerts - Instant notifications with photos sent to your phone
• 🎯 Motion Detection Backup - Dual detection system for maximum reliability
• 👁️ Live Preview - See what the camera sees in real-time
• 🔄 Auto Camera Adjustment - Automatically adjusts to lighting conditions
• ⚡ Fast Response - Sends alerts within seconds of detection
• 🚫 Anti-Spam - Configurable cooldown between alerts

📋 Requirements

Hardware

• Webcam (built-in laptop camera or USB webcam)
• Computer running Windows/Linux/Mac
• Internet connection for Telegram alerts

Software

• Python 3.7 or higher
• Telegram account

🚀 Quick Start

1. Install Python Dependencies

pip install opencv-python numpy requests

Or using requirements.txt:

pip install -r requirements.txt

2. Set Up Telegram Bot

Create Bot

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow instructions to create your bot
4. Copy the Bot Token (looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Get Your Chat ID

1. Search for @userinfobot on Telegram
2. Send any message or click "Start"
3. Copy the number it sends you (your Chat ID)

3. Configure the Script

Open motion_detector.py and update:

TELEGRAM_BOT_TOKEN = "YOUR_BOT_TOKEN_HERE"  # Paste your bot token
TELEGRAM_CHAT_ID = "YOUR_CHAT_ID_HERE"      # Paste your chat ID

4. Run the Script

python motion_detector.py

That's it! The system is now monitoring your room! 🎉

⚙️ Configuration

Edit these settings at the top of motion_detector.py:

# Detection sensitivity
MOTION_THRESHOLD = 800          # Lower = more sensitive (default: 800)
MIN_CONTOUR_AREA = 500         # Minimum object size to detect (default: 500)
MIN_TIME_BETWEEN_ALERTS = 8    # Seconds between alerts (default: 8)

# Human detection
DETECT_HUMANS = True           # Enable AI human detection (default: True)
MIN_HUMAN_CONFIDENCE = 0.3     # Detection confidence 0.0-1.0 (default: 0.3)

# Visual options
SHOW_PREVIEW = True            # Show live camera preview (default: True)
DRAW_DETECTION_BOXES = True    # Draw boxes around detections (default: True)

🎯 Usage Examples

Basic Usage (Sleep Mode)

python motion_detector.py

• Place laptop facing your door before sleeping
• Minimize or hide the preview window
• Get alerts on your phone when someone enters

Testing Mode

python motion_detector.py

• Keep preview window open
• Walk in front of camera to test
• Check Telegram for alerts
• Adjust sensitivity if needed

Headless Mode (No Preview)

Set SHOW_PREVIEW = False in the script for servers or background operation.

📊 How It Works

1. Camera Initialization

   • Opens webcam with optimal settings
   • Adjusts to lighting conditions (auto-exposure, auto-focus)
   • Captures high-resolution frames (1280x720)

2. Human Detection (Primary)

   • Uses HOG + SVM algorithm to detect human shapes
   • Analyzes body proportions and features
   • Draws red boxes around detected humans
   • Calculates confidence score

3. Motion Detection (Backup)

   • Background subtraction algorithm
   • Frame differencing for sensitivity
   • Detects any significant movement
   • Draws green boxes around motion

4. Alert System

   • Captures screenshot when detection occurs
   • Verifies image quality (brightness, file size)
   • Sends photo + details to Telegram
   • Implements cooldown to prevent spam

🔧 Troubleshooting

Camera Issues

Problem: Black screen or "Cannot open webcam"

Solutions:
✅ Close other apps using camera (Zoom, Skype, Teams, etc.)
✅ Try different USB port (for external webcams)
✅ Check Windows Camera app to verify camera works
✅ Restart computer
✅ Update camera drivers

Problem: Dark/black images sent to Telegram

Solutions:
✅ Turn on room lights
✅ Adjust camera position
✅ Increase MOTION_THRESHOLD value
✅ Wait longer for camera auto-exposure (script does this automatically)

Telegram Issues

Problem: "Telegram connection failed"

Solutions:
✅ Verify bot token is correct
✅ Verify chat ID is correct (just numbers, no letters)
✅ Start your bot (send /start command to it on Telegram)
✅ Check internet connection

Problem: Not receiving alerts

Solutions:
✅ Check if Telegram notifications are enabled on your phone
✅ Verify bot isn't blocked
✅ Send /start to your bot
✅ Test with send_telegram_message() function first

Detection Issues

Problem: Too many false alerts

Solutions:
✅ Increase MOTION_THRESHOLD (try 1200, 1500, 2000)
✅ Increase MIN_CONTOUR_AREA (try 800, 1000)
✅ Enable DETECT_HUMANS = True for better accuracy
✅ Increase MIN_HUMAN_CONFIDENCE (try 0.4, 0.5)
✅ Position camera to avoid moving objects (curtains, fans, pets)

Problem: Not detecting humans/motion

Solutions:
✅ Decrease MOTION_THRESHOLD (try 500, 300)
✅ Decrease MIN_CONTOUR_AREA (try 300, 200)
✅ Decrease MIN_HUMAN_CONFIDENCE (try 0.2, 0.15)
✅ Ensure good lighting in room
✅ Test by waving in front of camera
✅ Check preview window for visual feedback

🎨 Preview Window

The live preview shows:

• 🔴 Red boxes - Detected humans
• 🟢 Green boxes - Motion detection
• 📊 Status text - Current detection state
• 📈 Motion score - Real-time sensitivity indicator
• 👤 Human count - Number of people detected

Controls:

• Press Q to quit preview window
• Minimize window to run in background

📁 Project Structure

antispy_bot/
├── motion_detector.py    # Main script
├── README.md            # This file
├── requirements.txt     # Python dependencies
└── alert_*.jpg         # Temporary alert images (auto-deleted)

🔒 Security & Privacy

• ⚠️ Never share your bot token - It's like a password
• 🔐 Bot token grants full access to send messages
• 📱 Only you (your Chat ID) receives alerts
• 🗑️ Alert images are auto-deleted after sending
• 💾 No data is stored or uploaded anywhere except Telegram
• 🔄 Consider regenerating bot token if accidentally exposed

📝 Advanced Tips

Run on Startup (Windows)

1. Press Win + R
2. Type shell:startup
3. Create shortcut to motion_detector.py
4. Set to run minimized

Run as Background Service (Linux)

# Create systemd service
sudo nano /etc/systemd/system/motion-detector.service

# Add service configuration
[Unit]
Description=Room Motion Detector
After=network.target

[Service]
ExecStart=/usr/bin/python3 /path/to/motion_detector.py
Restart=always
User=yourusername

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable motion-detector
sudo systemctl start motion-detector

Multiple Cameras

Modify line in script:

cap = cv2.VideoCapture(0)  # 0 = first camera, 1 = second, etc.

Custom Alerts

Modify the caption in detect_motion() function:

caption = f"🚨 Custom message here!\n📅 {timestamp}"

🐛 Known Issues

1. Windows Camera Lag - First few frames may be slow (fixed with warmup)
2. CPU Usage - Can be high with human detection (run on less frames)
3. False Positives - Shadows, curtains, pets (adjust thresholds)

🤝 Contributing

Found a bug? Want to improve it?

1. Fork the repository
2. Make your changes
3. Test thoroughly
4. Submit pull request

📄 License

MIT License - Free to use and modify

💡 Use Cases

• 🏠 Home Security - Monitor your room while away
• 😴 Sleep Monitoring - Alert when someone enters while sleeping
• 🏢 Office Security - Monitor empty office spaces
• 👶 Baby Monitor - Enhanced baby room monitoring
• 🐕 Pet Monitoring - Check when pets enter restricted areas
• 📦 Package Detection - Alert when deliveries arrive

📞 Support

Having issues?

1. Check troubleshooting section above
2. Verify all requirements are installed
3. Test camera with Windows Camera app
4. Test Telegram bot with manual messages
5. Check preview window for visual debugging

⭐ Features Roadmap

• Multiple user support
• Discord/WhatsApp integration
• Video recording option
• Cloud storage integration
• Mobile app
• Face recognition
• Sound detection
• Email alerts

🎓 Technical Details

Algorithms Used:

• HOG (Histogram of Oriented Gradients) for human detection
• MOG2 (Mixture of Gaussians) for background subtraction
• Frame differencing for motion detection
• Gaussian blur for noise reduction
• Morphological operations (dilation) for better detection

Performance:

• ~30 FPS on modern laptops
• <5% CPU usage (motion only)
• ~15-20% CPU usage (with human detection)
• <50MB RAM usage
• Instant alerts (<2 seconds delay)

---

Made with ❤️ for better home security

Stay Safe! 🛡️s