---
name: wallpaper-gen
description: Generate procedural desktop wallpapers — pure Python + PIL, no AI. Pick a color or list of hex codes, choose a style (gradient, mesh-blur, noise-grain, ascii-stripes, scanlines), optionally add a centerpiece (circle/ring/triangle). Output is a 5K (5120x2880) PNG ready to drop into System Settings → Wallpaper. Pairs cleanly with palette-rip — extract a palette from a reference image, then generate wallpapers in that palette. Use when the user asks for a wallpaper, desktop background, lock screen, or wants minimalist abstract art they can use as a bg.
---


# wallpaper-gen

Procedural desktop wallpaper generator. Pure Python + PIL. No AI, no asset scraping — just math, color, and grain.

## Usage

```bash
python3 scripts/gen.py --colors "#1a1a1a,#ff3b30" --style gradient --output ~/Desktop/wp.png
```

## Flags

- `--colors` — comma-separated hex list (1-N colors). Examples: `#ff3b30` or `#000,#ff3b30,#ffe600`.
- `--style` — one of:
  - `gradient` — smooth linear blend across the color list
  - `mesh` — soft gaussian color blobs layered (perlin-ish)
  - `noise` — solid base + per-pixel additive grain
  - `ascii-stripes` — gradient bg + horizontal ASCII glyph stripes at low alpha
  - `scanlines` — gradient bg + thin black horizontal lines every N rows
- `--size` — `WxH`, default `5120x2880` (5K, fits 16:9 retina displays)
- `--centerpiece` — `none` (default) | `circle` | `ring` | `triangle`. Drawn dead-center, accent = first color in the list.
- `--output` — output PNG path (required)

## Examples

Minimalist red-on-black gradient:
```bash
python3 scripts/gen.py --colors "#000000,#ff3b30" --style gradient --output ~/Desktop/red.png
```

Mesh blur from a palette-rip palette:
```bash
python3 scripts/gen.py --colors "#0a0a0a,#1f3b73,#ff7f50,#ffe6a8" --style mesh --output ~/Desktop/mesh.png
```

ASCII stripe wallpaper with ring centerpiece:
```bash
python3 scripts/gen.py --colors "#0d0d0d,#7cffb2" --style ascii-stripes --centerpiece ring --output ~/Desktop/ascii.png
```

Scanline lockscreen at 1080p:
```bash
python3 scripts/gen.py --colors "#101010,#ff003c" --style scanlines --size 1920x1080 --output ~/Desktop/scan.png
```

## Pairs with

- **palette-rip** — extract a palette from a reference image, pipe its hex codes into `--colors`.
- **cover-art** — use a wallpaper as a base, then drop typography on top.

## Output

Single PNG at the requested size. Drop into macOS System Settings → Wallpaper, or use as a lock screen / iPad / phone bg by adjusting `--size`.