wordcloud-generator

Word Cloud Generator

A word cloud generation skill built from first principles. Rather than just handing you a script, it bakes in the understanding of "what a word cloud actually is, and why most people fail on their first attempt at a shaped word cloud," so that any shape and any data can reliably produce an image.

First Principles

1. What a word cloud is: a layout problem of "determining font size by weight and packing words into a canvas." Large words are placed first, spiraling outward from the center; font size = weight (frequency/importance).
2. What a mask is: a binary canvas that constrains "where words can land."
3. The one key pitfall (must-read)：wordcloud 1.9.x treats the mask asbaseline offsetconsumption— img_array = img_grey + (mask==255). The sampler prefers regions with the "lowest accumulated occupancy," so words actually land where mask==0 .Conclusion: to make words fill a shape, the shape interior must be set to 0 and the exterior to 255. The intuitive "mask==255 is the shape interior" is wrong; doing it the other way yields a hollow outline.
4. Coloring: each word can be bound to a category and colored by category (color_func); if there is no category, use a colormap.
5. Density: when there are few words, enable repeat=True to let small words fill the gaps, so the shape can be filled (a word cloud is not a solid block; the shape is already formed once internal text coverage is around 30%).

When to use

• "Make a word cloud" "turn these keywords into a word cloud"
• "arrange the text into a heart/circle/star shape" "shaped word cloud"
• "visualize this pile of high-frequency words/keywords/countries/tags"
• When there is no dedicated word cloud skill on this machine, generate directly with Python (no internet required)

How to use

Dependencies (one-time):pip install wordcloud matplotlib numpy pillow jieba; automatic photo cutout (optional) requires pip install "rembg[cpu,cli]"

python scripts/wordcloud_gen.py --input data.json --shape heart --output out.png

--input Supports two formats:

• .json：[{"word","weight","category"?}], or {词: 权重}, or {词: {weight, category}}
• .txt: raw text, automatically tokenized and counted (use jieba if available, otherwise regex splitting)

