---
name: mood-board
description: Build a polished moodboard collage from a folder of reference images. Smart non-uniform packing layout (mix of large hero + small accent cells), optional dominant-color rail along the bottom and caption strip at the top. Outputs one print-ready PNG you can post or use as a video reference. Distinct from gif-board (uniform contact sheet) — mood-board is curated, not exhaustive. Use when the user asks for a mood board, reference collage, visual brief, art direction sheet, inspiration sheet, or "build a board for this project".
---


# mood-board

Turn a folder of reference images into a single polished moodboard PNG with a smart non-uniform packing layout — one large hero cell on the left, a varied 2-column accent grid on the right. Optional caption strip across the top and a dominant-color palette rail across the bottom.

Distinct from `gif-board` (uniform contact sheet of every clip) — `mood-board` is curated, art-directed, and makes one shareable image.

## Usage

```bash
python3 scripts/board.py --input <folder> [options]
```

### Args

- `--input PATH` — folder of reference images (jpg/jpeg/png/webp). Required.
- `--output PATH` — output PNG path. Default: `<folder>_moodboard.png` next to the input folder.
- `--width N` — canvas width in px. Default: `2400`. Canvas height is 16:10 (so `1500` for default).
- `--hero-fraction F` — fraction of canvas width the hero cell occupies. Default: `0.4`.
- `--caption "TEXT"` — optional caption rendered in an 80px black strip at the top.
- `--no-rail` — skip the 60px dominant-color palette rail at the bottom.

### Examples

```bash
# Basic — pull every image in ./refs into a moodboard
python3 scripts/board.py --input ./refs

# With caption and custom output
python3 scripts/board.py --input ./refs --caption "ALBUM ART — DRAFT 1" --output board.png

# Bigger hero, no color rail, wider canvas
python3 scripts/board.py --input ./refs --hero-fraction 0.55 --width 3200 --no-rail
```

## How it works

1. Scans the `--input` folder for image files (jpg/jpeg/png/webp).
2. Shuffles, picks the first as the **hero** (fills the full left side, `hero_fraction` of canvas width).
3. Packs the remaining into a **2-column varied-height grid** on the right side. Heights are randomized within tight bounds so cells stagger naturally.
4. Optional **caption strip**: 80px black bar at top with white centered Helvetica/Menlo.
5. Optional **color rail**: extracts 8 dominant colors across all images via k-means (scikit-learn), draws a 60px striped band at the bottom.
6. Saves the composite as PNG.

Auto-installs `pillow` and `scikit-learn` on first run.

## Output

A single PNG at `--output` (default `<folder>_moodboard.png`). Print-ready — drop it into Telegram, paste into Figma, or use as a reference deck for video / cover art work.