post-process-logo

后处理徽标

此技能会将原始徽标图片转换为标准化的 256x256 PNG 格式，以用于 vault 协议元数据。它会自动从可用徽标中选择最接近正方形的版本，并在需要时添加留白，生成完美的正方形输出。

必需输入

开始前，请向用户收集以下信息：

1. 输入文件夹 - 存放原始徽标文件的文件夹（例如，eth_defi/data/vaults/original_logos/protocol-name/）
2. 输出文件夹 - 保存处理后徽标的文件夹（例如，eth_defi/data/vaults/formatted_logos/）
3. 版本偏好（可选）- 要处理的版本：generic、light、dark 或 all

如果缺少任何必需输入，请先询问用户。

前置条件

确保以下条件已满足：

1. 已安装 Python 依赖项：poetry install --with dev

已安装 Python Pillow，可用于检测图片格式、尺寸和透明度。

徽标术语

不同创作者为深色和浅色版本的徽标文件命名时，没有统一标准。在我们的用法中：

• light：深色或透明背景上的浅色（白色）文字
• dark：白色或透明背景上的深色（黑色）文字

使用以下术语：

• 品牌图形：也称为徽标图形，不含品牌名称文字的徽标
• 文字徽标：包含品牌名称文字的徽标

步骤 1：盘点输入徽标

列出输入文件夹中的所有图片文件并进行分类：

1. 识别文件格式：SVG、PNG、JPG、WEBP 等
2. 根据文件名按版本分类：
   • {slug}.generic.{ext} - 通用/默认主题
   • {slug}.light.{ext} - 浅色背景主题（深色徽标）
   • {slug}.dark.{ext} - 深色背景主题（浅色徽标）
3. 后处理时始终优先选择品牌图形，而非文字徽标作为源徽标
4. 检查宽高比：
   • 正方形宽高比：宽度等于高度（1:1）。检测时允许 90% 的误差，因为源素材可能存在个别像素误差。
   • 非正方形：宽度与高度不同，需要添加留白使其成为正方形
5. 检查徽标是否具有透明背景：
   • 透明背景：带有 Alpha 通道透明度的 PNG 文件
   • 假定 SVG 始终透明：原始 SVG 文件不应包含纯色背景
6. 向用户报告检查结果，并注明各版本的宽高比

步骤 2：选择版本

自动选择优先级

1. 选择最接近正方形的版本：计算每个版本的宽高比（较短边 / 较长边），并选择最接近 1.0 的版本
2. 如果多个版本的正方形程度相同：
   • 优先选择透明版本（带 Alpha 通道的 PNG、SVG）
   • 如果仍然持平，则优先级为 generic > light > dark
3. 如果用户指定了版本偏好：无论正方形程度如何，都使用该版本

步骤 3：处理徽标

处理所选徽标版本。脚本会自动为非正方形徽标添加留白，使其成为正方形，然后再缩放。

export INPUT_IMAGE=/path/to/original/logo.png
export OUTPUT_IMAGE=/path/to/output/logo.generic.png
poetry run python scripts/logos/post-process-logo.py

脚本将：

1. 如有需要，将 SVG 转换为 PNG
2. 添加透明留白，使徽标成为正方形（如果徽标不是正方形）
3. 如果背景尚未透明，则移除背景
4. 为深色背景重新着色（如果徽标颜色过暗，无法在深色背景上清晰显示，则反转颜色）
5. 裁去多余留白并缩放至 256x256

步骤 4：报告结果

向用户提供以下信息：

1. 已处理文件 - 列出所有创建的输出文件
2. 文件详情 - 每个文件的尺寸和大小
3. 任何问题 - 说明无法处理或存在质量问题的徽标

输出命名约定

输出文件应遵循以下命名模式：

• {protocol-slug}/light.png - 用于浅色背景
• {protocol-slug}/dark.png - 用于深色背景

故障排除

SVG 转换问题

如果 SVG 转换失败：

1. 检查 SVG 文件是否为有效的 XML
2. 某些复杂的 SVG 可能无法正确渲染
3. 尝试在浏览器中打开，确认 SVG 显示正常

背景移除问题

如果背景未能正确移除：

1. Logo 的边缘或渐变可能较复杂
2. 尝试提供分辨率更高的输入
3. 对于已包含透明度的 Logo，脚本会跳过背景移除