Initial project baseline

2026-07-04 02:40:45 +08:00
commit d5d8caef2f
86 changed files with 15590 additions and 0 deletions
@@ -0,0 +1,61 @@
+# EfficientWordCloud 使用文档
+
+## 1. 构建与安装
+在项目根目录执行：
+```bash
+python setup.py build
+python setup.py install
+```
+
+## 2. 基本使用示例
+```python
+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 默认字体，但测量与渲染效果可能不同。