ClockRoss - AI-Powered Analog Clock

# ClockRoss - AI-Powered Analog Clock

A Python-based analog clock application that combines real-time clock display with AI-generated backgrounds using local Stable Diffusion via Diffusers, enhanced with ControlNet and GPT-2 prompt generation. Supports both NVIDIA (CUDA) and Apple Silicon (MPS) hardware acceleration.

## Core Components

### Clock Face and Movement
- Renders a complete analog clock face with:
  - Customizable outer circle and design elements
  - Hour markers and numerals
  - Hour, minute, and second hands with dynamic styling
  - Center decoration and additional design elements
- Clock elements are rendered in white on a transparent background
- Supports multiple movement styles and animations

### Background Generation
- Uses local Stable Diffusion via Diffusers library with ControlNet integration
- Clock face template is used as a ControlNet conditioning image
- Backgrounds refresh automatically every 20 seconds
- Supports multiple Stable Diffusion models with "revAnimated" as default
- AI-enhanced prompt generation using GPT-2
- Advanced composition control through ControlNet guidance

### Display System
- Main display resolution: 1024x600
- Generation resolution: 640x360
- Semi-transparent clock overlay (40%)
- Smooth animations and transitions
- Dynamic color adaptation
- Supports both fullscreen and windowed modes
- Automatic display scaling and positioning

### Hardware Acceleration
- Multi-platform acceleration support:
  - NVIDIA GPUs via CUDA
  - Apple Silicon via Metal Performance Shaders (MPS)
  - CPU fallback for compatibility
- Automatic device detection and configuration
- Optimized memory management for each platform
- Dynamic batch size adjustment based on available memory

## Technical Implementation

### Diffusion Pipeline
- Local image generation using Hugging Face Diffusers
- ControlNet integration for precise background control
- Platform-specific optimizations (CUDA/MPS)
- Configurable pipeline parameters via config.yaml
- Memory-optimized inference with model offloading
- Advanced composition control via ControlNet conditioning

### Prompt Generation
- Multi-stage prompt generation system:
  - Base prompt template selection
  - GPT-2 enhancement and expansion
  - Style and theme integration
  - Technical parameter adjustment
- AI-driven prompt refinement
- Customizable enhancement templates
- Consistent style maintenance across generations

### Debug Features
Debug mode (--debug flag) generates:
- Pre-render clock face images (debug_prerender_*.png)
- ControlNet conditioning images (debug_control_*.png)
- Generated backgrounds (debug_background_*.png)
- Composite debug views (debug_composite_*.png)
- Raw and enhanced prompts (debug_prompts.log)
- Performance metrics for different devices

### Project Structure
```
src/
├── clockface/          # Clock face rendering and management
├── movement/           # Clock hand movement and animations
├── settings/          # Application settings and configuration
├── utils/            # Utility functions and helpers
└── config.py         # Core configuration
```

## Setup and Configuration
- Automated setup script (setup-clockross.sh)
- Python virtual environment management
- Dependency installation via requirements.txt
- Dual configuration system:
  - Global settings via config.yaml
  - Local overrides via local_config.yaml (gitignored)
- Automatic model downloading and caching
- Hardware acceleration detection and setup
- Display mode configuration

## Configuration Files

### Global Configuration (config.yaml)
- Core application settings
- Default model parameters
- ControlNet settings
- GPT-2 configuration
- Display and animation settings
- Hardware acceleration preferences
- Window mode settings
- Debug configuration
- Default prompt templates

### Local Configuration (local_config.yaml)
- Machine-specific settings
- Local model paths (Stable Diffusion, ControlNet, GPT-2)
- Cache directory locations
- Development overrides
- Personal customizations
- Model-specific parameters
- Device-specific optimizations
- Display preferences

## Command Line Options
- --debug: Enable debug mode
- --windowed: Run in windowed mode

Hardware acceleration is automatically selected based on the available hardware:
- NVIDIA GPUs: CUDA acceleration
- Apple Silicon: MPS acceleration
- Other systems: CPU fallback

## Logging and Monitoring
The application provides detailed logging:
- Raw and enhanced prompt details
- Generation pipeline timing
- Background update status (20-second intervals)
- Performance metrics
- Debug image generation status
- Model loading and memory usage
- ControlNet conditioning status
- GPT-2 prompt enhancement details