docs/11_layout_optimizer.md

# 布局优化模块 (layout_optimizer)

布局优化模块（`layout_optimizer`）是 ChartPipeline 框架的第九个也是最后一个处理环节，负责组合并优化图表和标题 SVG 元素，生成最终的可视化作品。

## 功能简介

本模块接收前面生成的图表、标题和主体图像 SVG 元素，根据布局配置将它们整合为一个统一的最终可视化作品。模块进行精确的空间布局、元素对齐和比例调整，确保最终作品视觉平衡、结构清晰，并适合目标显示环境。这一步是整个可视化生成流程的最后阶段，对最终输出的视觉质量和专业性至关重要。

## 输入与输出

### 输入

模块接收两个主要的 SVG 输入、主题图像和一个 JSON 数据对象：

- `chart_svg`: 图表引擎生成的图表 SVG
- `title_svg`: 标题样式化模块生成的标题 SVG
- `image_svg`: 主题图像 SVG
- 包含布局配置的数据对象（通过 JSON 文件）

### 输出

模块输出一个包含最终可视化的 SVG 文件：

```json
{
  "final_svg": "<svg width=\"1000\" height=\"650\" xmlns=\"http://www.w3.org/2000/svg\">...</svg>"
}
```

最终 SVG 包含：

- 整合后的标题、图表和主体图像元素
- 调整后的尺寸和位置

## 布局优化功能

模块提供多种布局优化功能：

1. **元素组合**
   - 根据布局配置组合图表和标题
   - 处理元素间的相对位置关系
   - 创建一致的视觉层次结构

2. **空间分配**
   - 优化整体画布尺寸
   - 分配合适的空间给各元素
   - 调整元素间距和边距

3. **对齐和分布**
   - 确保元素正确对齐
   - 均匀分布相关元素组
   - 创建视觉上的平衡感

## 元素表示与数学建模

为了实现精确的布局优化，本模块采用矩形表示方法对各元素进行建模：

### 元素形式化定义

- 元素集合 E={T,I,C}，其中：
  - T: 标题（Title）
  - I: 主题图像（Image）
  - C: 图表（Chart）

矩形表示 R<sub>e</sub> 可以写为:

- R<sub>e</sub> = [x<sub>e</sub>, y<sub>e</sub>, x<sub>e</sub> + w<sub>e</sub>, y<sub>e</sub> + h<sub>e</sub>]，表示元素的矩形区域。

对于不同的元素:

- 标题和图表有固定尺寸 (w<sub>T</sub>, h<sub>T</sub>) 和 (w<sub>C</sub>, h<sub>C</sub>)。
- 主题图像的尺寸是可变的，范围为 w<sub>I</sub> ∈ [w<sub>I,min</sub>, w<sub>I,max</sub>] 和 h<sub>I</sub> ∈ [h<sub>I,min</sub>, h<sub>I,max</sub>]。

### 矩形表示可视化

矩形模型在二维空间中可以表示为：

```
(x,y)
   ┌───────────────────┐
   │                   │
   │     Element       │ h
   │                   │
   └───────────────────┘
                       (x+w, y+h)
           w
```

其中：
- (x,y) 是元素左上角的坐标
- w 是元素的宽度
- h 是元素的高度
- (x+w, y+h) 是元素右下角的坐标

当布局中包含多个元素时，它们的位置关系可以通过这些矩形的相对位置来表示。例如，当标题在图表上方时（title_to_chart: "T"），可表示为：

```
   ┌───────────────┐
   │    Title      │
   └───────────────┘
   ┌───────────────┐
   │               │
   │    Chart      │
   │               │
   └───────────────┘
```

### 元素间的位置关系

布局优化模块使用以下位置关系描述符来定义元素之间的空间组织：

1. **上下关系（Top/Bottom）**：元素在另一元素的上方或下方
   - 标题相对于图表可以是上方（T）或下方（B）
   - 图像相对于图表可以是上方或下方的一部分

2. **左右关系（Left/Right）**：元素在另一元素的左侧或右侧
   - 标题可以在图表的左侧（L）或右侧（R）
   - 图像可以在图表的左侧或右侧

3. **组合位置关系**：结合上下和左右的复合位置
   - 左上（TL）、右上（TR）、左下（BL）或右下（BR）
   - 这些位置关系通过坐标约束来表达

4. **内嵌关系（Center）**：元素嵌入另一元素内部
   - 标题可以内嵌于图表（C）
   - 图像也可以内嵌于图表中

