🎨 Graffiti App - AI-Powered Image Tagging Tool

Transform your image collection with intelligent AI-generated descriptions and hashtags

Features • Installation • Usage • Configuration • Contributing

---

📖 About

Graffiti App is a powerful, user-friendly desktop application that leverages cutting-edge AI technology to automatically generate comprehensive descriptions and relevant hashtags for your images. Whether you're a content creator, social media manager, or just someone looking to organize their photo collection, Graffiti App streamlines the process of image tagging with support for multiple AI providers.

🎯 Why Graffiti App?

• Multi-AI Support: Works seamlessly with Ollama, LMStudio, and OpenAI API
• Batch Processing: Handle hundreds of images efficiently
• Smart Analysis: Generate detailed descriptions and contextual hashtags
• User-Friendly Interface: Intuitive PyQt6-based GUI with dark theme
• Flexible Configuration: Customize AI models and processing parameters
• Metadata Integration: Automatically saves tags and descriptions to image metadata

---

✨ Features

🖼️ Image Processing

• Batch Processing: Select and process multiple images simultaneously
• Smart Thumbnails: Preview images with zoom functionality
• Progress Tracking: Real-time processing status and progress bars
• Error Handling: Robust error management with retry mechanisms

🤖 AI Integration

• Multiple Providers:
  • 🦙 Ollama - Local AI models (llava, bakllava, etc.)
  • 🏠 LMStudio - Local model hosting
  • 🌐 OpenAI - GPT-4 Vision API
• Comprehensive Analysis: Detailed scene descriptions, object detection, and context understanding
• Smart Hashtag Generation: Relevant, trending hashtags based on image content

🎨 User Interface

• Modern Dark Theme: Easy on the eyes with professional aesthetics
• Intuitive Layout: Clean, organized interface with logical workflow
• Image Grid View: Visual thumbnail grid with selection capabilities
• Settings Management: Persistent configuration with easy access

⚙️ Advanced Features

• Memory Management: Automatic Ollama memory clearing for optimal performance
• Concurrent Processing: Multi-threaded processing for faster results
• Health Monitoring: AI service health checks and status indicators
• Metadata Writing: Automatic saving of descriptions and hashtags to image files

---

🚀 Installation

Prerequisites

• Python 3.8+ installed on your system
• pip (Python package installer)
• At least one AI provider configured (Ollama, LMStudio, or OpenAI API)

Step 1: Clone the Repository

git clone https://github.com/Massivemiike/Graffiti/graffiti-app.git
cd graffiti-app

Step 2: Install Dependencies

Option A: Using requirements.txt (Recommended)

pip install -r requirements.txt

Option B: Manual Installation

pip install PyQt6>=6.4.0 requests>=2.28.0

Dependencies Overview

• PyQt6 (>=6.4.0) - Modern GUI framework for the user interface
• requests (>=2.28.0) - HTTP library for API communications with AI providers

All other dependencies are part of Python's standard library.

Step 3: Set Up AI Provider

⚠️ Hardware Requirements: Vision models require significant computational resources. Consider your hardware limitations when choosing models:

• QWEN2.5VL:7b: Requires ~8GB RAM, recommended for most users
• Llama3.2-Vision: Requires ~4-6GB RAM, lighter alternative
• GPU acceleration highly recommended for better performance

Choose one or more of the following options:

---

🐋 Option A: Ollama with Docker (Recommended)

Windows Setup

Prerequisites

• Docker Desktop for Windows
• Windows 10/11 with WSL2 enabled

Installation Steps

1. Install Docker Desktop

   # Download and install Docker Desktop from the official website
   # Ensure WSL2 integration is enabled

2. Run Ollama Container with Network Access

   # Pull and run Ollama container
   docker run -d --name ollama -p 11434:11434 -v ollama:/root/.ollama ollama/ollama
   
   # Verify container is running
   docker ps

3. Pull Recommended Vision Models

   # Option 1: QWEN2.5VL:7b (Recommended for most users)
   docker exec -it ollama ollama pull qwen2.5-vl:7b
   
   # Option 2: Llama3.2-Vision (Lighter alternative)
   docker exec -it ollama ollama pull llama3.2-vision

4. Configure Network Access

   # Set environment variable for network binding
   docker exec -it ollama sh -c 'export OLLAMA_HOST=0.0.0.0:11434'
   
   # Restart container to apply changes
   docker restart ollama

