# rectloom API ## 数据类型 - `Rect`：输入矩形，包含 `id`、`width`、`height`。 - `Bin`：目标容器尺寸。 - `Padding`：`outer` 表示边框留白，`inner` 表示矩形之间的间距。 - `PackOptions`：打包配置，包含容器、padding、排序策略、算法和是否允许旋转。 - `Placed`：已放置矩形，包含坐标、实际尺寸、旋转状态和原始尺寸。 - `Layout`：打包结果，包含已放置项、未放入项、利用率和剩余面积。 - `Page`：多页打包中的一页。 - `MultiLayout`：多页打包结果，包含页面列表、最终未放入项和总体利用率。 - `RectSetStats` / `LayoutStats`：输入集合与输出布局的统计指标。 - `PackCandidate` / `PackComparison`：自动方案对比结果。 - `DensityCell` / `GridReport`：密度网格与热力图数据。 - `LayoutIssue` / `ConstraintViolation`：诊断与约束检查结果。 - `PlacementChange` / `LayoutDiff`：布局差异对比结果。 - `PackError`：输入、解析、越界、重叠等错误。 ## 主要函数 - `Rect::make(id, width, height)`：创建输入矩形。 - `Bin::make(width, height)`：创建容器。 - `Padding::make(outer, inner)`：创建 padding 配置。 - `PackOptions::default(width, height)`：创建默认 shelf-first-fit 配置。 - `pack(rects, options)`：打包矩形数组。 - `pack_pages(rects, options, max_pages)`：把矩形打包到多个相同尺寸页面中。 - `pack_spec(source)`：解析文本 spec 并打包。 - `pack_pages_spec(source, max_pages)`：解析文本 spec 并执行多页打包。 - `compare_packers(rects, base)`：自动比较算法、排序、旋转和间距组合。 - `recommend_pack(rects, base)`：返回评分最高的布局。 - `parse_spec(source)`：只解析 spec，不执行打包。 - `validate_layout(layout)`：校验布局是否越界、重复或重叠。 - `analyze_layout(layout)`：计算利用率、紧凑度、碎片化等统计指标。 - `density_grid(layout, cell_width?, cell_height?)`：生成粗粒度密度网格。 - `diagnose_layout(layout)`：生成结构化布局诊断。 - `check_constraints(layout, constraints)`：检查业务约束是否满足。 - `diff_layouts(left, right)`：对比两次布局输出。 - `fixture_rects(kind, count)`：生成内置基准数据。 - `dedupe_rect_ids(rects)`：稳定去重，并避开已有的生成式后缀冲突。 - `normalize_rects(rects, max_width, max_height)`：去重并拆分过大输入。 - `to_json_manifest(layout)`：导出稳定 JSON manifest。 - `to_pages_json_manifest(result)`：导出多页 JSON manifest。 - `to_report(layout)`：导出可读文本报告。 - `to_analysis_report(layout)`：导出布局统计报告。 - `to_comparison_report(comparison)`：导出自动方案对比报告。 - `full_layout_audit(layout)` / `packing_audit(rects, options)`：导出综合审计报告。 - `to_pages_report(result)`：导出多页文本报告。 - `to_ascii_preview(layout, cell_width?, cell_height?)`：导出终端友好的粗略字符预览。 - `error_message(err)`：把错误转换成稳定文本。 - `sample_spec()` / `sample_layout()`：内置最小示例。 ## Spec 指令 ```text bin padding algorithm shelf|guillotine|skyline sort input|area|height|width|perimeter rotate true|false rect ``` 所有尺寸均为正整数。`id` 不能为空且不能重复。