5. **包含关系**：一个元素完全包含另一元素
   - 图表是否包含标题（chart_contains_title）
   - 图表是否包含图像（chart_contains_image）

### 位置约束格式

位置约束通过如下 JSON 格式指定：

```json
{
  "title_to_chart": "T",    // 标题相对图表的位置：T/B/L/R/TL/TR/BL/BR、内嵌(C)
  "image_to_chart": "BL",   // 图像相对图表的位置：T/B/L/R/TL/TR/BL/BR、内嵌(C)
  "title_to_image": "L",    // 标题相对图像的位置：T/B/L/R/TL/TR/BL/BR、内嵌(C)
  "chart_contains_title": false,  // 图表是否包含标题
  "chart_contains_image": false   // 图表是否包含图像
}
```

### 布局优化数学模型

基于矩形表示，布局优化问题可以抽象为一个矩形打包问题，目标是在满足元素间位置关系约束的条件下，找到一个优化的布局方案。布局优化的数学模型包括：

1. **目标函数**：
   - 最小化整个布局矩形的面积
   - 最大化主题图像的显示面积（对于可变尺寸的元素）
   - 维持视觉平衡度量指标

2. **约束条件**：
   - 位置关系约束（如上述位置描述符定义）
   - 非重叠约束（确保元素不重叠）
   - 包含关系约束（如嵌套结构）
   - 空间边界约束（如最小/最大尺寸）

通过这种数学表示，可以将布局优化问题转化为一个可以通过算法求解的形式化问题。

### 布局优化算法

模块使用以下算法和方法来求解布局优化问题：

1. **约束满足算法**：
   - 处理位置关系约束，将抽象的位置描述（如"T"、"BL"等）转换为具体的几何约束
   - 迭代求解过程中确保所有约束条件同时满足
   - 解决约束冲突和优先级处理

2. **矩形打包优化**：
   - 使用启发式方法（如模拟退火）寻找优化布局方案
   - 逐步调整元素位置和尺寸，最小化目标函数
   - 采用多目标优化权衡布局紧凑性与视觉平衡

3. **布局流程**：
   - 初始化：为每个元素分配初始位置和尺寸
   - 约束应用：应用位置关系约束调整元素坐标
   - 优化迭代：通过目标函数评估并改进布局方案
   - 后处理：微调元素间距、对齐和视觉平衡

#### 约束处理方法

在处理位置关系约束时，模块采用以下方法：

1. **相对位置转换**：
   - 当 `title_to_chart: "T"` 时，确保 title.y + title.height ≤ chart.y
   - 当 `image_to_chart: "BL"` 时，确保 image.x + image.width ≤ chart.x 且 image.y ≥ chart.y + chart.height
   - 当涉及内嵌关系（如 `title_to_chart: "I"`）时，确保 title.x ≥ chart.x 且 title.y ≥ chart.y 且 title.x + title.width ≤ chart.x + chart.width 且 title.y + title.height ≤ chart.y + chart.height

2. **包含关系处理**：
   - 当 `chart_contains_title: true` 时，调整标题位置确保其完全位于图表区域内
   - 当 `chart_contains_image: true` 时，调整图像位置确保其完全位于图表区域内

3. **间距管理**：
   - 在元素间保持适当的间距（margin）以确保布局美观
   - 根据设计指南自动计算元素间最佳间距
   - 确保间距均匀一致，提升整体视觉效果

#### 优化策略

矩形打包优化采用多阶段策略：

1. **粗优化阶段**：
   - 初步定位各元素，满足基本约束
   - 使用贪婪算法快速获得可行解

2. **细优化阶段**：
   - 微调元素位置和尺寸
   - 最小化布局总面积
   - 平衡各元素的视觉重要性

3. **特殊情况处理**：
   - 当元素过多或空间受限时，自动调整布局策略
   - 处理不同纵横比的图表和标题组合
   - 支持响应式调整，适应不同显示环境

## 使用示例

### 命令行调用

```bash
python -m modules.layout_optimizer.layout_optimizer --input_chart chart.svg --input_title title.svg --input_image image.svg --output final.svg
```

### 程序调用

```python
from modules.layout_optimizer.layout_optimizer import process

success = process(
    input_chart='chart.svg',
    input_title='title.svg',
    input_image='image.svg',
    output='final.svg'
)

if success:
    print("布局优化完成")
else:
    print("布局优化失败")
```