PPTX/openspec/changes/archive/2026-03-04-add-image-fit-modes/design.md

图片适配模式技术设计

Context

当前状态

当前系统图片渲染逻辑非常简单：直接使用 python-pptx 的 add_picture() 方法，传入 box 的宽高参数。python-pptx 会自动将图片拉伸到指定尺寸，无法保持宽高比，也无法进行居中或裁剪处理。

# 当前实现 (pptx_renderer.py)
def _render_image(self, slide, elem: ImageElement, base_path):
    x, y, w, h = [Inches(v) for v in elem.box]
    slide.shapes.add_picture(str(img_path), x, y, width=w, height=h)

约束条件

• 必须保持向后兼容：未指定 fit 参数时，行为与当前一致
• PPTX 渲染使用英寸单位，图片处理需要像素单位
• HTML 预览需要与 PPTX 渲染保持一致的视觉效果
• DPI 配置需要同时影响两个渲染器

利益相关者

• 最终用户：需要多样化的图片适配选项
• HTML 预览用户：期望预览效果与最终 PPTX 一致

Goals / Non-Goals

Goals:

• 支持四种图片适配模式（stretch、contain、cover、center）
• 支持留白区域的背景色填充
• 支持可配置的 DPI 转换
• HTML 预览与 PPTX 渲染效果一致
• 向后兼容现有 YAML 文件

Non-Goals:

• 不支持图片的旋转、翻转等变换
• 不支持图片滤镜、水印等高级效果
• 不支持 fill（平铺）模式
• 不支持自适应 box 尺寸（box 必需，不是可选）

Decisions

决策 1: 使用 Pillow 作为图片处理库

选择理由：

• Pillow 是 Python 生态中最成熟的图片处理库，从 PIL 发展而来
• 内置 ImageOps 模块，直接提供 contain() 和 cover() 方法，与我们的需求完全匹配
• API 简洁直观，社区活跃，文档完善
• 轻量级，专注图片处理，不像 OpenCV 那样重量级

替代方案考虑：

方案	优势	劣势	结论
Pillow	API 简洁，ImageOps 直接匹配需求	需要额外依赖	✅ 选择
OpenCV	功能强大，性能优异	API 复杂，BGR 颜色顺序需转换，过度设计	❌
Wand	功能丰富	依赖 ImageMagick，安装复杂，跨平台问题多	❌
原生实现	无额外依赖	需要手动实现所有算法，容易出错	❌

决策 2: DPI 作为文档级配置

选择： 在 metadata.dpi 中配置，默认值 96

理由：

• DPI 影响整个文档的所有图片，不应在元素级别配置
• 96 是 Web 标准 DPI，与当前 HTML 渲染器一致
• 简洁的配置方式，符合 YAML 声明式风格

替代方案： metadata.image.dpi（更结构化，但过于复杂）

决策 3: PPTX 和 HTML 使用不同的实现方式

PPTX 实现：

• 使用 Pillow 处理图片（缩放、裁剪）
• 计算居中位置
• 添加背景色画布（如有需要）
• 使用 python-pptx 添加处理后的图片

HTML 实现：

• 使用 CSS object-fit 属性
• stretch → object-fit: fill
• contain → object-fit: contain
• cover → object-fit: cover
• center → object-fit: none + object-position: center
• 背景色使用 CSS background-color

理由： 两个平台的原生能力不同，使用各自的最佳实践，但确保视觉效果一致

决策 4: 图片适配模式算法设计

┌─────────────────────────────────────────────────────────────────────┐
│                        图片适配算法流程                              │
└─────────────────────────────────────────────────────────────────────┘

输入: img (PIL.Image), box_size (width, height), fit, background

1. stretch 模式
   ─────────────────────────────────────────────────────────────────
   直接使用 img.resize(box_size)，不考虑宽高比

2. contain 模式
   ─────────────────────────────────────────────────────────────────
   result = ImageOps.contain(img, box_size)
   # result.size <= box_size，保持宽高比
   if background:
       canvas = 创建 box_size 画布，填充背景色
       canvas.paste(result, 居中位置)
       result = canvas

3. cover 模式
   ─────────────────────────────────────────────────────────────────
   result = ImageOps.cover(img, box_size)
   # result.size == box_size，保持宽高比，裁剪超出部分

4. center 模式
   ─────────────────────────────────────────────────────────────────
   result = img  # 不缩放
   if img.width > box_size.width or img.height > box_size.height:
       result = 裁剪到 box_size（居中裁剪）
   if background:
       canvas = 创建 box_size 画布，填充背景色
       canvas.paste(result, 居中位置)
       result = canvas

