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

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

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