.txt Advanced parameters for.json mode (not effective in

• --stopwords 停用词.txt: one word per line, removed after tokenization (filter out function words of two or more characters such as "we/have not/because"—single-character function words like "of/了" are already filtered automatically); automatically merges wordcloud's built-in English stop words.
• --userdict 词典.txt: jieba custom dictionary (one per line 词 词频 词性), so that proper nouns like "socialism with Chinese characteristics" are not split apart.

# 原始文本 → 爱心词云（过滤虚词 + 保留专有名词）
python scripts/wordcloud_gen.py --input speech.txt --shape heart \
  --stopwords stopwords.txt --userdict userdict.txt --output out.png

--shape: 14 built-in templates, no external images needed:

Category	Shape	Description
Basic	heart / circle / star	Heart, circle, five-pointed star
Geometric	diamond / triangle / pentagon / hexagon	Diamond, triangle, regular pentagon, regular hexagon
Icons	ring / cloud / drop / arrow	Ring, cloud, water drop, upward arrow
Text mask	text + --text "中国"	Text as shape (Weici Cloud "Custom Text"), Chinese or English, 1–3 characters is best
Rectangle	rect + --width 16 --height 9	PPT-ratio rectangle (16:9, etc.)
Custom	custom + --mask 图片.png	Any image mask (white background with black shape / black background with white shape / transparent PNG all work; orientation is detected automatically)

Chinese text mask warning CJK characters have thin strokes and lots of blank space inside the glyph; in a 1000×1000px mask, stroke widths are only 8–40px, so the word cloud can only fit extremely tiny words (font-size 2–6), and the maximum stroke-area coverage is ~50%, consisting only of tiny scattered dots. fill_holes=True will also fill in the blank spaces inside the characters, turning four characters into four solid blocks, making the original characters unrecognizable. For Chinese scenarios, the "Brand Big Text" mode is recommended(see below) instead of a text mask.

Other common parameters:--colors cat.json(category→[r,g,b]),--colormap viridis、 --background white|black|transparent|任意颜色、--min-font 6、--max-font 100、 --repeat/--no-repeat、--title "说明文字"、--font 字体路径。

Brand Big Text mode (recommended approach for Chinese brand word clouds)

When you need to highlight Chinese brand names such as "Deheng Wuxi", "Tencent", or "Alibaba",do not use a text mask(for the physical limits of CJK text masks, see references/wordcloud-principles.md Section 11）。

Correct approach: make the brand name a word with overwhelming weight, and use rect or circle to build a dense cloud without a mask:

# 1. 在 JSON 里让品牌名权重 > 400（其他词 10–30）
#    品牌名自动成为最大最突出的视觉锚点
[
  {"word": "德恒无锡", "weight": 600, "category": "品牌"},
  {"word": "跨境投资与并购", "weight": 30, "category": "涉外优势"},
  ...
]

# 2. 纯白底、高密度、品牌红
python scripts/wordcloud_gen.py \
  --input brand.json --shape rect \
  --colors categories.json \
  --min-font 2 --max-font 140 --max-words 3000 \
  --background white --repeat \
  --output brand-cloud.png

Effect comparison：

Approach	Four characters visible	Layout density	Recommended
Text mask --shape text --text "德恒无锡"	❌ Blurry mess	~20%	Not recommended for CJK
Custom mask --shape custom --mask 图片	❌ Hit or miss	~30%	Recommended for English only
Brand Big Text --shape rect + high weight	✅ Clear and readable	~35%	Recommended (CJK)
Circle --shape circle + high weight	✅ Clear and readable	~30%	Recommended

• Background: For Chinese brand materials, prefera pure white background（--background white). Dark backgrounds suit tech/entertainment scenarios, while lawyer/enterprise/government materials should use white backgrounds.

• Mask orientation (when--shape custom )：--mask-mode auto|light|dark|alpha, default auto automatically detects the image orientation (see above).light= light background with dark shape,dark= dark background with light shape,alpha= transparent PNG uses the opaque area as the shape. Specify manually only when automatic detection is wrong.

• Automatic photo cutout (--auto-cutout）: When you provide anordinary photo(person/object with a cluttered background) rather than a clean silhouette, add --auto-cutout to have the script first use rembg to automatically cut it out into a transparent PNG, then use it as the mask—all in one step.rembg If not installed, it automatically warns and falls back to the original image. The first run downloads the model (~170MB, cached in ~/.u2net）。

• --colors prerequisite for taking effect: Colors are applied by category only when the data has a category field; when the data has no category , this parameter is ignored and colors are instead taken by word order via --colormap .

• Input tolerance: missing word, non-numeric weight, non-positive weight entries are automatically skipped with a warning printed, without interrupting the entire generation; when all are invalid, "no words found" is given.

• --colormap is invalid: automatically falls back to tab10 and warns, without crashing.

• Named themes (--theme, Micro Word Cloud "Themes"): 11 preset color schemes, switch styles with one click. When categorical data is present, overrides the category palette; when absent, overrides the colormap.

  Theme	Style	Use case
  rainbow	Rainbow gradient	Festive, lively
  warm / sunset	Warm/sunset	Celebration, year-end
  cool / ocean	Cool/ocean	Business, professional
  forest	Forest green	Eco-friendly, natural
  festive	Multicolor clash	Festive posters
  mono	Grayscale monochrome	Reports, papers
  business	Business blue	Corporate reports
  lucky	Chinese red-gold	Spring Festival, celebrations

• Chinese-English bilingual (--lang）：

  • auto(default): jieba word segmentation (handles mixed Chinese + English text), filtering both Chinese stopwords + English stopwords
  • zh: forces Chinese mode, loading Chinese stopwords (的/了/是/在/因为 etc., ~80 high-frequency function words)
  • en: English regex tokenization + automatic lowercasing + English stopword filtering (suitable for pure English text)
  • .json mode is unaffected (every word the user explicitly lists is kept)

Examples

Text mask (Chinese "中国" + lucky theme):

python scripts/wordcloud_gen.py \
  --input data.json --shape text --text "中国" \
  --theme lucky --output wordcloud-china.png

English circular word cloud (lang=en auto-lowercase):

python scripts/wordcloud_gen.py \
  --input speech.txt --shape circle --lang en \
  --theme ocean --output wordcloud-en.png

PPT 16:9 rectangular template (report keyword cloud):

python scripts/wordcloud_gen.py \
  --input report.json --shape rect --width 16 --height 9 \
  --theme business --output wordcloud-ppt.png

Photo cutout → word cloud (all in one step):

python scripts/wordcloud_gen.py \
  --input data.json --shape custom \
  --mask 人物照片.jpg --auto-cutout \
  --theme warm --output wordcloud-photo.png

Recreate this 53-country heart word cloud (Europe blue/Asia-Pacific green/Americas red/Middle East dark blue/others gray):

Examples

Recreate this 53-country heart word cloud (Europe blue/Asia-Pacific green/Americas red/Middle East dark blue/others gray):

python scripts/wordcloud_gen.py \
  --input references/example-53countries.json \
  --shape heart --repeat \
  --output wordcloud-heart-53countries.png \
  --title "Cross-Border Compliance · 可查法域 53 国"

One-click photo cutout into a word cloud: --auto-cutout lets rembg remove the background first

python scripts/wordcloud_gen.py
--input data.json --shape custom
--mask person photo.jpg --auto-cutout
--output wordcloud-photo.png

In depth

Source-level evidence of mask semantics, shape generation mathematics, color and density tuning, and "how to programmatically verify whether the finished product is a solid shape", see references/wordcloud-principles.md。