README.md

---
title: ImageMosaicGenerator
emoji: 🏆
colorFrom: green
colorTo: pink
sdk: gradio
sdk_version: 5.45.0
app_file: app.py
pinned: false
---

# Image Mosaic Generator

Turn any image into a photomosaic composed of color-matched tiles while collecting detailed performance metrics. This Gradio app ships with built-in benchmarking tools, profiling utilities, and reproducible analysis documented in `profiling_analysis.ipynb`.

## Features

- **Interactive mosaic builder** with selectable grid size, color palette, and reference image size.
- **Performance benchmark tab** that sweeps multiple configurations, plots the results, and logs cProfile + line_profiler stats.
- **Automatic tile caching & vectorized mapping** for sub-second generation on 1024×1024 inputs.
- **Validation & error messaging** to catch invalid grid/image combinations before processing.

## Installation

```bash
# clone the repository
 git clone https://huggingface.co/spaces/meryadri/ImageMosaicGenerator
 cd ImageMosaicGenerator

# create and activate a virtual environment (optional but recommended)
 python3 -m venv venv
 source venv/bin/activate  # Windows: venv\Scripts\activate

# install dependencies
 pip install -r requirements.txt
```

## Usage

### Local Gradio app

```bash
python app.py
```

Visit `http://127.0.0.1:7860` and either upload an image or choose one of the curated examples. Ensure the selected grid size divides the target image size (e.g., 512px image with 32×32 grid) for best results.

### Command-line benchmarking

The easiest way to reproduce the profiling numbers is to run the Performance Benchmark tab once. The first pass warms the tile cache; subsequent runs deliver the <10ms timings shown in the notebook.

## Deployed Demo

The project is available as a Hugging Face Space: [ImageMosaicGenerator](https://huggingface.co/spaces/meryadri/ImageMosaicGenerator). The space automatically stays in sync with this repository.

## Profiling Report

See [`profiling_analysis.ipynb`](profiling_analysis.ipynb) for:

- benchmark data (before/after speedups)
- cProfile summaries & line-profiler excerpts
- discussion of optimized bottlenecks (tile caching, vectorized grid processing, preprocessing reuse)

## Contributing

1. Fork the repository and open a feature branch.
2. Run `python app.py` and ensure both Gradio tabs still function.
3. Update the profiling notebook or README if your change affects performance.
4. Submit a pull request with a brief summary of the improvement.

## License

This project inherits the usage terms of the Hugging Face Space it powers. Refer to the Space card for additional information.