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,
    prefer_horizontal=0.9
)

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

3. 关键参数说明

• width / height：画布尺寸。
• font_path：字体路径。
• max_words：最大词数。
• min_font_size：最小字体。
• prefer_horizontal：水平排版概率。
• use_spiral_search：是否启用中心优先排序搜索。

4. 并行优化的使用说明

4.1 Python bbox 预取

• 自动启用，无需额外配置。
• 内部使用 ProcessPoolExecutor，将未来词语的 bbox 计算并行化。
• 运行 generate 时会输出预取/等待日志，便于观察并行效果。

4.2 C++ 并行搜索

• 当 use_spiral_search=True 时启用。
• 在 C++ 内部自动进行分块并行搜索，并保持中心优先排序的结果一致性。

5. 常见问题

5.1 为什么字体缩小时没有并行？

缩小字体后 bbox 依赖当前失败状态，需要同步确认以确保正确性。

5.2 多进程是否会导致额外内存开销？

是的，但任务仅用于 bbox 预取，且窗口大小有限，避免过度占用。

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

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