Skip to content

ConceptCodes/mantis

BranchesTags

Repository files navigation

Dog Poop Detection System

A specialized system for monitoring dog cleanup compliance using live camera feed processing with dual object detection, session management, and email notifications.

Features

  • 🚶‍♂️ Session Triggers: People and dogs entering/leaving start/end monitoring sessions
  • 💩 Waste Counting: Counts poop (or proxy objects) before and after each session
  • 📊 Cleanup Analysis: Determines if cleanup occurred by comparing before/after counts
  • 📧 Smart Notifications: Sends cleanup compliance reports with video footage
  • 🎥 Video Recording: Records complete sessions for review and evidence
  • 🖥️ Headless Operation: Can run 24/7 on servers without GUI

Installation

  1. Clone or download the project files

  2. Install dependencies:

    pip install -r requirements.txt

    For Python 3.13+ users: If you encounter installation issues, try:

    pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

  3. Configure for dog poop detection: Update the .env file for dog cleanup monitoring:

    # Dog Poop Detection System Configuration
CAMERA_INDEX=0
CONFIDENCE_THRESHOLD=0.5
SESSION_TIMEOUT=10
GRACE_PERIOD_SECONDS=30
OUTPUT_DIR=./recordings

# Dual Detection Mode for Dog Cleanup Monitoring
DUAL_DETECTION_MODE=true
SESSION_TRIGGER_OBJECTS=person,dog
COUNTING_OBJECTS=bottle  # Use 'bottle' as proxy for 'poop' during testing
ADDITIONAL_OBJECTS=cat

# Email Configuration
EMAIL_SMTP_SERVER=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_FROM=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
EMAIL_RECIPIENTS=reviewer1@email.com,reviewer2@email.com

# Database Configuration
DATABASE_PATH=data/mantis.db

  4. Configure interactively (recommended):

    python configure.py

Database Management

The system uses SQLite to store all session data and detected objects for analysis and review.

Database Features

  • Session Storage: All tracking sessions with timestamps, object counts, and grace period data
  • Object Detection History: Complete record of every detected object with confidence scores and positions
  • Activity Logging: Real-time logging of all detections for heatmap generation and spatial analysis
  • Email Tracking: Records which sessions have had notification emails sent
  • Statistics & Analysis: Query sessions by date range, object counts, and cleanup compliance
  • Heatmap Data: Generate activity density maps and spatial analysis reports

Database Commands

# View database statistics
python scripts/database_manager.py stats

# Show recent sessions
python scripts/database_manager.py recent --limit 20

# Show detailed session information
python scripts/database_manager.py details [session-id]

# Export all data to JSON
python scripts/database_manager.py export sessions_backup.json

# Activity analysis commands
python scripts/database_manager.py activity --days 7
python scripts/database_manager.py timeline --hours 24 --class person
python scripts/database_manager.py heatmap heatmap.json --days 1 --grid-size 50

Heatmap & Activity Analysis

# Generate heatmap visualization
python scripts/heatmap_visualizer.py --days 7 --grid-size 40

# Save heatmap data for external tools
python scripts/heatmap_visualizer.py --days 1 --save activity_data.json

# Load and analyze existing heatmap data
python scripts/heatmap_visualizer.py --load activity_data.json

# Filter by object class
python scripts/heatmap_visualizer.py --class person --days 3

Database Location

  • Default: data/mantis.db
  • Configurable via DATABASE_PATH in .env
  • Automatically created on first run
  • Excluded from git via .gitignore

Usage

Basic Usage

python run.py

Advanced Options

# Test configuration tool
python configure.py

# Use different camera
python run.py --camera-index 1

# Adjust detection sensitivity
python run.py --confidence 0.7

# Run without GUI (for servers)
python run.py --headless

# Test email notifications
python run.py --test-email

# See all detectable objects
python run.py --list-objects

Testing & Development

# Test detection functionality
python tests/test_detection.py

# Test email template generation
python tests/test_email_template.py

# Run grace period demonstration
python scripts/grace_period_demo.py

Email Configuration

For Gmail, you'll need to:

  1. Enable 2-factor authentication
  2. Create an app-specific password
  3. Use the app password in EMAIL_PASSWORD

System Architecture

Core Components

  1. ObjectTracker (object_tracker.py)

    • Dual detection mode with session triggers and counting objects
    • Manages dog cleanup monitoring sessions
    • Records video footage of interactions
    • Counts waste items before and after sessions

  2. EmailNotificationService (email_service.py)

    • Sends cleanup compliance reports
    • Attaches session videos as evidence
    • Provides detailed before/after analysis

  3. TrackingSystemManager (main.py)

    • Coordinates dual detection components
    • Monitors cleanup sessions
    • Handles system lifecycle

