Pigeon Guard

Detecting Pigeons in Images using Machine Learning:

Configuration

The application uses environment variables for configuration. Create a .env file in the project root:

cp .env.example .env

Then edit .env with your settings. See .env.example for all available options.

Key Configuration Variables

• PGUARD_MODEL_DIR: Folder path in which models are stored locally
• PGUARD_MODEL_FILE: File name of the model to use (if it does not exist locally, it will be downloaded from the model releases)
• PGUARD_STREAM_URL: URL of the video stream
• PGUARD_CONFIDENCE_THRESHOLD: Detection confidence threshold (0.0-1.0)
• PGUARD_PUSHOVER_ENABLED: Enable/disable Pushover notifications
• PGUARD_PUSHOVER_USER_KEY: Your Pushover user key
• PGUARD_PUSHOVER_API_TOKEN: Your Pushover API token
• See .env.example for complete list

Usage

Raspberry Pi 5 with AI HAT+

Prerequisites:

• Install required software packages for the AI HAT+
• Install Docker on your Raspberry Pi 5

Detection on local image

docker run --rm \
    --device /dev/hailo0:/dev/hailo0 \
    -v $(pwd)/.env.hailo:/app/.env \
    -v $(pwd)/models:/app/models \
    -v $(pwd)/data:/data \
    ghcr.io/pigeon-guard/app:latest-slim --image /data/test-image.jpg

Detection on local video file

docker run --rm \
    --device /dev/hailo0:/dev/hailo0 \
    -v $(pwd)/.env.hailo:/app/.env \
    -v $(pwd)/models:/app/models \
    -v $(pwd)/data:/data \
    ghcr.io/pigeon-guard/app:latest-slim --video /data/test-video.mp4 [--video-save /data/test-video-output.mp4]

Continuous detection in video stream over the network

docker run -d --restart always --name pguard \
    --device /dev/hailo0:/dev/hailo0 \
    -v $(pwd)/.env.hailo:/app/.env \
    -v $(pwd)/models:/app/models \
    -v $(pwd)/detections:/app/detections \
    -v $(pwd)/logs:/app/logs \
    ghcr.io/pigeon-guard/app:latest-slim

Other Systems

Detection on local image

docker run --rm \
    -v $(pwd)/.env:/app/.env \
    -v $(pwd)/models:/app/models \
    -v $HOME/Downloads:/data \
    ghcr.io/pigeon-guard/app:latest --image /data/test-image.jpg

Detection on local video file

docker run --rm \
    -v $(pwd)/.env:/app/.env \
    -v $(pwd)/models:/app/models \
    -v $HOME/Downloads:/data \
    ghcr.io/pigeon-guard/app:latest --video /data/test-video.mp4 [--video-save /data/test-video-output.mp4]

Continuous detection in video stream over the network

docker run -d --restart always --name pguard \
    -v $(pwd)/.env:/app/.env \
    -v $(pwd)/models:/app/models \
    -v $(pwd)/detections:/app/detections \
    -v $(pwd)/logs:/app/logs \
    ghcr.io/pigeon-guard/app:latest

Development

Detection on single image

./app.sh --image <path>

Continuous detection in interactive mode

./app.sh

Custom environment file

./app.sh --env-file .env.production

Running Tests

Run the unit tests:

source .venv/bin/activate
python3 -m unittest discover tests

Run tests with verbose output:

python3 -m unittest discover -v tests

Run a specific test file:

python3 -m unittest tests.test_event_bus

Test Coverage

The project includes comprehensive unit tests for:

• Event bus system
• Event handlers (detection and notification)
• Video stream observer
• Pushover notifier

Tests use mocks for external dependencies (cv2, requests, file I/O) and are fully automated via GitHub Actions.

See tests/README.md for more details.