word-cloud-generator

词云生成器

从文本、文件或词频字典创建美观的词云。自定义形状、颜色和字体，并导出为多种格式。

快速开始

from scripts.wordcloud_gen import WordCloudGenerator

# From text
wc = WordCloudGenerator("Python is amazing. Python is powerful. Code is fun.")
wc.generate().save("cloud.png")

# From file
wc = WordCloudGenerator.from_file("article.txt")
wc.colors("plasma").max_words(100).generate().save("cloud.png")

# From frequency dict
frequencies = {"python": 50, "code": 30, "data": 25, "analysis": 20}
wc = WordCloudGenerator(frequencies=frequencies)
wc.shape("circle").generate().save("cloud.png")

功能

• 多种输入来源：原始文本、文本文件或词频字典
• 形状选项：矩形、圆形或自定义蒙版图像
• 配色方案：20 多种 matplotlib 颜色映射或自定义颜色列表
• 字体选择：使用系统字体或自定义字体文件
• 停用词过滤：内置英文停用词，并支持自定义添加
• 导出格式：PNG、SVG

API 参考

初始化

# From text string
wc = WordCloudGenerator("Your text here")

# From frequency dictionary
wc = WordCloudGenerator(frequencies={"word": count, ...})

# From file
wc = WordCloudGenerator.from_file("path/to/file.txt")

配置方法

所有方法均返回 self，支持链式调用。

# Shape options
wc.shape("rectangle")           # Default rectangle
wc.shape("circle")              # Circular cloud
wc.shape(mask="logo.png")       # Custom shape from image

# Color schemes (matplotlib colormaps)
wc.colors("viridis")            # Default
wc.colors("plasma")             # Purple-yellow gradient
wc.colors("coolwarm")           # Blue-red diverging
wc.colors("Set2")               # Categorical colors
wc.colors(custom=["#FF0000", "#00FF00", "#0000FF"])  # Custom colors

# Font settings
wc.font("/path/to/font.ttf")    # Custom font file

# Stopwords
wc.stopwords(use_default=True)                    # Use built-in stopwords
wc.stopwords(words=["custom", "words"])           # Add custom stopwords
wc.stopwords(words=["the", "and"], use_default=False)  # Only custom

# Word limits
wc.max_words(200)               # Maximum words to display (default: 200)
wc.min_word_length(3)           # Minimum word length (default: 1)

# Size
wc.size(800, 400)               # Width x Height in pixels

生成与导出

# Generate the word cloud
wc.generate()

# Save to file
wc.save("output.png")           # PNG format
wc.save("output.svg")           # SVG format (auto-detected)
wc.save("output.png", format="png")  # Explicit format

# Display (matplotlib)
wc.show()

# Get word frequencies
freqs = wc.get_frequencies()    # Returns dict of word: frequency

配色方案

常用颜色映射

名称	描述
viridis	蓝-绿-黄（默认）
plasma	紫-橙-黄
inferno	黑-红-黄
magma	黑-紫-白
cividis	蓝-黄（适合色盲人士）
coolwarm	蓝-白-红
RdYlBu	红-黄-蓝
Spectral	彩虹光谱
Set1	鲜明的分类配色
Set2	柔和的分类配色
Pastel1	柔和的分类配色
Dark2	深色分类配色

自定义颜色

# Hex colors
wc.colors(custom=["#1a1a2e", "#16213e", "#0f3460", "#e94560"])

# Named colors
wc.colors(custom=["navy", "royalblue", "cornflowerblue", "lightsteelblue"])

形状蒙版

内置形状

wc.shape("rectangle")  # Default
wc.shape("circle")     # Circular
wc.shape("square")     # Square

自定义蒙版图像

使用任何图像，只要其中的白色区域会填入文字即可：

# Use logo or shape image as mask
wc.shape(mask="company_logo.png")
wc.shape(mask="heart.png")
wc.shape(mask="map_outline.png")

蒙版图像要求：

• 白色（#FFFFFF）区域将填入文字
• 黑色或深色区域将留空
• 高对比度图像效果最佳
• 建议尺寸：800x800 像素或更大

CLI 用法

# Basic usage
python wordcloud_gen.py --text "Your text here" --output cloud.png

# From file
python wordcloud_gen.py --file article.txt --output cloud.png

# With options
python wordcloud_gen.py --file data.txt \
    --shape circle \
    --colors plasma \
    --max-words 150 \
    --output cloud.png

# Custom mask
python wordcloud_gen.py --file speech.txt \
    --mask logo.png \
    --colors Set2 \
    --output branded_cloud.png

# SVG output
python wordcloud_gen.py --text "Hello World" --output cloud.svg

CLI 参数

参数	描述	默认值
--text	输入文本字符串	-
--file	输入文本文件路径	-
--output	输出文件路径	wordcloud.png
--shape	形状：rectangle、circle、square	rectangle
--mask	自定义蒙版图像路径	-
--colors	颜色映射名称	viridis
--max-words	最大词数	200
--min-length	最小词长	1
--width	图像宽度	800
--height	图像高度	400
--font	自定义字体文件	-
--no-stopwords	禁用停用词过滤	False
--stopwords	额外停用词（以逗号分隔）	-

示例

基础词云

text = """
Python is a versatile programming language. Python is used for web development,
data science, machine learning, and automation. Python's simplicity makes it
perfect for beginners while its power serves experts.
"""

wc = WordCloudGenerator(text)
wc.colors("plasma").generate().save("python_cloud.png")

基于词频的词云

# Word frequencies from analysis
tech_terms = {
    "Python": 100,
    "JavaScript": 85,
    "Machine Learning": 70,
    "API": 65,
    "Database": 60,
    "Cloud": 55,
    "DevOps": 45,
    "Kubernetes": 40,
    "Docker": 38,
    "React": 35
}

wc = WordCloudGenerator(frequencies=tech_terms)
wc.shape("circle").colors("Set2").generate().save("tech_cloud.png")

品牌词云

# Use company logo as mask
wc = WordCloudGenerator.from_file("company_values.txt")
wc.shape(mask="logo_white_bg.png")
wc.colors(custom=["#003366", "#0066cc", "#3399ff"])
wc.font("/fonts/OpenSans-Bold.ttf")
wc.generate().save("branded_cloud.png")

文章分析

# Analyze article removing common words
wc = WordCloudGenerator.from_file("news_article.txt")
wc.stopwords(words=["said", "according", "reported"])  # Add domain stopwords
wc.min_word_length(4)
wc.max_words(100)
wc.colors("RdYlBu")
wc.generate().save("article_themes.png")

# Get top words
top_words = wc.get_frequencies()
for word, freq in list(top_words.items())[:10]:
    print(f"{word}: {freq}")

依赖项

wordcloud>=1.9.0
matplotlib>=3.7.0
Pillow>=10.0.0
numpy>=1.24.0

局限性

• SVG 导出是由 PNG 转换而来（并非原生矢量格式）
• 处理超长文本可能较慢
• 自定义字体必须为 TrueType（.ttf）或 OpenType（.otf）
• 蒙版图像使用简单、高对比度的形状效果最佳