# rectloom Design

`rectloom` 是一个纯 MoonBit 的确定性矩形打包与布局校验库。它不读取图片、不依赖平台图形 API，而是把输入矩形转换成稳定坐标清单，供资源图集、UI 布局、文档导出、WASM 工具和 CI 快照使用。

## 架构

项目按五层组织：

- 输入层：`Rect`、`Bin`、`Padding`、`PackOptions` 与文本 spec 解析。
- 算法层：单页打包、多页打包、排序、旋转和 padding 处理。
- 校验层：输入合法性、重复 id、越界、重叠和业务约束检查。
- 分析层：利用率、紧凑度、碎片化、密度网格、热力图、诊断和差异对比。
- 导出层：文本 report、JSON manifest、CSV、Markdown 表格、ASCII 预览和综合审计报告。

所有算法都保证同一输入产生同一输出，便于在 CI 中比较结果。

## 打包算法

`ShelfFirstFit` 按排序后的矩形顺序放置，一行放不下时开启下一行。它速度快、行为直观，适合作为基线算法和文档布局类场景。

`GuillotineBestArea` 维护空闲矩形列表，每次选择面积浪费最小的空闲区域。放置后将剩余空间切分为右侧区域和下方区域。它更适合混合尺寸资源，输出仍然完全确定。

`SkylineBottomLeft` 逐点寻找最低、最靠左的可放置位置，并按方向优先级打破平局。它适合细长矩形、UI 面板和需要更紧凑底部轮廓的输入。

`compare_packers` 会自动组合算法、排序、旋转和 inner padding，使用稳定评分选出推荐布局。评分优先考虑放入数量、整体利用率、紧凑度、未放入惩罚、碎片化和旋转成本。

## 不变量

- 所有输入矩形尺寸必须为正整数。
- 容器尺寸必须为正整数。
- `outer * 2` 必须小于容器宽高。
- 同一批输入的 `id` 不得重复。
- 已生成布局不得越界、重复 placement 或相互重叠。
- 多页打包使用同一套 bin 和 options，逐页处理上一页剩余矩形。

## 分析与诊断

`analyze_layout` 计算放入数量、未放入数量、旋转数量、容器利用率、padding 后利用率、外接矩形利用率、行列数量、碎片化和紧凑度。

`density_grid` 将布局切成粗粒度网格，统计每个网格的使用面积和占用率，并可导出热力图或 CSV。它方便在日志里观察布局是否过于稀疏。

`diagnose_layout` 输出结构化问题列表，例如利用率低、存在未打包项、外接框过宽或过高、网格稀疏、旋转比例过高和行列碎片化。

`check_constraints` 面向生产约束，例如必须全部打包、最低利用率、最大浪费率、最小间距、最大行列数量和最大旋转比例。

`diff_layouts` 用 placement id 比较两个布局，标记新增、移除、移动、尺寸变化、旋转变化和未变化项，适合回归测试和版本升级说明。

## Fixture 与输入变换

内置 fixture 覆盖图集、UI 面板、文档块、混合图标和细条压力测试数据。它们用于示例、测试和本地 benchmark，避免依赖来源不明素材。

输入变换工具支持缩放、扩边、收缩、id 前后缀、重复 id 去重、过宽/过高矩形拆分、按 bin 过滤超尺寸矩形，以及 CSV/Markdown/spec 导出。

## 导出

JSON manifest 使用库内 `StringBuilder` 手写导出，避免引入额外 JSON 依赖，便于 WASM 或小工具环境复用。字段顺序固定，适合 CI 或资源管线比较输出。

ASCII 预览把布局按固定单元格压缩成字符网格，每个矩形使用 id 首字符标记。热力图则按网格利用率输出 `. : + * # @`，用于快速观察密度分布。

综合审计报告会串联布局报告、统计、诊断、约束和密度信息，适合作为命令行工具、CI 日志或评审材料的证据输出。

## 复杂度与边界

当前算法追求稳定、可解释和易复现，不承诺全局最优装箱。`SkylineBottomLeft` 会扫描候选坐标，适合中小规模资源集合；大规模资源管线可以先使用排序、过滤和拆分工具降低输入复杂度。

项目暂不处理图片像素、透明区域检测、PNG/JPEG 编码、任意多边形、浮点坐标或不同尺寸容器自动选择。