Graffiti Detection AI Model

YOLOv8-based graffiti detection for Python applications, model training, batch inference, camera monitoring, alerts, and API integration.

Why I Built It

I built this project because I hate seeing my city being destroyed and ruined by graffiti. It is intended to help maintenance and response teams detect incidents earlier and act faster.

What Makes It Useful

• A small Python API for image inference
• End-to-end scripts for dataset preparation, training, evaluation, and video inference
• Multi-camera monitoring with email, SMS, webhook, Discord, Slack, and OneSignal alerts
• FastAPI and Docker deployment options
• Private, offline Core ML inference on iPhone and iPad
• Street-scene augmentation for poor lighting, weather, perspective, and CCTV artifacts

Model weights are not bundled. Train a model with this project or provide compatible Ultralytics YOLO weights.

Installation

Python 3.9 or newer is required.

pip install graffiti-detection-ai-model

Install every runtime feature for training, alerts, and the API:

pip install "graffiti-detection-ai-model[all]"

For development from source:

git clone https://github.com/EfficientTools/graffiti-detection-ai-model.git
cd graffiti-detection-ai-model
python -m venv venv
source venv/bin/activate
python -m pip install -e ".[dev]"

Python Usage

from graffiti_detection import GraffitiDetector

detector = GraffitiDetector("models/best.pt", conf_threshold=0.25)
detections = detector.predict("image.jpg")

Each detection contains class_id, class_name, confidence, and an xyxy box.

Command Line

# Prepare a YOLO-format dataset
python scripts/prepare_dataset.py --data-dir data/raw --output-dir data --validate --copy

# Train and evaluate
python scripts/train.py --data configs/dataset.yaml --model yolov8n --epochs 100
python scripts/evaluate.py --model models/best.pt --data configs/dataset.yaml --split test

# Run image, directory, video, or webcam inference
python scripts/inference.py --model models/best.pt --source image.jpg

For camera monitoring, copy the example camera and alert files, insert your own credentials locally, then run:

python scripts/multi_camera_surveillance.py \
  --model models/best.pt \
  --cameras configs/cameras.json \
  --alert-config configs/alerts.json

Start the API with:

MODEL_PATH=models/best.pt uvicorn api.graffiti_detector:app --host 0.0.0.0 --port 8000

See DEPLOYMENT.md for Docker instructions.

iPhone and iPad

The universal SwiftUI app in ios/GraffitiGuard runs a bundled Core ML detector entirely on-device and overlays detected regions. Export your trained weights, then regenerate the Xcode project:

python -m pip install -e ".[apple]"
python scripts/export_coreml.py --weights models/best.pt
xcodegen generate --spec ios/GraffitiGuard/project.yml

See the app README for Xcode and TestFlight instructions.

Development

ruff check .
pytest tests/ -m "not gpu"
python -m build
twine check dist/*

Author

License

Distributed under the MIT License.

Responsible Use

Comply with local privacy, surveillance, and data-retention laws. Human review should remain part of any enforcement or response process.