Linux Setup

Prerequisites

• Docker installed (Installation Guide)
• NVIDIA Docker runtime (for GPU support) - Setup Guide

Installation Steps

1. Install Docker (if not already installed)

   # Ubuntu/Debian
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   
   # Add user to docker group
   sudo usermod -aG docker $USER
   newgrp docker

2. Run Ollama Container with GPU Support

   # With GPU support (recommended)
   docker run -d --gpus all --name ollama -p 11434:11434 -v ollama:/root/.ollama ollama/ollama
   
   # Without GPU (CPU only)
   docker run -d --name ollama -p 11434:11434 -v ollama:/root/.ollama ollama/ollama

3. Pull Recommended Vision Models

   # Option 1: QWEN2.5VL:7b (Recommended for most users)
   docker exec -it ollama ollama pull qwen2.5-vl:7b
   
   # Option 2: Llama3.2-Vision (Lighter alternative)
   docker exec -it ollama ollama pull llama3.2-vision

4. Configure Network Access

   # Create environment file
   echo "OLLAMA_HOST=0.0.0.0:11434" > ollama.env
   
   # Restart container with environment file
   docker stop ollama
   docker rm ollama
   docker run -d --gpus all --name ollama -p 11434:11434 --env-file ollama.env -v ollama:/root/.ollama ollama/ollama

Verification

# Test Ollama is accessible
curl http://localhost:11434/api/tags

# Test from another machine (replace YOUR_IP with your machine's IP)
curl http://YOUR_IP:11434/api/tags

---

🖥️ Option B: LMStudio (User-Friendly GUI)

Installation

1. Download LMStudio

   • Visit LMStudio.ai
   • Download the appropriate version for your OS
   • Install following the setup wizard

2. Download Recommended Models

   Method 1: Through LMStudio Interface

   • Open LMStudio
   • Navigate to the "Discover" tab
   • Search for and download:
     • qwen2.5-vl-7b-instruct (Recommended)
     • llama-3.2-11b-vision-instruct (Alternative)

   Method 2: Direct Model Links

   • QWEN2.5VL:7b on Hugging Face
   • Llama3.2-Vision on Hugging Face

3. Configure Local Server

   Step-by-Step Setup:

   1. Open LMStudio
   2. Go to "Local Server" tab
   3. Select your downloaded vision model
   4. Configure server settings:
      - Port: 1234 (default)
      - Host: 0.0.0.0 (for network access)
      - Enable CORS: ✓
   5. Click "Start Server"
   

4. Network Configuration

   {
     "server_host": "0.0.0.0",
     "server_port": 1234,
     "cors_enabled": true,
     "api_base": "http://localhost:1234/v1"
   }

5. Verify Installation

   # Test local access
   curl http://localhost:1234/v1/models
   
   # Test network access (replace YOUR_IP)
   curl http://YOUR_IP:1234/v1/models

---

🌐 Option C: OpenAI API (Cloud-Based)

Setup Steps

1. Get API Key

   • Visit OpenAI Platform
   • Create account or sign in
   • Generate new API key
   • ⚠️ Keep your API key secure and never share it publicly

2. Supported Models

   • gpt-4-vision-preview (Recommended)
   • gpt-4o (Latest with vision capabilities)
   • gpt-4o-mini (Cost-effective option)

3. Configuration

   {
     "provider": "openai",
     "api_key": "sk-your-api-key-here",
     "model": "gpt-4-vision-preview",
     "base_url": "https://api.openai.com/v1"
   }

---

🔧 Quick Configuration Reference

Provider	Default URL	Recommended Model	Hardware Requirements
Ollama	http://localhost:11434	qwen2.5-vl:7b	8GB+ RAM, GPU recommended
LMStudio	http://localhost:1234	qwen2.5-vl-7b-instruct	8GB+ RAM, GPU recommended
OpenAI	https://api.openai.com/v1	gpt-4-vision-preview	Internet connection + API credits

🚀 Performance Tips

• GPU Acceleration: Significantly improves processing speed
• Model Size: Larger models = better quality but slower processing
• Network Setup: Ensure firewall allows connections on configured ports
• Memory Management: Close other applications when processing large batches

---

📱 Usage

Quick Start

1. Launch the Application

   python graffiti_app.py

2. Configure Settings

   • Click the ⚙️ Settings button
   • Select your AI provider (Ollama/LMStudio/OpenAI)
   • Configure model parameters and API settings