输出: result (PIL.Image), display_size, display_position

决策 6: 模块化设计

utils/image_utils.py
├── inches_to_pixels(inches, dpi) -> float
├── pixels_to_inches(pixels, dpi) -> float
├── calculate_contain_size(img_size, box_size) -> tuple
├── calculate_cover_size(img_size, box_size) -> tuple
├── calculate_center_offset(img_size, box_size) -> tuple
└── apply_fit_mode(img, box_size, fit, background) -> PIL.Image

validators/image_config.py (新建)
├── validate_fit_value(fit) -> List[ValidationIssue]
└── validate_fit_box_dependency(elem) -> List[ValidationIssue]

理由： 单一职责原则，图片处理逻辑与渲染逻辑分离，便于测试和复用

决策 5: 模块化设计

utils/image_utils.py
├── inches_to_pixels(inches, dpi) -> float
├── pixels_to_inches(pixels, dpi) -> float
├── calculate_contain_size(img_size, box_size) -> tuple
├── calculate_cover_size(img_size, box_size) -> tuple
├── calculate_center_offset(img_size, box_size) -> tuple
└── apply_fit_mode(img, box_size, fit, background) -> PIL.Image

validators/image_config.py (新建)
├── validate_fit_value(fit) -> List[ValidationIssue]
└── validate_background_color(color) -> List[ValidationIssue]

理由： 单一职责原则，图片处理逻辑与渲染逻辑分离，便于测试和复用

注意： 由于 box 参数为必填，不存在"没有指定 box"的情况，因此 validate_fit_box_dependency 验证器已移除。

Risks / Trade-offs

风险 1: Pillow 依赖增加

风险： 新增外部依赖可能增加安装复杂度

缓解措施：

• Pillow 是 Python 生态标准库，安装简单（pip install pillow）
• 在 pyproject.toml 中不指定版本号，使用最新稳定版
• 在 README 中明确说明依赖变更

风险 2: PPTX 和 HTML 渲染效果不完全一致

风险： 两个平台实现方式不同，可能在边缘情况下效果有差异

缓解措施：

• 核心算法（尺寸计算）使用相同的 Python 函数
• 编写集成测试，对比两种渲染器的输出
• 在文档中说明已知差异（如抗锯齿算法不同）

风险 3: 大图片处理性能问题

风险： Pillow 处理大图片可能较慢，占用内存

缓解措施：

• 仅在需要时才处理图片（contain/cover/center 模式）
• stretch 模式直接使用 python-pptx 的原生处理，不经过 Pillow
• 文档中建议用户使用适当尺寸的图片

风险 4: DPI 配置不当导致尺寸错误

风险： 用户设置的 DPI 与实际使用场景不符，导致图片尺寸不符合预期

缓解措施：

• 默认值 96 适用于大多数场景
• 在 README 中说明 DPI 的含义和影响
• 验证器检查 DPI 值是否合理（如 72-300 之间）

Migration Plan

部署步骤

1. 代码变更

   • 添加 Pillow 依赖到 pyproject.toml
   • 创建 utils/image_utils.py
   • 创建 validators/image_config.py
   • 更新 core/elements.py 的 ImageElement
   • 更新 renderers/pptx_renderer.py
   • 更新 renderers/html_renderer.py

2. 测试

   • 单元测试：image_utils 的各个函数
   • 单元测试：validators 的图片配置验证
   • 集成测试：四种 fit 模式的 PPTX 渲染
   • 集成测试：四种 fit 模式的 HTML 渲染
   • 端到端测试：完整 YAML 转换流程

3. 文档更新

   • 更新 README.md，添加图片适配模式说明
   • 更新 README_DEV.md，添加架构说明

回滚策略

• 如果发现严重问题，可以回退到之前版本
• 向后兼容设计确保未指定 fit 参数的 YAML 文件仍能正常工作
• 回滚后用户只需删除 fit 和 background 参数即可

Open Questions

Q1: 是否需要在图片处理失败时提供降级方案？

决策： 图片处理失败时抛出 ERROR 级别错误，让用户修复图片问题，不提供降级方案。

理由： 保持简单明确，图片问题应该由用户在源头解决，而不是掩盖问题。

Q2: background 参数是否支持渐变色？

决策： background 参数仅支持纯色，不支持渐变色。

理由： 简化实现，满足绝大多数使用场景。如有后续需求，可以作为独立功能添加。

Q3: 是否需要支持图片质量设置？

决策： 使用 Pillow 的最高质量重采样算法（LANCZOS），不向用户暴露配置选项。

理由： 演示文稿场景下图片质量优先于处理速度，使用最高质量算法避免用户困惑。