# 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,
    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 默认字体，但测量与渲染效果可能不同。