---
name: emoji-mosaic
description: Convert any image to emoji art — output PNG (or text grid) where each cell is the color-closest emoji from a curated palette. Tunable cell size and emoji set (food, faces, nature, geometric). Pure PIL, no ML. Use when the user asks for emoji art, "make this image out of emojis", emoji mosaic, or wants a fun social-media-ready stylization of a photo.
---


# emoji-mosaic

Turn any image into emoji art. Each cell of the output is the emoji from a curated palette whose average RGB is closest to the average RGB of that region of the input.

Pure PIL, no ML, no model downloads. Auto-installs Pillow on first run.

## Modes

- `png` (default) — render emojis onto a PNG (uses Apple Color Emoji on macOS, falls back to colored squares + glyph overlay if the emoji font fails)
- `text` — print the emoji grid to stdout (paste into Twitter/IG/Discord)

## Palettes

- `geometric` (default) — colored squares + circles, full color spectrum, most reliable color match
- `food` — fruits, veg, snacks
- `faces` — emoji facial expressions for skin-tone-ish gradients
- `nature` — plants, animals, weather

## Usage

```bash
# Single image, default settings (png, geometric, cell-size 24)
python3 scripts/mosaic.py --input photo.jpg --output mosaic.png

# Custom cell size — bigger cells = chunkier mosaic, fewer emojis
python3 scripts/mosaic.py --input photo.jpg --output mosaic.png --cell-size 48

# Text grid (no PNG, just stdout — perfect for tweets)
python3 scripts/mosaic.py --input photo.jpg --mode text --cell-size 40

# Use food palette
python3 scripts/mosaic.py --input photo.jpg --output food_mosaic.png --palette food
```

## Args

- `--input` (required) — path to input image
- `--output` (default `mosaic.png`) — output PNG (only used in png mode)
- `--cell-size` (default 24) — pixel size of each emoji cell in png mode, or count of emojis across in text mode
- `--mode` (default `png`) — `png` or `text`
- `--palette` (default `geometric`) — `geometric`, `food`, `faces`, or `nature`

## Notes

- macOS color emoji rendering via PIL can be flaky; if it errors, the script falls back to a colored-square grid with a thin glyph overlay using the system regular font. The text mode always works.
- Geometric palette gives the cleanest color reproduction — use it for "looks like the photo" results. Food/faces/nature are more stylistic.