-update readme

README.md

@@ -1,229 +1,11 @@
-# 🎨 Mosaic Generator
+---
+title: Mosaic Generator
+emoji: 🧩
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+app_file: run_app.py   # use this since you recommend run_app.py
+pinned: false
+---
 
-A comprehensive mosaic generation system that transforms images into beautiful mosaic-style reconstructions using advanced image processing techniques.
 
-## Features
-
-### Core Functionality
-- **Image Preprocessing**: Automatic resizing and cropping to fit grid requirements
-- **Color Quantization**: Optional uniform and K-means quantization for simplified color variations
-- **Grid Analysis**: Efficient vectorized NumPy operations for analyzing image grid cells
-- **Tile Mapping**: Replace grid cells with matching image tiles from Hugging Face datasets
-- **Quality Metrics**: Comprehensive similarity analysis using MSE, PSNR, SSIM, and color metrics
-
-### Performance Features
-- **Vectorized Operations**: NumPy-based efficient processing for optimal performance
-- **Implementation Comparison**: Side-by-side comparison of vectorized vs loop-based methods
-- **Grid Size Benchmarking**: Performance analysis across different grid resolutions
-- **Real-time Metrics**: Live processing time and quality measurements
-
-### User Interface
-- **Interactive Gradio Interface**: Easy-to-use web interface with parameter controls
-- **Real-time Preview**: Instant visualization of mosaic generation results
-- **Performance Analysis**: Built-in benchmarking tools for optimization
-- **Comprehensive Settings**: Fine-grained control over all generation parameters
-
-## Installation
-
-1. Clone the repository:
-```bash
-git clone <repository-url>
-cd Mosaic_Generator
-```
-
-2. Install dependencies:
-```bash
-pip install -r requirements.txt
-```
-
-3. (Optional) Login to Hugging Face for dataset access:
-```bash
-huggingface-cli login
-```
-
-That's it! No setup script needed - just install the requirements and you're ready to go.
-
-## Usage
-
-### Running the Application
-
-Start the Gradio interface:
-```bash
-python run_app.py
-```
-
-The application will launch at `http://localhost:7860` with a comprehensive web interface.
-
-**Important**: Use `python run_app.py` instead of `python app.py` to prevent the dataset from being downloaded every time you upload an image. The `run_app.py` script disables auto-reload which causes the constant re-downloading.
-
-**Note**: The first time you generate a mosaic, the app will load tiles from Hugging Face (this takes a few moments). Subsequent generations will be much faster as tiles are cached. To pre-load tiles for faster startup, run:
-```bash
-python preload_tiles.py
-```
-
-### Using the Interface
-
-1. **Upload an Image**: Click on the image upload area and select your input image
-2. **Configure Parameters**:
-   - **Basic Settings**: Adjust grid size, tile size, and output resolution
-   - **Advanced Settings**: Choose implementation method, color matching space, and quantization options
-3. **Generate Mosaic**: Click "Generate Mosaic" to create your mosaic
-4. **View Results**: See the generated mosaic alongside quality metrics and processing information
-
-### Performance Analysis
-
-Use the "Performance Analysis" tab to:
-- Compare vectorized vs loop-based implementations
-- Benchmark different grid sizes
-- Analyze performance scaling characteristics
-
-### Command Line Benchmarking
-
-Run comprehensive benchmarks:
-```bash
-python benchmark.py --grid-sizes 16 32 48 64 --output-dir images
-```
-
-## Technical Architecture
-
-### Core Components
-
-1. **MosaicGenerator** (`src/mosaic.py`): Main mosaic generation engine
-2. **TileManager** (`src/tiles.py`): Manages tile collection and matching
-3. **Color Quantization** (`src/quantization.py`): Implements uniform and K-means quantization
-4. **Similarity Metrics** (`src/metrics.py`): Comprehensive quality assessment
-5. **Pipeline** (`src/pipeline.py`): Orchestrates the complete generation process
-6. **Configuration** (`src/config.py`): Centralized parameter management
-
-### Key Algorithms
-
-#### Grid Analysis
-- **Vectorized Operations**: Uses NumPy's `block_view` for efficient grid cell analysis
-- **Color Matching**: Supports both RGB (euclidean) and LAB (perceptual) color spaces
-- **Performance Optimization**: Vectorized operations provide significant speedup over loops
-
-#### Tile Matching
-- **Color Space Conversion**: Perceptual matching in LAB color space
-- **Distance Metrics**: Euclidean distance for optimal tile selection
-- **Brightness Normalization**: Optional tile brightness standardization
-
-#### Quality Assessment
-- **MSE/PSNR**: Standard pixel-wise similarity metrics
-- **SSIM**: Structural similarity for perceptual quality
-- **Color Analysis**: Histogram correlation and channel-specific metrics
-
-## Configuration Options
-
-### Grid Settings
-- **Grid Size**: 8×8 to 128×128 tiles (default: 32×32)
-- **Tile Size**: 16×16 to 64×64 pixels (default: 32×32)
-- **Output Resolution**: Customizable output dimensions
-
-### Processing Options
-- **Implementation**: Vectorized (recommended) or loop-based
-- **Color Matching**: LAB (perceptual) or RGB (euclidean)
-- **Quantization**: Uniform or K-means color reduction
-- **Tile Processing**: Optional brightness normalization
-
-### Dataset Configuration
-- **Tile Source**: Hugging Face "Kratos-AI/KAI_car-images" dataset
-- **Tile Limit**: Configurable number of tiles to load (default: 200 for better quality)
-- **Caching**: Tiles are cached after first load for faster subsequent use
-- **Streaming**: Uses streaming dataset loading to avoid downloading full dataset
-- **Fallback Tiles**: Extensive color palette (40+ colors) if dataset unavailable
-
-## Performance Characteristics
-
-### Scalability
-- **Linear Scaling**: Processing time scales linearly with number of tiles
-- **Memory Efficient**: Vectorized operations minimize memory overhead
-- **Optimized Algorithms**: NumPy-based implementations for maximum performance
-
-### Benchmark Results
-Typical performance on modern hardware:
-- **32×32 grid**: ~1-3 seconds processing time (optimized)
-- **64×64 grid**: ~3-8 seconds processing time (optimized)
-- **Vectorized vs Loops**: 3-10x speedup factor
-- **Tile matching**: Optimized with scipy and pre-computed LAB colors
-
-### Quality Metrics
-- **High SSIM**: Maintains structural similarity (>0.8 for most images)
-- **Low MSE**: Minimal pixel-wise error (<0.05 for quality reconstructions)
-- **Color Accuracy**: Good histogram correlation (>0.7)
-
-## Assignment Requirements Compliance
-
-✅ **Step 1: Image Selection and Preprocessing**
-- Automatic image resizing and cropping
-- Optional color quantization (uniform and K-means)
-- Grid-compatible resolution adjustment
-
-✅ **Step 2: Image Grid and Thresholding**
-- Configurable grid division (8×8 to 128×128)
-- Vectorized NumPy operations for performance
-- Intensity and color analysis per grid cell
-
-✅ **Step 3: Tile Mapping**
-- Hugging Face dataset integration for tile sources
-- Intelligent tile matching based on color similarity
-- Configurable tile sizes and processing options
-
-✅ **Step 4: Gradio Interface**
-- Comprehensive web interface with parameter controls
-- Real-time mosaic generation and preview
-- User-friendly parameter adjustment
-
-✅ **Step 5: Performance Metrics**
-- MSE (Mean Squared Error) calculation
-- SSIM (Structural Similarity Index) assessment
-- Additional metrics: PSNR, RMSE, MAE, color analysis
-
-✅ **Step 6: Performance Analysis**
-- Grid size benchmarking (16×16, 32×32, 64×64)
-- Implementation comparison (vectorized vs loops)
-- Performance scaling analysis and reporting
-
-## File Structure
-
-```
-Mosaic_Generator/
-├── app.py                 # Main application entry point
-├── run_app.py            # Recommended way to run the app (no auto-reload)
-├── benchmark.py           # Command-line benchmarking tool
-├── example.py             # Example usage demonstration
-├── preload_tiles.py       # Pre-load tiles for faster startup
-├── requirements.txt       # Python dependencies
-├── README.md             # This file
-├── src/                  # Source code directory
-│   ├── __init__.py       # Package initialization
-│   ├── config.py         # Configuration management
-│   ├── mosaic.py         # Core mosaic generation
-│   ├── tiles.py          # Tile management system
-│   ├── quantization.py   # Color quantization algorithms
-│   ├── metrics.py        # Similarity metrics
-│   ├── pipeline.py       # Complete generation pipeline
-│   ├── utils.py          # Utility functions
-│   └── gradio_interface.py # Gradio interface implementation
-├── helpers/              # Helper utilities
-│   └── download_tiles.py # Tile download utilities
-└── images/               # Output directory for generated images
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-## License
-
-This project is part of CS5130 coursework and follows academic integrity guidelines.
-
-## Acknowledgments
-
-- Hugging Face for providing the tile dataset
-- Scikit-image for image processing utilities
-- Gradio for the web interface framework
-- NumPy and PIL for efficient image manipulation