3. Load Images

   • Click "📁 Open Folder" to select your image directory
   • Images will appear as thumbnails in the grid

4. Select and Process

   • Use checkboxes to select images for processing
   • Click "🚀 Process Selected Images"
   • Monitor progress in the status bar

Detailed Workflow

🖼️ Image Selection

• Individual Selection: Click checkboxes on specific images
• Select All: Use the "Select All" button for batch operations
• Preview: Click on any thumbnail to view full-size image

⚙️ Configuration Options

Setting	Description	Default
AI Provider	Choose between Ollama, LMStudio, or OpenAI	Ollama
Model	Specific model to use (e.g., llava, gpt-4-vision)	llava
Server URL	Local server address for Ollama/LMStudio	http://localhost:11434
API Key	OpenAI API key (if using OpenAI)	-
Timeout	Request timeout in seconds	120
Max Retries	Number of retry attempts	3

🔄 Processing Flow

1. Image Analysis: AI analyzes visual content, objects, scenes, and context
2. Description Generation: Creates detailed, natural language descriptions
3. Hashtag Creation: Generates relevant hashtags based on content
4. Metadata Writing: Saves results to image metadata
5. Progress Updates: Real-time status updates and completion notifications

---

🔧 Configuration

AI Provider Setup

Ollama Configuration

{
  "provider": "ollama",
  "model": "llava",
  "server_url": "http://localhost:11434",
  "timeout": 120
}

LMStudio Configuration

{
  "provider": "lmstudio",
  "model": "your-vision-model",
  "server_url": "http://localhost:1234",
  "timeout": 120
}

OpenAI Configuration

{
  "provider": "openai",
  "model": "gpt-4-vision-preview",
  "api_key": "your-api-key-here",
  "timeout": 60
}

Advanced Settings

• Memory Management: Automatic Ollama memory clearing between batches
• Concurrent Processing: Configurable thread pool for parallel processing
• Error Handling: Automatic retry with exponential backoff
• Health Monitoring: Service availability checks before processing

---

🎨 Screenshots

Coming soon - Screenshots will be added to showcase the beautiful interface and workflow

---

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Add docstrings to new functions and classes
• Test your changes thoroughly
• Update documentation as needed

---

📄 License

This project is currently under private development and is not seeking contribution. Code is wholly owned by Michael Wright.

---

🚀 Future Improvements

🎯 Planned Features

Enhanced AI Capabilities

• Multi-Model Ensemble: Combine results from multiple AI models for improved accuracy
• Custom Model Training: Support for fine-tuned models specific to user domains
• Batch Optimization: Smart batching algorithms for improved processing speed
• Context Awareness: Remember previous images for better contextual understanding

Advanced Image Processing

• Image Enhancement: Pre-processing filters to improve AI analysis quality
• Format Support: Extended support for RAW, HEIC, and other image formats
• Duplicate Detection: Identify and handle duplicate or similar images
• Quality Assessment: Automatic image quality scoring and filtering

User Experience Improvements

• Drag & Drop Interface: Direct file dropping for easier workflow
• Keyboard Shortcuts: Comprehensive hotkey support for power users
• Custom Themes: Multiple UI themes and customization options
• Workspace Management: Save and load different project configurations

Export & Integration

• Export Formats: CSV, JSON, XML export options for metadata
• Cloud Integration: Direct upload to social media platforms
• Database Support: SQLite/PostgreSQL integration for large collections
• API Endpoints: RESTful API for integration with other tools

Performance & Scalability

• GPU Acceleration: CUDA support for faster local processing
• Distributed Processing: Multi-machine processing capabilities
• Caching System: Intelligent result caching to avoid reprocessing
• Memory Optimization: Improved memory usage for large image sets

Analytics & Insights

• Processing Statistics: Detailed analytics on processing performance
• Tag Analytics: Insights into most common tags and descriptions
• Quality Metrics: Accuracy scoring and improvement suggestions
• Usage Reports: Comprehensive usage statistics and trends

Enterprise Features

• User Management: Multi-user support with role-based access
• Audit Logging: Comprehensive logging for enterprise compliance
• Batch Scheduling: Automated processing schedules
• Integration APIs: Enterprise system integration capabilities

---

🌟 Star this repository if you find it useful!

Made with ❤️ by the Graffiti App Team

Report Bug • Request Feature • Documentation