How Dog Cleanup Monitoring Works

  1. 🚶‍♂️ Session Start: Person or dog enters the monitored area
  2. 💩 Initial Count: System counts waste items (poop/bottles) before interaction
  3. 📹 Activity Recording: Monitors people/dog movements throughout session
  4. ⏱️ Session End: No people/dogs detected for configured timeout period
  5. 🔢 Final Count: System counts waste items after interaction
  6. 📊 Cleanup Analysis: Compares before/after counts to determine compliance
  7. 📧 Notification: Email report with cleanup results and video evidence

Visual Indicators:

  • 🔵 Blue boxes: People and dogs (session triggers)
  • 🔴 Red boxes: Waste items being counted (poop/bottles)
  • 🟢 Green boxes: Additional tracked objects (cats, etc.)

Data Structures

  • DetectedObject: Represents a single detected object with position, confidence, and timestamp
  • TrackingSession: Contains complete session data including entry/exit objects and video path

Configuration

Camera Settings

  • CAMERA_INDEX: Which camera to use (0 for default)
  • CONFIDENCE_THRESHOLD: Minimum confidence for object detection (0.5 recommended)
  • SESSION_TIMEOUT: Seconds to wait before ending a session (10 recommended)
  • GRACE_PERIOD_SECONDS: Time to wait after session ends to detect new poop (30 recommended)

Dog Poop Detection Settings

  • DUAL_DETECTION_MODE=true: Enable specialized dog cleanup monitoring
  • SESSION_TRIGGER_OBJECTS: Objects that start/end sessions (e.g., "person,dog")
  • COUNTING_OBJECTS: Waste items to count before/after (e.g., "bottle" as poop proxy)
  • ADDITIONAL_OBJECTS: Other objects to track (e.g., "cat")

💡 Important Note: YOLO doesn't include "poop" by default. Use objects like "bottle" or "cup" as proxies for testing, or train a custom model for actual poop detection.

Grace Period Functionality

The grace period feature provides a monitoring window after a session ends to detect if new poop appears:

  1. Session End: When trigger objects (people/dogs) leave and SESSION_TIMEOUT expires
  2. Initial Count: System counts poop objects immediately after session timeout
  3. Grace Period: Waits for GRACE_PERIOD_SECONDS to allow cleanup time
  4. Final Count: Counts poop objects again after grace period expires
  5. Analysis: Compares initial vs. final counts to detect new poop or cleanup

This helps detect scenarios where:

  • Dogs poop after the owner has already left the area
  • Cleanup happens during the grace period
  • New poop appears from other dogs shortly after

Email Settings

  • Configure SMTP server settings for Gmail/other providers
  • Set reviewer email addresses (comma-separated)
  • Use app-specific passwords for Gmail

Output Settings

  • OUTPUT_DIR: Directory for saving videos and session data

API Reference

ObjectTracker Methods

# Start tracking
tracker.start_tracking()

# Count objects in current frame
counts = tracker.count_objects_in_frame(frame)

# Get object positions
positions = tracker.get_object_positions(frame)

# Get session summary
summary = tracker.get_session_summary(session_id)

# Get available objects for detection
available_objects = tracker.get_available_objects()

# Get current detection filter info
filter_info = tracker.get_detection_filter_info()

# Update object filter at runtime
tracker.update_object_filter(['person', 'dog'], detect_only_specified=True)

Email Service Methods

# Send session notification
email_service.send_session_notification(session)

# Send test email
email_service.send_test_email()

Output Files

Video Files

  • Saved as session_{session_id}_{timestamp}.mp4
  • Contains raw footage of the entire session

Session Data

  • Saved as session_{session_id}.json
  • Contains detailed object information and analysis

Example Session Data

{
  "session_id": "abc123...",
  "start_time": "2025-07-14T10:30:00",
  "end_time": "2025-07-14T10:32:30",
  "objects_entered": [...],
  "objects_exited": [...],
  "objects_before_count": 0,
  "objects_after_count": 2,
  "video_path": "./recordings/session_abc123_20250714_103000.mp4"
}

Email Report Content

The email template is a comprehensive HTML report that includes:

📧 Email Structure

  1. Header Section

    • System branding with dog emoji
    • Session ID for tracking
    • Professional green color scheme

  2. Detection Mode Alert

    • Clear explanation of dual detection mode
    • Session trigger objects (people/dogs)
    • Grace period duration
    • System purpose and functionality

  3. Session Overview

    • Start and end timestamps
    • Total session duration
    • Grace period status (completed/in progress)
    • Video attachment availability

  4. Statistics Dashboard

    • Items before session (baseline count)
    • Trigger events entered (people/dogs detected)
    • Trigger events exited (people/dogs left)
    • Items after session (post-session count)
    • Grace period count (final count after grace period)

  5. Activity & Departure Summary

    • Detailed tables of detected objects
    • Object type and count breakdown
    • Entry and exit event tracking

  6. Change Analysis

    • Net change calculation
    • Smart alerts based on detection results:
      • ✅ "Good Job: X waste items cleaned up!"
      • ⚠️ "Cleanup Alert: X more waste items detected!"
      • ℹ️ "No Change: Same number of items before/after"

  7. Grace Period Analysis (NEW!)

    • Items at session end vs. after grace period
    • Grace period change calculation
    • Specific grace period alerts:
      • 📈 "Additional Detection: X more items during grace period!"
      • 🧹 "Grace Period Cleanup: X items cleaned up during grace period!"
      • ⏹️ "No Additional Change: No activity during grace period"

  8. Detailed Object Positions

    • Precise coordinates for each detected object
    • Confidence scores for AI detections
    • Timestamps for forensic analysis

  9. Video Evidence

    • Complete session recording attached as MP4
    • File size and duration information

📱 Email Features

  • HTML Format: Professional, mobile-friendly design
  • Color-Coded Alerts: Green for good, red for alerts, blue for info
  • Responsive Layout: Works on desktop and mobile devices
  • Video Attachment: Complete session footage for review
  • Detailed Logging: Every detection event with timestamps

📄 Example Email Template

You can view a complete example of the email template by opening email_template_example.html in your web browser. This shows exactly how the email report will look with sample data including grace period information.

# View the email template example
open email_template_example.html  # macOS
# or
start email_template_example.html  # Windows
# or 
xdg-open email_template_example.html  # Linux

Troubleshooting

Common Issues

  1. Camera not found

    • Check camera index in configuration
    • Ensure camera is not being used by another application

  2. Email not sending

    • Verify SMTP settings
    • Check app password for Gmail
    • Test with --test-email option

  3. Poor object detection

    • Adjust confidence threshold
    • Ensure good lighting conditions
    • Check camera positioning

  4. High CPU usage

    • Use headless mode for servers
    • Consider reducing camera resolution
    • Adjust detection frequency

  5. Installation issues on Python 3.13+

    • Upgrade pip, setuptools, and wheel before installing requirements:
    pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Logs

System logs are saved to tracking_system.log and displayed in console.

Configuration Examples

Perfect Dog Cleanup Monitoring Setup

# Enable dual detection for dog cleanup monitoring
DUAL_DETECTION_MODE=true
SESSION_TRIGGER_OBJECTS=person,dog
COUNTING_OBJECTS=bottle  # Using bottle as poop proxy for testing
ADDITIONAL_OBJECTS=cat

Testing with Different Proxy Objects

# Use cups as waste proxies
COUNTING_OBJECTS=cup

# Use multiple proxy objects
COUNTING_OBJECTS=bottle,cup

# Track additional context
ADDITIONAL_OBJECTS=cat,bicycle,backpack

Custom Poop Detection (Advanced)

# Once you have a custom trained model for poop detection
COUNTING_OBJECTS=poop

Use Cases

  • 🐕 Dog Park Monitoring: Monitor cleanup compliance in dog parks and public areas
  • 🏠 Private Property: Track pet waste cleanup on private property
  • 🌳 Trail Monitoring: Ensure hikers clean up after their dogs on trails
  • 🏢 Apartment Complex: Monitor pet areas in residential complexes
  • 🎾 Training Tool: Help dog owners develop good cleanup habits

Technical Details

Dependencies

  • OpenCV: Camera handling and computer vision
  • Ultralytics YOLO: AI object detection model
  • python-dotenv: Configuration management
  • smtplib: Email notifications

Performance

  • Real-time Processing: ~30 FPS on modern hardware
  • Detection Model: YOLOv8 nano for speed/accuracy balance
  • Storage: Compressed MP4 video recordings
  • Memory: Optimized for 24/7 operation

Important Notes

  • Poop Detection: YOLO doesn't include "poop" by default
  • Proxy Objects: Use "bottle", "cup", or similar objects for testing
  • Custom Training: Train custom models for actual poop detection
  • Lighting: Good lighting improves detection accuracy

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages