Watercolor Header Image Generator

Watercolor Header Image Generator

Generate header images for note.com articles using Pillow-based text overlay on a background template. Supports Japanese text with automatic word wrapping.

---

Overview

Creates article header images by compositing text (tag + title) onto a background image template. Zero API cost, instant generation, deterministic output. Designed for note.com's 1280x670 recommended eyecatch dimensions but works for any size.

---

Prerequisites

• Pillow (pip install Pillow)
• A background image template (PNG or JPG, 1280x720 recommended). You provide your own.
• Japanese font available on the system (auto-detected via fallback chain)

---

Usage

Basic (title only)

python generate_header.py \
    --title "記事タイトル" \
    --background /path/to/background.png \
    --output header.jpg

With tag

python generate_header.py \
    --title "ChatGPTのカスタム指示に設定すべき8つのプロンプト" \
    --tag "【完全解説】" \
    --background /path/to/background.png \
    --output header.jpg

Custom colors

python generate_header.py \
    --title "記事タイトル" \
    --background /path/to/background.png \
    --output header.jpg \
    --tag-color "16,16,16" \
    --title-color "232,146,27"

Custom dimensions

python generate_header.py \
    --title "記事タイトル" \
    --background /path/to/background.png \
    --output header.jpg \
    --width 1920 \
    --height 1080

---

CLI Arguments

Argument	Required	Default	Description
--title	Yes	—	Article title text (Japanese)
--background	Yes	—	Path to background image file
--output	Yes	—	Output file path (.jpg or .png)
--tag	No	None	Bracketed tag text, e.g. "【完全解説】"
--tag-color	No	16,16,16	Tag text RGB color (comma-separated)
--title-color	No	255,255,255	Title text RGB color (comma-separated)
--width	No	1280	Output image width in pixels
--height	No	720	Output image height in pixels

---

How It Works

1. Load background: Opens the background image and resizes to target dimensions using Lanczos resampling.
2. Find font: Searches a fallback chain of Japanese fonts (macOS Hiragino, Linux NotoSansCJK, local fonts directory).
3. Draw tag: Renders the tag text (if provided) at the top-left position in the tag color.
4. Wrap title: Automatically wraps the title text to fit within the maximum width, breaking at natural Japanese break points (particles, punctuation).
5. Draw title: Renders each line of the wrapped title below the tag.
6. Save: Exports as JPEG (quality 92) or PNG depending on the output file extension.

---

Background Template

You provide your own background image. Recommendations:

• Dimensions: 1280x720 (16:9) for note.com eyecatch, or 1920x1080 for general use
• Format: PNG (for transparency) or JPG
• Design: Should have a text-safe area on the left side where the title will be rendered
• Branding: Pre-bake any logos or decorative elements into the background image

The script resizes the background to match --width and --height, so the background does not need to be exactly the target size.

---

Font Fallback Chain

The script searches for Japanese fonts in this order:

1. macOS: /System/Library/Fonts/ヒラギノ角ゴシック W9.ttc (extra bold)
2. macOS fallback: /System/Library/Fonts/ヒラギノ角ゴシック W7.ttc (bold)
3. Linux: /usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc
4. Local fallback: {workspace}/.tmp/fonts/ directory (for custom font installs)

Installing Fonts on Linux (VPS)

If no system Japanese font is available:

# Option A: Install Noto CJK fonts
sudo apt install -y fonts-noto-cjk

# Option B: Download a font manually
mkdir -p /path/to/workspace/.tmp/fonts
# Place .ttf or .ttc files in this directory

---

Japanese Word Wrapping

The wrap algorithm breaks text at natural Japanese boundary points:

• Break-after characters: の, を, に, は, で, が, と, も, や, 、, 。, ？, ！, ：
• Fallback: If no natural break point is found within the last 6 characters of the line, breaks at the pixel-width boundary

This produces visually natural line breaks that respect Japanese grammar, unlike character-count-based wrapping which can break in the middle of words.

---

Customization Guide

Text Layout Constants (in the script)

Constant	Default	Description
TAG_SIZE	48	Tag font size in pixels
TAG_POS	(50, 85)	Tag position (x, y) from top-left
TITLE_SIZE	62	Title font size in pixels
TITLE_POS_X	50	Title left margin
TITLE_POS_Y	170	Title top position (below tag)
TITLE_MAX_WIDTH	1020	Maximum title width in pixels before wrapping
TITLE_LINE_SPACING	1.45	Line spacing multiplier

Adjust these values in the script to match your background template's text-safe area.

---

Integration with Pipelines

In an automated article pipeline, call the header generator after the article is written:

# In your pipeline shell script or Claude Code prompt
python3 /path/to/generate_header.py \
    --title "$ARTICLE_TITLE" \
    --tag "$TAG" \
    --background /path/to/background.png \
    --output "$PROJECT_DIR/.tmp/$DATE/header.jpg"

The generated image can then be uploaded to note.com as the eyecatch image via the note.com publisher.

---

Header generator based on production image pipelines generating daily article headers.