README.md

metadata

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

# 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

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. The space automatically stays in sync with this repository.

Profiling Report

See 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.