# LCD 图片资源优化与维护

## 目标

固件使用的 LCD 为 RGB565 显示格式，而设计工具导出的 PNG 通常是 RGB888 或 RGBA8888。原始 PNG 中包含 LCD 无法显示的颜色精度，部分图片还携带未实际使用的 Alpha 通道。

本项目在不改变 LCD 最终 RGB565 像素的前提下，将固件图片转换成 RGB565 颜色精度，并在颜色数量不超过 256 时保存为索引色 PNG，以降低 `gifpack` LittleFS 分区的占用。

正常固件编译直接使用已经提交到 Git 的优化图片，不要求开发环境安装 Pillow。只有修改或验证图片资源时才需要 Pillow。

## 目录结构

```text
components/platform/assets/
├── lcd_source/       原始设计图片，不直接打包进固件
└── lcd_optimized/    优化图片和 manifest.json，固件实际使用
```

两个目录中的 PNG 文件名必须一致。运行时路径仍为 `/lcd/<文件名>.png`，业务代码不需要区分原图和优化图。

`lcd_source` 中的 `OTA.gif` 是历史资源，不属于当前 PNG 优化和 `gifpack` 打包清单。

## 优化规则

脚本 `tools/optimize_lcd_assets.py` 对每张 PNG 执行以下操作：

1. 检查图片尺寸和 Alpha 范围。
2. Alpha 全部为 255 时移除无用的 Alpha 通道。
3. 将 RGB888 颜色对齐到 LCD 的 RGB565 精度。
4. RGB565 颜色不超过 256 种时保存为索引色 PNG。
5. 超过 256 种颜色时保存为普通 RGB PNG，不进行额外颜色合并。
6. 逐像素比较原图和优化图转换后的 RGB565 数值。
7. 生成包含文件哈希、尺寸、颜色数和容量的 `manifest.json`。

只要有一个 RGB565 像素不同，生成操作就会失败。发现透明或半透明图片时也会停止，避免静默删除有效透明度。

## 首次准备环境

建议使用独立 Python 虚拟环境，避免修改系统 Python：

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r tools/requirements-assets.txt
python tools/optimize_lcd_assets.py check-env
```

ESP-IDF 自带的 Python 环境如果已经安装对应版本的 Pillow，也可以直接使用。

## 修改图片后的操作

只修改 `lcd_source` 中的原图，不要手动编辑 `lcd_optimized`。

生成全部优化图片：

```bash
python tools/optimize_lcd_assets.py generate
```

执行完整的 RGB565 等价验证：

```bash
python tools/optimize_lcd_assets.py verify
```

然后检查并提交以下内容：

```text
components/platform/assets/lcd_source/
components/platform/assets/lcd_optimized/
components/platform/assets/lcd_optimized/manifest.json
```

不要反复处理 `lcd_optimized` 中的图片。每次必须从 `lcd_source` 原图重新生成，避免累计颜色或压缩处理误差。

## 普通固件编译

普通构建不生成图片，也不导入 Pillow。构建系统只执行基于 Python 标准库的哈希检查，确认：

- 原图没有在生成后发生变化；
- 优化图片没有缺失或被手动修改；
- 原图、优化图和清单中的文件集合一致。

资源过期时，构建会停止并提示重新运行 `generate`。资源有效时，构建系统把 `lcd_optimized` 中的 PNG 复制到构建目录并生成 `gifpack` 分区镜像。

## 命令说明

| 命令 | 是否需要 Pillow | 用途 |
| --- | --- | --- |
| `check-env` | 是 | 检查 Python 和 Pillow 环境 |
| `generate` | 是 | 从原图重新生成全部优化图片和清单 |
| `check-current` | 否 | 通过哈希检查已提交资源是否同步 |
| `verify` | 是 | 检查哈希并逐像素验证 RGB565 等价性 |

## 注意事项

- 优化图片针对 RGB565 LCD 制作，在高色深电脑屏幕上查看时可能与原始图片有细微颜色差异。
- 对当前 LCD 而言，优化前后的输出像素完全一致。
- 该方案主要降低 Flash 占用，不改变运行时 PNG 解码流程、帧缓存大小或动画播放接口。
- 如果未来需要透明叠加效果，应先扩展转换和运行时合成方案，不能直接删除 Alpha。
- 不要使用普通的“自动量化到 256 色”工具替代本脚本，否则可能合并 LCD 原本能够区分的颜色。