wordcloud/backend/EfficientWordCloud/docs/usage.md

EfficientWordCloud 使用文档

1. 构建与安装

在项目根目录执行：

python setup.py build
python setup.py install

2. 基本使用示例

from efficient_wordcloud.wordcloud import EfficientWordCloud

freq = {
    "hello": 100,
    "world": 80,
    "efficient": 60,
    "wordcloud": 40
}

wc = EfficientWordCloud(
    width=800,
    height=600,
    font_path="/path/to/font.ttf",
    max_words=200,
    min_font_size=8,
    max_font_size=32,
    prefer_horizontal=0.9
)

wc.generate(freq)
img = wc.to_image()
img.show()

3. 关键参数说明

• width / height：画布尺寸。
• font_path：字体路径。
• max_words：最大词数。
• min_font_size / max_font_size：本次整批布局可使用的硬字号边界。
• prefer_horizontal：水平排版概率。
• relative_scaling：权重对目标字号的影响比例。
• margin：真实字形之间的最小工作网格间距。

4. 放置语义

• 每个词只使用权重映射得到的目标字号。
• 放不下时只尝试同字号的另一方向，不会逐词缩字号。
• 调用者需要检查 layout_ 的数量；若不完整，应整批调整字号或扩大画布后创建新实例重排。
• 项目正式流水线使用 C++ place_glyph_exact() 做真实字形碰撞；底层兼容类保留矩形搜索 API。

5. 常见问题

5.1 若没有字体文件怎么办？

会回退到 PIL 默认字体，但测量与渲染效果可能不同。